b0400bj B

B0400BJ
REV B
I/A Series®
NetAPI MFC Class
March 3, 2003
Invensys, AIM*API, AIM*AT, AIM*DataLink, AIM*Explorer, AIM*Historian, Foxboro, FoxAPI, 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 2002-2003 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
Organization .......................................................................................................................... xiii
Revision Information ............................................................................................................. xiv
Related Documents ................................................................................................................ xiv
Request For Comments .......................................................................................................... xiv
1. Overview ........................................................................................................................... 1
NetAPI MFC Methods ............................................................................................................. 2
2. Installation and Configuration .......................................................................................... 3

System Requirements ................................................................................................................ 4
Development Machine Installation Procedure ........................................................................... 5
Development Configuration ..................................................................................................... 8
3. Using the NetAPI MFC Class ......................................................................................... 11

Creating a Project .................................................................................................................... 11
Creating Instances of the CFoxAPIServer Class .................................................................. 11
CFoxAPIServer Class Methods ................................................................................................ 12
Server Connection Methods ............................................................................................... 12
Server Information ............................................................................................................. 12
Compound Summary Access (CSA) Methods .................................................................... 13
Data Object Access Methods .............................................................................................. 14
File Access Methods ........................................................................................................... 14
FoxAPI Data Sets Methods ................................................................................................ 15
Historian Access Methods .................................................................................................. 15
AIM*Historian Only Access Methods ................................................................................ 16
CDataElement Class Methods ................................................................................................ 16
Putting the Application into Production ................................................................................. 17
4. CFoxAPIServer Class Methods Reference........................................................................ 19

AddMultipleObjects ............................................................................................................... 19
AddObject .............................................................................................................................. 23
iii
B0400BJ – Rev B Contents
CloseFoxAPISet ...................................................................................................................... 25
ConfigureFoxHistory .............................................................................................................. 26
ConnectToServer .................................................................................................................... 33
ConnectToServerByName ...................................................................................................... 34
CreateEventMsgDef ................................................................................................................ 35
DisconnectFromServer ............................................................................................................ 36
dqObjectChange ..................................................................................................................... 37
EngUnits ................................................................................................................................. 38
EnumServerAlias ..................................................................................................................... 39
EnumServerHistorians ............................................................................................................ 40
FetchObjectIndex ................................................................................................................... 41
FetchObjectName ................................................................................................................... 42
FileRead .................................................................................................................................. 43
FileStat .................................................................................................................................... 44
FormatData ............................................................................................................................ 45
FormatDataAndTimeStamp ................................................................................................... 46
FoxHistSystem ........................................................................................................................ 47
GetAccessInfo ......................................................................................................................... 48
GetAliasPath ........................................................................................................................... 49
GetAllBlocks ........................................................................................................................... 50
GetAllCompounds .................................................................................................................. 51
GetBlkDescription .................................................................................................................. 52
GetBlockCompounds ............................................................................................................. 53
GetBlockParams ...................................................................................................................... 54
GetCompBlockAndType ........................................................................................................ 55
GetCompoundBlocks ............................................................................................................. 56
GetConfigFile ......................................................................................................................... 57
GetDirList .............................................................................................................................. 58
GetFile .................................................................................................................................... 59
GetFoxAPIVersion .................................................................................................................. 61
GetFoxHistGroups ................................................................................................................. 62
GetFoxHistMessageColumns .................................................................................................. 63
GetFoxHistMessageData ......................................................................................................... 64
Method 1 ........................................................................................................................... 64
Method 2 ........................................................................................................................... 65
GetFoxHistMessageGroupKeys ............................................................................................... 68
iv
Contents B0400BJ – Rev B
GetFoxHistConfigSessionRTPNames ..................................................................................... 69
GetFoxHistRTPDefinition ..................................................................................................... 70
GetFoxHistRTPValues ........................................................................................................... 74
GetHistArchiveGroups ........................................................................................................... 77
GetHistData ........................................................................................................................... 78
Method 1 ........................................................................................................................... 78
Method 2 ........................................................................................................................... 79
Method 3 ........................................................................................................................... 80
GetHistGroups ....................................................................................................................... 82
GetHistGrpMembers .............................................................................................................. 83
Method 1 ........................................................................................................................... 83
Method 2 ........................................................................................................................... 83
GetHistItemList ...................................................................................................................... 85
GetHistOperations .................................................................................................................. 86
GetHistVersion ....................................................................................................................... 87
GetHostID .............................................................................................................................. 88
GetIAVersion .......................................................................................................................... 89
GetMaxEntries ........................................................................................................................ 90
GetMaxSet .............................................................................................................................. 91
GetMessageData ..................................................................................................................... 92
Method 1 ........................................................................................................................... 92
Method 2 ........................................................................................................................... 93
GetMessageGroup ................................................................................................................... 95
GetMsgGroupAndName ......................................................................................................... 96
GetObjectCount ..................................................................................................................... 97
GetPackageUsers ..................................................................................................................... 98
GetPathAlias ........................................................................................................................... 99
GetServerBinDir ................................................................................................................... 100
GetServerDir ......................................................................................................................... 101
GetServerID .......................................................................................................................... 102
GetServerInfo ........................................................................................................................ 103
GetServerInstDir ................................................................................................................... 104
GetServerName ..................................................................................................................... 105
GetServerStatus ..................................................................................................................... 106
GetServerTimeout ................................................................................................................. 107
GetServerType ...................................................................................................................... 108
GetSetItemNames ................................................................................................................. 109
GetSetNames ........................................................................................................................ 110
v
GetStationCompounds ......................................................................................................... 111

GetStations ........................................................................................................................... 112
GetTimeLinearData .............................................................................................................. 113
GetTimeUsage ...................................................................................................................... 115
GetUserConnection .............................................................................................................. 116
IPAddress .............................................................................................................................. 117
Method 1 ......................................................................................................................... 117
Method 2 ......................................................................................................................... 117
IsDir ..................................................................................................................................... 118
IsFoxHistory ......................................................................................................................... 119
IsInHistorian ......................................................................................................................... 120
IsOffPlatform ........................................................................................................................ 121
IsServerOK ........................................................................................................................... 122
MakeSystemCall ................................................................................................................... 123
MultipleObjectWrite ............................................................................................................ 124
ObjectRange ......................................................................................................................... 125
ObjectRead ........................................................................................................................... 126
Method 1 ......................................................................................................................... 126
Method 2 ......................................................................................................................... 126
ObjectReadAll ....................................................................................................................... 128
ObjectType ........................................................................................................................... 129
ObjectWrite .......................................................................................................................... 130
OpenFoxAPISet .................................................................................................................... 131
PutFile .................................................................................................................................. 132
PutFoxHistRTPValue ........................................................................................................... 134
ReconnectToServer ............................................................................................................... 136
RemoveObject ...................................................................................................................... 137
RemoveObjects ..................................................................................................................... 138
SearchFoxHistRTPNames ..................................................................................................... 139
SetServerTimeout .................................................................................................................. 140
SetUserConnection ............................................................................................................... 141
WriteEventMsgData ............................................................................................................. 142
WriteMDEData .................................................................................................................... 143
5. CDataElement Class Methods Reference....................................................................... 145

Format() ................................................................................................................................ 146
Getmsec() .............................................................................................................................. 147
vi
Contents B0400BJ – Rev B
Getsource .............................................................................................................................. 148

GetStations ........................................................................................................................... 149
GetStrValue .......................................................................................................................... 150
GetTimeDiff ......................................................................................................................... 151
GetUseServerTime ................................................................................................................ 152
Getutc() ................................................................................................................................ 153
LoadValueFromString ........................................................................................................... 154
SetType ................................................................................................................................. 155
SetUseServerTime ................................................................................................................. 156
Type() ................................................................................................................................... 157
Type(CString &s) ................................................................................................................. 158
CDataElement Class Data Types .......................................................................................... 159
Appendix A. Error Messages.............................................................................................. 161
Appendix B. Object Status and Value Types ..................................................................... 167

AIM*Historian Reduction Status and Quality ....................................................................... 170
Index .................................................................................................................................. 173
vii
viii
Figures
1-1. I/A Series NetAPI MFC Interface with Various I/A Series Resources ............................ 1
2-1. Setup Welcome Dialog Box .......................................................................................... 5
2-2. Choose Destination Location Dialog Box ..................................................................... 6
2-3. Installation Complete Dialog Box ................................................................................. 7
2-4. Sample an_init.cfg File .................................................................................................. 8
ix
B0400BJ – Rev B Figures
x
Tables
1-1. I/A Series NetAPI MFC Methods ................................................................................. 2
2-1. AISnet Keywords .......................................................................................................... 9
4-1. Server Access Levels ..................................................................................................... 48
4-2. Configurable Reduction Group Operations ................................................................ 86
4-3. Configurable Historian Operations ........................................................................... 114
5-1. CDataElement Class Data Types .............................................................................. 159
A-1. Error Codes and Strings Returned by NetAPI MFC Class ........................................ 161
B-1. Status Definition with I/A Series Object Manager and AIM*Historian ..................... 167
B-2. I/A Series Object and AIM*Historian RTP Value Types ........................................... 168
B-3. Status Returned by Reductions APIs ......................................................................... 170
B-4. Reduction Value Types ............................................................................................. 171
xi
B0400BJ – Rev B Tables
xii
Preface
This document describes the I/A Series® NetAPI MFC Class software and how it is used to
access the I/A Series distributed control system, I/A Series Historian applications and
AIM*Historian instances.
Audience
This document is intended for programmers and other software professionals who are
developing or maintaining Microsoft® Windows® applications that require networked access to
an I/A Series system. The reader should have a working knowledge of Microsoft’s C++ implemen-
tations and Microsoft Foundation Class (MFC) programming.
Organization
This document is organized into seven sections:
♦ Chapter 1 “Overview” provides an introduction to the NetAPI MFC Class.
♦ Chapter 2 “Installation and Configuration” describes how to install and configure the
NetAPI MFC Class on the development machine using the distribution CD and
sample files.
♦ Chapter 3 “Using the NetAPI MFC Class” describes how to create instances of the
class and lists the server connection and data access methods included in the NetAPI
MFC Class.
♦ Chapter 4 “CFoxAPIServer Class Methods Reference” is a reference guide to the
methods available with NetAPI MFC Class CFoxAPIServer.
♦ Chapter 5 “CDataElement Class Methods Reference” describes the methods available
with NetAPI MFC Class CDataElement.
♦ Appendix A “Error Messages” lists error codes and strings issued by the NetAPI MFC
Class.
♦ Appendix B “Object Status and Value Types” describes the status words and value
types of I/A Series objects and AIM*Historian real-time points (RTPs) and reduction
RTPs.
xiii
B0400BJ – Rev B Preface
Revision Information
The following changes were made to this document for release of AIM*AT® 3.2:
♦ Chapter 2 “Installation and Configuration”
Updated to include support for additional Microsoft platforms.
♦ Chapter 3 “Using the NetAPI MFC Class”
Expanded to include methods related to time stamps.
♦ Chapter 4 “CFoxAPIServer Class Methods Reference”
Expanded to include methods related to time stamps.
Related Documents
Refer to the following documents for information on the APIs that the class uses to access
I/A Series resources and on related AIM*AT programs:
♦ AIM*API User’s Guide (B0193YN)
♦ AIM*Historian User’s Guide (B0193YL)
♦ AIM*AT Installation Guide (B0193YM)
♦ FoxAPI User’s Guide (B0193UD)
♦ Integrated Control Software Concepts (B0193AW)
♦ Integrated Control Block Descriptions (B0193AX).
Request For Comments

Please direct your comments and suggestions concerning the I/A Series NetAPI MFC Class and
this documentation to:
Customer Satisfaction Center
Invensys Systems, Inc.
33 Commercial Street
Foxboro, MA 02035-2099
Telephone within the US: 1-866-746-6477
Telephone from outside the US: 508-549-2424
Facsimile: 508-549-4999
xiv
1. Overview
This chapter provides an overview of the I/A Series NetAPI MFC Class.
The I/A Series NetAPI MFC Class is an implementation of Microsoft Foundation Class (MFC)
technology designed to simplify interface requirements with the I/A Series system resources. The
application interface enables more efficient development of Windows based programs that access
I/A Series systems and AIM*AT servers.
The class provides a C++ wrapper around an extensive library of C language calls developed earlier
with Networked FoxAPI™ software and AIM*API™ software. The class provides a thread-safe
connection interface, and simplifies the interface requirements, as developers use fewer, more
advanced C++ methods, and yet have all of the functionality and access of the earlier APIs.
The I/A Series NetAPI MFC Class consists of a single public object, CFoxAPIServer, which
defines methods for initialization, connection to I/A Series and AIM*AT Servers, and access to
real-time data, files, and process history.
The NetAPI MFC Class software consists of a header file, a library file, and a runtime DLL
that are installed on the application host. When the class is invoked, it creates an instance of the
object, which is destroyed at completion of the program. The methods transparently exploit
existing FoxAPI and AIM*API calls in the library to connect with the servers and access their data
(Figure 1-1).
Application Host
NetAPI MFC
Class
Networked FoxAPI
AIM*API
Networked Networked AIM*API

FoxAPI FoxAPI
CSA, Process I/A Series AIM*Historian

Objects Historian
I/A Series Server I/A Series Server AIM*AT Server
Figure 1-1. I/A Series NetAPI MFC Interface with Various I/A Series Resources
1
B0400BJ – Rev B 1. Overview
NetAPI MFC Methods

The NetAPI MFC Class provides methods in a variety of areas, as described in Table 1-1.
Table 1-1. I/A Series NetAPI MFC Methods
Method Type Description

Server Connection These methods identify available servers, establish and renew connections
with the servers, retrieve connection status, and convert I/A Series time to
local time.
Server Information Once the application is connected to the server, these methods access
information about the servers.
Compound Summary The CSA methods connect to the I/A Series Compound Summary Access
Access (CSA) (CSA) so the application can identify the components of the control data-
bases available via the connected servers, including letterbugs, com-
pounds, block names, types and parameters.
Each I/A Series control station is identified by a six-character electronic
address called the letterbug. The control databases on the stations consists
of software blocks organized into one or more compounds. The blocks are
configurable segments of executable code. The I/A Series software offers a
variety of block types for specific functions such as I/O, calculations,
sequence control, and alarms.
The objects are identified by control station and the block parameter
name using the syntax:
<COMPOUND>:<BLOCK>.<PARAMETER>
For additional information on I/A Series control databases, see Integrated
Control Software Concepts (B0193AW) and Integrated Control Block
Descriptions (B0193AX).
Data Object Access These methods establish a real-time connection with I/A Series objects.
The methods allow creation of object aliases, setting change deltas, deter-
mining object ranges, and writing objects.
File Access These methods include identifying directories and files, and reading and
writing files.
FoxAPI Data Sets The class includes five methods that deal with the data sets created with
older versions of FoxAPI software and its predecessor, AIS. These meth-
ods are designed to provide compatibility with legacy applications. Sets
are not used in later versions of FoxAPI software or with AIM*API soft-
ware. For additional information on FoxAPI sets, see the FoxAPI User’s
Guide (B0193UD).
Historian Access The class provides a variety of methods for accessing process history as
collected by the I/A Series Historian and AIM*Historian™ instances. In
addition to identifying historian instances and configurations, the meth-
ods access sample data, write real-time points configured for manual data
entry (MDE), retrieve reduction data, and access message groups. Many
of the methods apply to both historian types. The descriptions in
Chapter 4 “CFoxAPIServer Class Methods Reference” identify which
methods are used only with AIM*Historian.
2
2. Installation and Configuration
This chapter describes how to install and configure the I/A Series NetAPI MFC Class on the
development machine using the distribution CD and sample files.
The I/A Series NetAPI MFC software is distributed on a single CD-ROM. The CD includes
program files and an InstallShield® application that copies the software to the selected directories
on the development machine and updates the Windows or Windows NT® Registry.
The included program files are:
foxapiserver.h Header file that defines attributes and methods for the class.
apiserv32.lib Library of C++ calls that wrap around Networked FoxAPI and AIM*API
functions calls.
apiserv32d.lib Debug version of apiserv32.lib.
apiserv32.dll Runtime dynamic link library (DLL). This file must be ported to the
application hosts along with shared MFC libraries MFC42.dll and
MSVCRT.dll when the application is put into production.
apiserv32d.dll Debug version of apiserv32.dll.
errorstr.dat ASCII file that provides a descriptive string for each error code returned
from the target servers. This file must be ported to the application hosts
when the program is put into production. You can modify the strings
using a text editor to provide more detailed explanations. Appendix A
“Error Messages” lists the file contents.
an_init.cfg Sample client initialization file used by the application to identify target
servers and set trace options and other parameters. This file is used on
both the development machine and the application hosts. See “Develop-
ment Configuration” on page 8 for a description of the file keywords and
instructions on modifying an_init.cfg.
The development machine, and later the application hosts, communicate with various I/A Series
stations and AIM*API servers via a TCP/IP connection. If the servers are running AIM*API 3.1
or later, the NetAPI MFC Class software may use the server configuration file to determine server
names, path aliases and other data necessary for connection. For Networked FoxAPI server and
for AIM*API 3.0 and earlier, you must load the client initialization file (an_init.cfg) onto the
development and application hosts. The Setup program creates a Registry entry on the develop-
ment machine that identifies the location of the file. An application hosts’ Registry must also be
updated to define the location of the file.
NOTE
When debugging, make sure you link to the debug version of the libraries:
apiserv32d.lib and apiserv32d.dll.
3
B0400BJ – Rev B 2. Installation and Configuration
System Requirements
I/A Series NetAPI MFC Class is an implementation of Microsoft Foundation Class technology,
and is designed for application development using Microsoft Visual Studio. The application host
can be any of the following Microsoft platforms:
♦ Windows 95
♦ Windows 98
♦ Windows NT 4.0
♦ Windows 2000
♦ Windows XP.
The software also requires a TCP/IP connection with the target servers. Each server must be
running either Networked FoxAPI software or AIM*API software. The class does not require
authorization to access the servers, as the class has full access privileges with the APIs.
The I/A Series NetAPI MFC Class requires Microsoft Visual Studio, Version 6.0 with Service
Pack 3 or later. As an MFC extension class, the software uses shared MFC libraries. When you
begin a project, you must use the MFC Libraries as a shared DLL.
4
2. Installation and Configuration B0400BJ – Rev B
Development Machine Installation Procedure

