AIM*AT™Suite NetAPI MFC Class User’s Guide

I/A Series System

AIM*ATSuite NetAPI MFC Class Users GuideB0400BJ

Rev CAugust 30, 2012

Invensys, AIM*API, AIM*AT, AIM*DataLink, AIM*Explorer, AIM*Historian, Foxboro, FoxAPI, I/A Series, and the Invensys logo are trademarks of Invensys plc, its subsidiaries, and affiliates.

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

Copyright 20022012 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 .................................................................................................................... 11Creating Instances of the CFoxAPIServer Class .................................................................. 11

CFoxAPIServer Class Methods ................................................................................................ 12Server Connection Methods ............................................................................................... 12Server Information ............................................................................................................. 12Compound Summary Access (CSA) Methods .................................................................... 13Data Object Access Methods .............................................................................................. 14File Access Methods ........................................................................................................... 14FoxAPI Data Sets Methods ................................................................................................ 15Historian Access Methods .................................................................................................. 15AIM*Historian Only Access Methods ................................................................................ 16

CDataElement Class Methods ................................................................................................ 16

Putting the Application into Production ................................................................................. 17

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

AddMultipleObjects ............................................................................................................... 19

AddObject .............................................................................................................................. 22iii

B0400BJ Rev C Contents

CloseFoxAPISet ...................................................................................................................... 24

ConfigureFoxHistory .............................................................................................................. 24

ConnectToServer .................................................................................................................... 31

ConnectToServerByName ...................................................................................................... 31

CreateEventMsgDef ................................................................................................................ 32

DisconnectFromServer ............................................................................................................ 33

dqObjectChange ..................................................................................................................... 34

EngUnits ................................................................................................................................. 34

EnumServerAlias ..................................................................................................................... 35

EnumServerHistorians ............................................................................................................ 35

FetchObjectIndex ................................................................................................................... 36

FetchObjectName ................................................................................................................... 36

FileRead .................................................................................................................................. 37

FileStat .................................................................................................................................... 38

FormatData ............................................................................................................................ 38

FormatDataAndTimeStamp ................................................................................................... 39

FoxHistSystem ........................................................................................................................ 40

GetAccessInfo ......................................................................................................................... 40

GetAliasPath ........................................................................................................................... 41

GetAllBlocks ........................................................................................................................... 42

GetAllCompounds .................................................................................................................. 42

GetBlkDescription .................................................................................................................. 43

GetBlockCompounds ............................................................................................................. 44

GetBlockParams ...................................................................................................................... 44

GetCompBlockAndType ........................................................................................................ 45

GetCompoundBlocks ............................................................................................................. 46

GetConfigFile ......................................................................................................................... 47

GetDirList .............................................................................................................................. 47

GetFile .................................................................................................................................... 48

GetFoxAPIVersion .................................................................................................................. 49

GetFoxHistGroups ................................................................................................................. 50

GetFoxHistMessageColumns .................................................................................................. 50

GetFoxHistMessageData ......................................................................................................... 51Method 1 ........................................................................................................................... 51Method 2 ........................................................................................................................... 52

GetFoxHistMessageGroupKeys ............................................................................................... 54iv

Contents B0400BJ Rev C

GetFoxHistConfigSessionRTPNames ..................................................................................... 55

GetFoxHistRTPDefinition ..................................................................................................... 56

GetFoxHistRTPValues ........................................................................................................... 59

GetHistArchiveGroups ........................................................................................................... 61

GetHistData ........................................................................................................................... 61Method 1 ........................................................................................................................... 62Method 2 ........................................................................................................................... 63Method 3 ........................................................................................................................... 64

GetHistGroups ....................................................................................................................... 65

GetHistGrpMembers .............................................................................................................. 66Method 1 ........................................................................................................................... 66Method 2 ........................................................................................................................... 66

GetHistItemList ...................................................................................................................... 67

GetHistOperations .................................................................................................................. 68