To install the I/A Series NetAPI MFC software:
1. Insert the CD into the CD-ROM drive of the development machine.
2. If AutoRun is not enabled, start the program from the toolbar:
a. Choose Start > Run.
b. Browse to Setup on the CD.
c. Double-click Setup to load the program name in the Run dialog text box.
d. Click OK.
The Setup program opens with a Welcome dialog box (Figure 2-1).
Figure 2-1. Setup Welcome Dialog Box
3. Click Next.
Setup displays the license agreement.
5
4. Click OK to indicate that you have read the license and agree with the terms.
Setup displays the Choose Destination Location dialog box (Figure 2-2). You can
install the software in any directory, but it is strongly recommended that you use the
default, C:\Program Files\The Foxboro Company\NetAPI_MFC_Class.
Figure 2-2. Choose Destination Location Dialog Box
6
5. Click Next to accept the default selection, or use the Browse feature to select a
different destination directory and then click Next.
Setup copies the software to the selected directory and creates the following Registry
entry:
HKEY_LOCAL_MACHINE\Software\SimSci\Aim\Settings\an_init =
<drive:>\<path>\an_init.cfg
where drive and path define the directory selected in the Choose Destination Location
dialog box (Figure 2-2).
When the NetAPI MFC application is executed, the DLL references this file for server
connections and other settings. The DLL also creates the following Registry entries:
HKEY_LOCAL_MACHINE\Software\SimSci\Aim\Settings\BroadcastWait
HKEY_LOCAL_MACHINE\Software\SimSci\Aim\Settings\DisableBroadcast
Setup announces completion of the installation with the Installation Complete dialog
box (Figure 2-3).
Figure 2-3. Installation Complete Dialog Box
6. Click Finish to close the dialog box and exit Setup.
7
Development Configuration
When an instance of the I/A Series NetAPI MFC Class is started, it uses a network broadcast to
identify servers. If the target servers are running AIM*AT 3.1 or later and they are configured to
respond to the broadcasts, they provide the application with client configuration information
from their server initialization files. The application also checks the local an_init.cfg file for server
connections. During installation, a sample copy of this file is placed in the program directory at
the location identified in the Registry.
An an_init.cfg file may already exist on the host if the machine is already used for AIM*AT
programs such as AIM*Historian and AIM*DataLink™. The I/A Series NetAPI MFC Class relies
on the Registry entry to point to the correct file.
The file an_init.cfg is a keyword file similar to Windows initialization (*.ini) files with section
labels in brackets.
There are two required sections:
[AISnet] Defines trace options and maximum server interactions
[TCPIP] Specifies the path, protocol, and network API of the target servers.
Figure 2-4 shows a sample client initialization file.
Figure 2-4. Sample an_init.cfg File
8
The [AISnet] section keywords are described in Table 2-1.
Table 2-1. AISnet Keywords
Keyword Default Description

PrintErr 0 Print error help messages:
0 for no message
1 for brief message
2 for detailed message
TraceLevel 0 Trace Level:
0 none
1 all of send and receive messages
2 dot (.) for send messages
3 first 20 bytes of send and receive messages
LogFilePrefix c:\an Specifies where to put log files if Tracing is on. The default prefixes
file names with an so they are easily identified.
MaxLog 1000 Maximum size of log file, in kilobytes. When the file reaches its
maximum size, message logging wraps around to the beginning of the
file and overwrites the oldest data.
MaxEnt 500 Maximum number of AIM*API data set objects that can be viewed
concurrently from the application.
Multiples 0 By default, AddMultipleObjects filters out duplicate object names,
returning an error code for each duplicate. To allow duplicate objects,
enable Multiples (=1).
The [TCPIP] section keywords are the IP names or aliases of the target servers. Each alias is
equated with three parameters:
The entry uses the following format:
<server name> = "<IP address> <port number> /dev/tcp 1024"
To modify the sample configuration file:
1. Open the an_init.cfg file using Notepad or another text editor.
2. Modify AISnet parameters as required.
You may want to revisit these parameters later in the project.
3. Identify the target servers in the [TCPIP] section.
a. For server name, use whatever alias is to be used in the client application.
The server names in Figure 2-4 are letterbugs of I/A Series workstations.
b. Enter the full TCP/IP address of the target server.
c. Set the port number to 45678 if the server is an AIM*AT server. Set the port
number to 55555 if the server is a FoxAPI server.
In Figure 2-4, three servers are AIM*AT servers. The [TCPIP] entry that is com-
mented out is for an I/A Series station that was accessed using a
Networked FoxAPI instance.
d. Enter the protocol specification exactly as shown in the format and the examples.
9
10
3. Using the NetAPI MFC Class
This chapter describes creating instances of the class and lists the server connection and data
access methods included in the I/A Series NetAPI MFC Class.
Creating a Project
The I/A Series NetAPI MFC Class is designed for use with Microsoft Visual Studio. When you
begin a project, make sure you use the MFC Libraries as a shared DLL. When debugging, be sure
to link to the apiserv32d.lib and aipserv32d.dll libraries.
Creating Instances of the CFoxAPIServer Class

Create an instance of the class using one of the two methods below.
CFoxAPIServer MyServer;
or
CFoxAPIServer *pMyServer;
pMyServer = new CFoxAPIServer;
The following methods create a new instance of the class by duplicating the existing class:
MyServer= pMyServer
which uses overloaded operator= as declared in the operation:
void operator= (CFoxAPIServer * pServer);
or
CFoxAPIServer MyServer(pMyServer);
The default destructor virtual ~CFoxAPIServer(); is included in the class. Use good
programming practices and clear the instance upon completion of the program using:
delete pMyServer;
11
B0400BJ – Rev B 3. Using the NetAPI MFC Class
CFoxAPIServer Class Methods

The following describes the Server Connection and Data Access methods included in the NetAPI
CFoxAPIServer class, and groups the methods for those types by categories. The page number is
included so you can locate the methods easily in Chapter 4 “CFoxAPIServer Class Methods
Reference”.
Server Connection Methods

These methods identify available servers, establish and renew connections with the servers,
retrieve connection status, and convert I/A Series time to local time.
NOTE
A NetAPI MFC instance connects to one server at a time. Create multiple instances
to connect simultaneously with multiple servers.
Method Page
ConnectToServer page 33
ConnectToServerByName page 34
DisconnectFromServer page 36
EnumServerAlias page 39
GetConfigFile page 57
GetServerInfo page 103
GetServerStatus page 106
GetUserConnection page 116
ReconnectToServer page 136
SetUserConnection page 141
Server Information
Once the application is connected to the server, these methods access information about the
servers.
Method Page
GetAccessInfo page 48
GetAliasPath page 49
GetFoxAPIVersion page 61
GetHostID page 88
GetIAVersion page 89
GetMaxEntries page 90
GetPackageUsers page 98
GetPathAlias page 99
GetServerID page 102
12
3. Using the NetAPI MFC Class B0400BJ – Rev B
Method Page
GetServerName page 105
GetServerTimeout page 107
GetServerType page 108
GetTimeUsage page 115
BOOL IPAddress page 117
UINT IPAddress page 117
IsOffPlatform page 121
IsServerOK page 122
SetServerTimeout page 140
Compound Summary Access (CSA) Methods

The CSA methods connect to the I/A Series Compound Summary Access (CSA) so the
application can identify the components of the control databases available via the connected
servers. The components include letterbugs, compounds, block names, types, and parameters.
Each I/A Series control station is identified by a six-character electronic address called the letter-
bug. The control databases on the stations consists of software blocks organized into one or more
compounds. The blocks are configurable segments of executable code. The I/A Series software
offers a variety of blocks types for specific functions such as I/O, calculations, sequence control,
and alarms.
The objects are identified by control station and the block parameter name using the syntax:
<COMPOUND>:<BLOCK>.<PARAMETER>
For additional information on I/A Series control databases, see Integrated Control Software
Concepts (B0193AW) and Integrated Control Block Descriptions (B0193AX).
Method Page
GetAllBlocks page 50
GetAllCompounds page 51
GetBlkDescription page 52
GetBlockCompounds page 53
GetBlockParams page 54
GetCompBlockAndType page 55
GetCompoundBlocks page 56
GetStationCompounds page 111
GetStations page 112
13
Data Object Access Methods

These methods establish a real-time connection with I/A Series objects. The methods allow cre-
ation of object aliases, setting change deltas, determining object ranges, and writing objects.
Method Page
AddMultipleObjects page 19
AddObject page 23
dqObjectChange page 37
EngUnits page 38
FetchObjectIndex page 41
FetchObjectName page 42
FormatData page 45
FormatDataAndTimeStamp page 46
GetObjectCount page 97
MultipleObjectWrite page 124
ObjectRange page 125
ObjectRead page 126
ObjectReadAll page 128
ObjectType page 129
ObjectWrite page 130
RemoveObject page 137
RemoveObjects page 138
File Access Methods

These methods include identifying directories and files, and reading and writing files.
Method Page
IsDir page 118
GetDirList page 58
FileRead page 43
GetFile page 59
PutFile page 132
FileStat page 44
GetServerDir page 101
GetServerBinDir page 100
GetServerInstDir page 104
MakeSystemCall page 123
14
FoxAPI Data Sets Methods

The class includes five methods that deal with the data sets created with older versions of
FoxAPI software and its predecessor AIS. These methods are designed to provide compatibility
with legacy applications. Sets are not used in later versions of FoxAPI software or with AIM*API
software. For additional information on FoxAPI sets, see the FoxAPI User’s Guide (B0193UD).
Method Page
CloseFoxAPISet page 25
GetMaxSet page 91
GetSetItemNames page 109
GetSetNames page 110
OpenFoxAPISet page 131
Historian Access Methods

The class provides a variety of methods for accessing process history as collected by the I/A Series
Historian. In addition to identifying historian instances and configurations, the methods access
sample data, write points configured for manual data entry (MDE), retrieve reduction data, and
access message groups.
Method Page
EnumServerHistorians page 40
GetHistArchiveGroups page 77
I/A Series Historian only
GetHistData page 78
GetHistGroups page 82
GetHistGrpMembers page 83
GetHistItemList page 85
GetHistOperations page 86
GetMessageData page 92
GetMessageGroup page 95
GetTimeLinearData page 113
IsFoxHistory page 119
IsInHistorian page 120
WriteMDEData page 143
15
AIM*Historian Only Access Methods

The class provides a variety of methods for accessing process history as collected by
AIM*Historian instances only. This is noted in the description for the individual methods in
Chapter 4. In addition to identifying historian instances and configurations, the methods access
sample data, write real-time points configured for manual data entry (MDE), retrieve reduction
data, and access message groups.
Method Page
ConfigureFoxHistory page 26
CreateEventMsgDef page 35
FoxHistSystem page 47
GetFoxHistGroups page 62
GetFoxHistMessageColumns page 63
GetFoxHistMessageData page 64
GetFoxHistMessageGroupKeys page 68
GetFoxHistoryConfigSessionRTPNames page 69
GetFoxHistRTPDefinition page 70
GetFoxHistRTPValues page 74
GetHistVersion page 87
GetMsgGroupAndName page 96
PutFoxHistRTPValue page 134
SearchFoxHistRTPNames page 139
WriteEventMsgData page 142
CDataElement Class Methods

The CDataElement class has fourteen methods. These are described in Chapter 5 “CDataEle-
ment Class Methods Reference”.
16
Putting the Application into Production

When you have completed testing your application on the development machine and are ready to
put it into production, port the following files to the application hosts with your application files.
apiserv32.dll Runtime dynamic link library (DLL).
MFC42.dll and MSVCRT.dll Shared MFC libraries.
errorstr.dat ASCII file that provides a descriptive string for each
error code retuned from the target servers.
an_init.cfg Client initialization file used by the application to
identify target servers and set trace options and other
parameters. See “Development Configuration” on
page 8 for a description of the file keywords and
instructions on modifying an_init.cfg.
Chapter 2 “Installation and Configuration” provides detail on initially setting up these files.
If an AIM*AT application such as AIM*Explorer is already installed on the application host
machine, be sure not to overwrite its an_init.cfg.
17
18
4. CFoxAPIServer Class Methods
Reference
This chapter provides a reference guide to the methods available with I/A Series NetAPI MFC
Class CFoxAPIServer. The methods are listed in alphabetical order.
NOTE
The descriptions included in this section refer to AIM*Historian names of compo-
nents, attributes and other elements, for example, FH_COLLECTOR_NSIZ.
AddMultipleObjects
Synopsis
BOOL AddMultipleObjects(int nument, char * name_array, int * acctyp_array,
float * delta_array, int * rsr_array, float * wdelta_array, int * index_array,
int * error_array, int * reterr);
int nument Specifies the number of objects to add.

char * name_array Specifies an array of object names, one per object,
indicating objects for which you want changes.
Each array element contains 32 characters,
left-justified with trailing blanks or nulls. To specify
that the server is to scan all objects in its database
for changes, specify a name_array element as
$ALL_AIS_OBJS.
int * acctyp_array Specifies an array of access types, one per object:
1 = read only
2 = read/write
float * delta_array Specifies an array of positive floating point deltas in
engineering units, one for each object. The server
sends a change for an object to the application
when:
♦ An object changes value by an amount greater
than or equal to the delta_array element
or
♦ An object changes status. Zero deltas result in
a change on every scan, regardless of the
object's value type. These deltas can differ
from the deltas specified by other methods.
19
B0400BJ – Rev B 4. CFoxAPIServer Class Methods Reference
int * rsr_array Specifies an array of read scan rates, one per object.
A read scan rate indicates the frequency at which
the server checks the object for changes. Read scan
rates are positive integers, in half-second incre-
ments; for example, a read scan rate of 1 means 0.5
seconds; a read scan rate of 2 means 1.0 seconds,
and so on. These read scan rates can differ from the
read scan rates specified by other methods
float * wdelta_array Specifies an array of positive floating point write
change deltas in engineering units, one per object.
The Class writes a value to the server for an object
when you call AddMultipleObjects and when:
♦ A character, integer, boolean, or long integer
object changes “write value”
or
♦ The difference between a float object's “write
value” and “read value” is greater than or equal
to the wdelta_array element for the object. A
write delta of zero (0) causes the value to be
written to the server if there is any difference.
If the acctyp_array element for the object is set to
read-only (1), the wdelta_array element is ignored.
Each wdelta_array element must be greater than or
equal to its corresponding delta_array element,
unless the wdelta_array element is zero (0).
int * index_array Returns an array of object indexes, unique per
server, one per object. If the name_array element is
$ALL_AIS_OBJS, the corresponding index_array
element is MaxEnt +1, where MaxEnt is the value
returned by the GetMaxEntries function; this index
is unusable as an object index.
int * error_array Returns an array of error codes, one per object
(see “Errors” below).
int * reterr Returns an error code (see Appendix A “Error
Messages”)
20
4. CFoxAPIServer Class Methods Reference B0400BJ – Rev B
Description
The method AddMultipleObjects adds objects to the CDX for the current server. You specify the
number of objects, and a name, access type, read delta, read scan rate, and write delta for each
object. AddMultipleObjects returns an overall error code (reterr) and an index and error code
(in error_array) for each object.
The object name $ALL_AIS_OBJS has special significance. When this name is in the CDX, the
server scans for changes in all objects by looking for a difference in an object's change count
between subsequent scans. The change counts are not incremental. The change for an object
whose data set has been closed with CloseFoxAPISet is not sent. Note that $ALL_AIS_OBJS can
co-exist with other objects in the CDX. When $ALL_AIS_OBJS is in the CDX, however, all
other objects have no effect on the scanning for changes, and change-driven writes using the CDX
are not supported.
By default, AddMultipleObjects filters out duplicate object names, returning an error code for
each duplicate. To allow duplicate objects, specify Multiples in the an_init.cfg initialization file.
See Figure 2-4, “Sample an_init.cfg File” on page 8, and Table 2-1“AISnet Keywords” on page 9.
This feature can be useful when doing performance testing.
The AddMultipleObjects method adds an object for read-only access and returns error_array
element nowriteob even though the passed acctyp_array element is read/write, if one of the
following conditions exists:
♦ The object is opened for read-only access in the database on the server.
♦ The object's set has a zero (0) write scan rate (wsr).
♦ MaxWriteObjects is exceeded.
The maximum number of objects in a CDX is maxobj, that is, the maximum number of objects
that can be open concurrently. Different servers can have different maxobj limits.
Errors
reterr error_array return

noserver - -1
noaccess - -1
dqactive - -1
badent - -1
errfil - -1
-2000 - t_errno - -1
somerr noindex 0
badacc
invdnw
invdel
AN_ALLOCATION_ERROR
dupindex
succes
somerr_w nowriteobj 0
succes succes 0
21
NOTE
When you do not configure Multiples in the an_init.cfg initialization file and you
call the AddMultipleObjects method to add multiple objects with the same name,
AddMultipleObjects uses the first instance of the object and filters out the rest;
all instances of the object in subsequent AddMultipleObjects calls are also
filtered out.
NOTE
When you configure Multiples in the an_init.cfg initialization file and call the
AddMultipleObjects method to add multiple objects with the same name,
multiple instances of an object can have different access types, deltas and read scan
rates.
Return Values
Adds objects to the CDX for the current server if successful.
False if error; look at reterr and error_array for more detail.
See Also
♦ AddObject
♦ GetObjectCount
♦ ObjectReadAll
♦ RemoveObjects
♦ RemoveObject
22
AddObject
Synopsis
BOOL AddObject(LPCTSTR szName, int * nIndex, int accessType = 1,
int rsr = 1, float fDeadband = 0.001);
LPCTSTR szName Specifies the object name for which you want
changes. Each object name contains 32 characters,
left-justified with trailing blanks or nulls.
int * nIndex Returns an object index, unique per server,
one per object. If the name_array element is
$ALL_AIS_OBJS, the corresponding index_array
element is MaxEnt +1, where MaxEnt is the value
returned by the GetMaxEntries function; this index
is unusable as an object index.
int accessType = 1 Specifies an access type, one per object:
1 = read only
2 = read/write
The default is 1.
int rsr = 1 Specifies a read scan rate, one per object. A read
scan rate indicates the frequency at which the server
checks the object for changes. Read scan rates are
positive integers, in half-second increments; for
example, a read scan rate of 1 means 0.5 seconds; a
read scan rate of 2 means 1.0 seconds, and so on.
The default is set to 1 (0.5 seconds).
This read scan rate can differ from the read scan rate
specified by other methods.
float fDeadband = 0.001 Specifies a positive Deadband value in engineering
units, one for each object. The default is set to
0.001.
The server sends a change for an object to the client
when:
♦ An object changes value by an amount greater
than or equal to the deadband element,
or
♦ An object changes status. Zero deadbands
result in a change on every scan, regardless of
the object's value type. These deadbands can
differ from the deltas specified for other
methods.
23
Description
The AddObject method establishes a link with the server for the specified data object. This
linkage is required for the following methods:
♦ FetchObjectIndex
♦ ObjectReadAll
♦ dqObjectChange
Errors
See Appendix A “Error Messages” for error codes and corresponding messages.
Return Values
True if successful.
False if error.
See Also
♦ AddMultipleObjects
♦ GetObjectCount
♦ RemoveObjects
♦ RemoveObject
♦ ObjectReadAll
♦ dqObjectChange
24
CloseFoxAPISet
Synopsis
BOOL CloseFoxAPISet(LPCTSTR set_name);
LPCTSTR set_name Specifies the set to be closed.
Description
The CloseFoxAPISet method closes a FoxAPI data set.
Errors
Return Values
True if successful.
False if error.
See Also
♦ GetMaxSet
♦ GetSetNames
♦ GetSetItemNames
♦ OpenFoxAPISet
25
ConfigureFoxHistory
AIM*Historian instances only
Synopsis
BOOL ConfigureFoxHistory(int nFhsd, LPCTSTR szAction, LPCTSTR szComponent,
LPCTSTR szComponentName, LPCTSTR szAttribute, LPTSTR szValue, int &
nIndicator);
int nFhsd Specifies the AIM*Historian Session Descriptor,

which identifies the configuration session. Specify
fhsd as NULL if this call: creates an AIM*Historian
instance, creates a configuration session, gets the
number of AIM*Historian instances, or gets the
names of all AIM*Historian instances.
LPCTSTR szAction Specifies the null-terminated, case-insensitive
action to occur. Possible actions are:
FH_ACT_CREATE to create an AIM*Historian
instance, session, or component.
FH_ACT_GETQTY to get the number of
instances of the specified component or attribute.
FH_ACT_GET to get the next component name
or attribute value.
FH_ACT_PUT to create an attribute or give a
component or attribute its initial value after being
created.
FH_ACT_MOD to modify an attribute value.
FH_ACT_DEL to delete a component or attribute.
FH_ACT_UNDEL to undelete an RTP.
LPCTSTR szComponent Specifies the null-terminated, case-insensitive
component type.
For more details, see “Additional Information on
Variables” on page 28.
LPCTSTR szComponentName Specifies the null-terminated name of the
AIM*Historian component.
See “Additional Information on Variables” on
page 28 for more details.
LPCTSTR szAttribute Specifies the null-terminated, case-insensitive
attribute type of up to FH_ATTR_NAME_NSIZ
characters, or NULL if the attribute does not apply.
Possible attributes depend on the component speci-
fied. See Appendix E, “AIM*Historian Component
Attributes” in the AIM*Historian User’s Guide
(B0193YL) for tables showing the available
attributes for each type of component, attribute
default values, and supported actions for each
attribute.
26
LPCTSTR szValue If action is FH_ACT_PUT or FH_ACT_MOD,

value specifies the attribute’s null-terminated value
as an ASCII string.
If action is FH_ACT_GET, value returns the
attribute’s value as a null-terminated ASCII string.
If action is FH_ACT_GETQTY, value returns the
number of components of the specified component
type as a null-terminated ASCII string.
int nIndicator The indicator depends on the action specified. See
“Additional Information on Variables” on page 28
for more details.
Description
The ConfigureFoxHistory method creates and configures an AIM*Historian instance.
ConfigureFoxHistory is the only API required to configure an AIM*Historian instance, although
there are other APIs that simplify and speed up retrieval of certain commonly used configuration
information; those other APIs are listed in the AIM*API User’s Guide (B0193YN) and the
AIM*Historian User’s Guide (B0193YL).
In general, configuring AIM*Historian applications consists of specifying values that fit into a
three-tier hierarchy:
♦ AIM*Historian instance
♦ Components within an AIM*Historian instance
♦ Attributes of components.
In the ConfigureFoxHistory method, elements of this hierarchy are identified as follows:
♦ To create an instance and open a configuration session to the instance, an
AIM*Historian instance is identified by its instance name.
Once created and a session is open, an AIM*Historian instance is identified by the
AIM*Historian Session Descriptor (fhsd).
♦ A component is identified by its type (component) and its name (component name).
♦ An attribute is identified by its name (attribute) and its value (value).
Most configuration actions fit into this model. However, to support certain features of
AIM*Historian software without defining many additional arguments to ConfigureFoxHistory,
some components and attributes require more than a single name or value, or use the arguments
in a unique way. These special definitions are explained in Appendix E “AIM*Historian Compo-
nent Attributes” in the AIM*Historian User’s Guide (B0193YL).
You can modify the configuration of an AIM*Historian instance while the instance is running.
You do not need to stop the instance at any time to modify the instance. However,
modifying certain attributes that govern the maximum number of items of something requires the
AIM*Historian instance to be restarted for changes to take effect.
Some components cannot be deleted. To delete an AIM*Historian instance, refer to the AIM*His-
torian User’s Guide (B0193YL).
27
The aimhistorian.h header file has two types of #defines for attribute values:
♦ Numeric:
#define FH_FLOAT 3 /* Specifies the numeric value type for a float */
Use the numeric version when checking the result of getting an attribute value
in indicator.
♦ ASCII:
#define FH_A_FLOAT “FLOAT” /*Specifies the float value type as an ASCII string */
The ASCII version is indicated by the _A in the name. Use this version when putting
in an attribute value and when checking the result of getting an attribute value in
value.
Additional Information on Variables

component Specifies the null-terminated, case-insensitive component type.
Possible components are:
FH_COMP_SESSION represents a configuration session.
All configuration actions first require the creation of a configuration
session with an AIM*Historian instance, with the following exceptions:
create an AIM*Historian instance, get the number of AIM*Historian
instances, and get the names of all AIM*Historian instances. For
exception cases, specify the AIM*Historian Session Descriptor as NULL.
When you create a session, ConfigureFoxHistory returns an
AIM*Historian session descriptor (fhsd), which you then specify in
subsequent ConfigureFoxHistory calls that apply to that session.
A configuration session can be read-only (FH_READONLY)
or read/write (FH_READWRITE). Simultaneous read-only configura-
tion sessions are available, but only one read/write configuration session is
available per instance. Starting a second read/write configuration session
to an AIM*Historian instance results in the return of an error from
ConfigureFoxHistory. An application can, however, have a read/write
session to more than one AIM*Historian instance at a time.
You can choose among three methods of ending, or deleting, a
configuration session: Commit, Save, or Cancel. These methods are
discussed in detail on page 31.
♦ FH_COMP_AIMHIST represents an AIM*Historian instance.
The FH_COMP_AIMHIST component can be thought of as containing
both “instance-level” attributes such as FH_ATTR_MAXPTS, and all of
the components in the instance; for example, all the RTPs, messages and
control groups.
28
NOTE
If the station is an I/A Series station, creating an instance automatically results in
the creation of an RTP collector station of the same name – you do not need to
create the RTP collector station. Remote I/A Series real-time collectors and
I/O Gate Data collectors must be explicitly created and configured.
You can create another instance like an existing one. See the description of
the LIKE attribute in Appendix E “AIM*Historian Component
Attributes” in the AIM*Historian User’s Guide (B0193YL).
♦ FH_COMP_POINT represents a real-time point object (RTP).
The FH_COMP_POINT component is the only component that can be
deleted, then undeleted. While deleted, an RTP:
Is not modifiable.
Is not collected.
Returns no data upon a retrieval request.
Does use up an RTP slot, but does not count against the total number of
licensed RTPs authorized for your server.
A limited number of attributes for RTPs cannot be changed under
certain circumstances.
For example, you cannot change the NAMEINCOL of an RTP once the
RTP has a value in the AIM*Historian database. These cases are noted in
Appendix E “AIM*Historian Component Attributes” in the
♦ FH_COMP_MSG represents an event message group or event
message name.
If the component is FH_COMP_MSG and you are creating, deleting or
otherwise referencing a message group, component_name is NULL,
attribute is FH_ATTR_GROUP and value is the name of the message
group.
If the component is FH_COMP_MSG, and you are creating,
deleting, or otherwise referencing a message name within a message
group, component_name is message group and message name. Specify the
message group name, a space character, and the message name, followed
by the NULL terminator.
To define the format of a message type, add message field definitions
to the message component: action is FH_ACT_PUT, component
is FH_COMP_MSG, component_name is “<message_group>
<message_name>”, attribute is FH_ATTR_DEFN, and value is as defined
in Appendix E “AIM*Historian Component Attributes” in the AIM*His-
torian User’s Guide (B0193YL). Message definition attributes
act somewhat like components, because you add, and can retrieve,
<n> definitions (rather than just one attribute value).
29
AIM*Historian software requires the first three fields of all messages to

have the following definitions:
“group = 1,Y,string,32”
“message = 2,Y,string,32”
“time = 3,Y,long,1”
A limited number of attributes for messages cannot be changed
under certain circumstances. For example, you cannot change the
FH_ATTR_UPDATE attribute of a message type once the message type
has a message in the AIM*Historian database. These cases are listed in
Appendix E “AIM*Historian Component Attributes” in the
♦ FH_COMP_CGROUP represents a control group.
♦ FH_COMP_RGROUP represents a reduction group.
♦ FH_COMP_STATION represents a collector station.
component_name Specifies the null-terminated name of the AIM*Historian component.

If component is FH_COMP_SESSION, component_name is a session
name, which is the AIM*Historian instance name of up to six characters
consisting of lowercase letter, numbers and the _ character.
If component is FH_COMP_AIMHIST, component_name is a
AIM*Historian instance name of up to six characters consisting of lower-
case letter, numbers and the _ character.
If component is FH_COMP_POINT, component_name is an RTP tag
name of up to FH_TAG_NSIZ characters.
If component is FH_COMP_MSG, component_name can be NULL or a
message group/message name pair. A message group is up to
FH_MSG_GROUP_NSIZ characters. A message name is up to
FH_MSG_NAME_NSIZ characters.
NOTE
Message group “AIM*Historian” is reserved for use by AIM*Historian programs.
If component is FH_COMP_TRACK, component_name is a track key

name of up to FH_TRACK_NAME_NSIZ characters.
If component is FH_COMP_CGROUP, component_name is a
control group name of up to FH_GROUPNAME_NSIZ characters.
If component is FH_COMP_RGROUP, component_name is a
reduction group name of up to FH_GROUPNAME_NSIZ characters.
If component is FH_COMP_STATION, component_name is a
station name of up to FH_STATION_NAME_NSIZ characters.
If the component name does not apply, component_name is a NULL. For
example, component_name does not apply when you are getting the
number of messages in an AIM*Historian instance.
30
indicator For a Create Session (action is FH_ACT_CREATE and component is

FH_COMP_SESSION), indicator:
♦ Specifies the access privilege of the configuration session
(FH_READONLY or FH_READWRITE).
♦ Returns the AIM*Historian Session Descriptor. This descriptor is
passed as fhsd in subsequent ConfigureFoxHistory calls for this
session.
For a Delete Session (action indicator):
♦ Specifies the action to take upon deleting the session:
FH_SAVE_SESSION to temporarily save the session but not
commit it to the instance.
FH_COMMIT_SESSION to make the configuration as defined
in this session take effect on the AIM*Historian instance.
FH_CANCEL_SESSION to cancel the session as if it never
occurred.
For a Get Quantity (action is FH_ACT_GETQTY) indicator:
♦ Returns the number of instances of the requested component
or attribute.
For a Get (action is FH_ACT_GET) of component names or of attributes
with multiple values; for example, a message definition
(FH_ATTR_DEFN), indicator:
♦ Specifies a 0 or -1 to indicate that ConfigureFoxHistory is to
retrieve the value of the first component or attribute or it
specifies a value other than 0 or –1 to retrieve the value of the next
component or attribute.
♦ Returns the number of subsequent Get calls necessary to get the
value of the remaining components or attributes.
For a Get (action is FH_ACT_GET) of a component attribute with a
single value, indicator:
♦ If specified as NULL, returns nothing.
♦ If specified as non-NULL, returns the numeric value of the
attribute if of type int or long.
The indicator is ignored for all other actions.
Errors
31
Return Values
True if successful.
False if error; look at reterr for more detail.
See Also
♦ GetFoxHistoryConfigSessionRTPNames
♦ GetFoxHistRTPValues
♦ GetFoxHistRTPDefinition
♦ WriteEventMsgData
32
ConnectToServer
Synopsis
int ConnectToServer(LPCTSTR APAlias, LPCTSTR szPackage = NULL);
LPCTSTR APAlias Specifies the server by the path alias defined in the
local an_init.cfg file and EnumServerAlias.
LPCTSTR szPackage = NULL Identifies an AIM*AT client application that is
making the connection. Use the default NULL.
NOTE
szPackage is reserved for Invensys use. Do not pass this variable.
Description
The ConnectToServer method adds and establishes a connection to the server defined in the
an_init.cfg file to this class. Use EnumServerAlias to get a list of AP aliases.
Errors
Return Values
True if connection successful.
False if the connection attempt failed or package access was denied.
Use GetServerInfo or GetServerStatus to determine the reason for the failure. GetServerInfo
responds with a message, while GetServerStatus responds with a code.
See Also
♦ ConnectToServerByName
♦ ReconnectToServer
♦ GetServerInfo
♦ GetServerStatus
33
ConnectToServerByName
Synopsis
Bool ConnectToServerByName(LPCTSTR NetworkName);
LPCTSTR NetworkName Specifies the server by its IP name.
Description
The ConnectToServer method adds and establishes a connection to the server defined in the
TCPIP section of the an_init.cfg file to this class.
Return Values
True if successful.
See Also
♦ ConnectToServer
♦ GetServerInfo
♦ GetServerStatus
34
CreateEventMsgDef
Synopsis
BOOL CreateEventMsgDef(LPCTSTR Historian, LPCTSTR MessageTable, CStringArray
& ColumnList, CStringArray & ColDataTypes, CDWordArray & ColLengths);
LPCTSTR Historian Specifies the six-character null-terminated

AIM*Historian instance name.
LPCTSTR MessageTable Defines the message group and message name
combination.
CStringArray ColumnList Defines the keywords, or column names, in the
message table. The first three keywords must be group,
message, and time. Other columns are user-defined.
CStringArray ColDataTypes Specifies the data type of each column.
CWordArray ColLengths Specifies the size in characters of each column.
Description
CreateEventMsgDef adds a message definition to the event message configuration in the named
AIM*Historian instance. Each message definition consists of three required keywords or column
names, and optional user-defined keywords. Refer to Chapter 2, “AIM*Historian Configuration”
and Appendix E, “AIM*Historian Component Attributes” in the AIM*Historian User’s Guide
(B0193YL) for additional information on the event message configuration.
Errors
Return Values
The message is added to the message configuration file, hist_message.cfg, if successful.
False if error.
See Also
♦ WriteEventMsgData
35
DisconnectFromServer
Synopsis
Void DisconnectFromServer(void);
Description
The DisconnectFromServer method disconnects this class instance from the current server.
Checks to see if the server connection is OK. If OK, it closes this server_id, and sets this server_id
to 0.
Errors
Return Values
No return.
! CAUTION
DisconnectFromServer causes the CDX to be lost. After reestablishing a
connection to the server with ConnectToServer, call AddMultipleObjects to re-add
objects to the CDX.
NOTE
If you close the connection to the current server, there is no current server until you
call ConnectToServer. DisconnectFromServer does not choose another server to be
the current server. Methods that expect a connected server that are called while
there is no current server return an error code.
See Also
♦ ConnectToServer
36
dqObjectChange
Synopsis
BOOL dqObjectChange(CObArray & ChangedData);
CObArray ChangedData An array of new values in the CDX.
Description
The dqObjectChange method queries the current server for changed data in the Change Data
Extension since the last query. Fills the CObArray with changed objects of CDataElement type
(see Table 5-1).
NOTE
It is the programmer’s responsibility to release (delete) the array elements
(CDataElements).
Errors
Return Values
True if successful.
False if error.
See Also
♦ ObjectRead
♦ ObjectReadAll
37
EngUnits
Synopsis
BOOL EngUnits(LPCTSTR szName, CString & szEngUnits);
LPCTSTR szName Specifies the full path name of the object on the
server.
CString szEngUnits Engineering units as configured for the parameter
in the server.
Description
The EngUnits method finds the Engineering Units for a defined object name.
Errors
Return Values
True if object found and values passed to szEngUnits.
False if Error.
See Also
♦ ObjectRange
♦ ObjectType
38
EnumServerAlias
Synopsis
BOOL EnumServerAlias(CStringList & szServerEntry);
CStringList szServerEntry Contains the list of available/configured servers.
Description
The EnumServerAlias method fills the supplied buffer with server alias names.
Errors
Return Values
True if servers found and passed to szServerEntry.
False if no servers found.
39
EnumServerHistorians
Synopsis
BOOL EnumServerHistorians(CStringList & histlist);
CStringList histlist Contains the list of available historian names.
Description
The EnumServerHistorian method fills the supplied buffer with available historian names.
Errors
Return Values
True if historian names request completed.
False if error.
See Also
♦ IsFoxHistory
♦ IsInHistorian
40
FetchObjectIndex
Synopsis
BOOL FetchObjectIndex(LPCTSTR szName, int * nIndex);
server.
int * nIndex Object index for the specified name.
Description
When an object is added, an index is created for that object. FetchObjectIndex gets the index
number for specified object name.
Errors
Return Values
True if index to object is found.
False if error.
See Also
♦ FetchObjectName
♦ Remove Objects
♦ Remove Object
♦ ObjectReadAll
41
FetchObjectName
Synopsis
BOOL FetchObjectName(CString &szName, int nIndex);
CString szName Object name for the specified index.

int nIndex Specifies the index of the object to be found.
Description
When an object is added, an index is created for that object. FetchObjectName finds the Object
Name for the specified index number.
Errors
Return Values
True if object found for specified index.
False if error.
See Also
♦ Remove Objects
♦ Remove Object
♦ ObjectReadAll
42
FileRead
Synopsis
BOOL FileRead(LPCTSTR iafile, long offset, long numchar, char * buffer,
long * nRetLen);
LPCTSTR iafile Specify the iafile name of the file on the server.
Specify the complete I/A Series path and file name.
long offset Specify the byte position in the file from which to
start reading.
long numchar Specify the number of characters to be read. This
value should be no larger than the size of the buffer.
char * buffer The destination buffer.
long * nRetLen How much of the buffer is used.
Description
The FileRead method retrieves data about the specified file.
Errors
Return Values
The contents of the buffer and how much of the buffer is used if successful.
False if error.
See Also
♦ GetFile
43
FileStat
Synopsis
BOOL FileStat(LPCTSTR szIAFile, long & filesize, CTime & modtime,
CTime & createtime);
LPCTSTR szIAFile Specifies iafile name on the server. iafile is the