GetHistVersion ....................................................................................................................... 69

GetHostID .............................................................................................................................. 69

GetIAVersion .......................................................................................................................... 69

GetMaxEntries ........................................................................................................................ 70

GetMaxSet .............................................................................................................................. 70

GetMessageData ..................................................................................................................... 71Method 1 ........................................................................................................................... 71 ........................................................................................................................................... 72Method 2 ........................................................................................................................... 72

GetMessageGroup ................................................................................................................... 74

GetMsgGroupAndName ......................................................................................................... 74

GetObjectCount ..................................................................................................................... 75

GetPackageUsers ..................................................................................................................... 76

GetPathAlias ........................................................................................................................... 77

GetServerBinDir ..................................................................................................................... 77

GetServerDir ........................................................................................................................... 77

GetServerID ............................................................................................................................ 78

GetServerInfo .......................................................................................................................... 78

GetServerInstDir ..................................................................................................................... 79

GetServerName ....................................................................................................................... 79

GetServerStatus ....................................................................................................................... 80

GetServerTimeout ................................................................................................................... 80

GetServerType ........................................................................................................................ 81

GetSetItemNames ................................................................................................................... 82v


GetSetNames .......................................................................................................................... 82

GetStationCompounds ........................................................................................................... 83

GetStations ............................................................................................................................. 83

GetTimeLinearData ................................................................................................................ 84

GetTimeUsage ........................................................................................................................ 86

GetUserConnection ................................................................................................................ 86

IPAddress ................................................................................................................................ 87Method 1 ........................................................................................................................... 87Method 2 ........................................................................................................................... 87

IsDir ....................................................................................................................................... 87

IsFoxHistory ........................................................................................................................... 88

IsInHistorian ........................................................................................................................... 89

IsOffPlatform .......................................................................................................................... 89

IsServerOK ............................................................................................................................. 90

MakeSystemCall ..................................................................................................................... 90

MultipleObjectWrite .............................................................................................................. 91

ObjectRange ........................................................................................................................... 92

ObjectRead ............................................................................................................................. 92Method 1 ........................................................................................................................... 92Method 2 ........................................................................................................................... 93

ObjectReadAll ......................................................................................................................... 94

ObjectType ............................................................................................................................. 94

ObjectWrite ............................................................................................................................ 95

OpenFoxAPISet ...................................................................................................................... 96

PutFile .................................................................................................................................... 96

PutFoxHistRTPValue ............................................................................................................. 98

ReconnectToServer ................................................................................................................. 99

RemoveObject ...................................................................................................................... 100

RemoveObjects ..................................................................................................................... 100

SearchFoxHistRTPNames ..................................................................................................... 101

SetServerTimeout .................................................................................................................. 102

SetUserConnection ............................................................................................................... 102

WriteEventMsgData ............................................................................................................. 103

WriteMDEData .................................................................................................................... 104

5. CDataElement Class Methods Reference....................................................................... 107

Format() ................................................................................................................................ 107vi

Contents B0400BJ Rev C

Getmsec() .............................................................................................................................. 108

Getsource .............................................................................................................................. 108

GetStations ........................................................................................................................... 108

GetStrValue .......................................................................................................................... 109

GetTimeDiff ......................................................................................................................... 110

GetUseServerTime ................................................................................................................ 110

Getutc() ................................................................................................................................ 111

LoadValueFromString ........................................................................................................... 111

SetType ................................................................................................................................. 112

SetUseServerTime ................................................................................................................. 112

Type() ................................................................................................................................... 113

Type(CString &s) ................................................................................................................. 113

CDataElement Class Data Types .......................................................................................... 113

Appendix A. Error Messages.............................................................................................. 115

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

AIM*Historian Reduction Status and Quality ....................................................................... 124

Index .................................................................................................................................. 127vii


viii

Figures