complete I/A Series path and file name.
long filesize File size in bytes.
CTime modtime Time stamp of the last file modification.
CTime createtime Time stamp of the file creation.
Description
The FileStat method returns the file size, modification time, and the creation time for the
specified file.
Errors
Return Values
Returns the file size, modification time, and the creation time if successful.
False if error.
See Also
♦ GetDirList
♦ IsDir
44
FormatData
Synopsis
BOOL FormatData(LPCTSTR szName, Cstring & szItemValue, long value,
int status);
server.
CString szItemValue Returns the value and status of the specified object
separated by a tab character.
long value Current object value.
int status Object status word. See Appendix B “Object Status
and Value Types” for a definition of the I/A Series
status word and AIM*Historian status word.
Description
The FormatData method formats the specified object’s value and status into a string. The value
and status are separated by a tab character. The format of the value is determined by the data type
found in the status. For I/A Series string data type, the complete string is obtained. Refer to
Appendix B “Object Status and Value Types”.
Errors
Return Values
True if successful.
False if error.
45
FormatDataAndTimeStamp
Synopsis
BOOL FormatDataAndTimeStamp(LPCTSTR szName, CString & szItemName, long value,
int status, time_t * ts_utc, int * ts_msec, CString & szTimeStamp, int *
nSource);
server.
long value Current object value.
int status Object status word. See Appendix B “Object Status
and Value Types” for a definition of the I/A Series
status word and AIM*Historian status word.
time_t * ts_utc UTC time associated with object value in seconds,
from CDataElement.
int * ts_msec Millisecond associated with object value, from
CDataElement.
CString szTimeStamp Returns the time stamp, adjusted for local time, in
the form MM/DD/YY_hh:mm:ss.ddd where:
MM = month
DD = day
YY = year
hh = hour
mm = minute
ss = second
ddd = millisecond.
int * nSource Source of the time stamp:
1 = from the I/A Series system
2 = from the API
3 = from the client application.
Description
The FormatDataAndTimeStamp method formats the specified object’s value and status into one
string and the object’s time stamp into another string. The format of the value is determined by
the data type found in the status. For I/A Series string data type, the complete string is obtained.
Refer to Appendix B “Object Status and Value Types”.
Errors
Return Values
True if successful.
False if error.
46
FoxHistSystem
Synopsis
BOOL FoxHistSystem(LPCTSTR szAction, LPCTSTR szAttribute,
CString &sValue, UINT maxLen = 512);
Description
For Invensys use only.
Errors
47
GetAccessInfo
Synopsis
WORD GetAccessInfo(void);
Description
The GetAccessInfo method reads the access privileges configured in the server API for the current
user. User access privileges are configured with the API Admin utility for various AIM*AT
packages such as AIM*Explorer™ software and AIM*DataLink software. Table 4-1 lists the
security access levels that are defined in the Networked FoxAPI and AIM*API configurations for
various packages. If the current user is connected with no package, then user security access level
is overridden and access level is 16.
Table 4-1. Server Access Levels
Code Description
0 NO_ACCESS Access denied
1 READ_ACCESS User can only read objects
2 WOBJ_ACCESS User can read write objects
4 WFILE_ACCESS User can write files.
8 OPEN_ACCESS User can open FoxAPI data sets.
16 SYSTEM_ACCESS User has full privileges.
Errors
Return Values
Access code is successful.
False if error.
48
GetAliasPath
Synopsis
CString GetAliasPath(void);
Description
The GetAliasPath returns the directory path of the currently connected server. This path is used as
a root entry point for file access (rfs_path). (Generally, the top level of server.)
Errors
Return Values
A string with the Path Alias directory entry point if successful.
False if error.
49
GetAllBlocks
Synopsis
BOOL GetAllBlocks(CStringList * slStations, CStringList & slBlocks,
BOOL bType = FALSE);
CStringList * slStations A list of the I/A Series letterbugs of control stations.

CStringList slBlocks Block names or block types depending upon the
specified bType.
BOOL bType = FALSE If bType is TRUE, the block types are added to the
list. If bType is FALSE, the block names are added
to the list. The default is FALSE.
Description
The GetAllBlocks method fills the supplied CStringList with all block names or block types in the
specified stations depending upon the bType specified.
Errors
Return Values
Block names or block types if successful.
False if error.
See Also
♦ GetAllCompounds
♦ GetBlkDescription
♦ GetBlockCompounds
♦ GetBlockParams
♦ GetCompBlockAndType
♦ GetCompoundBlocks
50
GetAllCompounds
Synopsis
BOOL GetAllCompounds(CStringList * slStations, CStringList & slCompounds);
CStringList * slStations A list of the I/A Series letterbugs of control stations.

CStringList slCompounds Compound names.
Description
The GetAllCompounds method fills the specified CStringList with a list of all of the
compound names in the specified I/A Series stations.
Errors
Return Values
Compound names if successful.
False if error.
See Also
♦ GetAllBlocks
♦ GetBlockParams
♦ GetStationCompounds
51
GetBlkDescription
Synopsis
BOOL GetBlkDescription(LPCTSTR ianame, Cstring & szDescrp);
LPCTSTR ianame Specifies the block by station compound and block

name.
Cstring szDescrp Block description string.
Description
The GetBlkDescription method gets the description of the specified block.
Errors
Return Values
Description of specified block if successful.
False if error.
See Also
♦ GetAllBlocks
♦ GetAllCompounds
♦ GetBlockParams
52
GetBlockCompounds
Synopsis
BOOL GetBlockCompounds(LPCTSTR szBlock, CStringList * slStations,
CStringList & slCompounds);
LPCTSTR szBlock Specifies a block name.

CStringList * slStations Returns a list of the I/A Series letterbugs of control
stations.
CStringList slCompounds Returns a list of compound names.
Description
The GetBlockCompounds method retrieves all the compounds and stations that hold the
specified block.
Errors
Return Values
Compounds and stations for the specified block if successful.
False if error.
See Also
♦ GetAllBlocks
♦ GetAllCompounds
♦ GetBlockParams
53
GetBlockParams
Synopsis
BOOL GetBlockParams(LPCTSTR szBlockType, CStringList & slParams);
LPCTSTR szBlockType Specifies the type of block for which you want to
retrieve information.
CStringList slParams Returns a list of parameters.
Description
The GetBlockParams method retrieves a list of parameters for a specified block type.
Errors
Return Values
A list of parameters for specified block type if successful.
False if error.
See Also
♦ GetAllBlocks
♦ GetAllCompounds
54
GetCompBlockAndType
Synopsis
BOOL GetCompBlockAndType(LPCTSTR szCompound, CStringList & slNameType);
LPCTSTR szCompound Specifies the compound name.

CStringList slNameType Returns the block name and type of each block in
the compound.
Description
The GetCompBlockAndType method retrieves the name and type of each block in the specified
compound. The block name and type are separated by a tab character.
Errors
Return Values
A list containing the name and type of each block, separated by a tab character, if successful.
False if error.
See Also
♦ GetAllBlocks
♦ GetAllCompounds
♦ GetBlockParams
55
GetCompoundBlocks
Synopsis
BOOL GetCompoundBlocks(LPCTSTR szCompound, CStringList & slBlocks,
BOOL bType = FALSE);
LPCTSTR szCompound Specifies the compound name.

CStringList slBlocks Block name or block type depending upon the
specified bType.
BOOL bType = FALSE If bType is TRUE, the block types are added to the
list. If bType is FALSE, the block names are added
to the list. The default is FALSE.
Description
The GetCompoundBlocks method retrieves a list of block name or block type depending upon
the bType specified, for the specified compound.
Errors
Return Values
A list of block names or block types if successful.
False if error.
See Also
♦ GetAllBlocks
♦ GetAllCompounds
♦ GetBlockParams
56
GetConfigFile
Synopsis
CString GetConfigFile(void);
Description
The CString GetConfigFile method returns the contents of the Registry setting
HKEY_LOCAL_MACHINE\Software\SimSci\Aim\Settings\an_init =
<drive:>\<path>\an_init.cfg.
Refer to “Development Configuration” on page 8 for a description of the an_init.cfg file.
Errors
Return Values
Contents of the Registry setting if successful.
False if error.
57
GetDirList
Synopsis
BOOL GetDirList(LPCTSTR szPath, CStringList & slDirList,
CStringList & slIsDir);
LPCTSTR szPath Specify the path for which you want to list directory
information.
CStringList slDirList Returns the directory list.
CStringList slIsDir Checks to see if entry found is a directory.
Description
The GetDirList method retrieves the directory list information for the specified path.
Errors
Return Values
Single-level directory list if successful.
False if error.
See Also
♦ IsDir
♦ FileStat
58
GetFile
Synopsis
BOOL GetFile(LPCTSTR szIAFile, CString & szFileName, BOOL bAscii,
UINT nSkip = 0);
LPCTSTR szIAFile Specify the full path and file name of the file on
the server.
CString szFileName The application host full path and file name, or if
not specified, a created temporary file name. This
method overwrites any file with the same path and
name on the application host.
BOOL bAscii Set to TRUE to indicate the file should be
converted from UNIX® ASCII to DOS ASCII.
UINT nSkip = 0 Specify number of bytes to skip when copying file.
The default value is 0.
Description
The GetFile method copies a file on the connected server to a named file, or temporary file if not
named, on the application host. This method overwrites any file with the same path and name on
the application host.
Errors
#define Note Description

succes Success
hoperr 2 Host file cannot be opened
hrderr 2 Host file cannot be read
iclerr 2 I/A Series file cannot be closed
ioperr 2 I/A Series file cannot be opened
nonull 3 No null-terminator found
ucfgrn 1 Unconfigured remote file system logical name
irmerr 2 Unable to mount remote file system
hclerr 2 Unable to close file in application platform
59
Error Code Notes

1. Call-level programming or configuration error; fix and try again.
2. File access error; fix and try again.
3. Internal error with message.
NOTE
You can access UNIX “regular” files in an I/A Series AP, but not directory, special,
or FIFO files.
NOTE
To restrict access through DNBI gateways to an AP with UIDs and GIDs, you need
to modify the dsamap file in the AP. The dsamap file is: /etc/dsamap for AP10 and
AP20; /etc/fox/dsamap for 50 Series systems.
Return Values
A copy of the file is created on the application host if successful.
False if error.
See Also
♦ PutFile
♦ FileRead
60
GetFoxAPIVersion
Synopsis
CString GetFoxAPIVersion(void);
Description
The GetFoxAPIVersion method retrieves the version of the current API server.
Errors
Return Values
The API server version if successful.
False if error.
See Also
♦ GetIAVersion
♦ IsOffPlatform
61
GetFoxHistGroups
Synopsis
BOOL GetFoxHistGroups(LPCTSTR Historian, int nGrpType,
CStringList & GroupList, CStringList & GroupDescrp);

int nGrpType An integer that identifies a group type. Here, 11 is
the only valid input.
CStringList GroupList Returns the group and message names in the form
“<group>:<message>”.
CStringList GroupDescrp Returns the group descriptions, usually null
strings (““).
Description
The GetFoxHistGroups method retrieves the Group type, list and description for all groups
included in the specified AIM*Historian instance. The only valid input for group type is 11
(Historian Messages, Optional Errors).
Errors
Return Values
Group type, list and description if successful.
False if error.
See Also
♦ GetMsgGroupAndName
62
GetFoxHistMessageColumns
Synopsis
BOOL GetFoxHistMessageColumns(LPCTSTR Historian, LPCTSTR MessageTable,
CStringArray & ColumnList, CStringArray & ColDescList, CDWordArray &
ColDataTypes, CDWordArray & ColPrecisions);

LPCTSTR MessageTable Specify the message group and message name
combination.
CStringArray ColumnList Returns the keywords, or column names, in the
message table.
CStringArray ColDescList Returns the data type of each column.
CDWordArray ColDataTypes Returns the size in characters of each column.
CDWordArray ColPrecisions Returns the width of the column or size of the array.
Description
The GetFoxHistMessageColumns method retrieves the configurations of a message group for the
specified AIM*Historian instance.
Refer to Chapter 2, “AIM*Historian Configuration” and Appendix E, “AIM*Historian
Component Attributes” in the AIM*Historian User’s Guide (B0193YL) to review the elements of a
message configuration.
Errors
Return Values
Four arrays for the specified instance if successful.
False if error.
See Also
♦ GetFoxHistMessageGroupKeys
63
GetFoxHistMessageData
There are two methods provided to retrieve AIM*Historian Message Data. The first method
listed provides filtering based upon a time span using start and end times, and a filter on the mes-
sage string for the specified instance. The second method listed also provides filtering based upon
a time span and adds filtering on message group and message name, as well as complex filtering
using an SQL-like string.
Method 1
Synopsis
BOOL GetFoxHistMessageData(LPCTSTR Historian, time_t start, time_t finish,
LPCTSTR filter, char **msg_hdr, char **msg_body, int *more, BOOL new_request);

time_t start Specifies the lower limit of the requested time span
in UTC or I/A Series time, per the IATIME
attribute of the AIM*Historian instance. If 0, mes-
sage retrieval begins at the start of the message data-
base.
time_t finish Specifies the upper limit of the requested time span,
attribute of the AIM*Historian instance. If 0, mes-
sage retrieval ends at the end of the message data-
base.
LPCTSTR filter Specifies a null-terminated message filter. To get all
messages in the specified time span, specify filter as
* or NULL. To get messages in the time span for a
specific message group/message name, specify filter
as <msg_group>:<msg_name>.
char ** msg_hdr Returns the message header. The header is defined
in the aimhistorian.h file and is shown in Descrip-
tion for reference.
char ** msg_body Returns the message body. The format is defined by
the event message configuration.
64
int * more Specifies whether or not this is a continuation of a

previous GetFoxHistMessageData call:
0 = first time
1 = continuation of a previous
GetFoxHistMessageData call
Returns whether or not there are more elements
to get:
0 = no more
1 = more.
BOOL new_request TRUE allocates memory for msg_hdr and
msg_body.
Method 2
BOOL GetFoxHistMessageData(LPCTSTR Historian, time_t start, time_t finish,
LPCTSTR mgroup, LPCTSTR mname, char **header, char **body, int *more, BOOL
new_request, LPCTSTR filterCriteria, CStringArray & mFields);

time_t Start Specifies the lower limit of the requested time span
attribute of the AIM*Historian instance. If 0,
message retrieval begins at the start of the message
database.
attribute of the AIM*Historian instance. If 0,
message retrieval ends at the end of the message
database.
LPCTSTR mgroup Specifies the message group.
LPCTSTR mname Specifies the message name.
char ** header Returns the message header. The header is
defined as USR_FH_MSG_DBS_REC in the
aimhistorian.h include file.
char ** body Returns the message body. The format is defined by
the event message configuration.
int * more Specifies whether or not this is a continuation of a
previous GetFoxHistMessageData call:
0 = first time
GetFoxHistMessageData call.
to get:
0 = no more
1 = more.
65
BOOL new_request Specifies whether this a new request or not.

The first time GetFoxHistMessageData() call is
made, new_request should be set to TRUE in order
for memory to be allocated.
In subsequent GetFoxHistMessageData() calls,
new_request should be set to FALSE.
LPCTSTR filterCriteria Specifies a null-terminated filter criteria.
Filter criteria can specify up to four filter condi-
tions, separated by logical operations.
For example:
(BLOCK_NAME=SINE) AND (STATION=
P7AW01) OR (PRIORITY<5)
CStringArray mFields A CStringArray of null-terminated Message fields to
be returned.
Description
The GetFoxHistMessageData method retrieves event messages for a specified time frame. Use of
either method depends upon the complexity of the filtering you need to fulfill the requirements.
NOTE
The caller must delete the memory returned through the **header and **body
pointer arguments to avoid a memory leak.
Message Header Structure

The following excerpt from the AIM*Historian header file (aimhistroian.h) shows the structure of
the message header.
typedef struct
int record_size; /* Size of the message */
int lrc; /* Checksum */
int number; /* Message Number */
time_t seconds; /* Seconds in UTC or I/A Series time*/
char Msg_Group[FH_MSG_GROUP_LEN+1]; /* Message Group */
char Msg_Name[FH_MSG_NAME_LEN+1]; /* Message Name */
int nr_of_keys; /* Number of keys in the message */
int msg_offset; /* Offset to the message body */
int key_offset[1] /* Array of nr_of_keys holding offset to
each field in the message */
} USR_FH_MSG_DBS_REC;
66
Errors
Return Values
Event messages if successful.
False if error.
See Also
♦ GetMessageData
67
GetFoxHistMessageGroupKeys
Synopsis
BOOL GetFoxHistMessageGroupKeys(LPCTSTR Historian, LPCTSTR MessageTable,
CDWordArray & MessageTypes, CStringArray & MessageKeys, CString & KeyTypes,
CDWordArray & KeyNumbers, CDWordArray & KeyLengths);

LPCTSTR MessageTable Specify the message group and message name
combination.
CDWordArray MessageTypes Internal message number. For this message, every
entry will be the same.
CStringArray MessageKeys Keyname defined in the message.
CString KeyTypes Keytype for the message, such as float and int.
CDWordArray KeyNumbers The field number within the message.
CDWordArray KeyLengths Number of elements in key. If string, the maximum
key string is 500.
Description
The GetFoxHistMessageGroupKeys method retrieves the information for a specified Historian’s
message using the message group and name combination (<messagegroup>_<messagename>).
Errors
Return Values
True if successful.
False if error.
See Also
♦ GetFoxHistMessageColumns
68
GetFoxHistConfigSessionRTPNames
Synopsis
BOOL GetFoxHistConfigSessionRTPNames(LPCTSTR szHistorian, int nMaxnum,
int & nMore, CDWordArray & IndexArray, CStringArray & TagArray);
LPCTSTR szHistorian Specifies the six-character null-terminated

int nMaxnum Specify how many names to retrieve in a single call.
int nMore Specifies whether or not this is a continuation of a
previous GetFoxHistoryConfigSessionRTPNames
call:
0 = first time
GetFoxHistoryConfigSessionRTPNames call.
to get:
0 = no more
1 = more
CDWordArray IndexArray Returns the RTP index numbers from the session.
CStringArray TagArray Returns the RTP names from the session.
Description
The GetFoxHistoryConfigSessionRTPNames method retrieves RTP names specified in the latest
AIM*Historian configuration session. It allows you to view RTP names before configuration is
committed.
Errors
Return Values
The Index and Tag arrays for the specified RTP names if successful.
False if error.
69
GetFoxHistRTPDefinition
Synopsis
BOOL GetFoxHistRTPDefinition(LPCTSTR szHistorian, LPCTSTR szRTPName,
CRtpDef & RTPDefinition);

LPCTSTR szRTPName RTP name tag (not the name in the Collector
attribute).
CRtpDef RTPDefinition Configuration of the RTP (see “Description”
below).
Description
The GetFoxHistRTPDefinition method retrieves the configuration of an AIM*Historian
Real-time Point (RTP) object. For detailed information on RTP configuration see Appendix E,
“AIM*Historian Component Attributes” in the AIM*Historian User’s Guide (B0193YL). The
RTP definition includes the following elements:
CString NameInSatellite The null-terminated name for the RTP as defined

in the collector, of up to
FH_NAME_IN_COLLECTOR_NSIZ characters.
CString Satellite The null-terminated name of the collector, of up to
FH_COLLECTOR_NSIZ characters.
CString EngUnits The null-terminated engineering units of up to
FH_ENG_UNIT_NSIZ characters.
long Index The index of the RTP.
long ValSize The size of the value in bytes.
long NumElements The number of elements in the value. For non-array
value types, Num_Elements is 1.
CString Descriptor The null-terminated descriptor for the RTP, of up
to FH_DESCRIPTOR_NSIZ characters.
long Seconds UTC or I/A Series time per IAtime attribute in
AIM*Historian header.
int FastRate The FAST/SLOW collection state of the RTP:
1 = fast
0 = slow
70
int ScanRateUnits The fast scan rate units. Scan rate units are defined
in aimhistorian.h, and are included here for
reference:
#define FH_SCAN_UNIT_MILLI 1
/* milliseconds */
#define FH_SCAN_UNIT_SEC 2 /* seconds */
#define FH_SCAN_UNIT_MIN 3 /* minutes */
#define FH_SCAN_UNIT_HOUR 4 /* hours */
#define FH_SCAN_UNIT_DAY 5 /* days */
int ScanRate The fast scan rate, the frequency at which the
collector checks the RTP for a change, when the
FastRate is 1.
int SlowScanUnits The slow scan rate units. Scan rate units are defined
in aimhistorian.h, and are also included above in
the description of ScanRateUnits.
int SlowScanRate The slow scan rate, the frequency at which the
collector checks the RTP for a change, when the
FastRate is 0.
int Method The collection method, defined in aimhistorian.h
and included here for reference:
#define FH_HTYPE_MDE 1 /* Manual Data
Entry */
#define FH_HTYPE_CONNECTED 2
/* Connected, change-driven access */
#define FH_HTYPE_GETVAL 3 /* Unconnected,
on demand access */
int OnOff The ON/OFF state of the RTP:
1 = on
0 = off
int Bad The BAD/OK state of the RTP:
1 = bad
0 = OK
int Type The value type of the RTP, defined in
aimhistorian.h and included at the end of this
listing for reference.
int ValueInserted The UTC or I/A Series time stamp, per the
IATIME attribute of the AIM*Historian instance,
of the first value in the AIM*Historian database for
this RTP; 0 if no values yet.
71
float Delta The positive floating point delta in engineering

units of the RTP. When an RTP changes value by
an amount greater than or equal to its delta, its
AIM*Historian collector sends a change to the
AIM*Historian server. Also, zero change deltas
result in a change on every scan, regardless of the
RTP’s value type. The collector treats negative
change deltas as if they were positive.
float LowRange The low range value, for trending, in engineering
units.
float HighRange The high range value, for trending, in engineering
units.
historian.h RTP value types

/* RTP Value Types */ /* Size, in bytes */
#define FH_CHAR 1 /* 4 */
#define FH_INTEGER 2 /* 4 */
#define FH_FLOAT 3 /* 4 */
#define FH_BOOLEAN 5 /* 4 */
#define FH_LONG 6 /* 4 */
#define FH_SHORT 8 /* 4 */
#define FH_INT_PACKED 9 /* 4 */
#define FH_LONG_PACKED 10 /* 4 */
/* Size, in bytes per element */
#define FH_CHAR_ARRAY 21 /* 1 */
#define FH_SHORT_ARRAY 22 /* 2 */
#define FH_INTEGER_ARRAY 23 /* 4 */
#define FH_LONG_ARRAY 24 /* 4 */
#define FH_FLOAT_ARRAY 25 /* 4 */
#define FH_DOUBLE_ARRAY 26 /* 8 */
#define FH_UCHAR_ARRAY 27 /* 1 */
#define FH_USHORT_ARRAY 28 /* 2 */
#define FH_UINT_ARRAY 29 /* 4 */
#define FH_ULONG_ARRAY 30 /* 4 */
#define FH_STRING 31 /* Size is defined by the user
and must account for the largest
possible string value including
the null terminator*/
72
Errors
Return Values
RTP configuration for the specified object if successful.
False if error.
73
GetFoxHistRTPValues
Synopsis
BOOL GetFoxHistRTPValues(LPCTSTR szHistorian, long lPointIndex, LPCTSTR
szPointName, time_t tStartTime, time_t tEndTime, int nDirection, long
lNumPoints, long lMaxNum, int & nMore, long & lActNum, void * pValueArray,
time_t * pSecArray, int * pMsecArray, int * pStatusArray, long * pQualArray);

long lPointIndex Specifies the RTP index, or 0 if the RTP name is to
be used to get the RTP index.
LPCTSTR szPointName Specifies a null-terminated RTP name of up to
FH_TAG_NSIZ characters, or NULL. RTP is
ignored if a valid index of greater than 0 is specified.
time_t tStartTime Specifies the lower limit of the requested time span,
attribute of the AIM*Historian instance. Zero (0)
specifies the start of the RTP database.
time_t tEndTime Specifies the upper limit of the requested time span,
attribute of the AIM*Historian instance. Zero (0)
specifies the end of the RTP database.
int nDirection Specifies the direction of returning the values:
0 = ascending order
1 = descending order
long lNumPoints Specifies the number of data records in the range to
be returned. If zero, all data in the
tStartTime/tEndTime range will be returned.
long lMaxNum Specifies the maximum number of elements the
calling function can handle.
previous GetFoxHistRTPValues call:
0 = first time
GetFoxHistRTPValues call
to get:
0 = no more
1 = more
74
long lActNum Specifies the actual number of elements returned for

this call.
void* pValueArray Returns an array of values.
You must declare or cast the argument to a
double * to satisfy the compiler, but the type for
interpreting the values depends on how the RTP
was configured. See one of the following:
♦ Type (value type) argument returned by
GetFoxHistRTPDefinition
♦ FH_ATTR_TYPE attribute of the
FH_COMP_POINT configuration
component
♦ status_array element returned by this call.
Refer to Appendix E “AIM*Historian Component
Attributes” in the AIM*Historian User’s Guide
(B0193YL) for more information.
The number of bytes per value_array element also
depends on how the RTP was configured. See the
ValSize argument of GetFoxHistRTPDefinition or
the FH_ATTR_SIZE attribute of the
FH_COMP_POINT configuration component.
time_t * pSecArray Returns an array of UTC or I/A Series times, per
the IATIME attribute of the AIM*Historian
instance.
int * pMsecArray Returns an array of milliseconds within the
corresponding msecs_array element in which the
values were collected.
int * pStatusArray Returns an array of I/A Series formatted status. See
Appendix B “Object Status and Value Types”.
long * pQualArray Returns an array of user-defined quality values.
Description
The GetFoxHistRTPValues method retrieves collected values for the specified RTP within a spec-
ified time span.
Errors
Return Values
An array of values for the specified RTP and time span if successful.
False if error.
75
See Also
♦ IsFoxHistory
♦ GetHistData
♦ GetTimeLinearData
♦ IsInHistorian
♦ PutFoxHistRTPValue
76
GetHistArchiveGroups
I/A Series Historian only
Synopsis
BOOL GetHistArchiveGroups(int nGrpType, CStringList & GroupList);
int nGrpType Specify an integer that identifies SAMPLE and

ARCHIVE access.
CStringList GroupList Historian Sample and/or Archive Group names
depending upon the nGrpType.
Description
The GetHistArchiveGroups method fills the GroupList with Historian Sample and/or Archive
Group names.
Errors
Return Values
A list of sample or archive group names if successful.
False if error.
77
GetHistData
Three methods have been created to retrieve history data. The first method listed can be used for
AIM*Historian instances only. The other two methods can be used for all Historian instances. The
first method returns only numeric data, that is, the milliseconds and quality data for the specified
instance. The second and third methods listed can be used for all historian types. The second
method also returns only numeric data, that is, the milliseconds and status data for the specified
instance. The third method listed is the same as the second except that for an AIM*Historian
instance it can return string values using the 500 values maximum call.
Method 1
Synopsis
(This first method is used for AIM*Historian instances only.)
BOOL GetHistData(LPCTSTR Historian, LPCTSTR arch_name, LPCTSTR grp_name,
LPCTSTR col_name, LPCTSTR pntid, time_t start, time_t finish, int flags, int
numpts, int maxnum, int *more, int *actnum, long * timebuffer, int
*msecsbuffer, int * statusbuffer, long *qualbuffer, float * valuebuffer);

LPCTSTR arch_name Specifies the Archive name to retrieve from, or
NULL.
LPCTSTR grp_name Specifies the historian group for REDUCTION
and MDE data.
LPCTSTR col_name Specifies the REDUCTION operation name or
$SAMPLE, $MDE.
LPCTSTR pntid Specifies the collection point name.
time_t start Specifies the lower limit of the requested time span,
in I/A UTC time for retrieval. Zero (0) specifies the
start of the database.
end of the database.
int flags When 0 indicates data retrieval in an ascending
time manner, and descending when 1.
Specifies the direction of returning the values:
0 = ascending order
int numpts Specifies the number of data records in the range to
78
int maxnum Specifies the maximum number of array elements

the caller can receive in this call. maxnum can be
any positive integer. If maxnum is greater than
MaxEnt in the initialization file, an_init.cfg, this
call returns information for up to MaxEnt elements.
int * more Returns whether or not there are more elements
to get:
0 = no more
1 = more
int * actnum Specifies the actual number of elements returned for
this call.
long * timebuffer Data buffer to store the time stamp. Represented as
yyyy/mm/dd/hh/mn/sc.
int * msecsbuffer Data buffer to store the milliseconds.
int * statusbuffer Data buffer to store the retrieved status code.
long * qualbuffer Data buffer to store the user-defined quality
indicator.
float * valuebuffer Data buffer to store the value.
Method 2
(This method applies to I/A Series and AIM*Historian instances.)
LPCTSTR col_name, LPCTSTR pntid, time_t start, time_t finish, int flags,
int numpts, int maxnum, int *more, int *actnum, long * timebuffer,
int * statusbuffer, float * valuebuffer);

NULL.
and MDE data.
$SAMPLE, $MDE.
79
int flags When 0, indicates data retrieval in an ascending

Specifies the direction of returning the values:
0 = ascending order
int numpts Specifies the number of data records in the range to
int maxnum Specifies the maximum number of array elements
int* more Returns whether or not there are more elements
to get:
0 = no more
1 = more
int* actnum Specifies the actual number of elements returned for
this call.
long* timebuffer Data buffer to store the time stamp. Represented as
yyyy/mm/dd/hh/mn/sc.
int* statusbuffer Data buffer to store the retrieved status code.
float* valuebuffer Data buffer to store the value.
Method 3
(This method applies to I/A Series and AIM*Historian instances.)
LPCTSTR col_name, LPCTSTR pntid, time_t start, time_t finish, int flags,
int *num_entries, long * timebuffer, int * statusbuffer, float * valuebuffer,
int *more);

NULL.
and MDE data.
$SAMPLE, $MDE.
80
int flags When 0 indicates data retrieval in an ascending
int * num_entries Specifies the maximum number of array elements
long * timebuffer Data buffer to store the time stamp. Represented in
date, hour, minute, and second.
int * statusbuffer Data buffer to store the retrieved status code.
float * valuebuffer Data buffer to store the value.
to get:
0 = no more
1 = more
Description
The GetHistData method retrieves historical data from the specified Historian Sample,
Reduction or Manual Data Entry database.
Errors
Return Values
Historical data if successful.
False if error.
See Also
♦ IsInHistorian
81
GetHistGroups
Synopsis
BOOL GetHistGroups(LPCTSTR Historian, int nGrpType, CStringList & GroupList,
CStringList & GroupDescrp);

I/A Series Historian instance name.
int nGrpType Specifies which database you want to collect
information from.
CStringList GroupList Point list for the specified database.
CStringList GroupDescrp Point descriptions for the specified database.
Description
The GetHistGroups method fills the GroupList with the specified I/A Series Historian’s Collec-
tion point list and the GroupDescrp list with the point description for the specified database. The
nGrpType parameter selects the database (Sample, Archive, Reduction, Message, ManualData).
Group
Types
1 Sample Raw samples (RTPs)
2 Reduction Reduced data files
4 Archive Archive files
5 Message Collected messages
8 MDE Manual Data Entry
Errors
Return Values
The point list and description if successful.
False if error.
82
GetHistGrpMembers
There are two methods to retrieve History Group Members. The first method retrieves the
member list and description from the specified database, the second method also retrieves
member units.
Method 1
Synopsis
BOOL GetHistGrpMembers(LPCTSTR Historian, LPCTSTR Group, int nGrpType,
CStringList & MemberList, CStringList & MemberDescrp);

LPCTSTR Group Specifies the group name.
information from.
CStringList MemberList List of member names.
CStringList MemberDescrp List of member descriptions.
Method 2
BOOL GetHistGrpMembers(LPCTSTR Historian, LPCTSTR Group, int nGrpType,
CStringList & MemberList, CStringList & MemberDescrp, CStringList &
MemberUnits);

LPCTSTR Group Specifies the group name.
information from.
CStringList MemberList List of member names.
CStringList MemberDescrp List of member descriptions.
CStringList MemberUnits List of member units.
Description
The GetHistGrpMembers method retrieves the I/A Series Historian Group Member list informa-
tion for the nGrpType database. For the Sample database, only the MemberList is returned. For
the Reduction database, the MemberList and MemberDescrp list are returned. For the MDE
database, the MemberList and MemberDescrp list are returned.
When the second call interface form is used, the MemberUnits list is returned.
83
Errors
Return Values
The member list and description, and units if second call is used, if successful.
False if error.
84
GetHistItemList
Synopsis
BOOL GetHistItemList(LPCTSTR szHistorian, CStringList & szCollectionList);
LPCTSTR szHistorian Specifies the six-character null-terminated historian

instance name.
CStringList szCollectionList List of all collection points.
Description
The GetHistItemList method retrieves the sample collection from the specified I/A Series
Historian or a list of RTP names in the named AIM*Historian instance.
Errors
Return Values
List of collection points for the specified historian instance if successful.
False if error.
See Also
♦ SearchFoxHistRTPNames
85
GetHistOperations
Synopsis
BOOL GetHistOperations(LPCTSTR Historian, LPCTSTR szGroup, CWordArray &
nOprList, CStringList & OprDescrp);
LPCTSTR Historian Specifies the six-character null-terminated historian

instance name.
LPCTSTR szGroup Historian Reduction group name.
CWordArray nOprList The operation type code (See Table 4-2).
CStringList OprDescrp The operation description.
Description
The GetHistOperations method retrieves the specified Historian Reduction Group
Operations list information.
The nOprList array contains the operation type code, which can be any of those listed in
Table 4-2.
Table 4-2. Configurable Reduction Group Operations
Code Name Description

0 NULL_OP
1 USER_OP User defined operation.
2 SUM_OP The value represents the sum of the samples.
3 AVG_OP The value represents the average of the samples.
4 MAX_OP The value is the maximum value.
5 MIN_OP The value is the minimum value.
6 STDV_OP The reduction group computes the standard deviation.
7 KURT_OP The kurtosis.
8 HIST_OP The histogram.
Errors
Return Values
A list of operation descriptions for the specified reduction group if successful.
False if error.
86
GetHistVersion
Synopsis
BOOL GetHistVersion(LPCTSTR Historian, CString & HistVersion);

CString HistVersion The Historian software version.
Description
The GetHistVersion method returns the Historian software version.
Errors
Return Values
The software version if successful.
False if error.
87
GetHostID
Synopsis
long GetHostID(void);
Description
The GetHostID method returns the id of the host machine.
Errors
Return Values
HostID if successful.
False if error.
88
GetIAVersion
Synopsis
CString GetIAVersion(void);
Description
The GetIAVersion method determines if the station is an I/A Series station and if so, returns the
station’s I/A Series version string.
Errors
Return Values
The I/A Series version string if successful.
False if error.
See Also
♦ GetFoxAPIVersion
89
GetMaxEntries
Synopsis
int GetMaxEntries(void);
Description
The GetMaxEntries method gets the maximum array size (MaxEnt in the an_init.cfg) that can be
used with the methods, such as GetHistData and AddMultipleObjects, that return object arrays.
Errors
Return Values
An integer, typically set to 500, if successful.
False if error.
See Also
♦ GetHistData
90
GetMaxSet
Synopsis
int GetMaxSet(void);
Description
The GetMaxSet method gets the maximum number of data sets that can be opened
concurrently by the connected server. The limit is specified in the FoxAPI or AIM*API
configuration. This limit can be useful to dynamically allocate arrays.
Errors
Return Values
Maximum number of sets that can be opened concurrently.
False if error.
See Also
♦ GetSetNames
91
GetMessageData
There are two methods to retrieve message data. The first method retrieves the message data for
the specified time period; the second also returns the message time stamps.
Method 1
Synopsis
BOOL GetMessageData(LPCTSTR historian, LPCTSTR group, time_t finish,
time_t start, int * num_entries, CStringArray & MsgData, CStringArray &
MsgIdData, CStringArray & StationData);
LPCTSTR historian Specifies the six-character null-terminated historian