1-1. I/A Series NetAPI MFC Interface with Various I/A Series Resources ............................ 12-1. Setup Welcome Dialog Box .......................................................................................... 52-2. Choose Destination Location Dialog Box ..................................................................... 62-3. Installation Complete Dialog Box ................................................................................. 72-4. Sample an_init.cfg File .................................................................................................. 8ix

B0400BJ Rev C Figures

x

Tables

1-1. I/A Series NetAPI MFC Methods ................................................................................. 22-1. AISnet Keywords .......................................................................................................... 94-1. Server Access Levels ..................................................................................................... 414-2. Configurable Reduction Group Operations ................................................................ 684-3. Configurable Historian Operations ............................................................................. 855-1. CDataElement Class Data Types .............................................................................. 113A-1. Error Codes and Strings Returned by NetAPI MFC Class ........................................ 115B-1. Status Definition with I/A Series Object Manager and AIM*Historian ..................... 121B-2. I/A Series Object and AIM*Historian RTP Value Types ........................................... 122B-3. Status Returned by Reductions APIs ......................................................................... 124B-4. Reduction Value Types ............................................................................................. 125xi

B0400BJ Rev C 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.

AudienceThis 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 Microsofts C++ implemen-tations and Microsoft Foundation Class (MFC) programming.

OrganizationThis 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 C Preface

Revision InformationFor this revision of this document (B0400BJ, Rev. C), the following changes were made to this document for release of AIM*AT 3.4:

Chapter 2 Installation and Configuration

Updated the DLL names in the introduction. Updated System Requirements on page 4.

Chapter 3 Using the NetAPI MFC Class

Updated the DLL names in Creating a Project on page 11 and Putting the Appli-cation into Production on page 17.

Related DocumentsRefer 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 Users Guide (B0193YN) AIM*Historian Users Guide (B0193YL) AIM*AT Installation Guide (B0193YM) FoxAPI Users Guide (B0193UD) Integrated Control Software Concepts (B0193AW) Integrated Control Block Descriptions (B0193AX).

These are available on the I/A Series Electronic Documentation CD-ROM or DVD (K0173TQ or K0173WT) provided by the Foxboro business unit of Invensys Operations Management. The latest revisions may also be available through the Global Customer Support athttp://support.ips.invensys.com.

Request For CommentsPlease direct your comments and suggestions concerning the I/A Series NetAPI MFC Class and this documentation to:

Global Customer Support CenterInvensys Systems, Inc.33 Commercial StreetFoxboro, MA 02035-2099Telephone within the US: 1-866-746-6477Telephone from outside the US: 508-549-2424Facsimile: 508-549-4999xiv

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).

Figure 1-1. I/A Series NetAPI MFC Interface with Various I/A Series Resources

NetAPI MFCClass

Networked FoxAPIAIM*API

Application Host

NetworkedFoxAPI

CSA, Process

AIM*API

AIM*Historian

NetworkedFoxAPI

I/A SeriesHistorian

I/A Series Server I/A Series Server AIM*AT ServerObjects1

B0400BJ Rev C 1. Overview

NetAPI MFC MethodsThe 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 Access (CSA)

The CSA methods connect to the I/A Series Compound Summary Access (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::.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 Users 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 Registry.

The included program files are:

foxapiserver.h Header file that defines attributes and methods for the class.

apiserv34.lib Library of C++ calls that wrap around Networked FoxAPI and AIM*API functions calls.

apiserv34d.lib Debug version of apiserv34.lib.

apiserv34.dll Runtime dynamic link library (DLL). This file must be ported to the application hosts along with shared MFC libraries MFC100.dll and MSVCR100.dll when the application is put into production.

apiserv34d.dll Debug version of apiserv34.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.

NOTEWhen debugging, make sure you link to the debug version of the libraries: apiserv34d.lib and apiserv34d.dll.3

B0400BJ Rev C 2. Installation and Configuration

System RequirementsI/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 7 Windows Server 2008 Windows Server 2003 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 2010, Version 10.0 with Ser-vice Pack 1 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 C

Development Machine Installation ProcedureTo install the I/A Series NetAPI MFC software:

1. Insert the AIM*AT 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 Box6


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 =\\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 ConfigurationWhen 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:

Figure 2-4 shows a sample client initialization file.

Figure 2-4. Sample an_init.cfg File

[AISnet] Defines trace options and maximum server interactions

[TCPIP] Specifies the path, protocol, and network API of the target servers.8


The [AISnet] section keywords are described in Table 2-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:

= /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.

Table 2-1. AISnet Keywords

Keyword Default Description

PrintErr 0 Print error help messages:0 for no message1 for brief message2 for detailed message

TraceLevel 0 Trace Level:0 none1 all of send and receive messages2 dot (.) for send messages3 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).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 ProjectThe 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 apiserv34d.lib and aipserv34d.dll libraries.