instance name.
LPCTSTR group Specifies the null-terminated name of the Historian
message group of up to AN_GPID_NPSIZ charac-
ters. If either msg_id or org_sta is specified, and you
are interested in all message groups, specify a null
string. If both msg_id and org_sta are not specified,
that is, they are null strings, specify group name
ALL if you are interested in all message groups.
time_t finish Specifies the I/A Series UTC upper limit of the
requested time span. If 0, the last time entered is
used as a default.
time_t start Specifies the I/A Series UTC lower limit of the
requested time span. If 0, the start of the file is used
as a default.
int * num_entries Returns the actual number of elements returned in
this call.
CStringArray MsgData Specifies a pointer to a buffer in which
GetMessageData returns the Historian messages.
Each message is terminated with a null character,
with two consecutive null characters at the end of
the last message.
CStringArray MsgIdData Returns an array of null-terminated message IDs,
each of AN_MSID_NPSIZ characters.
CStringArray StationData Returns an array of null-terminated originating
station names, each of AN_LBUG_NPSIZ
characters.
92
Method 2
Synopsis
BOOL GetMessageData(LPCTSTR historian, LPCTSTR group, time_t finish,
time_t start, int * num_entries, time_t *time_buffer, CStringArray & MsgData,
CStringArray & MsgIdData, CStringArray & StationData, int * more);

instance name.
LPCTSTR group Specifies the null-terminated name of the Historian
message group of up to AN_GPID_NPSIZ charac-
ters. If either msg_id or org_sta is specified, and you
are interested in all message groups, specify a null
string. If both msg_id and org_sta are not specified,
that is, they are null strings, specify group name
ALL if you are interested in all message groups.
used as a default.
as a default.
int * num_entries Returns the actual number of elements returned in
this call.
time_t * time_buffer The message time stamps.
CStringArray MsgData Specifies a pointer to a buffer in which
GetMessageData returns the Historian messages.
Each message is terminated with a null character,
with two consecutive null characters at the end of
the last message.
CStringArray MsgIdData Returns an array of null-terminated message IDs,
each of AN_MSID_NPSIZ characters.
CStringArray StationData Returns an array of null-terminated originating
station names, each of AN_LBUG_NPSIZ
characters.
to get:
0 = no more
1 = more
93
Description
The GetMessageData method retrieves the specified I/A Series Historian message group
database data, such as System Monitor messages, for the specified time period. The second form
of the call interface is used to return the message time stamps in addition to the message data. If
the specified historian is an AIM*Historian instance, this method only returns the I/A Series
message types and only if they are configured in the instance.
Errors
Return Values
The number of messages retrieved is returned in the num_entries parameter.
True if successful.
False if error.
See Also
♦ GetFoxHistMessageData
94
GetMessageGroup
Synopsis
BOOL GetMessageGroup(LPCTSTR Historian, LPCTSTR & msgTable);

instance name.
LPCTSTR msgTable List of message groups.
Description
The GetMessageGroup method retrieves a list of message groups for the specified historian
instance.
Errors
Return Values
List of message groups that have been defined if successful.
False if error.
95
GetMsgGroupAndName
Synopsis
BOOL GetMsgGroupAndName(CString msgTable, CString & msgGroup,
CString & msgName);
CString msgTable Specify message table name.

CString msgGroup List of message group names.
CString msgName List of message names.
Description
The GetMsgGroupAndName method returns a list of message groups and message names for the
specified AIM*Historian message table.
Errors
Return Values
List of message names and message group names if successful.
False if error.
See Also
♦ GetFoxHistGroups
96
GetObjectCount
Synopsis
int GetObjectCount(void);
int nobj The number of data object links.
Description
The GetObjectCount method gets the number of Data Object links this connection has
established with the server and returns the value in nobj.
Errors
Return Values
The number of object links if successful.
False if error.
See Also
♦ AddObject
97
GetPackageUsers
Synopsis
BOOL GetPackageUsers(LPCTSTR strPackage, int nMaxNum, int &nMore,
int &nActnum, CStringList &slUsers, CStringList &slIPAddr, CWordArray &
aUserTypes);
LPCTSTR strPackage Specifies a null-terminated package identifier. The

package identifier is the same as that used in the
aimreg.dat file.
int nMaxNum Specifies the maximum number of array elements the
call can receive in this call. nMaxNum can be any posi-
tive number. If nMaxNum is greater than MaxEnt in
the initialization file, this call returns information for
up to MaxEnt elements.
previous GetPackageUsers call:
0 = first time
1 = continuation of a previous GetPackageUsers call
Returns whether or not there are more elements to get:
0 = no more
1 = more
int nActnum Returns the actual number of elements returned in this
call.
CStringList slUsers A CStringList of null-terminated user names.
CStringList slIPAddr A CStringList of null-terminated, dot formatted,
IP addresses.
CWordArray aUserTypes Returns an array of user types:
0 = Concurrent user
1 = Permanent user
Description
The GetPackageUsers method gets the active users of a specified package.
Errors
Return Values
A list of active users of the package if successful.
False if error.
98
GetPathAlias
Synopsis
CString GetPathAlias(void);
Description
The GetPathAlias method gets the current server path alias connection name, that is the name of
the server currently connected to.
Errors
Return Values
FoxAPI Server Path Alias name if successful.
False if error.
99
GetServerBinDir
Synopsis
CString GetServerBinDir();
Description
The GetServerBinDir method returns the directory where server-side executables are located.
Errors
Return Values
The server bin directory path if successful.
False if error.
See Also
♦ GetServerDir
♦ GetServerInstDir
100
GetServerDir
Synopsis
CString GetServerDir();
Description
The GetServerDir method returns the server installation directory.
Errors
Return Values
The server installation directory if successful.
False if error.
See Also
♦ GetServerBinDir
♦ GetServerInstDir
101
GetServerID
Synopsis
WORD GetServerID(void);
Description
Each time you connect to a server, a unique connection identification number is generated.
The GetServerID method returns the current server connection number.
Errors
Return Values
A unique connection identification number if successful.
False if error.
See Also
♦ GetServerName
♦ IsOffPlatform
102
GetServerInfo
Synopsis
CString GetServerInfo(void);
Description
The GetServerInfo method gets the most recent error string in the form of a message or returns
empty if the last call made was successfully completed.
Errors
Return Values
Error message resulting from the last operation performed.
Empty string if last call was successful.
False if error.
See Also
♦ GetServerStatus
♦ IsServerOK
103
GetServerInstDir
Synopsis
CString GetServerInstDir();
Description
The GetServerInstDir method returns the directory where AIM*Historian instances are located
on the server.
Errors
Return Values
The instance directory if successful.
False if error.
See Also
♦ GetServerBinDir
♦ GetServerDir
104
GetServerName
Synopsis
CString GetServerName(void);
Description
The GetServerName method retrieves the current server network connection name.
Errors
Return Values
Server name if successful.
False if error.
See Also
♦ GetServerID
♦ IsOffPlatform
105
GetServerStatus
Synopsis
WORD GetServerStatus(void);
Description
The GetServerStatus method gets the most recent error string in the form of a code or returns
empty if last call was successfully completed.
Errors
Return Values
If successful, returns the error code resulting from the last operation performed or 0 if last call was
successful.
False if error.
See Also
♦ GetServerInfo
♦ IsServerOK
106
GetServerTimeout
Synopsis
BOOL GetServerTimeout(int & ServerTimeout);
int ServerTimeout Time in minutes that the server connection stays

alive with no activity.
Description
The GetServerTimeout method returns the time in minutes the current server connection
stays alive with no activity. The value can be set in the ServerTimeout parameter in the [AISnet]
section of the server initialization file, an_init.tcp. If no value is set, the default is one minute. You
can also set the value in the MFC class using SetServerTimeout.
Errors
Return Values
The timeout value if successful.
False if error.
See Also
♦ SetServerTimeout
107
GetServerType
Synopsis
int GetServerType(void);
Description
The GetServerType method returns the server type.
Errors
Return Values
If true, returns the server type. Possible values are:
Value Server Type

20 AP20 station
50 50 Series station
71 Terminal Server
151 non I/A Series Solaris system
170 non I/A Series Windows NT system
False if error.
108
GetSetItemNames
Synopsis
BOOL GetSetItemNames(LPCTSTR set_name, CStringList &setlist);
LPCTSTR set_name Specifies the set to name to be queried.

CStringList setlist Resulting list of objects in the set.
Description
The GetSetItemNames method fills the supplied CStringList with the I/A Series block
parameters in the specified FoxAPI set. The parameters are identified by the compound, block,
and parameter name (for example, TANKS_001:AIN_37.PNT).
Errors
Return Values
A list of objects in the specified set if successful.
False if error.
109
GetSetNames
Synopsis
BOOL GetSetNames(CStringList & setnames);
CStringList setnames Resulting list of set names.
Description
The GetSetNames method fills the supplied CStringList with the FoxAPI set names “defined” on
the server.
The server is configured to allow a maximum number of sets that can be opened concurrently. For
each of these that is not defined, the method returns the name “Not Available.”
Errors
Return Values
List of set names if successful.
False if error.
See Also
♦ GetMaxSet
110
GetStationCompounds
Synopsis
BOOL GetStationCompounds(LPCTSTR szStation, CStringList & slCompounds);
LPCTSTR szStation The letterbug of the specified I/A Series station.

CStringList slCompounds Returns a list null-terminated compound names.
Description
The GetStationCompounds method fills the supplied CStringList with compound names found
in the specified I/A Series station.
Errors
Return Values
A list of compound names if successful.
False if error.
See Also
♦ GetStations
♦ GetAllCompounds
111
GetStations
Synopsis
BOOL GetStations(CStringList & slStations);
CStringList slStations The letterbugs of the I/A Series stations.
Description
The GetStations method fills the supplied CStringList with the letterbugs of the stations on the
I/A Series node to which the server is connected.
Errors
Return Values
A list of letterbugs if successful.
False if error.
See Also
♦ GetStationCompounds
112
GetTimeLinearData
Synopsis
BOOL GetTimeLinearData(LPCTSTR Historian, LPCTSTR arch_name, LPCTSTR point,
time_t start, time_t finish, int SortOrder, int MaxEntries, int SampFreq,
int * numpts, long * timebuffer, int * statusbuffer, float * valuebuffer,
int operation = 0, int PercentValid = 60);

instance name.
LPCTSTR arch_name Specifies the null-terminated archive database name
of up to AN_DBNM_NPSIZ characters, if applica-
ble; otherwise a null string. If this call is being made
for an AIM*Historian instance, this argument is
ignored. If for a legacy I/A Series Historian and a
name is specified, the call searches the archive direc-
tory first, then the playback directory for a match
on the full 10-character archive database name. If
only a six-character archive group name is supplied,
only the archive directory is searched. The archive
database name consists of a six-character name of a
configured archive group and an optional four-char-
acter time stamp.
If the archive group name is less than six characters,
the Archive function fills the remaining spaces with
underscores. The time stamp is specified by four
characters in the format <m><dd><t>, where:
<m> is the month: 1 through 9 for January through
September, and a, b, c for October, November and
December, respectively.
<dd> is the number of the day, 01 through 31
<t> is the hour, a through x for 12:00 am through
11:00 pm
LPCTSTR point Specifies the null-terminated collection point name.
as a default.
used as a default.
int SortOrder Specifies how the samples are to be accessed:
0 = ascending time order (FORWARD)
1 = descending time order (BACKWARD)
113
int MaxEntries Specifies the maximum number of array elements

the caller can receive in this call; MaxEntries can be
any positive integer. If MaxEntries is greater than
MaxEnt in the an_init.cfg initialization file, this call
returns information for up to MaxEnt samples.
int SampFreq Defines the sampling interval in seconds over which
values in the file are linearized.
int * numpts Returns the actual number of elements returned.
long * timebuffer Stores an array of I/A Series UTC sample time
stamps.
int * statusbuffer Stores an array of sample status words.
float * valuebuffer Stores an array of floating point sample values.
int operation = 0 Specifies the operation type. The default is 0 for
linearized data. The group operation types are
shown in Table 4-3.
int PercentValid = 60 Checks that at least this percentage of data for the
specified time period is good. The default is
60 percent.
Description
The GetTimeLinearData method retrieves time linearized historical data from the specified His-
torian Sample database.
Table 4-3. Configurable Historian Operations
Code Name Description

0 NULL_OP The value is time-linearized data.
1 USER_OP This is handled as a HILO operation and is not user defined.
2 SUM_OP The value represents the sum of the samples.
3 AVG_OP The value represents the average of the samples.
4 MAX_OP The value is the maximum value.
5 MIN_OP The value is the minimum value.
6 STDV_OP The reduction group computes the standard deviation.
7 KURT_OP The kurtosis.
8 HIST_OP The histogram.
Errors
Return Values
The time linearized historical data if successful.
False if error.
114
GetTimeUsage
Synopsis
BOOL GetTimeUsage(LPCTSTR Historian);

instance name.
Description
The GetTimeUsage method determines whether the specified historian is using I/A or UTC time.
Errors
Return Values
True if historian is using I/A Time.
False if historian is using UTC time.
See Also
♦ IsFoxHistory
115
GetUserConnection
Synopsis
CString GetUserConnection(void);
Description
The GetUserConnection method retrieves the user named in the connection.
Errors
Return Values
User named in the connection if successful.
False if error.
See Also
♦ SetUserConnection
116
IPAddress
There are two methods available to access the IP address. The first method listed returns the
IP address as a string. The second method returns the IP address as a number.
Method 1
BOOL IPAddress
Synopsis
BOOL IPAddress(CString ServerName, CString & IPaddress);
CString ServerName Specifies the server.

CString IPaddress The address of the named server.
Method 2
UINT IPAddress
Synopsis
UINT IPAddress(CString ServerName);
CString ServerName Specifies the server.
Description
The BOOL IPAddress method returns the string value of the TCP/IP address of the specified
server.
The UINT IPAddress method returns the unsigned, 32-bit integer representation of the
TCP/IP address for the specified server.
Errors
Return Values
For BOOL IPAddress, the string value of the TCP/IP address if successful.
For UINT IPAddress, the unsigned, 32-bit integer representation of the TCP/IP address if
successful.
False if error.
117
IsDir
Synopsis
BOOL IsDir(LPCTSTR szPath, int * nIsDir);
LPCTSTR szPath Specified directory path of the server.

int * nIsDir Returns 1 if a directory
If specified string is not a directory but exists,
returns 0.
Description
The IsDir method verifies the specified directory path from a specified server is a directory and
not a file.
Errors
Return Values
True if function completed.
False if function fails or if string does not exist.
See Also
♦ FileStat
♦ GetDirList
118
IsFoxHistory
Synopsis
BOOL IsFoxHistory(LPCTSTR Historian);

instance name.
Description
The IsFoxHistory method determines if the supplied name is an AIM*Historian instance.
Errors
Return Values
True if the name is an AIM*Historian instance.
False if the name is a not an AIM*Historian instance.
See Also
♦ GetTimeUsage
♦ IsInHistorian
119
IsInHistorian
Synopsis
BOOL IsInHistorian(LPCTSTR szCollectionPoint, CString & szHistorian);
LPCTSTR szCollectionPoint Specifies collection point or RTP to be found.

CString szHistorian Identifies the historian instance where the point is
collected.
Description
The IsInHistorian method identifies if this collection point is in a historian instance and returns
the first one it finds.
Errors
Return Values
Historian instance name if successful.
False if error.
See Also
♦ GetHistData
♦ IsFoxHistory
120
IsOffPlatform
Synopsis
BOOL IsOffPlatform();
Description
The IsOffPlatform method determines if the connected server is an I/A Series server.
Errors
Return Values
True if the server is not an I/A Series server.
False if the server is an I/A Series server.
See Also
♦ GetFoxAPIVersion
♦ GetServerID
♦ GetServerName
121
IsServerOK
Synopsis
BOOL IsServerOK(void);
Description
The IsServerOK method checks the status of the connected server.
Errors
Return Values
True if the server is OK.
False if a problem is detected.
See Also
♦ GetServerInfo
♦ GetServerStatus
122
MakeSystemCall
Synopsis
BOOL MakeSystemCall(LPCTSTR szCommand, BOOL wait = 0);
LPCTSTR szCommand Specifies the command to execute on the server.

The full path must be specified.
BOOL wait = 0 Wait option.
If = 1, pauses client until command is executed.
The default is 0, no wait.
Description
The MakeSystemCall method executes a command (specified in szCommand) on the I/A Series
systems. When wait = 1, the client waits for the operation to complete.
Errors
Return Values
Command executes if successful.
False if error.
123
MultipleObjectWrite
Synopsis
BOOL MultipleObjectWrite(int accessType, int nument, char * nameArray,
int * valTypeArray, long * valueArray, int * objIndexArray, int * errorArray,
int * reterr);
int accessType Opened with 1 = read, 2 = read/write.

int nument Number of values in the arrays.
char * nameArray Item names.
int * valTypeArray Data types in the case of non-string writes.
long * valueArray Values to write for non-string write.
int * objIndexArray Object indexes.
int * errorArray Array of error codes.
int * reterr Return code from the write function.
Description
The MultipleObjectWrite method allows the application to do multiple writes in a single call for
efficient performance for non-string data types.
NOTE
This method does not support bit position writes. The item names in nameArray
must use the <Compound>:<Block>.<Parameter> syntax with all characters in
uppercase.
Errors
Return Values
True if write call was successful.
False if error.
See Also
♦ ObjectWrite
124
ObjectRange
Synopsis
BOOL ObjectRange(LPCTSTR szName, float * HighScale, float * LoScale,
float * Delta);
server.
float * HighScale Returns the maximum value configured for the
specified object.
float * LoScale Returns the minimum value configured for the
specified object.
float * Delta Returns the change value configured for the
specified object.
Description
The ObjectRange method gets the range information for a specified object.
Errors
Return Values
The range information if successful.
False if error.
See Also
♦ ObjectType
125
ObjectRead
Method 1
Synopsis
BOOL ObjectRead(LPCTSTR szName, CString & szItemValue, int * nDataType);
server.
int * nDataType Returns the data type used to format the value
(see Appendix B “Object Status and Value Types”).
Method 2
Synopsis
BOOL ObjectRead(LPCTSTR szName, CString & szItemValue, int * nDataType CString
& szTimeStamp, int * nSource);
server.
int * nDataType Returns the data type used to format the value
CString szTimeStamp Returns the time stamp adjusted for local time,
in the form MM/DD/YY_hh:mm:ss:ddd where:
MM = month
DD = day
YY = year
hh = hour
mm = minute
ss = second
ddd = millisecond
int * nSource Returns an integer indicating the source of the
timestamp:
1 = from the I/A Series system
2 = from the API
3 = from the client
126
Description
The ObjectRead method reads the specified I/A Series data object, and formats the value and
status into a string. The value and status are separated by a tab character. The format of the value
is determined by the data type found. The complete string is obtained for I/A Series string data
types. Method 2 also returns the time and date, and the time source.
Errors
Return Values
The value and status of the specified object if successful.
False if error.
See Also
♦ ObjectReadAll
♦ dqObjectChange
127
ObjectReadAll
Synopsis
BOOL ObjectReadAll(CObArray & ChangedData);
CObArray ChangedData An array of current values in the CDX.
Description
The ObjectReadAll method queries the server for current values in the Change Data Extension,
and fills an array of objects of CDataElement type (see Table 5-1) for all items defined with
AddObject and AddMultiple Objects.
NOTE
It is the programmers responsibility to release (delete) the array elements
(CDataElements).
Errors
Return Values
An array of objects of CDataElement type if successful.
False if error.
See Also
♦ AddMultiple Objects
♦ AddObject
♦ dqObjectChange
♦ ObjectRead
128
ObjectType
Synopsis
BOOL ObjectType(LPCTSTR szName, int & nDataType, int & nConnType);
server.
int nDataType Returns the data type used to format the value
int nConnType Returns the connection type.
Description
The ObjectType method returns the data type and information about its connection, that is, how
you can write to the object if write is allowed. Connection types are:
Type Code Description