Creating Instances of the CFoxAPIServer ClassCreate an instance of the class using one of the two methods below.

CFoxAPIServer MyServer;

orCFoxAPIServer *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);

orCFoxAPIServer 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 C 3. Using the NetAPI MFC Class

CFoxAPIServer Class MethodsThe 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 MethodsThese methods identify available servers, establish and renew connections with the servers, retrieve connection status, and convert I/A Series time to local time.

NOTEA NetAPI MFC instance connects to one server at a time. Create multiple instances to connect simultaneously with multiple servers.

Server InformationOnce the application is connected to the server, these methods access information about the servers.

Method Page

ConnectToServer page 31

ConnectToServerByName page 31

DisconnectFromServer page 33

EnumServerAlias page 35

GetConfigFile page 47

GetServerInfo page 78

GetServerStatus page 80

GetUserConnection page 86

ReconnectToServer page 99

SetUserConnection page 102

Method Page

GetAccessInfo page 40

GetAliasPath page 41

GetFoxAPIVersion page 49

GetHostID page 69

GetIAVersion page 69

GetMaxEntries page 70

GetPackageUsers page 76

GetPathAlias page 77

GetServerID page 7812

3. Using the NetAPI MFC Class B0400BJ Rev C

Compound Summary Access (CSA) MethodsThe 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:

:.

For additional information on I/A Series control databases, see Integrated Control Software Concepts (B0193AW) and Integrated Control Block Descriptions (B0193AX).

GetServerName page 79

GetServerTimeout page 80

GetServerType page 81

GetTimeUsage page 86

BOOL IPAddress page 87

UINT IPAddress page 87

IsOffPlatform page 89

IsServerOK page 90

SetServerTimeout page 102

Method Page

GetAllBlocks page 42

GetAllCompounds page 42

GetBlkDescription page 43

GetBlockCompounds page 44

GetBlockParams page 44

GetCompBlockAndType page 45

GetCompoundBlocks page 46

GetStationCompounds page 83

GetStations page 83

Method Page13


Data Object Access MethodsThese 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.

File Access MethodsThese methods include identifying directories and files, and reading and writing files.

Method PageAddMultipleObjects page 19

AddObject page 22

dqObjectChange page 34

EngUnits page 34

FetchObjectIndex page 36

FetchObjectName page 36

FormatData page 38

FormatDataAndTimeStamp page 39

GetObjectCount page 75

MultipleObjectWrite page 91

ObjectRange page 92

ObjectRead page 92

ObjectReadAll page 94

ObjectType page 94

ObjectWrite page 95

RemoveObject page 100

RemoveObjects page 100

Method PageIsDir page 87

GetDirList page 47

FileRead page 37

GetFile page 48

PutFile page 96

FileStat page 38

GetServerDir page 77

GetServerBinDir page 77

GetServerInstDir page 79

MakeSystemCall page 9014


FoxAPI Data Sets MethodsThe 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 Users Guide (B0193UD).

Historian Access MethodsThe 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 PageCloseFoxAPISet page 24

GetMaxSet page 70

GetSetItemNames page 82