1 nonconnectable, nonsettable
2 nonconnectable, settable
3 read-only connectable, settable
4 read/write connectable, settable
Errors
Return Values
The specified object’s data and connection types if successful.
False if error.
See Also
♦ ObjectRange
129
ObjectWrite
Synopsis
BOOL ObjectWrite(LPCTSTR szName, char * szItemValue, int nDataType,
BOOL bBinaryMode, int accessType = 1, int objIndex = 0);
LPCTSTR szName Specifies the full path name of the object on

the server.
char * szItemValue Specifies the item value.
int nDataType Returns the data type used to format the value
BOOL bBinaryMode Set to FALSE if value is a string.
int accessType = 1 Opened with 1 = read, 2 = read/write.
The default is 1.
int objIndex = 0 Specify object index if known. The default is 0.
Description
The ObjectWrite method writes the ItemValue to the named I/A Series data object on the con-
nected server. The data object must be ‘settable’ and ‘not secured’. The data type is derived from
the value status. The ItemValue is assumed to be a string representation unless the binary_mode
flag is set to TRUE.
Errors
Return Values
True if write call was successful.
False if error.
See Also
♦ MultipleObjectWrite
130
OpenFoxAPISet
Synopsis
BOOL OpenFoxAPISet(LPCTSTR set_name, CStringList &setlist, float fRDelta);
LPCTSTR set_name Specifies the set to be opened.

CStringList setlist Specify the I/A Series objects you want to include in
the set.
float fRDelta The read Delta specifies the minimum change in
the object from the previous value to replace it with
a new value.
Description
The OpenFoxAPISet method creates a FoxAPI set on the connected server.
Errors
Return Values
Opens a set on the server if successful.
False if error.
See Also
♦ CloseFoxAPISet
131
PutFile
Synopsis
BOOL PutFile(LPCTSTR szIAFile, CString & szFileName, BOOL bAscii);
LPCTSTR szIAFile Specify the complete path and file name of the new
file on the connected sever. This method overwrites
any file with the same path and file name.
CString szFileName Specify the file on the application host to be copied
to the server.
BOOL bAscii When set to TRUE indicates that the file should be
converted from DOS ASCII to UNIX ASCII.
Description
The PutFile method copies a file on the Windows application host to an I/A Series station,
overwriting a file with the same path and name on the target machine. Set the bAscii flag to
FALSE when the destination server is an I/A Series AW70.
Errors
#define Note Description

succes Success
hoperr 2 Host file cannot be opened
hrderr 2 Host file cannot be read
iclerr 2 I/A Series file cannot be closed
ioperr 2 I/A Series file cannot be opened
nonull 3 No null-terminator found
ucfgrn 1 Unconfigured remote file system logical name
irmerr 2 Unable to mount remote file system
hclerr 2 Unable to close file in application platform
Error Code Notes

1. Call-level programming or configuration error; fix and try again.
2. File access error; fix and try again.
3. Internal error with message.
NOTE
1. You can access UNIX “regular” files in an I/A Series AP, but not directory, special,
or FIFO files.
2. To restrict access through DNBI gateways to an AP with UIDs and GIDs, you
need to modify the dsamap file in the AP. The dsamap file is: /etc/dsamap for AP10
and AP20; /etc/fox/dsamap for 50 Series systems.
132
Return Values
A file is created on the server if successful.
False if error.
See Also
♦ GetFile
133
PutFoxHistRTPValue
Synopsis
BOOL PutFoxHistRTPValue(LPCTSTR szHistorian, long lIndex, LPCTSTR szRTP,
int nType, long lValSize, long lNumElements, void * pValue, time_t tSeconds,
int tMsecs, int nStatus, long lQuality);

long lIndex Specifies the RTP index, or -1 if the RTP name is to
be used to get the RTP index.
LPCTSTR szRTP Specifies a null-terminated RTP name of up to
FH_TAG_NSIZ characters, or NULL. RTP is
ignored if a valid index of greater than 0 is specified.
int nType Specifies the value type for the specified instance
long lValSize Specifies the size, in bytes, of one value element. If
valsize is -1 or index is -1, the configured value size
is used. For example, valsize is 4 for a float, 8 for a
double. I/A Series value types require a valsize of 4.
long lNumElements Specifies the number of elements in the value. If
num_elems is -1 or index is -1, the configured
number of elements is used.
void * pValue Specifies a pointer to the value to be put in the RTP
database. You must declare or cast the variable to a
long * to satisfy the compiler, but the type for
interpreting the values depends on how the RTP
was configured. See the Type (value type) argument
returned by GetFoxHistRTPDefinition or the
TYPE attribute of the FH_COMP_POINT
configuration component.
time_t tSeconds Specifies the UTC or I/A Series time, per the
IATIME attribute of the AIM*Historian instance.
int tMsecs Specifies the number of milliseconds within the
second of the collection time.
int nStatus Specifies the status associated with the value in
I/A Series format (see Appendix B “Object Status
and Value Types”). As a minimum requirement,
status needs the RTP value type.
long lQuality Specifies the quality associated with the value in
user-defined format.
134
Description
The PutFoxHistRTPValue method adds an RTP value to the AIM*Historian database.
Errors
Return Values
Adds a sample to the RTP database if successful.
False if error.
See Also
♦ WriteMDEData
135
ReconnectToServer
Synopsis
int ReconnectToServer(LPCTSTR APAlias, LPCTSTR szPackage = NULL);
LPCTSTR APAlias Specifies the server by the path alias defined in the
local an_init.cfg file.
LPCTSTR szPackage = NULL Identifies an AIM*AT client application that is
making the connection. Use the default NULL.
NOTE
szPackage is reserved for Invensys use only. Do not pass this variable.
Description
The ReconnectToServer method attempts a connection to a server. Use this method if a
previous attempt to connect to a server failed.
Errors
Return Values
True if connection successful.
See Also
♦ GetServerInfo
♦ GetServerStatus
136
RemoveObject
Synopsis
BOOL RemoveObject(LPCTSTR szName);
server.
Description
The RemoveObject method removes the link with the FoxAPI server for the specified Data
Object.
Errors
Return Values
True if successful.
False if error.
See Also
♦ RemoveObjects
137
RemoveObjects
Synopsis
BOOL RemoveObjects(int nument, char* name_array, int * error_array,
int * reterr);
int nument Specifies the number of objects to remove.

char* name_array Specifies an array of object names, one per object,
indicating objects to remove from the CDX. Each
array element contains thirty-two (32) characters,
left-justified with trailing blanks or nulls.
int * error_array Returns an array of error codes, one per object.
int * reterr Returns an error code (see Appendix A “Error
Messages”).
Description
The RemoveObjects method removes objects from the CDX for the current server.
If no objects remain in the CDX for the current server, RemoveObjects forces the state of the
current server to “inactive” and returns the error “noobjects” as a warning.
Errors
Return Values
True if Object found and removed.
False if not found.
See Also
♦ RemoveObject
138
SearchFoxHistRTPNames
Synopsis
BOOL SearchFoxHistRTPNames(LPCTSTR historian, LPCTSTR wildcard,
CStringList & slRTP);
LPCTSTR historian Specifies the AIM*Historian instance to be

searched.
LPCTSTR wildcard Specifies the filter criteria string to be used in the
search. Wildcard characters * and ? can be used.
CStringList slRTP Returns a list of RTP names based upon the
specified historian and wildcard.
Description
The SearchFoxHistRTPNames method searches the RTP configuration instance for RTP names
containing a specific string. The method returns a list of the full RTP names based upon the filter
criteria.
This method is successful when the target historian is an AIM*Historian application.
Errors
Return Values
A list of RTP names if successful.
False if error.
See Also
♦ GetHistItemList
139
SetServerTimeout
Synopsis
BOOL SetServerTimeout(int ServerTimeout);
int ServerTimeout Time in minutes that the server connection stays

alive with no activity.
Description
The SetServerTimeout method sets the time in minutes that the current server connection stays
alive with no activity. This action overrides the value set in the ServerTimeout parameter in the
[AISnet] section of the server initialization file, an_init.tcp.
Errors
Return Values
True if successful.
False if error.
See Also
♦ GetServerTimeout
140
SetUserConnection
Synopsis
void SetUserConnection(LPCTSTR szUserID);
LPCTSTR szUserID Specify a user name.
Description
The SetUserConnection method overrides the default (logged in) client user name. Changes the
user name for the connection to a FoxAPI Server.
Errors
Return Values
None.
See Also
♦ GetUserConnection
141
WriteEventMsgData
Synopsis
BOOL WriteEventMsgData(LPCTSTR Historian, LPCTSTR TableName, int mode,
CStringArray & ColumnNames, CPtrArray & ColumnValues, CDWordArray & ValSizes);

LPCTSTR TableName Specifies the configured message group and message
name.
int mode Specifies the mode of the call:
1 = AN_ADD to add a sample.
CStringArray ColumnNames An array of the message keys. The key must
be specified for each value to be written.
CPtrArray ColumnValues An array of values to be entered for the keys
specified in ColumnNames.
CDWordArray ValSizes Indicates the size of each value.
Description
The WriteEventMsgData method puts an event message into the AIM*Historian message
database. Event message types are components of an AIM*Historian Instance and must be
configured using ConfigureFoxHistory before messages of those types can be put in the
message database.
NOTE
There is no specific method to change a message. To change a message, add another
message with the same time stamp as the one you want to change. A message cannot
be deleted.
Errors
Return Values
An Event Message is written if successful.
False if error.
See Also
♦ ConfigureFoxHistory
♦ GetFoxHistConfigSessionRTPNames
142
WriteMDEData
Synopsis
BOOL WriteMDEData(LPCTSTR historian, LPCTSTR group. LPCTSTR point, int mode,
float * value, time_t timestamp, int status);

instance name.
LPCTSTR group Specifies the null-terminated name of the MDE
group of up to AN_GPID_NPSIZ characters. If
gname[0] = 0, the member file is searched for
pname, and the change is made in all groups of
which the point is a member; otherwise, the change
is made only in the specified group’s data file.
LPCTSTR point Specifies the null-terminated collection point name
of up to AN_PTID_NPSIZ characters.
int mode Specifies the mode of the call:
1 = AN_ADD to add a sample
2 = AN_DELETE to delete a sample
3 = AN_MODIFY to modify a sample
NOTE: DELETE and MODIFY only work with
legacy Historian systems.
float * value Specifies a floating point sample value.
time_t timestamp Specifies the I/A Series UTC stamp of the sample.
In the Delete and Modify modes, 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.
int status Specifies the sample status word. The sample value
and the status word are not used in Delete mode. In
Modify mode, they overwrite the existing data.
Description
The WriteMDEData method writes the specified values to the RTPs that are configured for Man-
ual Data Entry (MDE). Use this method when the target historian is an I/A Series Historian. Use
PutFoxHistRTPValue when writing MDE values to an AIM*Historian database.
Errors
143
Return Values
The values are written to the RTPs if successful.
False if error.
See Also
♦ PutFoxHistRTPValue
144
5. CDataElement Class Methods
Reference
This chapter provides a reference guide to the methods available with I/A Series NetAPI MFC
Class CDataElement.
The following CDataElement Class methods are described in this chapter:
♦ “Format()” on page 146
♦ “Getmsec()” on page 147
♦ “Getsource” on page 148
♦ “GetStations” on page 149
♦ “GetStrValue” on page 150
♦ “GetTimeDiff” on page 151
♦ “GetUseServerTime” on page 152
♦ “Getutc()” on page 153
♦ “LoadValueFromString” on page 154
♦ “SetType” on page 155
♦ “SetUseServerTime” on page 156
♦ “Type()” on page 157
♦ “Type(CString &s)” on page 158
145
B0400BJ – Rev B 5. CDataElement Class Methods Reference
Format()
Synopsis
CString Format();
Description
The Format() method takes the internal representation of the datatype and returns it as a string.
Errors
Return Values
Provides the string representation of the value if true.
False if error.
146
5. CDataElement Class Methods Reference B0400BJ – Rev B
Getmsec()
Synopsis
time_t Getmsec():
Description
The Getmsec() method returns the millisecond portion of the time associated with the value.
Errors
Return Values
Returns the millisecond portion of the time.
See Also
♦ Getsource()
♦ Getutc()
147
Getsource
Synopsis
int Getsource();
Description
The Getsource() method returns the source of the time stamp: 1 = from the I/A Series system,
2 = from the API server, 3 = from the client.
Errors
Return Values
Returns the source of the time stamp.
See Also
♦ Getmsec()
♦ Getutc()
148
GetStations
Synopsis
BOOL GetStations(CStringList & slStations, unsigned long stationmask);
CStringList slStations Letterbug of the I/A Series station.

unsigned long stationmask Mask of desired station types.
Description
The GetStations method fills the supplied CStringList with the letterbugs of the stations on the
I/A Series node to which the server is connected based on a bit mask of desired station types
(stationmask). A stationmask of zero returns all.
Station type bit definitions:
Communication Server bit 0 0x00000001 1
Unit Controller bit 1 0x00000002 2
File Server bit 2 0x00000004 4
Graphics Controllers bit 3 0x00000008 8
FOXNET Slave Gateway bit 4 0x00000010 16
LAN INTERFACE bit 5 0x00000020 32
SiteWide Lan Interface bit 6 0x00000040 64
Gateway Processor bit 7 0x00000080 128
Gateway 30 bit 8 0x00000100 256
PC station bit 9 0x00000200 512
Alan Bradley Gateway bit 16 0x00010000 65536
Modbus Gateway bit 17 0x00020000 131072
760/761 Gateway bit 18 0x00040000 262144
Foreign Device Gateway bit 19 0x00080000 524288
X.25 INI Interface types bit 20 0x00100000 1048576
Display Station ECB 28 Type bit 21 0x00200000 2097152
Hydro Tank Station Type bit 22 0x00400000 4194304
Spectrum Interface Processor bit 23 0x00800000 8388608
Interspec Gateway bit 24 0x01000000 16777216
Errors
Return Values
A list of letterbugs if successful.
False if error.
149
GetStrValue
Synopsis
const CString &GetStrValue();
CString &GetStrValue Supplied string value.
Description
The GetStrValue method checks the type. If type is a string, it returns the stored value (or nothing
if it is empty).
Errors
Return Values
Returns the stored value of a string (or nothing) if true.
False if error.
150
GetTimeDiff
Synopsis
long GetTimeDiff(void);
Description
The GetTimeDiff method returns a long signed integer that represents the difference between the
client computer clock and the server computer clock.
Errors
Return Values
The time difference in seconds.
151
GetUseServerTime
Synopsis
BOOL GetUseServerTime(void);
Description
The GetUseServerTime method returns a Boolean indicator of how historian time stamps are to
be expressed. When false (default), the client adjusts the time relative to the difference between
the client computer clock and the server computers clock. When true, the client does not adjust
the time relative to the difference between the clocks. This value is taken from the following entry
in the client computer’s registry:
HKEY_LOCAL_MACHINE\Software\SimSci\Aim\Settings\UseServerTime
Errors
Return Values
The time usage indicator.
152
Getutc()
Synopsis
time_t Getutc();
Description
The Getutc() method returns the UTC time, in seconds associated with the value.
Errors
Return Values
Returns the UTC time (seconds since January 1, 1970).
See Also
♦ Getmsec()
♦ Getsource()
153
LoadValueFromString
Synopsis
BOOL LoadValueFromString(const CString &str, IADataType dataType);
CString str Supplied string value by reference.

IADataType dataType Supplied data type.
Description
The LoadValueFromString method when given the ASCII string value and a valid datatype, will
fill in status and data value member of the class of the internal structure. Table 5-1 at the end of
this chapter provides the CDataElement class data types.
Errors
Return Values
Provides the status if true.
False if error.
154
SetType
Synopsis
void SetType (IADataType type);
IADataType type Provides a numeric data type.
Description
The SetType method tells which data type to set internally in the class.
Errors
Return Values
Sets the datatype if true.
False if error.
155
SetUseServerTime
Synopsis
BOOL SetUseServerTime(BOOL value);
BOOL value Indicates whether time is adjusted for a difference between the
client and server clocks:
0 = time is adjusted
1= time is not adjusted
Description
The SetUseServerTime method sets and returns a Boolean indicator of how historian time stamps
are to be expressed. When false (default), the client adjusts the time relative to the difference
between the client computer clock and the server computer’s clock. When true, the client does
not adjust the time relative to the difference between the clocks. This value is set/taken from the
following entry in the client computer’s registry:
HKEY_LOCAL_MACHINE\Software\SimSci\Aim\Settings\UseServerTime
Errors
Return Values
The time usage indicator.
156
Type()
Synopsis
IADataType Type();
Description
The Type() method returns the numeric data type of the value in the class.
Errors
Return Values
Provides the numeric datatypes if true.
False if error.
157
Type(CString &s)
Synopsis
void Type(CString &s);
CString s Supplied string value by reference.
Description
The Type(CString &s) method, when passed a string reference, takes the type and returns a string
representation of the datatype (that is, “character”).
Errors
Return Values
Provides the string representation of the type if true.
False if error.
158
CDataElement Class Data Types

Table 5-1 includes the data types used by the CDataElement class. The number is the numeric
value that is returned for datatype and the Data Type is the string value that is returned.
Table 5-1. CDataElement Class Data Types
Number Data Type Size