GetSetNames page 82

OpenFoxAPISet page 96

Method PageEnumServerHistorians page 35

GetHistArchiveGroupsI/A Series Historian only

page 61

GetHistData page 61

GetHistGroups page 65

GetHistGrpMembers page 66

GetHistItemList page 67

GetHistOperations page 68

GetMessageData page 71

GetMessageGroup page 74

GetTimeLinearData page 84

IsFoxHistory page 88

IsInHistorian page 89

WriteMDEData page 10415


AIM*Historian Only Access MethodsThe 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.

CDataElement Class MethodsThe CDataElement class has fourteen methods. These are described in Chapter 5 CDataEle-ment Class Methods Reference.

Method PageConfigureFoxHistory page 24

CreateEventMsgDef page 32

FoxHistSystem page 40

GetFoxHistGroups page 50

GetFoxHistMessageColumns page 50

GetFoxHistMessageData page 51

GetFoxHistMessageGroupKeys page 54

GetFoxHistoryConfigSessionRTPNames page 55

GetFoxHistRTPDefinition page 56

GetFoxHistRTPValues page 59

GetHistVersion page 69

GetMsgGroupAndName page 74

PutFoxHistRTPValue page 98

SearchFoxHistRTPNames page 101

WriteEventMsgData page 10316


Putting the Application into ProductionWhen 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.

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.

apiserv34.dll Runtime dynamic link library (DLL).

MFC100.dll and MSVCR100.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.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.

NOTEThe descriptions included in this section refer to AIM*Historian names of compo-nents, attributes and other elements, for example, FH_COLLECTOR_NSIZ.

AddMultipleObjects

SynopsisBOOL 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 only2 = 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 elementor 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 C 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 valueor 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 C

DescriptionThe 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-1AISnet 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 noindexbadaccinvdnwinvdelAN_ALLOCATION_ERRORdupindexsucces

0

somerr_w nowriteobj 0

succes succes 021


NOTEWhen 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.

NOTEWhen you configure Multiples in the an_init.cfg initialization file and call the Add-MultipleObjects 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 ValuesAdds 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

AddObject

SynopsisBOOL 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.22


DescriptionThe AddObject method establishes a link with the server for the specified data object. This linkage is required for the following methods:

FetchObjectIndex ObjectReadAll dqObjectChange

ErrorsSee Appendix A Error Messages for error codes and corresponding messages.

Return ValuesTrue if successful.

False if error.

See Also AddMultipleObjects GetObjectCount RemoveObjects

int accessType = 1 Specifies an access type, one per object: 1 = read only2 = read/writeThe 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


RemoveObject FetchObjectIndex ObjectReadAll dqObjectChange

CloseFoxAPISet

SynopsisBOOL CloseFoxAPISet(LPCTSTR set_name);

DescriptionThe CloseFoxAPISet method closes a FoxAPI data set.


Return ValuesTrue if successful.False if error.

See Also GetMaxSet GetSetNames GetSetItemNames OpenFoxAPISet

ConfigureFoxHistoryAIM*Historian instances only

SynopsisBOOL ConfigureFoxHistory(int nFhsd, LPCTSTR szAction, LPCTSTR szComponent,LPCTSTR szComponentName, LPCTSTR szAttribute, LPTSTR szValue, int &nIndicator);

LPCTSTR set_name Specifies the set to be closed.24


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 27.

LPCTSTR szComponentName Specifies the null-terminated name of the AIM*Historian component.See Additional Information on Variables on page 27 for more details.

LPCTSTR szAttribute Specifies the null-terminated, case-insensitive attri-bute type of up to FH_ATTR_NAME_NSIZ char-acters, 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 Users Guide (B0193YL) for tables showing the available attri-butes for each type of component, attribute default values, and supported actions for each attribute.25


DescriptionThe 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 Users Guide (B0193YN) and the AIM*Historian Users 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 Users 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 Users Guide (B0193YL).

LPCTSTR szValue If action is FH_ACT_PUT or FH_ACT_MOD, value specifies the attributes null-terminated value as an ASCII string.If action is FH_ACT_GET, value returns the attri-butes 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 27 for more details.26


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 29.

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.

NOTEIf 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.27


You can create another instance like an existing one. See the description of the LIKE attribute in Appendix E AIM*Historian Component Attri-butes in the AIM*Historian Users 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 AIM*Historian Users Guide (B0193YL).

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, attri-bute 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 , attribute is FH_ATTR_DEFN, and value is as defined in Appendix E AIM*Historian Component Attributes in the AIM*His-torian Users Guide (B0193YL). Message definition attributes act somewhat like components, because you add, and can retrieve, definitions (rather than just one attribute value).

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 28


Appendix E AIM*Historian Component Attributes in the AIM*Historian Users Guide (B0193YL).

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.

NOTEMessage 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.

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):29


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 attri-

bute if of type int or long.

The indicator is ignored for all other actions.



False if error; look at reterr for more detail.

See Also GetFoxHistoryConfigSessionRTPNames GetFoxHistRTPValues GetFoxHistRTPDefinition WriteEventMsgData30


ConnectToServer

Synopsisint ConnectToServer(LPCTSTR APAlias, LPCTSTR szPackage = NULL);

NOTEszPackage is reserved for Invensys use. Do not pass this variable.

DescriptionThe 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.


Return ValuesTrue 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

ConnectToServerByName

SynopsisBool ConnectToServerByName(LPCTSTR NetworkName);

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.

LPCTSTR NetworkName Specifies the server by its IP name.31


DescriptionThe ConnectToServer method adds and establishes a connection to the server defined in the TCPIP section of the an_init.cfg file to this class.


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 ConnectToServer GetServerInfo GetServerStatus ReconnectToServer

CreateEventMsgDefAIM*Historian instances only

SynopsisBOOL CreateEventMsgDef(LPCTSTR Historian, LPCTSTR MessageTable, CStringArray& ColumnList, CStringArray & ColDataTypes, CDWordArray & ColLengths);

DescriptionCreateEventMsgDef 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 Users Guide (B0193YL) for additional information on the event message configuration.


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.32


Return ValuesThe message is added to the message configuration file, hist_message.cfg, if successful.

False if error.

See Also WriteEventMsgData

DisconnectFromServer

SynopsisVoid DisconnectFromServer(void);

DescriptionThe 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.


Return ValuesNo 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.

NOTEIf 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 ReconnectToServer ConnectToServerByName33


dqObjectChange

SynopsisBOOL dqObjectChange(CObArray & ChangedData);

DescriptionThe 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).

NOTEIt is the programmers responsibility to release (delete) the array elements (CDataElements).



False if error.

See Also ObjectRead ObjectReadAll

EngUnits

SynopsisBOOL EngUnits(LPCTSTR szName, CString & szEngUnits);

DescriptionThe EngUnits method finds the Engineering Units for a defined object name.

CObArray ChangedData An array of new values in the CDX.

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.34



Return ValuesTrue if object found and values passed to szEngUnits.

False if Error.

See Also ObjectRange ObjectType

EnumServerAlias

SynopsisBOOL EnumServerAlias(CStringList & szServerEntry);

DescriptionThe EnumServerAlias method fills the supplied buffer with server alias names.


Return ValuesTrue if servers found and passed to szServerEntry.

False if no servers found.

EnumServerHistorians

SynopsisBOOL EnumServerHistorians(CStringList & histlist);

DescriptionThe EnumServerHistorian method fills the supplied buffer with available historian names.


CStringList szServerEntry Contains the list of available/configured servers.

CStringList histlist Contains the list of available historian names.35


Return ValuesTrue if historian names request completed.

False if error.

See Also IsFoxHistory IsInHistorian

FetchObjectIndex