0 IAUnknown
1 IAChar 1 byte
2 IAInt 2 bytes
3 IAFloat 4 bytes
4 IAString 4 characters max
5 IABool 1 byte
6 IALong 4 bytes
7 IAUnused Type 7 is unused
8 IAShort 1 byte
9 IAPackedBool 2 bytes
10 IALongPackedBool 4 bytes
159
160
Appendix A. Error Messages
This appendix lists error codes and strings issued by the I/A Series NetAPI MFC Class.
Table A-1. Error Codes and Strings Returned by NetAPI MFC Class
Code String
-2 Invalid state for request
-3 CSA authorization code
-4 Cmpd or block name already used
-5 Required element not found
-6 Block not part of compound
-7 Invalid Informix reference
-8 User filter rejected
-9 Location is not defined in system
-10 Missing compound or block name
-11 process not set-up for CSA IPC
-13 name used in another domain
-12 user list is too large for IPC
-20 unrecognized CSA request
-30 CSA server is unavailable
-50 File I/O error detected
-100 Thought-to-never-occur condition
-30000 Unknown error
#
-3004 Function not supported.
0 Success
1 Invalid number of entries (call-level error)
2 Invalid access type.
3 Unable to allocate resources.
4 All datasets are used.
5 Not longer used.
6 All change queues are used.
7 Out of resources
8 Out of resources (rw when gws specified)
9 I/O error on request file.
10 I/O error on rebuild file.
11 AIM*API Task is unable to open this INI-10 list.
161
B0400BJ – Rev B Appendix A. Error Messages
Table A-1. Error Codes and Strings Returned by NetAPI MFC Class (Continued)
Code String
12 AIM*API Task is unable to close this INI-10 list
13 At least one of the value types does not match.
14 Data set is not within range.
15 Data set not currently opened.
16 System dependent error. (General routines).
17 File I/O error. (General routines)
18 X.25 I/O error. (General routines)
19 Not locked. (General routines)
20 Reassign in progress. (General routines).
21 Invalid queue number.
22 Queue is empty.
23 Queue not empty.
24 Fewer changes returned than requested.
25 Invalid gateway.
26 At least one of the entries has an error.
27 Too many entries invalid size or value
28 Type mismatch (uread only).
29 Write to read-only data set.
30 Unconfigured gateway (‘node’
31 Invalid circuit type.
32 Have already specified ‘keep’ with GETCIR.
33 Have NOT specified ‘keep’ with GETCIR.
34 No string to get
35 Invalid group for load levelling.
36 Invalid value type
37 Invalid write delta
38 Invalid read scan rate
39 Invalid write scan rate
40 Invalid match of read and write scan rate
41 Invalid match of read and write delta
42 Invalid match of read and write delta
46 Remote directory not writable
47 HOSTNAM not found
48 HOSTNAM or HOSTDIR not found directory invalid etc
49 No Read or Read/Write access
50 Host I/O error
51 Host file cannot be opened and/or created
52 Host file cannot be opened
162
Appendix A. Error Messages B0400BJ – Rev B
Code String
53 Unable to assign channel
54 Unable to set up the circuit
55 IA file cannot be opened
56 IA file cannot be read
57 Host file cannot be written
58 Host file cannot be read
59 Unable to set pointer to IA file
60 IA file cannot be written
61 IA file cannot be closed
62 Unable to clear circuit
63 Unable to deassign channel
64 Not in range ‘0’ to ‘9’
65 No null terminator found
66 Offset and/or numchr not valid
67 Unable to specify conversion files
68 Unable to specify convert qualifiers
69 Unable to perform conversion of file
70 Unable to open strmfile.tmp after conversion
71 Unable to close strmfile.tmp after conversion
72 Unconfigured remote file system logical name
73 Unable to rmount remote file system
74 Host file cannot be closed
75 pfwrit numchr > 1000
76 Invalid argument like a NULL pointer.
80 invalid gateway
81 unconfigured gateway
82 unable to assign a channel
83 unable to set up a circuit
84 unable to read x.25 channel
85 unable to access terminal characteristics
86 unable to modify terminal characteristics
87 unable to restore terminal characteristics
88 unable to read character from keyboard
89 unable to write to INI
90 unable to release circuit
91 unable to deassign channel
92 invalid letterbug
93 invalid login name
163
Code String
94 invalid password or primary prompt string
95 I/O error opening VENIX command line file
96 I/O error opening VENIX response file
97 no letterbug prompt returned from INI
98 login name character not echoed
99 command line character not echoed
100 not able to logoff of VENIX
101 response_buffer is not large enough
102 I/O error on write to VENIX response file
103 INI only
104 auxiliary_buffer is not large enough
105 Mapping a file to virtual SUN memory failed
110 CBP not found in CSA.
111 CBP or Shared variable is secured.
112 CBP is not an input parameter.
113 CBP or Shared variable is not found.
114 om_getval or getval failed.
115 Station not found in station table.
128 Bit for bad value returned from Collector
200 Object not opened in Fox API database
201 Object not added to change-driven extension
202 an_dq_changes() allowed NOT an_poll_changes()
203 No active servers with objects in CD extension
204 Unable to access object (object-level error)
205 Object already added multiples not allowed
206 Invalid delta value (negative)
207 No current server
208 Object not added for read/write access
209 Some object has warning error
210 nument is bigger then g_maxent
211 No objects in CD extension
212 Not enough access for client at server
230 Illegal number of variables in omopen()
231 List does not exist
232 List not in legal range
233 More changes in the list
234 No changes in the list
235 Index outside range of data set
164
Appendix A. Error Messages B0400BJ – Rev B
Code String
1001 Memory Allocation error
1002 Protocol not specified
1003 Invalid message type
1004 Invalid opocode
1005 Hostname not specified
1006 All server entries were use.
1007 Unable to communicate with server
1008 Server ID is out of range
1010 Max number of no connection reach
1011 Server are connected but not selected
1012 Maximum number of servers running
1013 Null pointer as argument
1014 available for use
1015 Compound Name too long
1016 Block Name to long
1017 Parameter Name to long
1018 CSA error encountered see errno
1019 ICC error encountered see errno
1020 Historian error encountered see errno
1021 Informix error encountered see errno
1022 Buffer size less than minimum required
1023 OM error encountered see errno
1099 WinSock blocking call in progress; retry required
165
166
Appendix B. Object Status and
Value Types
This appendix describes the status words and value types of I/A Series objects and
AIM*Historian real-time points (RTPs) and reduction RTPs.
The I/A Series Object Manager defines the object status as a 16-bit word. The network API repre-
sents it as a thirty-two bit integer. Bit 31 is the most significant bit.
An AIM*Historian RTP status has the same format as the status of an I/A Series object, except
that AIM*Historian software supports additional value types. The software represents object sta-
tus as a 32-bit integer, with bit 31 being the most significant bit (MSB).
The status word for an AIM*Historian Reduced RTP is described on page 170.
Table B-1 and the notes that follow define the object status when a process point is read from the
I/A Series Object Manager (Version 4.2 and later) or an RTP is read from the AIM*Historian
instance.
Table B-1. Status Definition with I/A Series Object Manager and AIM*Historian
31 (MSB) to 16 15 14 13 12 11 10 9 8 7 to 5 4 3 to 0 (LSB)
OM Connect Status
Ack/uncond. init
Limited High
Limited Low
Bad/Dis/Ok
Value Type
Sec/Unsec
Reserved
Shadow
Change
Error
00S
Bits 0 to 3 Object Manager or AIM*Historian value type per Table B-2. Value types
1 to 10 are I/A Series value types. Each of the I/A Series value types 1, 2,
3, 5, 6, 8, 9, and 10 are contained within 4 bytes.
167
B0400BJ – Rev B Appendix B. Object Status and Value Types
Table B-2. I/A Series Object and AIM*Historian RTP Value Types
Object Manager AIM*Historian RTP

No. Data Type Data Type Size
1 Character FH_CHAR 4 bytes
2 Integer FH_INTEGER 4 bytes
3 Float FH_FLOAT 4 bytes
4 String
5 1 byte Boolean FH_BOOLEAN 4 bytes
6 long integer FH_LONG 4 bytes
8 short integer FH_SHORT 4 bytes
9 packed boolean FH_INT_PACKED 4 bytes
10 long packed boolean FH_LONG_PACKED 4 bytes
21 FH_CHAR_ARRAY 1 byte per element
22 FH_SHORT_ARRAY 2 bytes per element
23 FH_INTEGER_ARRAY 4 bytes per element
24 FH_LONG_ARRAY 4 bytes per element
25 FH_FLOAT_ARRAY 4 bytes per element
26 FH_DOUBLE_ARRAY 8 bytes per element
27 FH_UCHAR_ARRAY 1 byte per element
28 FH_USHORT_ARRAY 2 bytes per element
29 FH_UINT_ARRAY 4 bytes per element
30 FH_ULONG_ARRAY 4 bytes per element
31 FH_STRING String. Size is user-defined,
and must account for the
longest string value including
the null terminator. The
number of elements is 1.
Non I/A Series types (21 and greater) exceed the four-bit field allotted for
the value type. If you use any of these value types, you must retrieve the
value type from the RTP configuration using GetFoxHistRTPValues or
GetFoxHistRTPDefinition to be sure of the value type.
For user-defined value types, the value type field is considered to be bits 0
to 7. For array type value types (21 to 31), the value type field is
considered to be bits 0 to 4.
168
Appendix B. Object Status and Value Types B0400BJ – Rev B
Bit 4 Change (setval) (1) / else (0)
Bits 5 to 7 Object Manager connect status:

0 No response
1 Being scanned
2 Disconnected
3 Deleted
4 Bad data type or unconnectable compound
6 Non-connectable parameter
Bit 8 The object is BAD (1), disconnected (1), or OK (0).
Bit 9 The parameter is secured (1) or unsecured (0).
Bit 10 Ack/uncond. init (1) or else (0).
Bit 11 The object is out of service (1) or in service (0).
Bit 12 The point is a shadow parameter (1) or not a shadow parameter (0).
Bit 13 The parameter is limited high (1) or not (0).
Bit 14 The parameter is limited low (1) or not (0).
Bit 15 There is an error condition upstream (1) or no upstream error

detected (0).
Bits 16 to 31 Reserved.
169
AIM*Historian Reduction Status and Quality

This section describes the status and quality returned by AIM*Historian reduction APIs.
AIM*Historian reduction APIs fh_FdbReduction() and fh_FdbRedArray() return a 32-bit status
and quality word, with bit 31 being the most significant bit (MSB).
The status contains a value type in the low order bits, which can be FH_FLOAT (3) or
FH_DOUBLE_ARRAY (26) as listed in Table B-2. In addition, one or more of the following val-
ues may be OR’d into the status, which are defined in aimhistorian.h and are listed from the
header for reference:
/* Reduced value status definitions */

#define UNAVAIL 128 /* bit set means unavailable (not
enough good values */
#define FH_OUT_OF_COLLECTED_RANGE 256 /* bit set means at least part of
interval was out of the collected
range of the RTP database */
#define FH_PARTIAL_INTERVAL 512 /* bit set means corresponding
reduced values are based on a
partial time interval */
Table B-3 and the notes that follow define the status returned by these APIs.
Table B-3. Status Returned by Reductions APIs
31 (msb) to 10 9 8 7 6 to 5 4 to 0 (lsb)
FH_OUT_OF_COLLECTED_RANGE
FH_PARTIAL_INTERVAL
Value Type
UNAVAIL
Reserved
Reserved
170
Appendix B. Object Status and Value Types B0400BJ – Rev B
Bits 0 to 4 define the value type of the reduced data as shown in Table B-4.
Table B-4. Reduction Value Types
Name Number Type Size

FH_FLOAT 3 4 bytes
FH_DOUBLE_ARRAY 26 8 bytes
If the reduction request was for peaks, the quality word has bit 30 (the next to the most
significant bit) set. In addition, if the peak was a minimum, bit 31 (the most significant bit) is set.
Otherwise, quality is zero.
171
172
Index
A
AddMultipleObjects 19
AddObject 23
AIM*Historian only access methods 16
AIM*Historian reduction status and quality 170
AISnet keywords 9
C
CDataElement class data types 159
CDataElement class methods 16
CDataElement class methods reference 145
CFoxAPIServer class methods 12
CFoxAPIServer class methods reference 19
CloseFoxAPISet 25
Compound Summary Access (CSA) methods 13
ConfigureFoxHistory 26
ConnectToServer 33
ConnectToServerByName 34
CreateEventMsgDef 35
Creating a project 11
Creating instances of the CFoxAPIServer class 11
D
Data object access methods 14
Development configuration 8
Development machine installation procedure 5
DisconnectFromServer 36
dqObjectChange 37
E
EngUnits 38
EnumServerHistorians 40
F
FetchObjectIndex 41
FetchObjectName 42
File access methods 14
FileRead 43
FileStat 44
Format() 146
FormatData 45
FormatDataAndTimeStamp 46
FoxAPI Data Sets Methods 15
173
B0400BJ – Rev B Index
FoxHistSystem 47
G
GetAccessInfo 48
GetAliasPath 49
GetAllBlocks 50
GetAllCompounds 51
GetBlkDescription 52
GetBlockCompounds 53
GetBlockParams 54
GetCompBlockAndType 55
GetCompoundBlocks 56
GetConfigFile 57
GetDirList 58
GetFile 59
GetFoxAPIVersion 61
GetFoxHistGroups 62
GetFoxHistMessageColumns 63
GetFoxHistMessageData 64
GetFoxHistMessageGroupKeys 68
GetFoxHistoryConfigSessionRTPNames 69
GetFoxHistRTPDefinition 70
GetFoxHistRTPValues 74
GetHistArchiveGroups 77
GetHistData 78
GetHistGroups 82
GetHistGrpMembers 83
GetHistItemList 85
GetHistOperations 86
GetHistVersion 87
GetHostID 88
GetIAVersion 89
GetMaxEntries 90
GetMaxSet 91
GetMessageData 92
GetMessageGroup 95
Getmsec() 147
GetMsgGroupAndName 96
GetObjectCount 97
GetPackageUsers 98
GetPathAlias 99
GetServerBinDir 100
GetServerDir 101
GetServerID 102
GetServerInfo 103
GetServerInstDir 104
GetServerName 105
GetServerStatus 106
GetServerTimeout 107
GetServerType 108
GetSetItemNames 109
174
Index B0400BJ – Rev B
GetSetNames 110
Getsource 148
GetStationCompounds 111
GetStations 112, 149
GetStrValue 150
GetTimeDiff 151
GetTimeLinearData 113
GetTimeUsage 115
GetUserConnection 116
GetUseServerTime 152
Getutc() 153
H
Historian access methods 15
I
I/A Series NetAPI MFC interface 1
Install I/A Series NetAPI MFC software 5
IPAddress 117
IsDir 118
IsFoxHistory 119
IsInHistorian 120
IsOffPlatform 121
IsServerOK 122
L
LoadValueFromString 154
M
MakeSystemCall 123
MaxEnt 9
MaxLog 9
MultipleObjectWrite 124
N
NetAPI MFC Methods 2
O
ObjectRange 125
ObjectRead 126
ObjectReadAll 128
ObjectType 129
ObjectWrite 130
OpenFoxAPISet 131
175
B0400BJ – Rev B Index
P
PrintErr 9
PutFile 132
PutFoxHistRTPValue 134
Putting the Application into Production 17
R
ReconnectToServer 136
RemoveObject 137
RemoveObjects 138
S
SearchFoxHistRTPNames 139
Server Connection Method 12
Server Information 12
SetServerTimeout 140
SetType 155
SetUserConnection 141
SetUseServerTime 156
System Requirements 4
T
TraceLevel 9
Type() 157
Type(CString &s) 158
W
WriteEventMsgData 142
WriteMDEData 143
33 Commercial Street
Foxboro, Massachusetts 02035-2099
United States of America
www.foxboro.com
Inside U.S.: 1-866-PHON-IPS (1-866-746-6477)
Outside U.S.: 1-508-549-2424 or contact your local Foxboro representative.
Facsimile: 1-508-549-4999
Printed in U.S.A. 0303

b0400bj B

Uploaded by

Copyright:

Available Formats

You might also like

b0400bj B

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

b0400bj B

Uploaded by

Copyright:

Available Formats

B0400BJ

All other brand names may be trademarks of their respective owners.

Copyright 2002-2003 Invensys Systems, Inc.

SOFTWARE LICENSE AND COPYRIGHT INFORMATION

2. Installation and Configuration .......................................................................................... 3

3. Using the NetAPI MFC Class ......................................................................................... 11

4. CFoxAPIServer Class Methods Reference........................................................................ 19

GetStationCompounds ......................................................................................................... 111

5. CDataElement Class Methods Reference....................................................................... 145

Getsource .............................................................................................................................. 148

Appendix A. Error Messages.............................................................................................. 161

Appendix B. Object Status and Value Types ..................................................................... 167

Index .................................................................................................................................. 173

Request For Comments

Networked Networked AIM*API

CSA, Process I/A Series AIM*Historian

NetAPI MFC Methods

Table 1-1. I/A Series NetAPI MFC Methods

Method Type Description

apiserv32d.lib Debug version of apiserv32.lib.

apiserv32d.dll Debug version of apiserv32.dll.

Development Machine Installation Procedure

Figure 2-1. Setup Welcome Dialog Box

Figure 2-2. Choose Destination Location Dialog Box

Figure 2-3. Installation Complete Dialog Box

6. Click Finish to close the dialog box and exit Setup.

Figure 2-4 shows a sample client initialization file.

Figure 2-4. Sample an_init.cfg File

The [AISnet] section keywords are described in Table 2-1.

Table 2-1. AISnet Keywords

Keyword Default Description

Creating Instances of the CFoxAPIServer Class

CFoxAPIServer Class Methods

Server Connection Methods

Compound Summary Access (CSA) Methods

Data Object Access Methods

File Access Methods

FoxAPI Data Sets Methods

Historian Access Methods

AIM*Historian Only Access Methods

CDataElement Class Methods

Putting the Application into Production

int nument Specifies the number of objects to add.

reterr error_array return

LPCTSTR set_name Specifies the set to be closed.

int nFhsd Specifies the AIM*Historian Session Descriptor,

LPCTSTR szValue If action is FH_ACT_PUT or FH_ACT_MOD,

Additional Information on Variables

AIM*Historian software requires the first three fields of all messages to

component_name Specifies the null-terminated name of the AIM*Historian component.

If component is FH_COMP_TRACK, component_name is a track key

indicator For a Create Session (action is FH_ACT_CREATE and component is

LPCTSTR NetworkName Specifies the server by its IP name.

LPCTSTR Historian Specifies the six-character null-terminated

CObArray ChangedData An array of new values in the CDX.

CStringList szServerEntry Contains the list of available/configured servers.

CStringList histlist Contains the list of available historian names.

CString szName Object name for the specified index.