SynopsisBOOL FetchObjectIndex(LPCTSTR szName, int * nIndex);

DescriptionWhen an object is added, an index is created for that object. FetchObjectIndex gets the index number for specified object name.


Return ValuesTrue if index to object is found.

False if error.

See Also FetchObjectName AddMultipleObjects Remove Objects Remove Object ObjectReadAll

FetchObjectName

SynopsisBOOL FetchObjectName(CString &szName, int nIndex);


int * nIndex Object index for the specified name.36


DescriptionWhen an object is added, an index is created for that object. FetchObjectName finds the Object Name for the specified index number.


Return ValuesTrue if object found for specified index.

False if error.

See Also AddMultipleObjects Remove Objects Remove Object FetchObjectIndex ObjectReadAll

FileRead

SynopsisBOOL FileRead(LPCTSTR iafile, long offset, long numchar, char * buffer,long * nRetLen);

DescriptionThe FileRead method retrieves data about the specified file.


CString szName Object name for the specified index.

int nIndex Specifies the index of the object to be found.

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.37


Return ValuesThe contents of the buffer and how much of the buffer is used if successful.

False if error.

See Also GetFile

FileStat

SynopsisBOOL FileStat(LPCTSTR szIAFile, long & filesize, CTime & modtime,CTime & createtime);

DescriptionThe FileStat method returns the file size, modification time, and the creation time for the specified file.


Return ValuesReturns the file size, modification time, and the creation time if successful.

False if error.

See Also GetDirList IsDir

FormatData

SynopsisBOOL FormatData(LPCTSTR szName, Cstring & szItemValue, long value,int status);

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.38


DescriptionThe FormatData method formats the specified objects 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.



False if error.

FormatDataAndTimeStamp

SynopsisBOOL FormatDataAndTimeStamp(LPCTSTR szName, CString & szItemName, long value, int status, time_t * ts_utc, int * ts_msec, CString & szTimeStamp, int * nSource);


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.


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.

time_t * ts_utc UTC time associated with object value in seconds, from CDataElement.

int * ts_msec Millisecond associated with object value, from CDataElement.39


DescriptionThe FormatDataAndTimeStamp method formats the specified objects value and status into one string and the objects 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.



False if error.

FoxHistSystemAIM*Historian instances only

SynopsisBOOL FoxHistSystem(LPCTSTR szAction, LPCTSTR szAttribute,CString &sValue, UINT maxLen = 512);

DescriptionFor Invensys use only.


GetAccessInfo

SynopsisWORD GetAccessInfo(void);

CString szTimeStamp Returns the time stamp, adjusted for local time, in the form MM/DD/YY_hh:mm:ss.ddd where: MM = monthDD = dayYY = yearhh = hourmm = minutess = secondddd = millisecond.

int * nSource Source of the time stamp: 1 = from the I/A Series system2 = from the API3 = from the client application.40


DescriptionThe 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.


Return ValuesAccess code is successful.

False if error.

GetAliasPath

SynopsisCString GetAliasPath(void);

DescriptionThe 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.)


Return ValuesA string with the Path Alias directory entry point if successful.

False if error.

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.41


GetAllBlocks

SynopsisBOOL GetAllBlocks(CStringList * slStations, CStringList & slBlocks,BOOL bType = FALSE);

DescriptionThe GetAllBlocks method fills the supplied CStringList with all block names or block types in the specified stations depending upon the bType specified.


Return ValuesBlock names or block types if successful.

False if error.

See Also GetAllCompounds GetBlkDescription GetBlockCompounds GetBlockParams GetCompBlockAndType GetCompoundBlocks

GetAllCompounds

SynopsisBOOL GetAllCompounds(CStringList * slStations, CStringList & slCompounds);

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.

CStringList * slStations A list

AIM*AT™Suite NetAPI MFC Class User’s Guide

Documents

invensys systems

invensys logo

supplied software

software media

copyrighted software

trademarks of invensys

license provisions

copyright informationbefore