Instruction Exaquantum API Reference Manual

Manual
IM 36J04A14-01E

IM 36J04A14-01E
Yokogawa December 28 2005
7th Edition Issue 1
Exaquantum API Reference Manual i

Copyright and Trademark Notices

2006 Yokogawa Electric Corporation

All Rights Reserved

All rights are reserved in this document, which is the property of Yokogawa Electric
Corporation. Information contained herein is the property of Yokogawa Electric
Corporation.

Unless agreed in writing by Yokogawa Electric Corporation, the licensee shall not remove,
release, disclose, reveal, copy, extract all or part of the documentation.

Trademark Acknowledgements

Exaquantum, Exaopc and CENTUM are trademarks of Yokogawa.

Microsoft, Windows, Windows 2000, Windows XP, Windows Server 2003, Microsoft
Word, Microsoft Excel, Microsoft Office 97, Microsoft Office 2000, Microsoft Office XP,
Microsoft Office 2003 Visual Basic, Visual C++, SQL Server, ActiveX and .NET are either
registered trademarks or trademarks of Microsoft Corporation in the United States and/or
other countries.

Exaquantum uses Microsoft SQL Server as part of an Integrated Value Added Solution.

Adobe and Acrobat are registered trademarks of Adobe Systems Incorporated, and registered
within particular jurisdictions.

Ethernet is a registered trademark of XEROX Corporation.

Basic Scripting Engine provided by Cypress Software Inc., Copyright 1993 2000, all rights
reserved.

All other company and product names mentioned in this manual are trademarks or registered
trademarks of their respective companies.

We do not use TM or to indicate trademarks or registered trademarks in this manual.

IM 36J04A14-01E 7th Edition Issue 1 December 28 2005-08

ii Contents

Highlights

The Highlights section gives details of the changes made since the previous issue of this
document.

Summary of Changes

This is the 7th Edition, Issue 1, Revision 8 of the document.

Detail of Changes

The changes are as follows.

Chapter/Section/Page Change
14.2 Added and section numbers are changed.
15.1 Added and section numbers are changed.
Chapter 17 Newly added and Chapter numbers of later chapters are
changed.
23.2 Added description
23.8 Added and section numbers are changed.
Chapter 24 Newly added.
24.5 Signatures and parameters in DeleteTag Method and
DeleteFolder Method changed.

IM 36J04A14-01E 7th Edition Issue 1 December 28 2005-08

Exaquantum API Reference Manual iii

Exaquantum Document Set

The documents available for Exaquantum are:

Exaquantum General Specification (GS 36J04A10-01E)

Exaquantum Technical Information (TI 36J04A10-01E)

Exaquantum/PIMS User's Manual (IM 36J04A11-01E)

Exaquantum/Explorer User's Manual Volume 1

General Information (IM 36J04A12-01E)

Exaquantum/Explorer User's Manual Volume 2

Custom Controls (IM 36J04A12-02E)

Exaquantum/Explorer User's Manual Volume 3

Microsoft Excel Reports (IM 36J04A12-03E)

Exaquantum/Explorer User's Manual Volume 4

Advanced Configuration (IM 36J04A12-04E)

Exaquantum Installation Guide (IM 36J04A13-01E)

Exaquantum API Reference Manual

(IM 36J04A14-01E)

Exaquantum Engineering Guide Volume 1

Administration (IM 36J04A15-01E)

Exaquantum Engineering Guide Volume 2

Network Configuration (IM 36J04A15-02E)

Exaquantum Engineering Guide Volume 3

Support Tools (IM 36J04A15-03E)

Exaquantum Engineering Guide Volume 4

Web Authoring (IM 36J04A15-04E)

IM 36J04A14-01E 7th Edition Issue 1 December 28 2005-08

iv Contents

Table of Contents

Chapter 1 Introduction ...........................................................................................................1-1

1.1 Summary .......................................................................................................................... 1-1
Chapter 2 Using the Exaquantum APIs ................................................................................2-1
2.1 COM API ......................................................................................................................... 2-1
2.2 OPC Server API ............................................................................................................... 2-1
2.3 .NET API.......................................................................................................................... 2-1
Chapter 3 Introduction to the COM API Example Chapters .............................................3-1
Chapter 4 Common Activities ................................................................................................4-1
4.1 Accessing the API Objects............................................................................................... 4-1
4.2 Accessing Multiple Exaquantum Servers......................................................................... 4-2
4.3 Resolving a Path to an Item Id ......................................................................................... 4-3
4.4 Browsing the Role based namespace (RBNS) ................................................................. 4-4
4.5 Obtaining an OPCAEPumpHistId for a specific OPC Gateway ...................................... 4-5
Chapter 5 Reading the Latest Item Value.............................................................................5-1
5.1 Synchronous Read............................................................................................................ 5-1
5.2 Asynchronous Read ......................................................................................................... 5-2
Chapter 6 Reading the History of Item Values.....................................................................6-1
6.1 Synchronous Read............................................................................................................ 6-1
6.2 Asynchronous Read ......................................................................................................... 6-2
Chapter 7 Setting a Filter and Reading the Results .............................................................7-1
7.1 Resolution filtering algorithm .......................................................................................... 7-1
7.2 Aggregation calculations.................................................................................................. 7-2
7.3 Example code ................................................................................................................... 7-4
Chapter 8 Writing Item Values..............................................................................................8-1
Chapter 9 Accessing Exaquantum Server(s) through RBNS ..............................................9-1
9.1 Reading Data .................................................................................................................... 9-1
9.2 Writing Data..................................................................................................................... 9-2
Chapter 10 Reading the History of Alarm and Events ........................................................10-1
10.1 Synchronous Read.......................................................................................................... 10-1
10.2 Asynchronous Read ....................................................................................................... 10-3
Chapter 11 Conducting Recalculation and Re-aggregation ................................................11-1
11.1 Concept of Recalculation ............................................................................................... 11-1
11.2 Recalculation Engine...................................................................................................... 11-2
11.3 Introduction to Recalculation API.................................................................................. 11-3

IM 36J04A14-01E 7th Edition Issue 1 December 28 2005-08

Exaquantum API Reference Manual v

11.4 Notes on Minimum and Maximum aggregation results................................................. 11-4

11.5 Sample code ................................................................................................................... 11-4
Chapter 12 Setting Tags and Function Blocks Offline.........................................................12-1
Chapter 13 Introduction to the API Reference Chapters....................................................13-1
Chapter 14 Session Object API Reference ............................................................................14-1
14.1 Browser Property ........................................................................................................... 14-1
14.2 NamespaceBuilder Property........................................................................................... 14-1
14.3 NetworkError Event Method.......................................................................................... 14-1
14.4 QuantumShutdown Event Method ................................................................................. 14-2
Chapter 15 Session2 Object API Reference ..........................................................................15-1
15.1 ServerName Property ..................................................................................................... 15-1
15.2 IsConnected Method ...................................................................................................... 15-1
15.3 QuantumAvailable Event Method.................................................................................. 15-1
15.4 ConnectState Method ..................................................................................................... 15-2
Chapter 16 Browser Object API Reference ..........................................................................16-1
16.1 Browse Method .............................................................................................................. 16-1
16.2 PathToMetadata Method ................................................................................................ 16-3
16.3 ItemIdToPath Method .................................................................................................... 16-3
16.4 PathToIds Method.......................................................................................................... 16-4
16.5 WritePlotLimits Method ................................................................................................ 16-6
Chapter 17 RBNSBrowseEx Object API Reference.............................................................17-1
17.1 Browse Method .............................................................................................................. 17-1
17.2 PathToMetadata Method ................................................................................................ 17-3
Chapter 18 QDataAccess Object API Reference..................................................................18-1
18.1 Add Method ................................................................................................................... 18-1
18.2 Cancel Method ............................................................................................................... 18-1
18.3 Count Property ............................................................................................................... 18-1
18.4 Execute Method ............................................................................................................. 18-2
18.5 Item Method ................................................................................................................... 18-2
18.6 OnData Event Method.................................................................................................... 18-3
18.7 OnError Event Method................................................................................................... 18-4
18.8 ReadValue Method......................................................................................................... 18-5
18.9 Remove Method ............................................................................................................. 18-6
18.10 SetProcessOptions Method ............................................................................................ 18-6
18.11 SetQueryTimes Method ................................................................................................. 18-8
18.12 SetFilterParameters Method........................................................................................... 18-9

IM 36J04A14-01E 7th Edition Issue 1 December 28 2005-08

vi Contents

18.13 SetSession Method ....................................................................................................... 18-12

18.14 WriteValue Method...................................................................................................... 18-12
18.15 WriteHistoryValue Method.......................................................................................... 18-13
Chapter 19 QDataAccessMulti Object API Reference ........................................................19-1
19.1 Add Method ................................................................................................................... 19-1
19.2 Clear Method.................................................................................................................. 19-1
19.3 Cancel Method ............................................................................................................... 19-2
19.4 ReadValue Method......................................................................................................... 19-2
19.5 SetQueryTimes Method ................................................................................................. 19-3
19.6 SetReportTimes Method ................................................................................................ 19-4
19.7 SetProcessOptions Method ............................................................................................ 19-5
19.8 SetFilterParameter Method ............................................................................................ 19-6
19.9 AddWrite Method .......................................................................................................... 19-6
19.10 ExecuteWrite Method .................................................................................................... 19-7
19.11 CancelWrite Method ...................................................................................................... 19-8
19.12 Remove Method ............................................................................................................. 19-8
19.13 Execute Method ............................................................................................................. 19-8
19.14 OnData Event Method.................................................................................................... 19-9
19.15 OnError Event Method................................................................................................. 19-10
Chapter 20 QAEAccess Object API Reference ....................................................................20-1
20.1 Add Method ................................................................................................................... 20-1
20.2 Cancel Method ............................................................................................................... 20-1
20.3 ClearFilterOptions Method ............................................................................................ 20-1
20.4 Count Property ............................................................................................................... 20-2
20.5 Execute Method ............................................................................................................. 20-2
20.6 Item Method ................................................................................................................... 20-2
20.7 OnAE Event Method...................................................................................................... 20-3
20.8 OnError Event Method................................................................................................... 20-4
20.9 ReadValue Method......................................................................................................... 20-5
20.10 Remove Method ............................................................................................................. 20-6
20.11 SetFilterOptions Method ................................................................................................ 20-6
20.12 SetProcessOptions Method ............................................................................................ 20-7
20.13 SetQueryTimes Method ................................................................................................. 20-8
20.14 SetSession Method ......................................................................................................... 20-8
Chapter 21 QQualityHelper Object API Reference.............................................................21-1
21.1 IsBad Method ................................................................................................................. 21-1

IM 36J04A14-01E 7th Edition Issue 1 December 28 2005-08

Exaquantum API Reference Manual vii

21.2 IsGood Method............................................................................................................... 21-1

21.3 IsUncertain Method........................................................................................................ 21-2
21.4 IsAssumed Method......................................................................................................... 21-2
21.5 Quality Method .............................................................................................................. 21-2
21.6 QualityText Method ....................................................................................................... 21-3
21.7 SecondaryQuality Method ............................................................................................. 21-3
21.8 SecondaryQualityText Method ...................................................................................... 21-4
21.9 RawQuality Method ....................................................................................................... 21-5
21.10 QualityTexts Property .................................................................................................... 21-5
21.11 SecondaryQualityTexts Property ................................................................................... 21-5
Chapter 22 Recalculation API Reference..............................................................................22-1
22.1 NewRecalcJobDefinition method .................................................................................. 22-1
22.2 SetRecalcInputItems method.......................................................................................... 22-2
22.3 DeleteRecalcJobDefinition method................................................................................ 22-3
22.4 RecalcJobName property ............................................................................................... 22-3
22.5 SetRecalcTimes method................................................................................................. 22-4
22.6 Recalc method................................................................................................................ 22-4
22.7 Commit method.............................................................................................................. 22-6
22.8 Cancel method................................................................................................................ 22-7
22.9 RecalcInputItems property ............................................................................................. 22-7
22.10 RecalcJobDefinition property ........................................................................................ 22-8
22.11 Reason property ............................................................................................................. 22-8
22.12 GetDependentItems method........................................................................................... 22-9
22.13 GetRecalcJobs method ................................................................................................. 22-10
Chapter 23 Exaquantum OPC Server API ...........................................................................23-1
23.1 Introduction .................................................................................................................... 23-1
23.2 OPC Compliance............................................................................................................ 23-1
23.3 IOPCCommon Interface................................................................................................. 23-4
23.4 Historical Data Access ................................................................................................... 23-5
23.5 IOPCHDA_Browser interface........................................................................................ 23-9
23.6 IOPCHDA_SyncRead interface................................................................................... 23-10
23.7 Exaquantum OPC HDA Service .................................................................................. 23-12
23.8 IOPCHDA_SyncUpdate Interface ............................................................................... 23-13
23.9 Data Access.................................................................................................................. 23-14
23.10 IOPCItemProperties interface ...................................................................................... 23-16
23.11 IOPCBrowseServerAddressSpace interface ................................................................ 23-18

IM 36J04A14-01E 7th Edition Issue 1 December 28 2005-08

viii Contents

23.12 IOPCItemMgt interface................................................................................................ 23-20

23.13 IOPCGroupStateMgt interface ..................................................................................... 23-21
23.14 IOPCSyncIO interface.................................................................................................. 23-22
23.15 IOPCAsyncIO2 interface ............................................................................................. 23-23
23.16 IOPCDataCallback client callback interface ................................................................ 23-24
23.17 Exaquantum Server-specific error codes...................................................................... 23-25
Chapter 24 Exaquantum.NET API........................................................................................24-1
24.1 Installation Types for .NET API .................................................................................... 24-4
24.2 Exaquantum .NET API .................................................................................................. 24-4
24.3 Session Interface ............................................................................................................ 24-6
24.4 AggregationPeriodManager interface ............................................................................ 24-6
24.5 TemplateManager interface.......................................................................................... 24-13
24.6 TagManager interface .................................................................................................. 24-20
24.7 Operation interface....................................................................................................... 24-33
24.8 Enumerations................................................................................................................ 24-35
24.9 Definition of Structures................................................................................................ 24-42
24.10 Error Code List............................................................................................................. 24-53

IM 36J04A14-01E 7th Edition Issue 1 December 28 2005-08

Exaquantum API Reference Manual 1-1

Chapter 1 Introduction
This document serves as a reference document describing the Exaquantum Application
Programming Interfaces (APIs).

Two types of Interface are provided, COM interface and .NET interface. The Summary
section below describes what is available for each type.

The COM Interfaces are standard COM Automation Interfaces and are available to Windows
developers who develop applications in languages such as Microsoft Visual Basic (VB) and
Microsoft Visual C++ (VC++).

The .NET Interfaces are available to any .NET language, such as Microsoft C# and
Microsoft VB .NET.

The definitions of the COM APIs given in this document are in a VB style, but the APIs are
available to other languages including VC++.

This document is arranged in two broad sections, a section giving examples of each of the
data exchanges available via the APIs and a reference section giving details of the APIs.

1.1 Summary
APIs are available for the following:

COM APIs:

Reading the latest RTDB Item values in both a synchronous and asynchronous way

Reading the history of RTDB Item values in both a synchronous and asynchronous way

Writing to RTDB Item values

Reading the history of Alarm and Event data in both a synchronous and asynchronous
way.

Reading and writing item values through RBNS (Role Based Namespace)

Conducting recalculation and re-aggregation

Setting Tags and Function Blocks offline

IM 36J04A14-01E 7th Edition Issue 1 December 28 2005-08

1-2 Chapter 1 Introduction

OPC Server APIs:

Tag Browsing

Synchronous Reading and Writing of Live Data

Asynchronous Reading and Writing of Live Data

Synchronous Reading and Writing of History Data

NET APIs:

Management of Production Calendar and Tag Templates

Management of Tags and Folders

IM 36J04A14-01E 7th Edition Issue 1 December 28 2005-08

Exaquantum API Reference Manual 2-1

Chapter 2 Using the Exaquantum APIs

2.1 COM API
The Exaquantum COM APIs can be used on any PC that has either the Exaquantum Server
or Client components installed.

Access to the APIs is via the QuantumAutomation 1.0 Type Library installed as
'\Yokogawa\Exaquantum PIMS\System\QuantumAutomation.dll. In VB first make a
reference to this type library in your project before trying to use the API functions.

Note: This type library exposes more functionality than is described in this document.
These additional functions are not supported for this release of Exaquantum.

2.2 OPC Server API

The Exaquantum OPC Server APIs can be used on any PC that has the OPC Server client
libraries installed.

2.3 .NET API

The Exaquantum .NET APIs can be used on any PC that has either the Exaquantum Server
or Client components installed.

Access to the API is via the following two libraries:

Yokogawa.Exa.Exaquantum.Common.dll defines structures and enumerations

Yokogawa.Exa.Exaquantum.dll defines interfaces and methods

These are located under the '\Yokogawa\Exaquantum PIMS\System folder.

IM 36J04A14-01E 7th Edition Issue 1 December 28 2005-08

2-2 Chapter 2 Using the Exaquantum APIs

This page intentionally left blank

IM 36J04A14-01E 7th Edition Issue 1 December 28 2005-08

Exaquantum API Reference Manual 3-1

Chapter 3 Introduction to the COM API Example Chapters

The following chapters give simple examples of how to perform the key operations available
via the API. The examples are taken from three VB projects that are installed with the
Exaquantum documentation, as follows:

Table 3-1

Install Place Project Contents

\Documentation\SampleCode\ Examples of reading and writing the latest Item

QDataAccessSample\QDALive value, both synchronously and asynchronously.

\Documentation\SampleCode\ Examples of reading Item value and Alarm and

QDataAccessSample\QDAHistory Event history, both synchronously and
asynchronously.

\Documentation\SampleCode\ Examples of reading the latest and historical Item

QDataAccessSample\QDAMultiServer values from multiple Exaquantum servers.

IM 36J04A14-01E 7th Edition Issue 1 December 28 2005-08

3-2 Chapter 3 Introduction to the API Example Chapters

This page intentionally left blank

IM 36J04A14-01E 7th Edition Issue 1 December 28 2005-08

Exaquantum API Reference Manual 4-1

Chapter 4 Common Activities

This chapter explains the common activities required for all API calls.

4.1 Accessing the API Objects

Before a client program can use any API it must first get an Exaquantum Session object. The
Session object allows access to all the other API functions.

It is good programming practice for each client to obtain a single Session object, and keep
hold of this for the entire time that access to Exaquantum API functions is required. This
will help clients respond to the various events available on Session, such as NetworkError; .

An Example of how to obtain and use the Session Object:

' Get a session object
Set objSession = New QUANTUMAUTOMATIONLib.Session

' Get a DataAccess object.

Set objDataAccess = New QUANTUMAUTOMATIONLib.QDataAccess

' Get the Browser Object from Session.

Set objBrowser = objSession.Browser

' Give the Session Pointer to the DataAccess object.

objDataAccess.SetSession objSession

' Get a Alarm & Event Access object.

Set objAEAccess = New QUANTUMAUTOMATIONLib.QAEAccess

' Give the Session Pointer to the Alarm & Event Access object.
objAEAccess.SetSession objSession

' Get a QualityHelper object

Set objQualityHelper = New QUANTUMAUTOMATIONLib.QQualityHelper

' Do some work ..

' I've finished so tidy up.

Set objDataAccess = Nothing
Set objAEAccess = Nothing
Set objBrowser = Nothing
Set objSession = Nothing
Set objQualityHelper = Nothing

IM 36J04A14-01E 7th Edition Issue 1 December 28 2005-08

4-2 Chapter 4 Common Activities

4.2 Accessing Multiple Exaquantum Servers

In order to access multiple Exaquantum servers a client must first create an Exaquantum
Session2 object for each server. The Session2 object allows the client to specify the machine
name of the Exaquantum server to connect to using its ServerName property. ServerName
may only be set once for a Session2 object. Unlike the single-server Session object, a
Session2 object can be set to connect to an Exaquantum server that is not currently running.
A client can test whether the Exaquantum server is available by calling the Session2
IsConnected() method.

It is good programming practice for each client to obtain a single Session2 object for each
Exaquantum server, and retain these for the entire time that access to Exaquantum API
functions is required. This will help clients respond to the various events available on
Session2, such as QuantumShutdown and QuantumAvailable.

An Example of how to obtain and use the Session2 Object:

' Get a Session2 object for the first server.
Set objSession1 = New QUANTUMAUTOMATIONLib.Session2

' Tell Session2 which Exaquantum server to connect to.

objSession1.ServerName = Server1

' Get a Session2 object for the second server.

Set objSession2 = New QUANTUMAUTOMATIONLib.Session2

' Tell Session2 which Exaquantum server to connect to.

objSession2.ServerName = Server2

' Check that both Exaquantum servers are running.

If Not objSession1.IsConnected() Or Not objSession2.IsConnected() Then
Exit Sub
End If

' Get a DataAccess object for the first server.

Set objDataAccess1 = New QUANTUMAUTOMATIONLib.QDataAccess

' Give the Session Pointer to the DataAccess object.

objDataAccess1.SetSession objSession1

' Get a DataAccess object for the second server.

Set objDataAccess2 = New QUANTUMAUTOMATIONLib.QDataAccess

' Give the Session Pointer to the DataAccess object.

objDataAccess2.SetSession objSession2

' Get a Browse object to the first server

Set objBrowser1 = objSession1.Browser

' Get a Browse object to the second server

Set objBrowser2 = objSession2.Browser

IM 36J04A14-01E 7th Edition Issue 1 December 28 2005-08

Exaquantum API Reference Manual 4-3

4.3 Resolving a Path to an Item Id

In order to read or write data to Items it is first necessary to obtain an Item Id. An Item Id is a
64 bit number represented as an 8 element byte array that is used to uniquely identify an
Item in the RTDB.

An Item Id can be obtained from an Item Path by using the Browser PathToMetaData
method as follows:
Dim sItemsArray(1) As String
Dim lNumItems As Long
Dim Count As Long
Dim vItemID As Variant
Dim rsBrowseResults As ADODB.Recordset

' Define the Items required by their paths.

sItemsArray(0) = "Root.Tag1.Value"
sItemsArray(1) = "Root.Tag1.Aggregations.Hour.Mean.Value"
lNumItems = 2

' Resolve the paths to Item Ids

Set rsBrowseResults = objBrowser.PathToMetaData(sItemsArray, lNumItems,
brDetail)

' Run through the Recordset returned from Browse and add check which
' is valid.
For Count = 1 To lNumItems
vItemID = rsBrowseResults!ItemID
If Not IsNull(vItemID) Then
' Do something with the Item ID..

Else
MsgBox "Path is invalid:" & sItemsArray(Count - 1)
End If
rsBrowseResults.MoveNext
Next Count

IM 36J04A14-01E 7th Edition Issue 1 December 28 2005-08

4-4 Chapter 4 Common Activities

4.4 Browsing the Role based namespace (RBNS)

Browsing of the namespace allows for all tags (or function blocks) under a specific folder to
be listed, so they may be used by an application:
Dim sPath As String
Dim sFilter As String
Dim sItemPath As String
Dim objRBNSBrowse As QUANTUMAUTOMATIONLib.RBNSBrowseEx
Dim rsRBNSBrowseResults As ADODB.Recordset

Set objRBNSBrowse = New QUANTUMAUTOMATIONLib.RBNSBrowseEx

' Specify the retrieved folder

sPath = "MyNamespace.Folder1"
' Specify the filter
sFilter = "*"

' Get the tags in the specified folder

Set rsRBNSBrowseResults = objRBNSBrowse.Browse(sPath, sFilter, brDetail)

' Iterate through the returned Recordset

While (rsRBNSBrowseResults.EOF <> True)
sItemPath = rsRBNSBrowseResults!Path

' Add the code using sItemPath here

rsRBNSBrowseResults.MoveNext
Wend

IM 36J04A14-01E 7th Edition Issue 1 December 28 2005-08

Exaquantum API Reference Manual 4-5

4.5 Obtaining an OPCAEPumpHistId for a specific OPC Gateway

In order to read Alarm and Event data it is first necessary to obtain an OPCAEPumpHistId.
An OPCAEPumpHistId is a 64-bit number represented as an 8-element byte array that is
used to uniquely identify the history stream for a particular OPC Gateway.

An OPCAEPumpHistId can be obtained from the QConfig database by executing a query to

the OPCServer table using ADO as follows:
Dim ConnectStr As String
Dim objConnection As ADODB.Connection
Dim objRecordset As ADODB.Recordset
Dim vAEId As Variant

' Make the Connect String

Set objConnection = New ADODB.Connection
ConnectStr = "Provider=sqloledb;" 'Provider
ConnectStr = ConnectStr + "Network Library=dbmssocn;" 'Network Library
ConnectStr = ConnectStr + "Server=;" 'Server Name
(Local)
ConnectStr = ConnectStr + "database=QConfig;" 'Database Name
ConnectStr = ConnectStr + "Trusted_Connection=yes" 'Make it trusted
'connection

'Connect to the database

objConnection.Open ConnectStr

' Run the SQL Script and get the recordset

Set objRecordset = New ADODB.Recordset
objRecordset.LockType = adLockOptimistic
objRecordset.Open "SELECT OPCAEPumpHistId FROM OPCServer WHERE Name = 'OPC
Gateway 1'", objConnection

'Check whether the Recordset is returned from query

If objRecordset.EOF Then
MsgBox "Invalid OPC Gateway name"
Exit Sub
End If

' Get the OPCAEPumpHistId (first row only for this example)
vAEId = objRecordset!OPCAEPumpHistId

'Check whether the OPC Gateway Alarm & Events Id is found

If Not IsNull(vAEId) Then
' Do something with the Alarm & Event ID..

Else
MsgBox "OPCAEPumpHistId is Null"
Exit Sub
End If

IM 36J04A14-01E 7th Edition Issue 1 December 28 2005-08

4-6 Chapter 4 Common Activities

This page intentionally left blank

IM 36J04A14-01E 7th Edition Issue 1 December 28 2005-08

Exaquantum API Reference Manual 5-1

Chapter 5 Reading the Latest Item Value

The latest, or most resent, value of an Item can be read in a one off, synchronous way or
continuously updated with changes to the latest value in an asynchronous way. In both cases,
reading an Item value is a two-stage process; first resolve the path to the Item required to an
Item ID, then use the DataAccess object to return the data.

5.1 Synchronous Read

This type of read is used when a one off request for the latest value is required. If the client
must be notified on an event basis each time the Item is updated then an Asynchronous read
should be used.

This example reads the current value for two items:

Dim rsBrowseResults As ADODB.Recordset
Dim sItemsArray(1) As String
Dim lNumItems As Long
Dim Count As Long
Dim vItemID As Variant
Dim vData As Variant
Dim vValue1, vValue2 As Variant
Dim lQuality1, lQuality2 As Long
Dim dTimeStamp1, dTimeStamp2 As Date

' Define the Items required by their paths.

sItemsArray(0) = "Root.Tag1.Value"
sItemsArray(1) = "Root.Tag1.Aggregations.Hour.Mean.Value"
lNumItems = 2

' Resolve the paths to Item Ids

Set rsBrowseResults = objBrowser.PathToMetaData(sItemsArray, lNumItems,
brDetail)

' Run through the Recordset returned from Browse and add the Item Ids
' to the DataAccess collection.
For Count = 1 To lNumItems
vItemID = rsBrowseResults!ItemID
If Not IsNull(vItemID) Then
' Add the item to the DataAccess collection
objDataAccess.Add vItemID
rsBrowseResults.MoveNext
Else
MsgBox "Path is invalid:" & sItemsArray(Count - 1)
Exit Sub
End If
Next Count

' Get the latest values of all Items in the collection.

vData = objDataAccess.ReadValue

' Get VTQ from the Variant Array for each Item
The order is not necessarily the order in which
they were added in.
vValue1 = vData(1, 0)(0, 0) Value
lQuality1 = vData(1, 0)(1, 0) Quality

IM 36J04A14-01E 7th Edition Issue 1 December 28 2005-08

5-2 Chapter 5 Reading the Latest Item Value

dTimeStamp1 = vData(1, 0)(2, 0) Timestamp

vValue2 = vData(1, 1)(0, 0) Value
lQuality2 = vData(1, 1)(1, 0) Quality
dTimeStamp2 = vData(1, 1)(2, 0) Timestamp

5.2 Asynchronous Read

This type of read is used when the client must be notified on an event basis each time the
Item is updated.

Note: For this type of read, the Data Access object must be defined 'With Events' as follows:
Dim WithEvents objDataAccess As QUANTUMAUTOMATIONLib.QDataAccess
This example is kept updated with the current value for two items. The first piece of code
registers the items and the second piece of code defines an event routine that will receive the
data:
Dim rsBrowseResults As ADODB.Recordset
Dim sItemsArray(1) As String
Dim lNumItems As Long
Dim Count As Long
Dim vItemID As Variant

' Define the Items required by their paths.

sItemsArray(0) = "Root.Tag1.Value"
sItemsArray(1) = "Root.Tag1.Aggregations.Hour.Mean.Value"
lNumItems = 2

' Resolve the paths to Item Ids

Set rsBrowseResults = objBrowser.PathToMetaData(sItemsArray, lNumItems,
brDetail)

' Run through the Recordset returned from Browse and add the Item Ids
' to the DataAccess collection.
For Count = 1 To lNumItems
vItemID = rsBrowseResults!ItemID
If Not IsNull(vItemID) Then
' Add the item to the DataAccess collection
objDataAccess.Add vItemID
rsBrowseResults.MoveNext
Else
MsgBox "Path is invalid:" & sItemsArray(Count - 1)
Exit Sub
End If
Next Count

' Call Execute on DataAccess object to read data Asnchronously

objDataAccess.Execute

This piece of code shows how to define an event routine that will receive the data. This will
be called once for each Item registered with the initial value then again on an item by item
basis as an item changes:
Private Sub objDataAccess_OnData(ByVal ItemID As Variant, ByVal
DataReturnType As QUANTUMAUTOMATIONLib.qdaDataReturnType, ByVal Data As
Variant)
Dim vValue As Variant

IM 36J04A14-01E 7th Edition Issue 1 December 28 2005-08

Exaquantum API Reference Manual 5-3

Dim lQuality As Long

Dim dTimeStamp As Date
Dim vItemID As Variant

' Read the Item Id for which this data is sent

vItemID = ItemID

' Get VTQ from the Variant Array for this Item.
vValue = Data(0, 0) Value
lQuality = Data(1, 0) Quality
dTimeStamp = Data(2, 0) Timestamp

End Sub

IM 36J04A14-01E 7th Edition Issue 1 December 28 2005-08

5-4 Chapter 5 Reading the Latest Item Value

This page intentionally left blank

IM 36J04A14-01E 7th Edition Issue 1 December 28 2005-08

Exaquantum API Reference Manual 6-1

Chapter 6 Reading the History of Item Values

The history of an item, for a given time period, can be read in a one off, synchronous way or
in an asynchronous way. In both cases, reading an Item value is a two-stage process; first
resolve the path to the Item required to an Item ID, then use the DataAccess object to return
the data.

6.1 Synchronous Read

This type of read is used when a client can be suspended while the read request is being
satisfied. If the client must continue execution and receive data as it is ready via an event,
then an Asynchronous read should be used.

This example reads the values for an item from History for the last 5 minutes:
Dim rsBrowseResults As ADODB.Recordset
Dim sItem As String
Dim lNumItems As Long
Dim Count As Long
Dim vItemID As Variant
Dim vData As Variant
Dim vValue As Variant
Dim lQuality As Long
Dim dTimeStamp As Date
Dim dQueryTime As Date

' Define the Items required by their paths.

sItem = "Root.Tag1.Value"
lNumItems = 1

' Resolve the paths to Item Id

Set rsBrowseResults = objBrowser.PathToMetaData(sItem, lNumItems,
brDetail)

' Using the Recordset returned from Browse add the Item Id
' to the DataAccess collection.
vItemID = rsBrowseResults!ItemID
If Not IsNull(vItemID) Then
' Add the item to the DataAccess collection
objDataAccess.Add vItemID
Else
MsgBox "Path is invalid:" & sItem
Exit Sub
End If

' Lets query for the last 5 minutes

dQueryTime = DateAdd("n", -5, Now)

' Set the QueryTimes on DataAccess object

objDataAccess.SetQueryTimes , dQueryTime

' Get the latest values of all Items in the collection.

vData = objDataAccess.ReadValue

IM 36J04A14-01E 7th Edition Issue 1 December 28 2005-08

6-2 Chapter 6 Reading the History of Item Values

' Loop through all the VTQs returned and store them
If Not IsNull(vData) Then
' Loop through the entire array and store the data
' NB: In this sample only the last data in the Array is stored when we
are out of the loop
For Count = 0 To UBound(vData(1, 0), 2)
vValue = vData(1, 0)(0, Count) Value
lQuality = vData(1, 0)(1, Count) Quality
dTimeStamp = vData(1, 0)(2, Count) Timestamp
Next Count
End If

6.2 Asynchronous Read

This type of read is used when client must continue execution and receive data as it is ready
via an event.

Note: For this type of read, the Data Access object must be defined 'With Events' as follows:
Dim WithEvents objDataAccess As QUANTUMAUTOMATIONLib.QDataAccess
This example receives values for an item from history for the past 5 minutes. The first piece
of code registers the items and the second piece of code defines an event routine that will
receive the data:
Dim rsBrowseResults As ADODB.Recordset
Dim sItem As String
Dim lNumItems As Long
Dim vItemID As Variant
Dim dQueryTime As Date

' Define the Items required by their paths.

sItem = "Root.Tag1.Value"
lNumItems = 1

' Resolve the paths to Item Ids

Set rsBrowseResults = objBrowser.PathToMetaData(sItem, lNumItems,
brDetail)

' Using the Recordset returned from Browse add the Item Id
' to the DataAccess collection.
vItemID = rsBrowseResults!ItemID
If Not IsNull(vItemID) Then
' Add the item to the DataAccess collection
objDataAccess.Add vItemID
Else
MsgBox "Path is invalid:" & sItem
Exit Sub
End If

' Lets query for the last 5 minutes

dQueryTime = DateAdd("n", -5, Now)

' Set the QueryTimes on DataAccess object

objDataAccess.SetQueryTimes , dQueryTime

' Call Execute on DataAccess object to read data asynchronously

objDataAccess.Execute

IM 36J04A14-01E 7th Edition Issue 1 December 28 2005-08

Exaquantum API Reference Manual 6-3

This piece of code shows how to define an event routine that will receive the data. This will
be called for multiple times until DataReturnType is qdaEnd for each Item registered:
Private Sub objDataAccess_OnData(ByVal ItemID As Variant, ByVal
DataReturnType As QUANTUMAUTOMATIONLib.qdaDataReturnType, ByVal Data As
Variant)
Dim vValue As Variant
Dim lQuality As Long
Dim dTimeStamp As Date
Dim vItemID As Variant
Dim Count As Long

' Read the Item Id for which this data is sent

vItemID = ItemID

' Loop through the entire array and store the data
' NB: In this sample only the last data in the Array is stored
' when we are out of the loop
If Not IsNull(Data) Then ' Ignore notification if Data is NULL
For Count = 0 To UBound(Data, 2)
vValue = Data(0, Count) Value
lQuality = Data(1, Count) Quality
dTimeStamp = Data(2, Count) Timestamp
Next Count
End If

' Check whether more data to come

If DataReturnType = qdaNew Then
MsgBox "First notification received"
ElseIf DataReturnType = qdaMoreRows Then
MsgBox "More notifications to be received"
ElseIf DataReturnType = qdaEnd Then
MsgBox "Last notification received"
End If

IM 36J04A14-01E 7th Edition Issue 1 December 28 2005-08

6-4 Chapter 6 Reading the History of Item Values

This page intentionally left blank

IM 36J04A14-01E 7th Edition Issue 1 December 28 2005-08

Exaquantum API Reference Manual 7-1

Chapter 7 Setting a Filter and Reading the Results

The filter allows you to reduce the amount of raw tag data returned by two methods:

Resolution filtering algorithm - Splitting the overall time period into smaller individual
periods for which minimum and maximum values will be returned.

Aggregation calculations - Apply some pre-processing to summarise the data using

defined statistical functions.

This method is defined on both the IQDataAccess and IQDataAccessMulti interfaces. Refer
to section 18.12 SetFilterParameters Method for more details.

7.1 Resolution filtering algorithm

For one item, the input parameters to the algorithm are:

Number of periods required (for example the number of horizontal pixels)

Start time of data

End Time of data

The algorithm then works on the resulting data, as follows:

1 A query is issued covering the duration between the two input parameters; Start time of
data and the End time of data.

2 The data returned by the query is time-sliced into periods. The number of periods being
determined by the Number of periods input parameter.

3 For each period, the points with the Maximum and Minimum values are extracted. These
points will be sent to the client application. The Timestamps sent will be those associated
with the Maximum and Minimum values in that period.

4 If a bounding value is requested, an extra period is created whose boundary time is the
start time of the query. The only point contained within this extra period is the bounding
value.
NOTES
1. If there is only one point within a period, then this point is sent to the client.

2. If there are no points within a period, then no data is sent to the client for this period.

3. For string data, an attempt will be made to convert them to a DOUBLE. If it

succeeds, these data will be included in the processing for minimum and maximum.

4. For any period, if there is a point with quality bad or uncertain shutdown, and whose
value is either:

IM 36J04A14-01E 7th Edition Issue 1 December 28 2005-08

7-2 Chapter 7 Setting a Filter and Reading the Results

greater than any maximum value with a good quality,

less than a minimum value with a good quality,

then this point is returned in addition to the max and /or min points having good
quality. This means up to four points can be returned from one period, two with good
quality, and two with bad or uncertain shutdown quality.

5. Data having a secondary quality of deleted, irrespective of the primary quality, will
be deleted by the filtering. A client receiving raw data never gets these points.

7.2 Aggregation calculations

The following form of aggregation calculations are supported.

Table 7-1

Type of data Types of Aggregation calculations

Continuation data Sum, Mean, Minimum, Maximum, StdDev, Spot

Discrete data Status count, OnTime

Aggregation types

This section describes the method used to calculate each types of aggregation.

Mean

The calculation of the Mean is based on the difference between the timestamp of the current
input notification and the equivalent timestamp form the previous input notification as
follows:

Mean = ( ( Mean * Ttotal ) + (( Vn-1 ) * ( Tn Tn-1 )) )/ ( Ttotal + ( Tn Tn-1 ) )

Where:

Mean Is the accumulating mean.

Ttotal Is the accumulating time for the input being valid i.e. its data quality was either
GOOD or Uncertain.

Vn-1 Is the value of the input at the last time notification.

Tn-1 Is the timestamp of the input at the last time notification.

Tn Is the timestamp of the input at this time notification.

Where:

Mean Is the mean value.

IM 36J04A14-01E 7th Edition Issue 1 December 28 2005-08

Exaquantum API Reference Manual 7-3

Ttotal Is the request time for the input being valid i.e. its data quality was either
GOOD or Uncertain.

Minimum

Determines the minimum value within the required period data. The timestamp indicates
when the minimum value was recorded

Maximum

Determines the maximum value within the required period data. The timestamp indicates
when the maximum value was recorded.

Standard deviation

The standard deviation builds upon the Mean calculation shown above:

SumOfXSquared = SumOfXSquared + ( ( Vn-1 )2 * ( Tn Tn-1 ) )

StdDev = Sqrt((( SumOfXSquared ) ( Ttotal * Mean2 )) / Ttotal 1)

Summation

There are two ways used to calculate the Summation that depend on the TimeFactor
configured for the aggregation calculation:

When TimeFactor > 0, Integration summation is used.

When TimeFactor = 0 , Simple summation is used.

These two methods are explained below.

TimeFactor > 0 (Integration Summation )

The time difference between the timestamp of the current input notification from the
timestamp of the previous input notification is used to calculate the contribution towards the
summation.

Sum = Sum + ( Vn-1 ) * ( Tn Tn-1 )

Where:

Sum Is the accumulating summation.

Vn-1 Is the value of the input at the final requirement time.

Tn-1 Is the timestamp of the input at the final requirement time or the timestamp
of the start of the current aggregation period if no notifications have been received
during the current period. T is measured in units of 100 nanoseconds.

Tn Is the timestamp of the input at this data.

IM 36J04A14-01E 7th Edition Issue 1 December 28 2005-08

7-4 Chapter 7 Setting a Filter and Reading the Results

At the end of the aggregation period, the summation is calculated as:

Summation = Sum / (10,000,000 * TimeFactor)

TimeFactor = 0 (Simple Summation)

At the beginning of the aggregation period the internal summation is reset to zero. As each
input notification arrives, it is added to the summation. The summation result is the
accumulated summation at the end of the aggregation period.

Spot value

By default, the value of the input at the end of the aggregation period. The value at the
beginning of the period may be selected by setting registry value
HKLM\Software\Quantum\Server\AggSpotValueAtPeriodStart to 1.

Count

Within the aggregation period under consideration, this represents the number of times the
input notification value changes from a value not equal to the On State value, to a value
equal to the On State value.

On Time

The number of seconds the input value has been equal to the On State value within the
aggregation period.

7.3 Example code

The following two examples of code demonstrate how to use the SetFilterParameters method
to set the properties for a filter, and then read the results.

Intrinsic using single server Data Access

Dim objDataAccess As QUANTUMAUTOMATIONLib.QDataAccess
Dim rsBrowseResults As ADODB.Recordset
Dim sItem As String
Dim lNumItems As Long
Dim Count As Long
Dim vItemID As Variant

' Dimension the filter parameters to return interpolated data

Dim vFilterParameters as Variant
Dim vFilterParms(1) As Variant
Dim lFilterId as Long
Dim lNumPeriods as Long

Dimension variable to receive the data

Dim vData As Variant
Dim vValue as Variant
Dim vQuality as Variant
Dim vTimestamp as Variant

' Create new Exaquantum Data Access object

Set objDataAccess = New QUANTUMAUTOMATIONLib.QDataAccess

IM 36J04A14-01E 7th Edition Issue 1 December 28 2005-08

Exaquantum API Reference Manual 7-5

' Items are requested by using Intrinsic Namespace Access strings, i.e.
Root.???
sItem = "Root.Tag1.Value"
lNumItems = 1

' Resolve the paths to Item Id

Set rsBrowseResults = objBrowser.PathToMetaData(sItem, lNumItems,
brDetail)

' Using the Recordset returned from Browse add the Item Id
' to the DataAccess collection.
vItemID = rsBrowseResults!ItemID
If Not IsNull(vItemID) Then
' Add the item to the DataAccess collection
objDataAccess.Add vItemID
Else
MsgBox "Path is invalid:" & sItem
Exit Sub
End If

' Set time range from yesterday to now

objDataAccess.SetQueryTimes StartTime:= now 1 day

' Set filter parameters to return interpolated data

lFilterId = 1
lNumPeriods = 200
vFilterParms(0) = lFilterId
vFilterParms(1) = lNumPeriods
vFilterParameters = vFilterParms
objDataAccess.SetFilterParameters vFilterParameters

' Read filtered data from yesterday to now

Dim data as Variant
vData = objDataAccess.ReadValue()

'Iterate through the returned data retrieving the history values

Dim lNumberOfPoints As Long
Dim lPoint As Long

lNumberOfPoints = UBound(data(1, 0), 2)

For lPoint = 0 To lNumberOfPoints
vValue = vData(1, 0)(0, lPoint)
vQuality = vData(1, 0)(1, lPoint)
vTimestamp = vData(1, 0)(2, lPoint)

Next

Set objDataAccess = Nothing

IM 36J04A14-01E 7th Edition Issue 1 December 28 2005-08

7-6 Chapter 7 Setting a Filter and Reading the Results

RBNS using Multi-Server Interface

Dim objMDA As QUANTUMAUTOMATIONLib.QDataAccessMulti

Dim sItem As String

' Dimension the filter parameters to return interpolated data

Dim vFilterParameters as Variant
Dim vFilterParms(1) As Variant
Dim lFilterId as Long
Dim lNumPeriods as Long

Dimension variable to receive the data

Dim vData as Variant
Dim vValue as Variant
Dim vQuality as Variant
Dim vTimestamp as Variant

' Items are requested by using Role-Based Namespace Access strings

sItem = MyNamespace.Tag1.Value

' Create new Exaquantum QDataAccessMulti object

Set objMDA = New QUANTUMAUTOMATIONLib.QDataAccessMulti
objMDA.Add sItem

' Set time range from yesterday to now

objMDA.SetQueryTimes StartTime:= now 1 day

' Set filter parameters to return interpolated data

lFilterId = 1
lNumPeriods = 200
vFilterParms(0) = lFilterId
vFilterParms(1) = lNumPeriods
vFilterParameters = vFilterParms
objMDA.SetFilterParameters vFilterParameters

' Read filtered data from yesterday to now

Dim data as Variant
vData = objMDA.ReadValue()

'Iterate through the returned data retrieving the history values

Dim lNumberOfPoints As Long
Dim lPoint As Long

lNumberOfPoints = UBound(data(1, 0), 2)

For lPoint = 0 To lNumberOfPoints
vValue = vData(1, 0)(0, lPoint)
vQuality = vData(1, 0)(1, lPoint)
vTimestamp = vData(1, 0)(2, lPoint)

Next

Set objMDA = Nothing

IM 36J04A14-01E 7th Edition Issue 1 December 28 2005-08

Exaquantum API Reference Manual 8-1

Chapter 8 Writing Item Values

Writing values into an item can be done using the DataAccess object. First resolve the path
to an Item Id, and then use DataAccess object to write values.
Dim rsBrowseResults As ADODB.Recordset
Dim vItemID As Variant
Dim lNumItems As Long
Dim vValue As Variant
Dim lQuality As Long
Dim sItem As String

' Define the item that is to be written

sItem = "Root.Tag1.Value"
lNumItems = 1

' Resolve the paths to Item Id

Set rsBrowseResults = objBrowser.PathToMetaData(sItem, lNumItems,
brDetail)

' Read the Item Id from the recordset

vItemID = rsBrowseResults!ItemID

'If the Item Id is NULL, then the defined item does not exist
If IsNull(vItemID) Then
MsgBox "Invalid Path: " & sItem
Exit Sub
End If

' define the VTQ to be written into Item

vValue = CSng(100) ' Value of data type single
' Use QualityHelper function to fetch raw quality definition
lQuality = objQualityHelper.RawQuality(qdaQualityGood) ' Quality good

' Write into DataAccess

Leave TimeStamp empty so that Server time is used
objDataAccess.WriteValue vValue, vItemID, lQuality

IM 36J04A14-01E 7th Edition Issue 1 December 28 2005-08

8-2 Chapter 8 Writing Item Values

This page intentionally left blank

IM 36J04A14-01E 7th Edition Issue 1 December 28 2005-08

Exaquantum API Reference Manual 9-1

Chapter 9 Accessing Exaquantum Server(s) through RBNS

Session2 object is an explicit way of accessing multiple Exaquantum servers. Instead of
managing multiple servers yourself, you can use QDataAccessMulti object to access
multiple Exaquantum servers transparently through RBNS (Role Based Namespace)
mechanism.

Accessing Exaquantum data through RBNS also provides a high security by way of the
RBNS configuration. For example one user can read an item but another user may not be
able to read the same item.

QDataAccessMulti is built on top of QDataAccess and Session2 objects, and the same
principle applies to QDataAccessMulti object as to these two. One difference is that
QDataAccessMulti methods use path names and not item identifiers to identify items.

9.1 Reading Data

Dim objMDA As QDataAccessMulti

' Items are requested by using Role-Based Namespace Access strings

'Dim item1 As String
'Dim item2 As String

item1 = MyNamespace.Tag1.Value
item2 = MyNamespace.Folder1.Tag1.Value

' Create new Exaquantum QDataAccessMulti object

Set objMDA = New QDataAccessMulti
objMDA.Add item1
objMDA.Add item2

Dim data as Variant

data = objMDA.ReadValue()

' Retrieve VQT for first Item

Dim value1 as Variant
Dim quality1 As Long
Dim timestamp1 As Date
value1 = data(1, 0)(0, 0)
quality1 = data(1, 0)(1, 0)
timestamp1 = data(1, 0)(2, 0)

' Get yesterdays value of item 1

objMDA.SetQueryTimes SpotTime:= now 1 day
data = objMDA.ReadValue()
value11 = data(1, 0)(0, 0)

' Get values from yesterday to now for item 1

objDA.SetQueryTimes StartTime:= now 1 day
data = objMDA.ReadValue()
'Iterate through the returned data retrieving the history values
Dim lNumberOfPoints As Long
lNumberOfPoints = UBound(data(1, 0), 2)
Dim nPoint As Long
For nPoint = 0 To lNumberOfPoints

IM 36J04A14-01E 7th Edition Issue 1 December 28 2005-08

9-2 Chapter 9 Accessing Exaquantum Server(s) through RBNS

value1 = data(1, 0)(0, nPoint)

quality1 = data(1, 0)(1, nPoint)
timestamp1 = data(1, 0)(2, nPoint)

Next

Set objMDA = Nothing

9.2 Writing Data

Dim objMDA As QDataAccessMulti

' Items are requested by using Role-Based Namespace Access strings

'Dim item1 As String
'Dim item2 As String

item1 = MyNamespace.Tag1.Value
item2 = MyNamespace.Folder1.Tag1.Value

' Create new Exaquantum QDataAccessMulti object

Set objMDA = New QdataAccessMulti

' Start registering new current data to write

Dim value1 as Variant
value1 = 123.0
objMDA.AddWrite item1, value1
value1 = hello
objMDA.AddWrite item2, value1

' Write new values to server

Dim vStatus as Variant
vStatus = objMDA.ExecuteWrite(The Reason)

Set objMDA = Nothing

IM 36J04A14-01E 7th Edition Issue 1 December 28 2005-08

Exaquantum API Reference Manual 10-1

Chapter 10 Reading the History of Alarm and Events

The history of Alarm and Events, for a given time period, can be read in a one off,
synchronous way or in an asynchronous way. In both cases, reading an Alarm and Event
data is a two-stage process; first obtain the history stream OPCAEPumpHistID for a
particular OPC Gateway, then use the AEAccess object to return the data.

10.1 Synchronous Read

This type of read is used when a client can be suspended while the read request is being
satisfied. If the client must continue execution and receive data as it is ready via an event,
then an Asynchronous read should be used.

This example reads the Alarm and Events for a particular OPC Gateway from History:
Dim ConnectStr As String
Dim objConnection As ADODB.Connection
Dim objRecordset As ADODB.Recordset
Dim Count As Long
Dim i As Long
Dim vAEId As Variant
Dim Events As Variant
Dim vOPCAEPumpHistID As Variant
Dim sSource As String
Dim sMessage As String
Dim dTimeStamp As Date
Dim lSequenceNo As Long
Dim lEventCategory As Long
Dim lSeverity As Long
Dim sConditionName As String
Dim lNoOfAttributes As Long
Dim vEventAttributesArray As Variant
Dim vEventAttribute As Variant
Dim dQueryTime As Date

' Make the Connect String

Set objConnection = New ADODB.Connection
ConnectStr = "Provider=sqloledb;" 'Provider
ConnectStr = ConnectStr + "Network Library=dbmssocn;" 'Network Library
ConnectStr = ConnectStr + "Server=;" 'Server
Name(Local)
ConnectStr = ConnectStr + "database=QConfig;" 'Database Name
ConnectStr = ConnectStr + "Trusted_Connection=yes" 'Make it trusted
'connection

'Connect to the database

objConnection.Open ConnectStr

' Run the SQL Script and get the recordset

Set objRecordset = New ADODB.Recordset
objRecordset.LockType = adLockOptimistic
objRecordset.Open "SELECT OPCAEPumpHistId FROM OPCServer WHERE Name = 'OPC
Gateway 1'", objConnection

'Check whether the Recordset is returned from query

If objRecordset.EOF Then

IM 36J04A14-01E 7th Edition Issue 1 December 28 2005-08

10-2 Chapter 10 Reading the History of Alarm and Events

MsgBox "Invalid OPC Gateway name"

Exit Sub
End If

' Get the OPCAEPumpHistId (first row only for this example)
vAEId = objRecordset!OPCAEPumpHistId

'Check whether the OPC Gateway Alarm & Events Id is found

If Not IsNull(vAEId) Then
' Add the AE Id into the AEAccess collection
objAEAccess.Add vAEId
Else
MsgBox "OPCAEPumpHistId is Null"
Exit Sub
End If

' Lets query for the last 5 minutes

dQueryTime = DateAdd("n", -5, Now)

' Set the QueryTimes on AEAccess object

objAEAccess.SetQueryTimes dQueryTime

' Now read the values

Events = objAEAccess.ReadValue

' Check to see if there are any data returned

If Not IsNull(Events) Then
' Loop through the entire array and store the AE data
' NB: In this sample only the last data in the Array is stored
' when we are out of the loop
For Count = 0 To UBound(Events, 2)
vOPCAEPumpHistID = Events(0, Count) ' OPCAEPumpHistID
sSource = Events(1, Count) ' Source
sMessage = Events(2, Count) ' Message
dTimeStamp = Events(3, Count) ' TimeStamp
lSequenceNo = Events(4, Count) ' SequenceNumber
lEventCategory = Events(5, Count) ' EventCate
lSeverity = Events(6, Count) ' Severity
sConditionName = Events(7, Count) ' ConditionName
lNoOfAttributes = Events(8, Count) ' Number Of
EventAttributes
vEventAttributesArray = Events(9, Count) ' EventAttributes in
an Array

' Loop through all the EventAttributes and store them

For i = 0 To lNoOfAttributes - 1
vEventAttribute = vEventAttributesArray(i)
Next i

Next Count
End If

IM 36J04A14-01E 7th Edition Issue 1 December 28 2005-08

Exaquantum API Reference Manual 10-3

10.2 Asynchronous Read

This type of read is used when client must continue execution and receive data as it is ready
via an event.

Note: For this type of read, the AEAccess object must be defined 'With Events' as follows:
Dim WithEvents objAEAccess As QUANTUMAUTOMATIONLib.QAEAccess

This example receives the Alarm and Events for a particular OPC Gateway from History.
The first piece of code registers the Alarm and Event HistID, and the second piece of code
defines an event routine that will receive the data:
Dim vAEId As Variant
Dim vData As Variant
Dim vAEData As Variant
Dim lQuality As Long
Dim dTimeStamp As Date
Dim ConnectStr As String
Dim objConnection As ADODB.Connection
Dim objRecordset As ADODB.Recordset
Dim dQueryTime As Date

' Make the Connect String

Set objConnection = New ADODB.Connection
ConnectStr = "Provider=sqloledb;" 'Provider
ConnectStr = ConnectStr + "Network Library=dbmssocn;" 'Network Library
ConnectStr = ConnectStr + "Server=;" 'Server
Name(Local)
ConnectStr = ConnectStr + "database=QConfig;" 'Database Name
ConnectStr = ConnectStr + "Trusted_Connection=yes" 'Make it trusted
connection

'Connect to the database

objConnection.Open ConnectStr

' Run the SQL Script and get the recordset

Set objRecordset = New ADODB.Recordset
objRecordset.LockType = adLockOptimistic
objRecordset.Open "SELECT OPCAEPumpHistId FROM OPCServer WHERE Name = 'OPC
Gateway 1'", objConnection

'Check whether the Recordset is returned from query

If objRecordset.EOF Then
MsgBox "Invalid OPC Gateway name"
Exit Sub
End If

' Get the OPCAEPumpHistId (first row only for this example)
vAEId = objRecordset!OPCAEPumpHistId

'Check whether the OPC Gateway Alarm & Events Id is found

If Not IsNull(vAEId) Then
' Add the AE Id into the AEAccess collection
objAEAccess.Add vAEId
Else
MsgBox "OPCAEPumpHistId is Null"
Exit Sub

IM 36J04A14-01E 7th Edition Issue 1 December 28 2005-08

10-4 Chapter 10 Reading the History of Alarm and Events

End If

' Lets query for the last 5 minutes

dQueryTime = DateAdd("n", -5, Now)

' Set the QueryTimes on AEAccess object

objAEAccess.SetQueryTimes dQueryTime

' Call Execute on AEAccess to read data asynchronously

objAEAccess.Execute

This piece of code shows how to define an event routine that will receive the data. This will
be called multiple times until EventReturnType is qdaEnd:
Private Sub objAEAccess_OnAE(ByVal EventReturnType As
QUANTUMAUTOMATIONLib.qeaEventReturnType, ByVal Events As Variant)
Dim vOPCAEPumpHistID As Variant
Dim sSource As String
Dim sMessage As String
Dim dTimeStamp As Date
Dim lSequenceNo As Long
Dim lEventCategory As Long
Dim lSeverity As Long
Dim sConditionName As String
Dim lNoOfAttributes As Long
Dim vEventAttributesArray As Variant
Dim vEventAttribute As Variant
Dim Count As Long
Dim i As Long

' Check if the data is NULL

If Not IsNull (Events) Then
' Loop through the entire array and store the AE data
' NB: In this sample only the last data in the Array is stored
' when we are out of the loop
For Count = 0 To UBound(Events, 2)
vOPCAEPumpHistID = Events(0, Count) ' OPCAEPumpHistID
sSource = Events(1, Count) ' Source
sMessage = Events(2, Count) ' Message
dTimeStamp = Events(3, Count) ' TimeStamp
lSequenceNo = Events(4, Count) ' SequenceNumber
lEventCategory = Events(5, Count) ' EventCate
lSeverity = Events(6, Count) ' Severity
sConditionName = Events(7, Count) ' ConditionName
lNoOfAttributes = Events(8, Count) ' Number Of
EventAttributes
vEventAttributesArray = Events(9, Count) ' EventAttributes in
an Array

' Loop through all the EventAttributes and store them

For i = 0 To lNoOfAttributes - 1
vEventAttribute = vEventAttributesArray(i)
Next i

Next Count

End If

IM 36J04A14-01E 7th Edition Issue 1 December 28 2005-08

Exaquantum API Reference Manual 10-5

' Check whether more data to come

If EventReturnType = qeaNew Then
MsgBox "First notification received"
ElseIf EventReturnType = qeaMoreEvents Then
MsgBox "More notification to be received"
ElseIf EventReturnType = qeaEnd Then
MsgBox "Last notification received"
End If

End Sub

IM 36J04A14-01E 7th Edition Issue 1 December 28 2005-08

10-6 Chapter 10 Reading the History of Alarm and Events

This page intentionally left blank

IM 36J04A14-01E 7th Edition Issue 1 December 28 2005-08

Exaquantum API Reference Manual 11-1

Chapter 11 Conducting Recalculation and Re-aggregation

The recalculation and re-aggregation is a mechanism to update Exaquantum calculated tags
and aggregation result items after raw data have been changed that would affect dependent
calculated tags and aggregation result items.

The operation consists of two major steps:

1 To update raw data with an existing data write mechanism, e.g. Data Write API

2 To execute recalculation and re-aggregation by this new Recalculation API

This chapter covers the second step mentioned above.

11.1 Concept of Recalculation

The recalculations are based upon Recalculation Jobs defined by the user and stored in a
database for re-use.

For each job the user must specify a unique name and a set of input Items these are the
Items for which updated data has been previously written to the Exaquantum Historian.

The user may also optionally de-select one or more dependent items to be excluded from the
recalculation.

For this version of Exaquantum the following scope will be applied:

Only dependent aggregations and scripted aggregations will be recalculated.

Recalculation can only be requested for dependent aggregations after having changed
the aggregation result items on which they depend. [See Note 1]

All dependent aggregations will be recalculated the user cannot deselect any items.

Recalculation will be synchronous. No notifications on progress status will be sent to

the user as the time is expected to be very short (a few seconds).

All result items set in a scripted aggregation will be recalculated, but only those that
are aggregation result items will have their dependent aggregations recalculated.

Number of aggregation result items must be small, e.g. a few. Also the time span to
recalculate should be short, e.g. a few hours. [See Note 2]

Note 1: Future release of Exaquantum will allow specifying raw data that will affect
referencing calculated tags as well as base and dependent aggregations.

Note 2: There is no hard figure, the actual number depends on the system work load. But
keep it to a minimum.

IM 36J04A14-01E 7th Edition Issue 1 December 28 2005-08

11-2 Chapter 11 Conducting Recalculation and Re-aggregation

When requesting recalculation for an aggregation result item, the PercentTimeGood item
may not be selected this will be updated automatically when other aggregation results are
recalculated.

If an aggregation result uses the Changed property of the PercentTimeGood item (as shown
below) then it not be recalculated. This is because the PercentTimeGood value is calculated
internally and should not be written to explicitly.
if [Root.Tag1.Aggregations.Hour.PercentTimeGood.Value].Changed then

[Result.Aggregations.Hour.Mean.Value] = <n>

[Result.Aggregations.Hour.PercentTimeGood.Value] = <n>

end if

A recalculation operation cannot be carried out for:

A period that lies within an archive. - If the start time is within an archive period and
the end time is valid then the data within the valid online period will be recalculated.
The Systems Events Viewer will report a failed recalculation.

A period before the time that an item was created. - If the start time is before the
creation of the item and the end time is valid then the data within the valid online
period will be recalculated. The Systems Events Viewer will report a failed
recalculation.

11.2 Recalculation Engine

The Exaquantum Recalculation Engine is implemented as a free-threaded COM server
(QRecalcEngine.exe). It has a similar architecture to Quantum.exe with a single
RecalcBroker object responsible for:

Saving RecalculationJob definitions in a database

Determining the input and output dependencies of Items requested for recalculation

Reading data from Historian to initialise input items

Starting up all Item, Aggregation and Calculation objects required for the
recalculation

Providing locking so that only one recalculation can be performed at once

Driving the recalculation and building an information of recalculated values for

inspection by the user

Writing recalculated data points to the Historian

Logging recalculation details to audit trail tables

IM 36J04A14-01E 7th Edition Issue 1 December 28 2005-08

Exaquantum API Reference Manual 11-3

Forwarding updated current aggregation estimated results to the Exaquantum RTDB

to update live aggregations.

Commit of a recalculation is synchronous. The method does not return to the user until all
updated data has been written into history and any updates to live aggregations have been
made to the RTDB.

11.3 Introduction to Recalculation API

The client accesses the API through the RecalcJob property of the Exaquantum Session2
object. Only members of the QAdministratorGroup or QDataWriteGroup are allowed to
access Recalculations.

Typical scenarios are described below.

User creates a new Recalc Job:

Call NewRecalcJobDefinition to create a new job.

Call the SetRecalcInputItemIds method to specify the Items whose data will be changed.

User re-runs an existing Recalc Job:

Set the RecalcJobName property to specify which job to run.

Then in both cases:

Set the time range for recalculation by calling SetRecalcTimes.

Call Recalc to request recalculation a Recordset of data values that will be written is
returned for review.

User either calls Commit to save the recalculated data to Exaquantum Historian or calls
Cancel to abandon the recalculation.

A recalculation is active from the beginning of a call on the Recalc() method until the end
of a call on the Commit() or Cancel() methods. Only one recalculation may be active at one
time. If a user releases a RecalcJob object that they have called the Recalc() method on
without calling Commit() or Cancel(), the recalculation will be automatically cancelled.

Users may still configure other recalculation job definitions while a recalculation is active.
Only one user may access a given job definition at one time.

IM 36J04A14-01E 7th Edition Issue 1 December 28 2005-08

11-4 Chapter 11 Conducting Recalculation and Re-aggregation

11.4 Notes on Minimum and Maximum aggregation results

In the case where the user wishes to write a new timestamp as well as a new value for a
Minimum or Maximum aggregation result, the user must also update the existing Minimum
or Maximum point with a secondary quality of DELETED. If this results in a change to the
timestamp of recalculated dependent Minimum or Maximum points, the Recalculation
Engine will set the secondary quality of old dependent points to DELETED.

If the user writes an aggregation result item at a timestamp which is not on the aggregation
period boundary for any result other than a Minimum or Maximum, the point will be
ignored.

11.5 Sample code

User changes a single hourly aggregation result

Production calendar dependencies look as follows:

Raw -> Hour -> Day -> Month

New data points written:

Table 11-1

ItemPath Value Quality Timestamp

Root.Tag1.Aggregatio 118 Good #1/26/2003 9:00:00

ns.Hour.Mean.Value AM#

Dim objSession As QUANTUMAUTOMATIONLib.Session2

Dim objRecalcJob As QUANTUMAUTOMATIONLib.IQRecalcAuto
Dim lRecalcSessionID As Long
Dim objItemValuesRS As ADODB.Recordset

' Get a Recalculation Job handler object

Set objSession = New QUANTUMAUTOMATIONLib.Session2
Set objRecalcJob = objSession.RecalcJob

' Create a new recalculation job definition

objRecalcJob.NewRecalcJobDefinition "Tag1Hourly", "The reason"

' Define the items to be recalculated for this job

objRecalcJob.SetRecalcInputItems("Root.Tag1.Aggregations.Hour.Mean.Value")

' Specify the time for recalculation current time is #1/27/2003

9:00:00 AM#
objRecalcJob.SetRecalcTimes #1/26/2003 9:00:00 AM#

' Do the recalculation

lRecalcSessionID = objRecalcJob.Recalc(, objItemValuesRS)

' Inspect the results

IM 36J04A14-01E 7th Edition Issue 1 December 28 2005-08

 Exaquantum API Reference Manual 11-5

.
' Commit the recalculation results to history
objRecalcJob.Commit lRecalcSessionID
Example of item values recordset showing points that may be affected:

Table 11-2

Item ID Item Path Timestam Value Quality Prev. Prev. Previous

p Value Quality Timestamp

14 Root.Tag1.A #1/27/200 120 Good 119 Good #1/27/2003

ggregations. 3 00:00:00#
00:00:00#
Day.Mean.V
alue

21 Root.Tag1.A #1/27/200 100 Good Null Null Null

ggregations. 3 Estimat
00:00:00# ed
Month.Mean.
Value

User uses an existing recalculation job definition

The plan is to change the same hourly aggregation result item for more than one hour within
a day.

New data points written:

Table 11-3

ItemPath Value Quality Timestamp

Root.Tag1.Aggregations.Hour.Mean.Value 118 Good #1/27/2003 9:00:00 AM#

Root.Tag1.Aggregations.Hour.Mean.Value 120 Good #1/27/2003 10:00:00

AM#

Dim objSession As QUANTUMAUTOMATIONLib.Session2

Dim objRecalcJob As QUANTUMAUTOMATIONLib.IQRecalcAuto
Dim lRecalcSessionID As Long
Dim objItemValuesRS As ADODB.Recordset

' Get a Recalculation Job handler object

Set objSession = New QUANTUMAUTOMATIONLib.Session2
Set objRecalcJob = objSession.RecalcJob

' Use existing recalculation job definition

objRecalcJob.RecalcJobName = "Tag1Hourly"

IM 36J04A14-01E 7th Edition Issue 1 December 28 2005-08

11-6 Chapter 11 Conducting Recalculation and Re-aggregation

' Specify a time range for recalculation current time is #2/01/2003

9:00:00 AM#
objRecalcJob.SetRecalcTimes , #1/27/2003 9:00:00 AM#, #1/27/2003
10:00:00 AM#

' Do the recalculation

lRecalcSessionID = objRecalcJob.Recalc( , objItemValuesRS)

' Inspect the results

.
' User decides to cancel the recalculation
objRecalcJob.Cancel lRecalcSessionID

IM 36J04A14-01E 7th Edition Issue 1 December 28 2005-08

Exaquantum API Reference Manual 11-7

Example of item values recordset showing points that may be affected:

Table 11-4

Item Item Path Timesta Value Quality Prev. Prev. Previous

ID mp Value Quality Timestam
p

14 Root.Tag1.Aggregati #1/28/20 120 Good 121 Good #1/28/200

ons. 03 3
00:00:00 00:00:00#
Day.Mean.Value #

21 Root.Tag1.Aggregati #2/01/20 100 Good 101 Good #2/01/200

ons. 03 3
00:00:00 00:00:00#
Month.Mean.Value #

User changes two hourly aggregation result items that feed a scripted aggregation

Production calendar dependencies look as follows:

Raw -> Hour -> Day -> Month

Scripted aggregation calculation generates Hours aggregated value as in:

( Result.Aggregations.Hour.Mean.Value =

Root.Tag3.Aggregations.Hour.Mean.Value +

Root.Tag4.Aggregations.Hour.Mean.Value )

New data points written:

Table 11-5

ItemPath Value Quality Timestamp

Root.Tag3.Aggregations.Hour.Mean.Value 118 Good #1/26/2003 9:00:00 AM#

Root.Tag4.Aggregations.Hour.Mean.Value 230 Good #1/26/2003 9:00:00 AM#

Dim objSession As QUANTUMAUTOMATIONLib.Session2

Dim objRecalcJob As QUANTUMAUTOMATIONLib.IQRecalcAuto
Dim lRecalcSessionID As Long
Dim objItemValuesRS As ADODB.Recordset
Dim ItemPaths(2) as String

IM 36J04A14-01E 7th Edition Issue 1 December 28 2005-08

 11-8 Chapter 11 Conducting Recalculation and Re-aggregation

' Get a Recalculation Job handler object

Set objSession = New QUANTUMAUTOMATIONLib.Session2
Set objRecalcJob = objSession.RecalcJob

' Set the item paths for the items to recalculate

ItemPaths (0) = GetItemID("Root.Tag3.Aggregations.Hour.Mean.Value")
ItemPaths (1) = GetItemID("Root.Tag4.Aggregations.Hour.Mean.Value")

' Create a new recalculation job definition

objRecalcJob.NewRecalcJobDefinition "CalcHourly", "The reason"

' Define the items to be recalculated for this job

objRecalcJob.SetRecalcInputItems ItemPaths

' Specify the time for recalculation current time is #2/01/2003

9:00:00 AM#
objRecalcJob.SetRecalcTimes #1/26/2003 9:00:00 AM#

' Do the recalculation

lRecalcSessionID = objRecalcJob.Recalc( , objItemValuesRS)

' Inspect the results

.
' Commit the recalculation results to history
objRecalcJob.Commit lRecalcSessionID

Example of item values recordset showing points that may be affected:

Table 11-6

Item Item Path Timestam Value Quality Prev. Prev. Previous

ID p Value Quality Timestamp

9 Root.Tag3.Aggregati #1/28/200 120 Good 121 Good #1/28/2003

ons. 3 00:00:00#
00:00:00#
Day.Mean.Value

6 Root.Tag3.Aggregati #2/01/200 100 Good 101 Good #2/01/2003

ons. 3 00:00:00#
00:00:00#
Month.Mean.Value

70 Root.Tag4.Aggregati #1/28/200 220 Good 208 Good #1/28/2003

ons. 3 00:00:00#
00:00:00#
Day.Mean.Value

77 Root.Tag4.Aggregati #2/01/200 210 Good 200 Good #2/01/2003

ons. 3 00:00:00#
00:00:00#
Month.Mean.Value

84 Root.Calc.Aggregatio #1/26/200 320 Good 318 Good #1/26/2003

IM 36J04A14-01E 7th Edition Issue 1 December 28 2005-08

 Exaquantum API Reference Manual 11-9

Item Item Path Timestam Value Quality Prev. Prev. Previous

ID p Value Quality Timestamp
ns. 3 09:00:00#
09:00:00#
Hour.Mean.Value

88 Root.Calc.Aggregatio #1/28/200 340 Good 329 Good #1/28/2003

ns. 3 00:00:00#
00:00:00#
Day.Mean.Value

92 Root.Calc.Aggregatio #2/01/200 310 Good 301 Good #2/01/2003

ns. 3 00:00:00#
00:00:00#
Month.Mean.Value

User changes multiple hourly Minimum or Maximum aggregation result

Production calendar dependencies look as follows:

Raw -> Hour -> Day -> Month

New data points written (current time is #2/01/2003 9:00:00 AM#):

Table 11-7

ItemPath Value Quality Timestamp

Root.Tag1.Aggregations.Hour.Minimum.Value 118 Good #1/26/2003

8:45:00 AM#

Root.Tag1.Aggregations.Hour.Minimum.Value 120 Bad | #1/26/2003

Deleted 8:50:00 AM#

Root.Tag1.Aggregations.Hour.Minimum.Value 116 Good #1/26/2003

9:30:00 AM#

Root.Tag1.Aggregations.Hour.Minimum.Value 122 Bad | #1/26/2003

Deleted 9:40:00 AM#

IM 36J04A14-01E 7th Edition Issue 1 December 28 2005-08

11-10 Chapter 11 Conducting Recalculation and Re-aggregation

(Sample code is not shown.)

Example of item values recordset showing points that may be affected:

Table 11-8

Item Item Path Timestamp Value Quality Prev. Prev. Previous

ID Value Quality Timestm
p

14 Root.Tag1.Aggregations #1/26/2003 120 Bad | 120 Good #1/26/20

. 09:00:00# Deleted 03
09:00:00
Day.Minimum.Value #

14 Root.Tag1.Aggregations #1/26/2003 116 Good Null Null #1/26/20

. 10:00:00# 03
09:00:00
Day.Minimum.Value #

21 Root.Tag1.Aggregations #1/27/2003 116 Good 120 Good #1/27/20

. 00:00:00# 03
00:00:00
Month.Minimum.Value #

IM 36J04A14-01E 7th Edition Issue 1 December 28 2005-08

Exaquantum API Reference Manual 12-1

Chapter 12 Setting Tags and Function Blocks Offline

Tags and Function Blocks may be set Offline or Online using the NamespaceBuilder object
that is obtained from the Session object. First resolve the path of the Tag or Function Block
to a Namespace Id using the Browser object, and then use the NamespaceBuilder object to
set the Tag or Function Block Offline or Online.
Dim objSession As QUANTUMAUTOMATIONLib.Session
Dim objNamespaceBuilder As QUANTUMAUTOMATIONLib.INamespaceBuilder2
Dim objBrowser As QUANTUMAUTOMATIONLib.Browse2
Dim rsBrowseResults As ADODB.Recordset

Dim vNamespaceIDs(1) As Variant

Dim lNumNamespaceItems As Long
Dim vValue As Variant
Dim lQuality As Long
Dim sTagPaths(1) As String
Dim vStatusArray As Variant
Dim sUserName as String

' Create Session and Browser objects

Set objSession = New QUANTUMAUTOMATIONLib.Session
Set objBrowser = objSession.Browser

' Define the Tags and Function Blocks to be set Offline

sTagPaths(0) = "Root.OPCTag1"
sTagPaths(1) = "Root.OPCTag2"
lNumNamespaceItems = 2

' Resolve the paths to Item Id

Set rsBrowseResults = objBrowser.PathToMetaData(sTagPaths,
lNumNamespaceItems, brDetail)

' Read the Namespace Ids from the recordset

For i = 0 To lNumNamespaceItems - 1
vNamespaceIDs(i) = rsBrowseResults!NamespaceId
' If the Namespace Id is NULL, then the defined path does not exist
If IsNull(vNamespaceIDs(i)) Then
MsgBox "Invalid Path: " & sTagPaths(i)
Exit Sub
End If
rsBrowseResults.MoveNext
Next

' Get a NamespaceBuilder object from Session

Set objNamespaceBuilder = objSession.NamespaceBuilder

' Tell NamespaceBuilder to set the Tag or Function Block Offline

objNamespaceBuilder.SetOfflineState True, vNamespaceIDs,
lNumNamespaceItems, sUserName, vStatusArray

' Check the returned status array for errors

For i = 0 To lNumNamespaceItems - 1
If vStatusArray(i) > 0 Then
MsgBox "Not a Tag or Function Block: " & sTagPaths(i)
End If
Next

IM 36J04A14-01E 7th Edition Issue 1 December 28 2005-08

12-2 Chapter 12 Setting Tags and Function Blocks Offline

This page intentionally left blank

IM 36J04A14-01E 7th Edition Issue 1 December 28 2005-08

Exaquantum API Reference Manual 13-1

Chapter 13 Introduction to the API Reference Chapters

The following chapters provide the definition of the Exaquantum APIs. Each Object is dealt
with in a separate chapter. The definitions are given in a VB style.

IM 36J04A14-01E 7th Edition Issue 1 December 28 2005-08

13-2 Chapter 13 Introduction to the API Reference Chapters

This page intentionally left blank

IM 36J04A14-01E 7th Edition Issue 1 December 28 2005-08

Exaquantum API Reference Manual 14-1

Chapter 14 Session Object API Reference

The Session object controls the connection from the client to the server.

14.1 Browser Property

Description

Returns a Browser object.

14.2 NamespaceBuilder Property

Description

Returns a NamespaceBuilder object used for setting Tags and Function Blocks Offline and
Online. This object can only be obtained if the client is a member of QAdministratorGroup.

14.3 NetworkError Event Method

Description

This method is called back on the client when the network connection fails between client
and server.

Clients cannot recover the connection to Exaquantum after this failure without first closing
the connection and re-establishing it by destroying and recreating the Session object.

Signature
Event NetworkError()

IM 36J04A14-01E 7th Edition Issue 1 December 28 2005-08

14-2 Chapter 14 Session Object API Referencee

14.4 QuantumShutdown Event Method

Description

This method is called back on the client when the Exaquantum Server processes are shut
down.

Clients cannot recover the connection to Exaquantum after this failure without first closing
the connection and reestablishing it by destroying and recreating the Session object.

Signature
Event QuantumShutdown(bErrored As Boolean)
Parameters

bErrored is False if the Exaquantum processes shutdown normally (by stopping the
Service) or True if the processes shutdown abnormally.

IM 36J04A14-01E 7th Edition Issue 1 December 28 2005-08

Exaquantum API Reference Manual 15-1

Chapter 15 Session2 Object API Reference

The Session2 object controls the connection from the client to a server in a multi-server
environment. It should be used in place of the Session object. Session is maintained for
backward compatibility. Existing applications using Session will continue to function. It
supports the same properties and methods as Session in addition to the following:

15.1 ServerName Property

Description

ServerName is a string property allowing the client to specify the machine name of the
Exaquantum server to connect to. This property must be set before calling any other method
on the Session2 object. If not set, it will default to using the DesignatedServer in the same
way as the Session object.

ServerName may only be set once an attempt to reset it, or to set it after calling any other
method, will raise an error.

15.2 IsConnected Method

Description

This method may be used to determine whether the Exaquantum server that the Session2
object is set to connect to is available. It returns True if the Exaquantum server is running or
False if the server is shutdown or the network is unavailable.

Signature
Public Function IsConnected() As Boolean

15.3 QuantumAvailable Event Method

Description

This method is called back on the client when the Exaquantum server that the Session2
object is set to connect to has been unavailable but is now connected.

Signature
Event QuantumAvailable()

IM 36J04A14-01E 7th Edition Issue 1 December 28 2005-08

15-2 Chapter 15 Session2 Object API Reference

15.4 ConnectState Method

Description
A read-only property which returns the current connection state of an Exaquantum client to the
Exaquantum server.
Signature
Public Function ConnectState() As qsmConnectState

Parameters
The connection state is an enumeration:
Table 15-1

Enumeration Value Meaning

qsmConnected 0 Client is successfully connected

qsmNotRunning 1 The Exaquantum Server is not in a

running state

qsmShutdown 2 The Exaquantum Server has been shut

down

qsmNetworkDown 3 A network error has been detected only

set after initial successful connection has
been lost

qsmConnectFailed 4 Connection to the Exaquantum server

failed possibly a security or network
problem

IM 36J04A14-01E 7th Edition Issue 1 December 28 2005-08

Exaquantum API Reference Manual 16-1

Chapter 16 Browser Object API Reference

The Browse object gives access to the Exaquantum Namespace information. This
information is used to locate a particular Tag, Folder, Function Block or Item in the
hierarchy as displayed in the Data Selector in the Tag Editor or Explorer.

16.1 Browse Method

Description

Return a Recordset of metadata information for the contents of a single leaf in the
namespace.

Signature
Public Function Browse(Path As String, _
Optional Filter As String = "*", _
Optional Fields As brFields = brSummary) As ADODB.Recordset
Return Value

A Recordset will be returned populated with metadata information for the selected Path. The
information will be returned in alphabetic order based on the Name column. The columns
returned will be defined by the Fields parameter.

Parameters

Path specifies the leaf of the namespace to use e.g. Root.Folder1.

Filter specifies a text filter to apply to the names of the leaves. This allows the client to
reduce the number of rows returned. The filter allows wildcards specified with *. Filter will
be ignored for browsing below a tag.

Fields allows the fields returned to be selected by the enumeration brFields as described
below.

Table 16-1 Enumeration brSummary=1

Column Data Type Comments

Name

Name nvarchar(32) The name for this leaf.

Id int The id for this leaf. This is typically the column

ExtId from table namespace. See below for details.

ClassName nvarchar(32) The class name from the column Name in table
Class.

IM 36J04A14-01E 7th Edition Issue 1 December 28 2005-08

16-2 Chapter 16 Browser Object API Reference

Table 16-2 Enumeration brDetail=2

Column Name Data Type Comments

Name nvarchar(32) The name for this leaf.

Id int The id for this leaf. This is typically the column ExtId
from table namespace. See below for details.

ClassName nvarchar(32) The class name from the column Name in table Class.

ItemDataTypeId tinyint For Items this returns the data type from the column
DataTypeId in table Item.

ItemId binary(8) For Items this returns the Item ID which is required
when using the DataAccess object.

NamespaceId int The id for this leaf from the Namespace table.

If this leaf is not stored in the namespace table, i.e. it is

detail below the tag, then NULL is returned.

IsShortcut bit Indicates that this leaf is a shortcut.

Id returned in Recordset
The Id returned depends on the class of the leaf and whether it exists above or below a tag in
the hierarchy as described below:

Table 16-3

Class Example Id returned

Tag or Function Root.Tag1 The ExtId column from the

block Namespace table. This matches the
relevant row in the Tag or
FunctionBlock tables Id column.

Folders above Root.Folder1 The ExtId column from the

the level of a Namespace table. This also matches
tag the Id column of the Namespace
table.

Item Root.Tag1.Value The Id column from the Item table.

Aggregations Root.Tag1.Aggregations NULL

folder

Aggregations or Root.Tag1.Aggregations.Hour or NULL

tags below

IM 36J04A14-01E 7th Edition Issue 1 December 28 2005-08

Exaquantum API Reference Manual 16-3

Class Example Id returned

aggregations Root.Tag1.Aggregations.Hour.Mean

16.2 PathToMetadata Method

Description

Return a Recordset of metadata information for objects in the namespace hierarchy as

defined by a list of one or more paths.

Signature
Public Function PathToMetadata(Paths() As String, _
NumPaths As Long, _
Optional Fields As brFields = brSummary) As ADODB.Recordset
Return Value

A Recordset will be returned populated with metadata information for the selected Paths.
The information will be returned in the same order as the entries in the Paths array.

Fields allows the fields returned to be selected by the enumeration brFields as described in
section 16.1

If a Path is invalid then all fields in the Recordset will be NULLs.

Parameters

Paths specifies a set of leaves in the namespace to use e.g. Root.Folder1.

NumPaths specifies the number of entries in the Paths array.

Fields allows the fields returned to be selected by the enumeration brFields as described
above.

16.3 ItemIdToPath Method

Description

Return a Recordset of paths for Items in the namespace hierarchy as defined by a list of one
or more Ids.

If more than one path exists due to a shortcut then return just one of the possible paths.

Signature
Public Function ItemIdToPath(Ids() As Long, _
NumIds As Long) As ADODB.Recordset

IM 36J04A14-01E 7th Edition Issue 1 December 28 2005-08

16-4 Chapter 16 Browser Object API Reference

Return Value

A Recordset will be returned populated with a single column Path for the selected Ids. The
information will be returned in the same order as the entries in the Ids array.

If an Id is invalid then the corresponding row in the Recordset will be NULL.

Recordset shape:

Table 16-4

Column Name Data Type Comments

Path nvarchar(256) The Path for the corresponding Id or NULL if the Id is

invalid.

Parameters

Ids specifies a set of Ids as defined by the Id column of the Item Table.

NumIds specifies the number of entries in the Ids array.

16.4 PathToIds Method

Description
Returns VARIANT array of 8 byte item ids for supplied array of item paths. If paths are invalid, ids are returned as
VT_NULL.

Public Function PathToIds ( _

NamespaceId As Long, _
RemainingPaths() As String, _
NumPaths As Long, _
Optional FolderFilter As String = "*", _
Optional FolderFilterAdditive As Boolean = TRUE, _
Optional FBFilter As String = "*", _
Optional FBFilterAdditive As Boolean = TRUE, _
Optional FBTagFilter As String = "*", _
Optional FBTagFilterAdditive As Boolean = TRUE, _
Optional TagFilter As String = "*", _
Optional TagFilterAdditive As Boolean = TRUE, _
Optional ShowAggregations As Boolean = TRUE) As VARIANT
Return Value

A VARIANT, containing an array of 8 byte item ids, will be returned for the selected
NamespaceId, RemainingPaths, HiRange and LowRange. The information will be
returned in the same order as the entries in the RemainingPaths array.

Parameters

NamespaceId Specifies the id in the namespace to start parsing the path from.

IM 36J04A14-01E 7th Edition Issue 1 December 28 2005-08

Exaquantum API Reference Manual 16-5

RemainingPaths Specifies the leaf of the namespace to use below the specified
NamespaceId e.g. Folder1.Folder2.

NumPaths Specifies the number of entries in the RemainingPaths arrays.

Various filters may be specified to allow the client to reduce the number of rows returned.
Filters allow wildcards specified with *. Each filter has an associated flag to specify
whether the filter is additive (only matching leaves are returned) or subtractive (all matching
leaves are excluded)

FolderFilter Specifies a text filter to apply to the names of folders.

FolderFilterAdditive Specifies whether the FolderFilter is additive or subtractive.

FBFilter Specifies a text filter to apply to the names of Function Blocks.

FBFilterAdditive Specifies whether the FBFilter is additive or subtractive.

FBTagFilter Specifies a text filter to apply to the names of Tags within Function Blocks.

FBTagFilterAdditive Specifies whether the FBTagFilter is additive or subtractive.

TagFilter Specifies a text filter to apply to the names of Tags outside Function Blocks.

TagFilterAdditive Specifies whether the TagFilter is additive or subtractive.

ShowAggregations Specifies whether to return metadata for Aggregations below a Tag.

IM 36J04A14-01E 7th Edition Issue 1 December 28 2005-08

16-6 Chapter 16 Browser Object API Reference

16.5 WritePlotLimits Method

Description
This method controls the writing of the plot limits of specified items.
Signature
Public Sub WritePlotLimits( NamespaceID as Long, _
RemainingPaths() as Variant, _
lNumPaths as long, _
PlotRanges() as Variant )

Parameters

Table 16-5

Parameter Description

NamespaceID Specifies the ID in the namespace under which the paths in

RemainingPaths start from.

RemainingPaths Specifies the leaf of the namespace to use below the specified
NamespaceID. For example; Folder1.Folder2.

lNumPaths Number of paths in RemainingPaths

PlotRanges Contains a 2 column SAFEARRAY of doubles; column 0 contains

lowranges, column 1 hiranges. Should contain the same number of
rows as there are ItemIDs.

Errors

E_INVALIDARG

Either:

The specified number of IDs does not concur with the size of either of the input arrays.

Either of the input arrays are of the wrong data type.

IM 36J04A14-01E 7th Edition Issue 1 December 28 2005-08

Exaquantum API Reference Manual 17-1

Chapter 17 RBNSBrowseEx Object API Reference

The RBNSBrowseEx object enables you to access to the information defined with the
Exaquantum RBNS. This information is used to find the position of tree-structured tags,
function blocks, or items displayed with the Tag Editor or Exaquantum/Explorer Data
Selector. Also, if RBNS is not defined in Exaquantum, this object performs the same
function as the Browser object does.

17.1 Browse Method

Description

Return a Recordset of metadata information for the contents of a single leaf in the
namespace.

Signature
Public Function Browse(Path As String, _
Optional Filter As String = "*", _
Optional Fields As brFields = brSummary) As ADODB.Recordset

Return Value

A Recordset will be returned populated with metadata information for the selected Path. The
information will be returned in alphabetic order based on the Name column. The columns
returned will be defined by the Fields parameter.

Parameters

Path specifies the leaf of the namespace to use e.g. Root.Folder1.

Filter specifies a text filter to apply to the names of the leaves. This allows the client to
reduce the number of rows returned. The filter allows wildcards specified with *. Filter will
be ignored for browsing below a tag.

Fields allows the fields returned to be selected by the enumeration brFields as described
below.

Table 17-1 Enumeration brSummary=1

Column Data Type Comments

Name

Name nvarchar(32) The name for this leaf.

ClassName nvarchar(32) The class name from the column Name in table
Class.

IM 36J04A14-01E 7th Edition Issue 1 December 28 2005-08

17-2 Chapter 17 RBNSBrowseEx Object API Reference

Table 17-2 Enumeration brDetail=2

Column Name Data Type Comments

Name nvarchar(32) The name for this leaf.

ClassName nvarchar(32) The class name from the column Name in table Class.

ItemDataTypeId Tinyint For Items this returns the data type from the column
DataTypeId in table Item.

Path nvarchar(256) The full path for specifying a leaf.

ServerId Int Exaquantum server ID

ServerName nvarchar(32) Exaquantum server name

Id returned in Recordset
The Id returned depends on the class of the leaf and whether it exists above or below a tag in
the hierarchy as described below:

Table 17-3

Class Example Id returned

Tag or Root.Tag1 The ExtId column from the

Function block Namespace table. This matches the
relevant row in the Tag or
FunctionBlock tables Id column.

Folders above Root.Folder1 The ExtId column from the

the level of a Namespace table. This also matches
tag the Id column of the Namespace
table.

Item Root.Tag1.Value The Id column from the Item table.

Aggregations Root.Tag1.Aggregations NULL

folder

Aggregations Root.Tag1.Aggregations.Hour or NULL

or tags below
aggregations Root.Tag1.Aggregations.Hour.Mean

IM 36J04A14-01E 7th Edition Issue 1 December 28 2005-08

Exaquantum API Reference Manual 17-3

17.2 PathToMetadata Method

Description

Return a Recordset of metadata information for objects in the namespace hierarchy as

defined by a list of one or more paths.

Signature
Public Function PathToMetadata(Paths() As String, _
NumPaths As Long, _
Optional Fields As brFields = brSummary) As ADODB.Recordset
Return Value

A Recordset will be returned populated with metadata information for the selected Paths.
The information will be returned in the same order as the entries in the Paths array.

Fields allows the fields returned to be selected by the enumeration brFields as described in
section 17.1

If a Path is invalid then all fields in the Recordset will be NULLs.

Parameters

Paths specifies a set of leaves in the namespace to use e.g. Root.Folder1.

NumPaths specifies the number of entries in the Paths array.

Fields allows the fields returned to be selected by the enumeration brFields as described
above.

IM 36J04A14-01E 7th Edition Issue 1 December 28 2005-08

17-4 Chapter 17 RBNSBrowseEx Object API Reference

This page intentionally left blank

IM 36J04A14-01E 7th Edition Issue 1 December 28 2005-08

Exaquantum API Reference Manual 18-1

Chapter 18 QDataAccess Object API Reference

The DataAccess Object allows Item data to be read and written.

Items of interests are specified by Item Ids, these can be resolved from the Item Path using
the Browser object. Before an Item can be read its Id must first be added to a collection
maintained by QDataAccess. After filling the collection, clients select the function they
require either for the whole collection (typical) or for individual items in the collection.

18.1 Add Method

Description

Add an Item Id to the collection of Items of interest. On add, if a request for data is current,
data for the new ItemID will be fetched automatically.

Signature
Sub Add (ItemID As Variant)

Parameters

ItemId - specifies the Item of interest. This should be an 8 byte array as returned by the
browser.

18.2 Cancel Method

Description

Cancels the current request and stops acquisition of live data.

Signature
Sub Cancel ()

18.3 Count Property

Description

Read the number of Items in the collection of Items of interest.

Signature
Property Count () As Long

IM 36J04A14-01E 7th Edition Issue 1 December 28 2005-08

18-2 Chapter 18 QDataAccess Object API Reference

18.4 Execute Method

Description

Starts the asynchronous acquiring of data using the current time and processing options set
for the QDataAccess Object.

Data is returned via the OnData event.

Signature
Sub Execute (Optional WithChanges As Boolean = True, _
Optional ReturnDataAsReady As Boolean = True )

Parameters

WithChanges - When requesting latest data, if set FALSE then only a single event will be
fired to the client for each Item. The default is to notify the client whenever the value of any
Item in the collection changes.

ReturnDataAsReady - When requesting historical data, if set FALSE then all the values for
each Item will be returned in a single event. The default is to send data as soon as it is
available to allow a more responsive user interface.

18.5 Item Method

Description

Return an Item Id from the collection.

Signature
Function Item (Index As Variant) as Variant

Parameters

Index is the position in the collection.

Return Value

The 8 byte array representing the Item Id.

IM 36J04A14-01E 7th Edition Issue 1 December 28 2005-08

Exaquantum API Reference Manual 18-3

18.6 OnData Event Method

Description

This method is called back on the client for asynchronous events initiated by Execute().

Signature
Event OnData (ItemId As Variant, _
DataReturnType As qdaDataReturnType, _
Data As Variant)

Parameters

ItemId is the Id of the Item for which data is arriving.

DataReturnType One of enumeration qdaDataReturnType :

qdaNew=0 This is new data for this item. This is always the type for the first
notification for an item after Execute(), and for live data.

qdaMoreRows=1 For historical data, this is additional data to append to previously

received data.

qdaEnd=2 For historical data, this is the final data for this Item.

Data - A 2-dimensional array of Variants with the following format:

Variant Value Long Quality Date Timestamp

where live data has only one row and historical data has one row for each time point.

Note: Data may be NULL and clients should check for this. This indicates that no data is
returned for this firing of the event.

IM 36J04A14-01E 7th Edition Issue 1 December 28 2005-08

18-4 Chapter 18 QDataAccess Object API Reference

18.7 OnError Event Method

Description

This method is called back on the client for asynchronous requests if an error occurs.

Signature
Event OnError(Number As Long, _
Description As String, _
Source As String, _
HelpFile As String, _
HelpContext As Long)

Parameters

Number - is the Quantum error number.

Description - is the error text.

Source - is the component that raised the error.

HelpFile - is the name of the HelpFile containing further information on the error.

HelpContext - is the Help context number.

IM 36J04A14-01E 7th Edition Issue 1 December 28 2005-08

Exaquantum API Reference Manual 18-5

18.8 ReadValue Method

Description

Perform a synchronous read for values of items using the current time and processing
options set for the QDataAccess Object.

Data may be read for all items in the QDataAccess collection or for one specific item.

Data is always fetched for the whole collection and stored in the local cache. Subsequent
calls to ReadValue retrieve data from the cache. If the query times are not set, updating live
data is fetched so that the value in the cache is always up to date.

Signature
Function ReadValue (Optional ItemID As Variant) As Variant

Parameters

ItemID -An Item internal ID as an 8-byte array. If not supplied then defaults to fetch data
for all items in the collection.

Note: Specifying ItemID as Null or Empty is equivalent to not supplying it.

Return Value

A 2-dimensional array of Variants with the following format:

Variant ItemID Variant VQT

one row for each Item, where ItemID is the Item Id and VQT is a 2-dimensional Variant
array with the format:

Variant Value Long Quality Date Timestamp

with one row for each data point.

Note: The Return Value may be NULL and clients should check for this. This indicates
that no data is returned for this query.

IM 36J04A14-01E 7th Edition Issue 1 December 28 2005-08

18-6 Chapter 18 QDataAccess Object API Reference

18.9 Remove Method

Description

Remove an Item Id from the collection of Items of interest.

Signature
Sub Remove (ItemID As Variant)

Parameters

ItemId - specifies the Item of interest. This should be an 8 byte array as returned by the
browser.

18.10 SetProcessOptions Method

Description

Allows the processing of item data to be specified.

Cancels any current query.

Signature
Sub SetProcessOptions(Optional UpdateRate As Variant, _
Optional InterpMethod As qdaInterpMethod, _
Optional EdgeValueOptions As qdaEdgeValueOptions, _
Optional TimeIncrement As Variant, _
Optional ResampleInterval As Variant, _
Optional bUTC As Boolean = False)

Parameters

UpdateRate - specifies the maximum rate at which the client is to be notified of data
changes. If not specified the default is 5 seconds (must be specified as DATE.) The DATE
is converted to an interval by subtracting the earliest date that can be represented by the
DATE data type, i.e. midnight on 30th December 1899. This allows VB assignments such as
#00:00:05# for 5 seconds, or #00:02:00# for 2 minutes.

Note: Specifying UpdateRate as Null or Empty is equivalent to not supplying it.

InterpMethod - determines how the raw historised data should be processed. If not
specified then defaults to qdaPreviousForward.

Otherwise one from the enumeration qdaInterpMethod:

qdaDefault=0 the default (qdaPreviousForward)

IM 36J04A14-01E 7th Edition Issue 1 December 28 2005-08

Exaquantum API Reference Manual 18-7

qdaNextBackward=1 Cast the next value backwards. (Not supported)

qdaPreviousForward=2 Cast the previous value forwards.

qdaLinear=3 Linear interpolation between the previous and next values. (Not
supported)

EdgeValueOption - determines how data matching the start and end times of a historical
query should be processed. If not specified then defaults to qdaIncludeEdge.

Otherwise one from the enumeration qdaEdgeValueOptions:

qdaIncludeEdge=0 Include values at specified start and end times by using the
propagating data using the selected interpolation method.

qdaIncludeBoundingValues =1 Include bounding value i.e. the data point immediately

before the requested start time.

TimeIncrement - If this is specified, a timed request for history data will be made at the
UpdateRate, incrementing the SpotTime or StartTime by this amount. If latest data is
requested, polling is simulated by firing the latest value to the Client at the UpdateRate
(must be specified as DATE). See UpdateRate for details of how the DATE type is
interpreted as an interval.

Note: Specifying TimeIncrement as Null or Empty is equivalent to not supplying it.

ResampleInterval - If this is specified, history data will be resampled to provide exactly one
point per ResampleInterval (Must be specified as DATE.). See UpdateRate for details of
how the DATE type is interpreted as an interval.

Timestamps for all items except Minimum and Maximum Aggregation result items are
returned as the fixed ResampleInterval time. If an Aggregation result item is resampled at
its aggregation period, Exaquantum shutdown points within a period are automatically
screened out.

Minimum and Maximum Aggregation result items show the timestamp of the actual
minimum or maximum value within the ResampleInterval. Any Minimum or Maximum
Aggregation result item data with Deleted secondary quality is screened out.

Note: Specifying ResampleInterval as Null or Empty is equivalent to not supplying it.

bUTC If specified as True the timestamps returned will be in UTC. The timestamp that is
specified in SetQueryTime(), WriteValue(), should be in UTC as well. The default is False.

IM 36J04A14-01E 7th Edition Issue 1 December 28 2005-08

18-8 Chapter 18 QDataAccess Object API Reference

18.11 SetQueryTimes Method

Description

Allows the period or point in time to be specified for the items of interest.

Cancels any current query.

Signature
Sub SetQueryTimes(Optional SpotTime As Variant, _
Optional StartTime As Variant, _
Optional EndTime As Variant)

Parameters

SpotTime - if specified, return data at this time otherwise return live data (must be specified
as a DATE).

Note: Specifying SpotTime as Null or Empty is equivalent to not supplying it.

StartTime & EndTime - If only StartTime is specified then return data from this time to the
latest data. If both StartTime and EndTime are specified then return data over this period
(must be specified as DATE).

Note 1: Specifying StartTime or EndTime as Null or Empty is equivalent to not supplying

them.

Note 2: If the period of time specified by StartTime and EndTime falls wholly or partially in
the future (with respect to the Exaquantum Server clock), then additional data points
will be introduced in the data returned by DataAccess with a data quality of
Bad/Not Available. The points will be introduced for all times greater than the
Exaquantum Server clock.

IM 36J04A14-01E 7th Edition Issue 1 December 28 2005-08

Exaquantum API Reference Manual 18-9

18.12 SetFilterParameters Method

This method is defined on both the IQDataAccess and IQDataAccessMulti interfaces.

Description

This method may be called before performing a read of history data to specify a filter to pre-
process the data. Any current query is cancelled.

Signature
Sub SetFilterParameters( Optional FilterParameters As Variant )

Parameters

FilterParameters - An optional VARIANT holding an array of filter parameters. If

specified, the VARIANT should hold an array of VARIANTs, with the first array member
being the long identity of the filter algorithm and subsequent parameters being algorithm-
dependent.

If called with no arguments any existing filter parameters are unset.

Parameters Definition

The following table shows the details of the parameters:

Table 18-1

Array parameters

Filter Description Element Contents Data type

Algorith Number
m ID
1 Interpolated 0 Id = 1 Long integer
data
1 Number of periods Long integer
2 Mean 0 Id = 2 Long integer
1 Interval Period (1 second Date
upwards)
0 = Aggregation of whole period
2 Partial aggregation support option Boolean
flag (0/1)
3 Summation 0 Id = 3 Long integer
1 Interval Period (1 second Date
upwards)
0 = Aggregation of whole period

IM 36J04A14-01E 7th Edition Issue 1 December 28 2005-08

18-10 Chapter 18 QDataAccess Object API Reference

Array parameters

Filter Description Element Contents Data type

Algorith Number
m ID
2 Partial aggregation support option Boolean
flag (0/1)
3 Sum Time Factor (0 to 3600 Date
seconds). Only used if element 4
is FALSE.
4 Use Differential Summation Boolean

5 Reset Value. Only used if element Double

4 is TRUE.
6 Maximum number of Decimal Integer
places. Only used if element 4 is
TRUE.
7 Percentage Difference. Only used Double
if element 4 is TRUE.
4 Maximum 0 Id = 4 Long integer
1 Interval Period (1 second Date
upwards)
0 = Aggregation of whole period
2 Partial aggregation support option Boolean
flag (0/1)
5 Minimum 0 Id = 5 Long integer
1 Interval Period (1 second Date
upwards)
0 = Aggregation of whole period
2 Partial aggregation support option Boolean
flag (0/1
6 Standard 0 Id = 6 Long integer
Deviation
1 Interval Period (1 second Date
upwards)
0 = Aggregation of whole period
2 Partial aggregation support option Boolean
flag (0/1)
7 Spot Value 0 Id = 7 Long integer

IM 36J04A14-01E 7th Edition Issue 1 December 28 2005-08

Exaquantum API Reference Manual 18-11

Array parameters

Filter Description Element Contents Data type

Algorith Number
m ID
1 Interval Period (1 second Date
upwards)
0 = Aggregation of whole period
2 Partial aggregation support option Boolean
flag (0/1)
8 Count 0 Id = 8 Long integer
1 Interval Period (1 second Date
upwards)
0 = Aggregation of whole period
2 Partial aggregation support option Boolean
flag (0/1)
3 On State value Variant
9 OnTime 0 Id = 9 Long integer
1 Interval Period (1 second Date
upwards)
0 = Aggregation of whole period
2 Partial aggregation support option Boolean
flag (0/1)
3 On State value Variant

IM 36J04A14-01E 7th Edition Issue 1 December 28 2005-08

18-12 Chapter 18 QDataAccess Object API Reference

18.13 SetSession Method

Description

This method may be called by a client to allow the QDataAccess object to share its Session
connection. This is the recommended way to use QDataAccess.

If this method is not called before a request to fetch data, the QDataAccess object will create
its own Session object.

Signature
Sub SetSession(pSession As Object)

Parameters

pSession - A pointer to the clients Session object

18.14 WriteValue Method

Description

This method may be called by a client to write Values into an Item.

Signature
Sub WriteValue (Value As Variant, _
Optional Item As Variant, _
Optional Quality As Variant, _
Optional TimeStamp As Variant)

Parameters

Value - The new value to be written to the Item.

Item - The ItemId of the Item as an 8-byte array. This need not be specified if there is only a
single item in the collection.

Note: Specifying Item as Null or Empty is equivalent to not supplying it.

Quality - The quality of the new value to be written to the Item. This defaults to GOOD if
not specified. If specified, it must be long integer.

If the primary quality Assumed is written to an Item that is not Offline, the Item quality will
remain unchanged. If a new value is written to an Offline Item, its secondary quality will
always be set to Replaced.

Note: Specifying Quality as Null or Empty is equivalent to not supplying it.

IM 36J04A14-01E 7th Edition Issue 1 December 28 2005-08

Exaquantum API Reference Manual 18-13

Timestamp - The timestamp of the new value to be written to the Item. This defaults to the
current time if not specified. If specified, it must be DATE.

Note: Specifying Timestamp as Null or Empty is equivalent to not supplying it.

18.15 WriteHistoryValue Method

Description

This method may be called by a client to write Values into the history of an Item. The
method blocks until the write to history is complete. The new value is written directly to
history even if the timestamp is more recent than the latest timestamp in the Item.

Signature
Sub WriteHistoryValue(Value As Variant, _
Item As Variant, _
Quality As Long, _
TimeStamp As Date, _
Optional WaitTimeout As Long)

Parameters

Value - The new value to be written to the Item.

Item - The ItemId of the Item as an 8-byte array.

Quality - The quality of the new value to be written to the Item as a long integer.

Timestamp - The timestamp of the new value to be written to the Item as a DATE.

WaitTimeout - The time in milliseconds to block before timing out. Default is 5 minutes.

Note: If a value less than or equal to zero is specified, the default is used.

IM 36J04A14-01E 7th Edition Issue 1 December 28 2005-08

18-14 Chapter 18 QDataAccess Object API Reference

This page intentionally left blank

IM 36J04A14-01E 7th Edition Issue 1 December 28 2005-08

Exaquantum API Reference Manual 19-1

Chapter 19 QDataAccessMulti Object API Reference

QDataAccessMulti object that is directly created by a client provides IQDataAccessMulti
interfaces.

It provides access to Exaquantum Item data distributed across multiple servers. Only
synchronous access is provided.

Only the methods detailed in this section are supported on this interface, all other methods
should not be used.

In addition to the specific errors listed, any method may return the standard system errors
E_INVALIDARG (for a parameter of incorrect type) or E_OUTOFMEMORY.

19.1 Add Method

Description

The client adds paths to item data that it is interested in. Data is fetched for the entire
collection when ReadValue() is called.

Internally QDataAccessMulti calls the RBNSBrowse object which browses the Role-Based
Namespace to fetch the ServerID, ServerName and ItemID for each Item path

Signature
Sub Add(ItemPath as String)

Parameters

ItemPath - A full path to an Item from the Role-Based Namespace for this user

Errors

May return any of the errors defined for QDataAccess::Add()

19.2 Clear Method

Description

Cancels any current data request, removes all added paths and clears all internally allocated
resources.

Signature
Sub Clear()

IM 36J04A14-01E 7th Edition Issue 1 December 28 2005-08

19-2 Chapter 19 QDataAccessMulti Object API Reference

19.3 Cancel Method

Description

Cancels any current read data request but maintains list of added Items.

Signature
Sub Cancel ()

19.4 ReadValue Method

Description

Reads the values of all added items using the current time and processing options set for the
QDataAccessMulti Object.

If no query is currently active, internally it creates a Session2 object for each group of Items
and sets the ServerName for that group. It also creates a QDataAccess object for each group
and passes in the Session2 object. It then calls SetQueryTimes and SetProcessOptions
passing on its own settings to each QDataAccess object and finally calls Execute() on each
QDataAccess object to obtain the data asynchronously. Subsequent calls to ReadValue()
retrieve data from the QDataAccess cache. If the query times are not set, updating live data
is fetched so that the value in the cache is always up to date.

Signature
Function ReadValue() As Variant

Parameters

Data - A 2-dimensional array of VARIANTs with the following format:

BSTR ItemPath VARIANT VQT

One row for each Item, where ItemPath is the added Item Path and VQT is a 2-dimensional
VARIANT array with the format:

VARIANT Value long Quality DATE Timestamp

One row for each data point.

N.B. Item Paths are returned in the same order in which they were added.

The array for return is built by calling QDataAccess::ReadValue() specifying an individual

ItemID for each Item Path in the collection in order.

If an Exaquantum server is unavailable, Item data for that server will appear with quality
BAD/NOTAVAILABLE when the server is restarted live and updating history data will
automatically be recovered.

IM 36J04A14-01E 7th Edition Issue 1 December 28 2005-08

Exaquantum API Reference Manual 19-3

Errors

Any of the errors defined for QDataAccess::ReadValue() may be returned

19.5 SetQueryTimes Method

Description

Allows the period or point in time to be specified for the items of interest.

Cancels any current read query.

If times are specified as type string or string by reference, internally QDataAccessMulti calls
QTimeHelper::ParseTimes() to validate the time formats.

Signature
Sub SetQueryTimes( _
Optional SpotTime as Variant, _
Optional StartTime as Variant, _
Optional EndTime as Variant)

Parameters

SpotTime - If specified, return data at this time otherwise return the latest data.

If latest data is requested, the client will be notified when the data changes. (Must be
specified in one of the formats described below.)

StartTime & EndTime - If only StartTime is specified then return data from this time to the
latest data.

If both StartTime and EndTime are specified then return data over this period. (Must be
specified in one of the formats described below.)

Errors

E_Q_STARTTIMEAFTEREND - Start time is later than end time (from QDataAccess).

IDS_ERR_InvalidTime - Invalid time format specified (from QTimeHelper)

IM 36J04A14-01E 7th Edition Issue 1 December 28 2005-08

19-4 Chapter 19 QDataAccessMulti Object API Reference

19.6 SetReportTimes Method

Description

If times are specified to SetQueryTimes() as type string or string by reference, internally

QDataAccessMulti passes the Report Times to QTimeHelper::SetReportTimes() followed
by calling QTimeHelper::ParseTimes() to validate the time formats.

Signature
Sub SetReportTimes ( _
Optional ReportStart as Variant, _
Optional ReportEnd as Variant, _
Optional SpotTime as Variant)

Parameters

ReportStart - Defines the time specification to be substituted if ReportStart is referenced

in times specified to SetQueryTimes(). If not specified, defaults to Now.

ReportEnd - Defines the time specification to be substituted if ReportEnd is referenced in

times specified to SetQueryTimes(). If not specified, defaults to Now.

SpotTime - Defines the time specification to be substituted if SpotTime is referenced in

times specified to SetQueryTimes(). If not specified, defaults to Now.

Errors

IDS_ERR_InvalidTime - Invalid time format specified (from QTimeHelper)

Valid Time formats

Times may be specified to QDataAccessMulti in the following syntax (in BNF):

TimeSpec ::= ((<ABSOLUTEDATE>) | (<NOW> (+ | -) <number> <TIMELBL>)) |

( <PRODCALDATE> + <number> (<PRODCALPERIOD>)) | (<RANGE>) |
(<RESERVED> (+ | -) <number> <TIMELBL>))

<ABSOLUTEDATE> ::= System date format including time always taken as client local
machine time unless the bUTC flag is set in SetProcessOptions()

e.g. #31/12/00 01:00:00#

<NOW> ::= Current server time (taken from the Designated Server)

<number ::= (0..9)

<TIMELBL> ::= (S... | M... | H... | D...) abbreviations for Seconds, Minutes, Hours, Days

e.g. now 1 hour

IM 36J04A14-01E 7th Edition Issue 1 December 28 2005-08

Exaquantum API Reference Manual 19-5

< PRODCALDATE > ::= System date format excluding time

< PRODCALPERIOD >::= A valid Production Calendar Period name (as configured on the
Designated Server)

e.g. 31/12/00 + 1 (SHIFT)

<RANGE> ::= Where the StartTime is specified using the Production Calendar, RANGE
may be used to specify the EndTime as the end of the specified Production Calendar Period.

<RESERVED> ::= (NOW | REPORTSTART | REPORTEND | SPOTTIME)

19.7 SetProcessOptions Method

Description

Allows the processing of the raw item data to be specified.

Cancels any current read query.

Signature
Sub SetProcessOptions( _
Optional UpdateRate As Variant, _
Optional InterpMethod As qdaInterpMethod = 0, _
Optional EdgeValueOptions As qdaEdgeValueOptions = 0, _
Optional TimeIncrement as Variant, _
Optional ResampleInterval as Variant, _
Optional bUTC As Boolean, _
Optional TZIndex As Long = -1)

Parameters

UpdateRate - Specifies the maximum rate at which the client is to be notified of data
changes. The default is 5 seconds. (Must be specified as DATE.)

InterpMethod - Currently only qdaPreviousForward is supported. See appendix for the use
of interpolation.

EdgeValueOptions - One of:

qdaIncludeEdge=0 Include values at specified times. (default) (see figure 2)

qdaIncludeBoundingValues =1 Include bounding values. [See Note 1]

TimeIncrement - If this is specified, a timed request for history data will be made at the
UpdateRate, incrementing the SpotTime or StartTime by this amount. If latest data is
requested, polling is simulated by firing the latest value to the Client at the UpdateRate.
(Must be specified as DATE.)

IM 36J04A14-01E 7th Edition Issue 1 December 28 2005-08

19-6 Chapter 19 QDataAccessMulti Object API Reference

ResampleInterval - If this is specified, history data will be resampled to provide exactly one
point per ResampleInterval (see figures 3 and 4). (Must be specified as DATE.)

BUTC - If set TRUE, timestamps specified in SetQueryTimes are interpreted as UTC and
timestamps are returned in UTC. Defaults to FALSE where times are specified and returned
as local time.

TZIndex - A long integer uniquely identifying the client Time Zone. If specified, time
conversions to and from UTC will be performed using the specified Time Zone rather than
the current Time Zone.

This allows conversions between UTC and local time to be performed on the server when the
server and client are running in different time zones.

If the UTC flag is set TRUE, the value of TZIndex will be ignored and no local time
conversions will be performed.

TZIndex will usually be obtained by calling method GetTZIndex() on QTimeHelper.

Note : Bounding values are returned when the requested times do not exactly lie on points
stored in history. They are the first point before the start time and the last point after
the end time. If Bounding Values are requested, data is returned directly from
QHistorian and may in some circumstances comprise only one data point.

19.8 SetFilterParameter Method

Description

This method may be called before performing a read of history data to specify a filter to pre-
process the data. Any current query is cancelled. For full details see section 18.12
SetFilterParameters Method

19.9 AddWrite Method

Description

Writes the specified value, quality and timestamp to the specified Item.

Internally QDataAccessMulti queries the RBNSBrowse object which browses the Role
Based Namespace to obtain ServerID, ServerName and ItemID. It groups Items according to
Server.

Signature
Sub AddWrite (ItemPath as String, _
Value As Variant, _
Optional Quality As Variant, _
Optional Timestamp as Variant)

IM 36J04A14-01E 7th Edition Issue 1 December 28 2005-08

Exaquantum API Reference Manual 19-7

Parameters
ItemPath - A fully specified path to the Item through the Role-Based Namespace.

Value - The new value to be written to the Item.

Quality - The quality of the new value to be written to the Item. Defaults to GOOD. If
specified, must be long integer.

Timestamp - The timestamp of the new value to be written to the Item. Defaults to the
current time. If specified, must be DATE.
Errors

Any error defined for IQItemWriter::Add() may be returned

E_Q_INVALIDPATH - The specified path does not exist or the user does not have access
rights to view the namespace

E_Q_NOWRITEACCESS - The user does not have write access to the Item

19.10 ExecuteWrite Method

Description

Called by client to write all registered data to Exaquantum servers.

Internally creates a QItemWriter object for each Server group of Items and calls Add one or
more times, and Execute on each. The returned status arrays are amalgamated for return to
the client.

Signature
Function ExecuteWrite(Optional Reason As String = ) As Variant

Parameters

Reason - An optional string describing why the data is being written. Must be specified for
CFR Part 11 compliance.

The Variant returned contains a 2-dimensional array of ItemPath/Status Code where the
StatusCode is the worst return code for any value written to the item, i.e.

S_OK = all successful,

S_FALSE = at least one value not written to real-time database for this item,

<0 = error, one or more values not written to this item.

Errors

Any error defined for IQItemWriter::Execute() may be returned

IM 36J04A14-01E 7th Edition Issue 1 December 28 2005-08

19-8 Chapter 19 QDataAccessMulti Object API Reference

19.11 CancelWrite Method

Description

Clears any Item data entered by the AddWrite() method before Execute() has been called.

Signature
Sub CancelWrite ()

19.12 Remove Method

Description

This method removes paths to specified items added using the Add() method.

Signature
Sub Remove (ItemPath As String)

Parameters

ItemPath - A full path to an Item from the Role-Based Namespace for this user

Errors

May return any of the errors defined for QDataAccess::Remove()

If called when object is in intrinsic mode, will return E_INVALIDARG

19.13 Execute Method

Description

Starts acquiring data asynchronously using current time and processing options set for the
QDataAccessMulti object.

Signature

Sub Execute ( optional WithChanges As Boolean = TRUE, _

optional ReturnDataAsReady As Boolean = TRUE )

Parameters

WithChanges - When requesting latest data, if set FALSE then only a single event will be
fired to the client for each Item. The default is to notify the client whenever the value of any
Item in the collection changes.

IM 36J04A14-01E 7th Edition Issue 1 December 28 2005-08

Exaquantum API Reference Manual 19-9

ReturnDataAsReady - When requesting historical data, if set FALSE then all the values for
each Item will be returned in a single event. The default is to send data as soon as it is
available to allow a more responsive user interface.

Errors

Can return any of the errors defined for:

IQDataAccess::Add()

IQDataAccess::Execute()

19.14 OnData Event Method

Description

This method is called back on the client for asynchronous events initiated by Execute().

Signature
Event OnData (ItemPath As String, _
DataReturnType As qdaDataReturnType, _
Data As Variant)

Parameters

ItemPath is the full path to an Item from the Role-Based Namespace for this user.

DataReturnType One of enumeration qdaDataReturnType :

qdaNew=0 This is new data for this item. This is always the type for the first
notification for an item after Execute(), and for latest data.

qdaMoreRows=1 For trend data, this is additional data to append to previously received
data.

qdaEnd=2 For historical data, this is the final data for this Item.

Data - A 2-dimensional array of Variants with the following format:

Variant Value Long Quality Date Timestamp

where spot data has only one row and trend data has one row for each time point.

Note: Data may be NULL and clients should check for this. This indicates that no data is
returned for this firing of the event.

IM 36J04A14-01E 7th Edition Issue 1 December 28 2005-08

19-10 Chapter 19 QDataAccessMulti Object API Reference

19.15 OnError Event Method

Description

This method is called back on the client for asynchronous requests if an error occurs.

Signature
Event OnError(Number As Long, _
Description As String, _
Source As String, _
HelpFile As String, _
HelpContext As Long)

Parameters

Number - is the Quantum error number.

Description - is the error text.

Source - is the component that raised the error.

HelpFile - is the name of the HelpFile containing further information on the error.

HelpContext - is the Help context number.

IM 36J04A14-01E 7th Edition Issue 1 December 28 2005-08

Exaquantum API Reference Manual 20-1

Chapter 20 QAEAccess Object API Reference

The AEAccess Object allows Alarm and Event data history to be read for one or more OPC
Gateway.

OPC Gateways of interest are specified by OPCAEPump Ids, these can be resolved the OPC
Gateway name by retrieving the column OPCAEPumpHistId from the table OPCServer in
the QConfig SQL Server database. Before Alarm and Event history can be read for a
specific OPC Gateway, its OPCAEPumpHistId must first be added to a collection
maintained by QAEAccess. After filling the collection, clients select the function they
require either for the whole collection (typical) or for individual items in the collection.

20.1 Add Method

Description

Add an OPCAEPumpHistId to the collection of OPC Gateways of interest. On add, if a

request for data is current, data for the new OPCAEPumpHistId will be fetched
automatically.

Signature
Sub Add (AEPumpID As Variant)

Parameters

AEPumpId - specifies the OPC Gateway of interest. This should be an 8 element byte array
as returned from column OPCAEPumpHistId from the table OPCServer.

20.2 Cancel Method

Description

Cancels the current request.

Signature
Sub Cancel ()

20.3 ClearFilterOptions Method

Description

Clears any filters set up by SetFilterOptions().

Signature
Sub ClearFilterOptions ()

IM 36J04A14-01E 7th Edition Issue 1 December 28 2005-08

20-2 Chapter 20 QAEAccess Object API Reference

20.4 Count Property

Description

Read the number of OPC Gateways in the collection of OPC Gateways of interest.

Signature
Property Count () As Long

20.5 Execute Method

Description

Starts the asynchronous acquiring of data using the current time, filter and processing
options set for the QAEAccess Object.

Data is returned via the OnAE event.

Note: If the user calls the Execute Method before the previous Execute operation is
complete/canceled, it returns an error.

Signature
Sub Execute(Optional ReturnEventsAsReady As Boolean = True)

Parameters

ReturnEventsAsReady - When requesting historical data, if set FALSE then all the values
for each OPC Gateway will be returned in a single event. The default is to send data as soon
as it is available to allow a more responsive user interface.

20.6 Item Method

Description

Return a OPCAEPumpHistId from the collection.

Signature
Function Item(Index As Variant) as Variant

Parameters

Index - is the position in the collection.

Return Value

The 8 element byte array representing the OPCAEPumpHistId.

IM 36J04A14-01E 7th Edition Issue 1 December 28 2005-08

Exaquantum API Reference Manual 20-3

20.7 OnAE Event Method

Description

This method is called back on the client for asynchronous events initiated by Execute().

Signature
Event OnAE(EventReturnType As qaeEventReturnType, _
Events As Variant)

Parameters

EventReturnType - One of ennumeration qaeEventReturnType from:

qeaNew=0 This is new data for this OPCAEPumpHistId. This is always the type for
the first notification for an OPCAEPumpHistId after Execute(). This is not used if
Execute is called with ReturnEventsAsReady=False.

qeaMoreEvents=1 This is additional data to append to previously received data. This is

not used if Execute is called with ReturnEventsAsReady=False.

qeaEnd=2 This is the final piece of data for this OPCAEPumpHistId.

Events A 2-dimensional array of Variant with the following format:

Variant OPCAEPumpHistId

String Source

String Message

Date Timestamp

Long SequenceNo

Long Category

Long Severity

String ConditionName

Long NumberOfAttributes

Variant Attributes

one row for each Alarm/Event.

IM 36J04A14-01E 7th Edition Issue 1 December 28 2005-08

20-4 Chapter 20 QAEAccess Object API Reference

The Attributes column contains a 1-dimensional array of Variant attributes, the number and
order of which are configured in the QConfig database for the particular Event Category.

The data is returned in time order from the oldest to the newest event with records from
different OPC Gateways interleaved as necessary.

Note: Events may be NULL and clients should check for this. This indicates that no data
is returned for this firing of the event.

This information is as defined by the OPC Foundation for the OPC Alarm and Event
Interface Specification.

20.8 OnError Event Method

Description

This method is called back on the client for asynchronous requests if an error occurs.

Signature
Event OnError(Number As Long, _
Description As String, _
Source As String, _
HelpFile As String, _
HelpContext As Long)

Parameters

Number - is the Quantum error number.

Description - is the error text.

Source - is the component that raised the error.

HelpFile - is the name of the HelpFile containing further information on the error.

HelpContext - is the Help context number.

IM 36J04A14-01E 7th Edition Issue 1 December 28 2005-08

Exaquantum API Reference Manual 20-5

20.9 ReadValue Method

Description

Perform a synchronous read for values of Alarm and Events data using the current time,
filter and processing options set for the QAEAccess Object.

Data is read for all OPCAEPumpHistIds in the QAEAccess collection.

Note: If the user calls the ReadValue Method during asynchronous operations (Execute
request) is in progress, it returns an error.

Signature
Function ReadValue () As Variant

Return Value

This is a 2-dimensional Variant array with the format:

Variant OPCAEPumpHistId

String Source

String Message

Date Timestamp

Long SequenceNo

Long Category

Long Severity

String ConditionName

Long NumberOfAttributes

Variant ATTRIBUTES

one row for each Alarm/Event.

The Attributes column contains a 1-dimensional array of Variant attributes, the number and
order of which are configured in the QConfig database for the particular Event Category.

The data is returned in time order from the oldest to the newest event with records from
different OPC Gateways interleaved as necessary.

Note: The Return Value may be NULL and clients should check for this. This indicates
that no data is returned for this query.

IM 36J04A14-01E 7th Edition Issue 1 December 28 2005-08

20-6 Chapter 20 QAEAccess Object API Reference

This information is as defined by the OPC Foundation for the OPC Alarm and Event
Interface Specification.

20.10 Remove Method

Description

Remove a OPCAEPumpHistId from the collection of OPC Gateways of interest.

Signature
Sub Remove(AEPumpID As Variant)

Parameters

AEPumpId - specifies the OPC Gateway of interest. This should be an 8 element byte array
from column OPCAEPumpHistId from the table OPCServer.

20.11 SetFilterOptions Method

Description

Allows filtering of the Alarm and Event data that will be returned to be specified.

Cancels any current query.

Signature
Sub SetFilterOptions(
FilterField As qdaAEFilterField, _
FilterOperator As qdaAEFilterOperator, _
varMatch As Variant)

Parameters

FilterField - is one of enumeration qdaAEFilterFields:

qdaAEFilterMessage=2 Filter on the Message field.

qdaAEFilterGeneric=3 Use the varMatch parameter as a valid SQL string to be applied

directly to the SQL query.

FilterOperator - is one of enumeration qdaAEFilterOperator:

qdaAEFilterLikeOperator=1 Match field specified in FilterField with value specified in

varMatch allowing wildcard characters '*'.

IM 36J04A14-01E 7th Edition Issue 1 December 28 2005-08

Exaquantum API Reference Manual 20-7

varMatch - is the filter operator parameter. May contain the wildcard * to match many or
no characters and the wildcard ? to match any single character.

Both or neither filter options may be set.

The filters are applied in the form <alarm/event query> WHERE ( message LIKE
<MsgFilter> ) AND ( <Filter> ). For example, to return events that have a Severity of
500 and a Data Value of more than 20 use the string (Severity = 500) AND (DataValue
> 20).

It is important that this field is set correctly as now validation is carried out. The names of
the fields for comparison can be obtained from the event storage tables in the Historian
databse.

20.12 SetProcessOptions Method

Description

Allows the processing of Alarm and Event data to be specified.

Cancels any current query.

Signature
Sub SetProcessOptions(Optional UpdateRate As Variant, _
Optional ActiveTime As Variant, _
Optional MaximumEvents As Long = -1)

Parameters

UpdateRate - specifies the rate at which history should be polled to check for new
alarms/events (must be specified as DATE). The DATE is converted to an interval by
subtracting the earliest date that can be represented by the DATE data type i.e. midnight on
30th December 1899. This allows VB assignments such as #00:00:05# for 5 seconds or
#00:02:00# for 2 minutes.

Note: Specifying UpdateRate as Null or Empty is equivalent to not supplying it.

ActiveTime - specifies the time band before the previous EndTime which should be re-
queried to catch any late-arriving events (must be specified as DATE). See UpdateRate for
details of how the DATE data type is interpreted as an Interval.

Note: Specifying ActiveTime as Null or Empty is equivalent to not supplying it.

IM 36J04A14-01E 7th Edition Issue 1 December 28 2005-08

20-8 Chapter 20 QAEAccess Object API Reference

MaximumEvents - specifies the maximum number of Alarm and Event records that will be
returned to the client. Processing begins at the specified start time, with data returned to the
client for subsequent times until this limit is reached. At this point any additional events are
discarded and not returned to the client. This option allows the client to limit the number of
events returned in the case where this may be very large. MaximumEvents is ignored if an
UpdateRate is specified.

20.13 SetQueryTimes Method

Description

Allows the period to be specified for the portion of Alarm and Event history of interest.

Cancels any current query.

Signature
Sub SetQueryTimes(Optional StartTime As Variant, _
Optional EndTime As Variant)

Parameters

StartTime & EndTime - If only StartTime is specified, then return data from this time to
the latest data. If both StartTime and EndTime are specified, then return data over this
period (must be specified as DATE).

Note: Specifying StartTime or EndTime as Null or Empty is equivalent to not supplying

them.

20.14 SetSession Method

Description

This method may be called by a client to allow the QAEAccess object to share its Session
connection. This is the recommended way to use QAEAccess.

If this method is not called before a request to fetch data, the QAEAccess object will create
its own Session object.

Signature
Sub SetSession (pSession As Object)

Parameters

pSession - A pointer to the clients Session object.

IM 36J04A14-01E 7th Edition Issue 1 December 28 2005-08

Exaquantum API Reference Manual 21-1

Chapter 21 QQualityHelper Object API Reference

The QQualityHelper object can be used to interpret the 32 bit Raw data quality code for an
Item.

The Raw Data Quality of an Item encodes both Primary and Secondary qualities. The
QQualityHelper object has enumeration qdaQuality and qdaSecondaryQuality to determine
the Primary and Secondary Data Qualities respectively.

21.1 IsBad Method

Description

Tests whether the Primary Data Quality is Bad based on the Raw Data Quality passed in.

Signature
Function IsBad(RawQuality As Long) as Boolean

Parameters

RawQuality - specifies the Raw Data Quality.

Return Value

Returns a TRUE or FALSE.

21.2 IsGood Method

Description

Tests whether the Primary Data Quality is Good based on the Raw Data Quality passed in.

Signature
Function IsGood(RawQuality As Long) as Boolean

Parameters

RawQuality - specifies the Raw Data Quality.

Return Value

Returns TRUE or FALSE.

IM 36J04A14-01E 7th Edition Issue 1 December 28 2005-08

21-2 Chapter 21 QQualityHelper Object API Reference

21.3 IsUncertain Method

Description

Tests whether the Primary Data Quality is Uncertain based on the Raw Data Quality passed
in.

Signature
Function IsUncertain(RawQuality As Long) as Boolean

Parameters

RawQuality - specifies the Raw Data Quality.

Return Value

Returns TRUE or FALSE.

21.4 IsAssumed Method

Description

Tests whether the Primary Data Quality is Assumed, based on the Raw Data Quality passed
in.

Signature
Function IsAssumed(RawQuality As Long) as Boolean

Parameters

RawQuality - specifies the Raw Data Quality.

Return Value

Returns TRUE or FALSE.

21.5 Quality Method

Description

Returns an enumeration for the Primary Data Quality based on the Raw Data Quality passed
in.

Signature
Function Quality(RawQuality As Long) as qdaQuality

IM 36J04A14-01E 7th Edition Issue 1 December 28 2005-08

Exaquantum API Reference Manual 21-3

Parameters

RawQuality- specifies the Raw Quality for an Item.

Return Value

One of enumerated qdaQuality is returned:

qdaQualityGood=0 The Primary Quality is Good

qdaQualityUncertain=1 The Primary Quality is Uncertain

qdaQualityBad=2 The Primary Quality is Bad

qdaQualityUnknown=3 The Primary Quality is Unknown

21.6 QualityText Method

Description

Returns the Primary Quality Text as a string based on the Raw Data Quality passed in.

Signature
Function QualityText(RawQuality As Long) as String

Parameters

RawQuality - specifies the Raw Data Quality for an Item.

Return Value

Returns Primary Raw Data Quality as a string.

21.7 SecondaryQuality Method

Description

Returns an enumeration for the Secondary Data Quality based on the Raw Data Quality
passed in.

Signature
Function SecondaryQuality(RawQuality As Long) As qdaSecondaryQuality

Parameters

RawQuality - specifies the Raw Data Quality for an Item.

IM 36J04A14-01E 7th Edition Issue 1 December 28 2005-08

21-4 Chapter 21 QQualityHelper Object API Reference

Return Value

One of enumerated qdaSecondaryQuality is returned.

qdaSecondaryQualityNone=0 None

qdaSecondaryQualityBadCalc=1 Bad calculation result.

qdaSecondaryQualityEstimated=2 Estimated aggregation result.

qdaSecondaryQualityOffline=3 Item offline.

qdaSecondaryQualityOfflineArch=4 Data not available because archive is offline.

qdaSecondaryQualityNotAvail=5 Data not available for the specified time.

qdaSecondaryQualityShutdown=6 Item shutdown marker.

qdaSecondaryQualityOPCError=7 OPC Communications error.

qdaSecondaryQualityTimeChange=8 Aggregations have detected a time change.

qdaSecondaryQualityBeginCatchup=9 Historical data was requested from OPC Server.

qdaSecondaryQualityDeleted=10 Deleted.

qdaSecondaryQualityReplaced=11 Offline Item has been manually overwritten.

qdaSecondaryQualityUnknown=9 Unknown.

21.8 SecondaryQualityText Method

Description

Returns the Secondary Quality Text as a string based on the Raw Data Quality passed in.

Signature
Function SecondaryQualityText(RawQuality As Long) As String

Parameters

RawQuality - specifies the Raw Data Quality for an Item.

Return Value

Returns Secondary Data Quality as a string.

IM 36J04A14-01E 7th Edition Issue 1 December 28 2005-08

Exaquantum API Reference Manual 21-5

21.9 RawQuality Method

Description

Returns the Raw Data Quality based on the enumerations qdaQuality and
qdaSecondaryQuality passed in.

Signature

Function RawQuality(Quality As qdaQuality, _

Optional SecondaryQuality As qdaSecondaryQuality) As Long

Parameters

Quality - specifies the enumerated Primary Quality for an Item.

SecondaryQuality - specifies the enumerated Secondary Quality for an Item. If not supplied
then assumes

Return Value

Returns the Raw Data Quality based on the combination of Primary Quality and Secondary
Quality passed in.

21.10 QualityTexts Property

Description

Returns a pointer to a collection of Primary Quality Text strings.

This may be used by a Client to present a list of possible Primary Qualities to a user.

Signature
Property QualityTexts () As Object

21.11 SecondaryQualityTexts Property

Description

Returns a pointer to a collection of Secondary Quality Text strings.

This may be used by a Client to present a list of possible Secondary Qualities to a user.

Signature
Property SecondaryQualityTexts () As Object

IM 36J04A14-01E 7th Edition Issue 1 December 28 2005-08

21-6 Chapter 21 QQualityHelper Object API Reference

This page intentionally left blank

IM 36J04A14-01E 7th Edition Issue 1 December 28 2005-08

Exaquantum API Reference Manual 22-1

Chapter 22 Recalculation API Reference

User will use IQRecalcAuto interfaces to conduct recalculation.

For any optional parameters, VARIANT types of VT_ERROR, VT_EMPTY or VT_NULL

will be accepted as missing parameters.

For any method, the standard automation errors such as E_INVALIDARG or

E_OUTOFMEMORY may be returned in addition to any method-specific errors.

Additional general errors may be raised by the recalculation engine these will also be
logged in the Application EventLog to aid in error diagnosis.

General errors

E_RECALC_UNEXPECTED (58432) - An unexpected error has occurred - generally

indicates that an exception has been thrown.

E_RECALC_ERROR (58433) - An internal error has occurred during processing further

details should be available in the Application EventLog.

22.1 NewRecalcJobDefinition method

Description

The user calls this method to create a new recalculation job definition. If successful, the
RecalcJobName property is set to the new job definition.

Signature
Sub NewRecalcJobDefinition ( _
ByVal Name As String, _
Optional ByVal Reason As String = )

Parameters

Name - A unique name to identify this recalculation job. May be up to 256 characters.

Reason - The reason for this recalculation. May be up to 2000 characters.

Errors

E_JOBEXISTS (58435) - A recalculation job already exists with the specified name

E_INVALIDSTRING (58450) - String parameter supplied is either greater than maximum

allowed length or empty.

IM 36J04A14-01E 7th Edition Issue 1 December 28 2005-08

22-2 Chapter 22 Recalculation API Reference

22.2 SetRecalcInputItems method

Description

The user calls this method after creating a new RecalcJobDefinition to specify the items
whose values have been updated in history and whose dependent items should be
recalculated. If changes to the list of items are required, the whole list should be re-specified.
If a failure status code is returned for any Item, this Item is not added to the RecalcInputItem
table.

Signature
Function SetRecalcInputItems (ByVal ItemPaths As Variant) As Variant

Parameters

ItemPaths - May be a single ItemPath as a BSTR, or a SAFEARRAY of ItemPaths to

specify multiple items.

For R2.01.50 only aggregation result items may be specified. An error is returned if any
other item type is specified.

The return value is a single HRESULT defining the status of the requested ItemPath, or if an
array of ItemPaths is specified, a SAFEARRAY of HRESULTS, one for each ItemID in the
input array.

Item Status Codes to be returned

S_OK - The Item is valid and was successfully added as an input Item for this
RecalcJobDefinition

E_ITEMNOTFOUND (58440) - The Item does not exist

E_INVALIDITEMTYPE (58441) - The Item is not a valid type for recalculation. This
error is returned if a reference data Item is specified.

For R2.01.50 this error is returned if the Item is not an Aggregation Result Item.

E_DUPLICATEITEM (58451) - This Item has already been specified.

E_DEPENDENTITEM (58452) - This Item is a dependent item of another specified Recalc

Input Item.

Errors

E_NOJOB (58438) - The RecalcJobName property has not been set.

IM 36J04A14-01E 7th Edition Issue 1 December 28 2005-08

Exaquantum API Reference Manual 22-3

22.3 DeleteRecalcJobDefinition method

Description

The user calls this method to delete a specified job definition.

Signature
Sub DeleteRecalcJobDefinition (ByVal JobName As String)

Parameters

RecalcJobName - A unique name to identify an existing recalculation job to delete. May be

up to 256 characters.

Errors

E_JOBNOTFOUND (58436) - No recalculation job was found with the specified name

E_JOBINUSE (58437) - This recalculation job is in use by another user

22.4 RecalcJobName property

Description

The user sets this property to specify an existing job definition to use. Only one user may use
a given recalculation job definition at one time.

Signature
Property Let RecalcJobName (ByVal Name As String)
Property Get RecalcJobName () As String

Parameters

Name - A unique name to identify this recalculation job. May be up to 256 characters. When
setting the property, any existing JobName is cleared. The property may be set to an empty
string.

Errors

E_JOBNOTFOUND (58436) - No recalculation job was found with the specified name

E_JOBINUSE (58437) - This recalculation job is in use by another user

IM 36J04A14-01E 7th Edition Issue 1 December 28 2005-08

22-4 Chapter 22 Recalculation API Reference

22.5 SetRecalcTimes method

Description

The user calls this method to set the time range for recalculation. Either SpotTime should be
specified for a single point, or StartTime and optionally EndTime to recalculate a range of
data. If StartTime is specified and EndTime is not specified, recalculation will continue to
the current systemtime.

Signature
Sub SetRecalcTimes( _
Optional ByVal SpotTime As Variant, _
Optional ByVal StartTime As Variant, _
Optional ByVal EndTime As Variant)

Parameters

SpotTime - The local timestamp of a single updated point to use to recalculate dependent
items. If specified, must be type VT_DATE. If SpotTime is specified, StartTime and
EndTime will be ignored.

StartTime - The inclusive local start time of a range of data points to use to recalculate
dependent items. If specified, must be type VT_DATE.

EndTime - The inclusive local end time of a range of data points to use to recalculate
dependent items. If specified, must be type VT_DATE. If not specified and StartTime is
specified, EndTime is taken to be the current system time. If SpotTime is specified,
StartTime and EndTime will be ignored.

Errors

E_NOJOB (58438) - The RecalcJobName property has not been set.

E_STARTAFTEREND (58442) - StartTime specified is later than EndTime

E_FUTURETIME (58443) - Future time is specified

22.6 Recalc method

Description

The user calls this method to perform the recalculation. A Recordset of recalculated values is
returned for inspection. The user is not allowed to modify the recalculated values they can
only Commit all values to history or Cancel the recalculation. The QConfig database
RecalcSession table is populated to indicate that a recalculation is active and no other
recalculation may be performed from the beginning of the Recalc() method until completion
of a Commit() or Cancel() call for this recalculation.

If any error occurs during recalculation, the QConfig database RecalcSession table is cleared
of data. Additional error information will be logged to the Windows Application Event Log.

IM 36J04A14-01E 7th Edition Issue 1 December 28 2005-08

Exaquantum API Reference Manual 22-5

Signature
Function Recalc( _
Optional ByVal bAutoCommit = False, _
ItemValueRS As Variant) As Long

Parameters

bAutoCommit - Default value is false.

Set to VARIANT_TRUE to specify that Commit() of data should be performed

automatically when recalculation is complete.

ItemValuesRS - If AutoCommit is not specified, an ADO Recordset of recalculated Item

values is returned so that the user can inspect the data that will be written to history and
decide whether to Commit or Cancel.

Recordset fields:

ItemID - long

ItemPath - BSTR

Timestamp - DATE (as local time)

Value - VARIANT

Quality - long

PreviousValue - VARIANT (may be NULL)

PreviousQuality - long (may be NULL)

PreviousTimestamp - DATE (may be NULL)

Note: Only one value will be returned per Item at a given timestamp.
PreviousValue, PreviousQuality and PreviousTimestamp will be NULL where a previous
point did not exist in history, e.g. for a current Aggregation estimated value.

Where a previous value does exist, PreviousTimestamp will only be different from the new
timestamp when the timestamp of an Aggregation Minimum or Maximum has changed.

The return value is a unique ID assigned for this calculation and referenced in the
recalculation audit logs.

Errors

E_NOJOB (58438) - The RecalcJobName property has not been set.

E_Q_RECALCINPROGRESS (58444) - Recalculation in progress

IM 36J04A14-01E 7th Edition Issue 1 December 28 2005-08

22-6 Chapter 22 Recalculation API Reference

E_Q_NORECALCITEMS (58445) - No recalculation input items are defined for the

current RecalcJobDefinition

E_Q_NORECALCTIMES (58446) - No times have been specified for the recalculation.

This error can only be returned before a recalculation job has been successfully run and
committed. For subsequent recalculations the last committed run times will be used if no
new times are specified.

E_ITEMNOTFOUND (58440) - The Item does not exist

E_INVALIDITEMTYPE (58441) - The Item is not a valid type for recalculation. This
error is returned if a reference data Item is specified.

For R2.01.50 this error is returned if the Item is not an Aggregation Result Item.

E_NOITEMSUPDATED (58453) - No item values were updated by this recalculation

22.7 Commit method

Description

The user calls this method to write all recalculated data to history. Any updated live
aggregation results are notified to the Exaquantum RTDB. Control is not returned to the user
until data has been written to Historian and the QConfig database RecalcSession table is
cleared of data.

If one or more current aggregation values are recalculated and a new live aggregation
period completes between the Recalc and the Commit, an error is returned and the
recalculation must be re-executed.

Signature
Sub Commit (ByVal RecalcSessionID As Long)
Parameters

RecalcSessionID - The unique ID assigned for this recalculation.

Errors

E_NOJOB (58438) - The RecalcJobName property has not been set.

E_Q_NORECALC (58447) - No recalculation is waiting for commit.

E_Q_INVALIDSESSIONID (58448) - This RecalcSessionID is not in progress or does not

belong to this RecalcJob object.

E_Q_LIVEAGGPERIODPASSED (58449) - A live aggregation period has expired since

the recalculation was run. The recalculation must be re-executed.

IM 36J04A14-01E 7th Edition Issue 1 December 28 2005-08

Exaquantum API Reference Manual 22-7

E_Q_ITEMSNOTCOMMITTED (58454) - One or more recalculated points were not

successfully written to History. See the Application Event Log for details of failure.

22.8 Cancel method

Description

The user calls this method to terminate the current recalculation session and discard all
recalculated data. The QConfig database RecalcSession table is cleared of data. The Cancel()
method may only be called after a successful Recalc() which is not committed.

Signature
Sub Cancel (ByVal RecalcSessionID As Long)
Parameters

RecalcSessionID - The unique ID assigned for this recalculation.

Errors

E_NOJOB (58438) - The RecalcJobName property has not been set.

E_Q_NORECALC (58447) - No recalculation is in progress.

E_Q_INVALIDSESSIONID (58448) - This RecalcSessionID is not in progress or does not

belong to this RecalcJob object.

22.9 RecalcInputItems property

Description

A read-only property to allow the user to view the input items defined for the current job.

Signature
Property Get RecalcInputItems () As Variant

Parameters

InputItemsRS - An ADO Recordset containing a list of all the Recalc Input Items defined
for the current RecalcJob.

Recordset fields are:

ItemID - long

ItemPath - BSTR

Errors

E_NOJOB (58438) - The RecalcJobName property has not been set.

IM 36J04A14-01E 7th Edition Issue 1 December 28 2005-08

22-8 Chapter 22 Recalculation API Reference

22.10 RecalcJobDefinition property

Description

A read-only property returning details about the current job.

Signature
Property Get RecalcJobDefinition () As Variant

Parameters

The return value is a variant containing an ADO Recordset containing results from a query
of the QConfig RecalcJobDefinition table for the current job.

Errors

E_NOJOB (58438) - The RecalcJobName property has not been set.

22.11 Reason property

Description

The user may set this property to alter the Reason associated with the current
RecalcJobName at any time after creation of the Recalculation Job Definition.

Signature
Property Let Reason (ByVal Reason As String)
Property Get Reason () String
Parameters

Reason - The reason for this recalculation. May be up to 2000 characters. The property may
be set to an empty string.

Errors

E_NOJOB (58438) - The RecalcJobName property has not been set.

E_INVALIDSTRING (58450) - String parameter supplied is greater than maximum

allowed length.

IM 36J04A14-01E 7th Edition Issue 1 December 28 2005-08

Exaquantum API Reference Manual 22-9

22.12 GetDependentItems method

Description

This method may be called without setting the RecalcJobDefinition property to determine all
Items that are immediately dependent upon the specified Item ID. This would typically be
called by a user-interface application to display Items affected by changing a highlighted
Item path.

Signature
Function GetDependentItems (ByVal ItemPath As String) As Variant

Parameters

ItemPath - A single Item path.

The return value is a variant containing an ADO Recordset listing all Items dependent upon
the specified ItemID.

Recordset fields:

ItemID

ItemPath

ItemTypeID (aggregation or calculation)

3 = aggregation

4 = calculation

Errors

E_ITEMNOTFOUND (58440) - The Item does not exist

IM 36J04A14-01E 7th Edition Issue 1 December 28 2005-08

22-10 Chapter 22 Recalculation API Reference

22.13 GetRecalcJobs method

Description

This method may be called without setting the RecalcJobDefinition property to return a
recordset of all configured Recalc Job Definitions.

Signature
Function GetRecalcJobs () As Variant

Parameters

The return value is a variant containing an ADO Recordset listing all configured
Recalculation Job Definitions, ordered in descending time order by LastRunDate.

Recordset fields:

Name

CreationDate

Reason

LastRunDate

LastRecalcStartTime

LastRecalcEndTime

LastRunUserId

LastMachineName

LastCommitStatus

IM 36J04A14-01E 7th Edition Issue 1 December 28 2005-08

Exaquantum API Reference Manual 23-1

Chapter 23 Exaquantum OPC Server API

23.1 Introduction
This chapter describes aspects of the interfaces supported by the Exaquantum OPC Server
component.

A comprehensive description of the full OPC interface is available in the documentation

made available by the OPC foundation. The documents can be downloaded from the OPC
Foundation Web sites at: http://www.opcfoundation.org/

The interfaces supported by the Exaquantum OPC are listed in the following section.

The rest of the chapter provides extra information concerning the Exaquantum OPC server
implementation and highlights specific behaviour and any differences from the published
standard.

23.2 OPC Compliance

OPC HDA Server

Custom Interface

The supported OPC HDA interfaces Version 1.1 are:

IOPCCommon Version 1.0
IOPCHDA_Server
IOPCHDA_Browser
IOPCHDA_SyncRead
IOPCHDA_SyncUpdate

The following OPC HDA interfaces are not supported:

IOPCHDA_SyncAnnotations
IOPCHDA_AsyncRead
IOPCHDA_AsyncUpdate
IOPCHDA_AsyncAnnotations
IOPCHDA_Playback

IM 36J04A14-01E 7th Edition Issue 1 December 28 2005-08

23-2 Chapter 23 Exaquantum OPC Server API

Automation Interface

The supported OPC HDA automation interfaces Version 1.0 are:

Table 23-1

Method / Property
Object Name Description
Name

OPCHDAServer OPCHDAItems
HDA Item Property
Property

Connect Connect

Disconnect disconnect

OPCHDAItem Parent Property Parent group object

Count Property Number of connection

AddItem Add one item

AddItems Add many items

Remove Remove one item

RemoveAll Remove all items

In case of no data then data insert, in

SyncInsertReplace case of data had already set then data
replace

SyncDeleteRaw Delete date range

OPC DA Server

The following custom interfaces are supported, partially compliant with OPC DA Version
2.05A.
IOPCCommon Version 1.0
IOPCServer
IOPCItemMgt
IOPCGroupStateMgt
IOPCSyncIO
IOPCAsyncIO2

IM 36J04A14-01E 7th Edition Issue 1 December 28 2005-08

Exaquantum API Reference Manual 23-3

IOPCItemProperties (partial, LookupItemIDs is not implemented)

IOPCBrowseServerAddressSpace (partial, BrowseAccessPaths is not implemented)

The following OPC DA interfaces are not supported:

IOPCServerPublicGroups
IPersistFile
IOPCPublicGroupStateMgt

IM 36J04A14-01E 7th Edition Issue 1 December 28 2005-08

23-4 Chapter 23 Exaquantum OPC Server API

23.3 IOPCCommon Interface

Exaquantum supports only the System Default LocaleID.

This method ignores the entered locale and returns S_OK.

IOPCCommon::GetLocaleID
Exaquantum OPCHDA server behaviour:

Exaquantum returns the System Default LocaleID.

IOPCCommon:: QueryAvailableLocaleIDs
Exaquantum OPCHDA server behaviour:

This method returns a single LocaleID: the System Default LocaleID.

IOPCCommon::GetErrorString
Exaquantum OPCHDA server behaviour:

This method calls the ::FormatMessage API to obtain an error description for standard
Windows errors or for Exaquantum OPC HDA Server-specific errors. The only OPC-
defined errors and information codes returned by the Exaqauntum OPC HDA server are:

OPC_UNKNOWNITEMID

OPC_E_INVALIDHANDLE

OPC_E_UNKNOWNATTRID

OPC_E_NOT_AVAIL

OPC_S_MOREDATA

OPC_S_NODATA

OPC_S_CURRENTVALUE

Calling this method with any other OPC-defined code will return E_INVALIDARG.

IOPCCommon::SetClientName
Exaquantum OPCHDA server behaviour:

This method is ignored Exaquantum returns S_OK.

IM 36J04A14-01E 7th Edition Issue 1 December 28 2005-08

Exaquantum API Reference Manual 23-5

23.4 Historical Data Access

A stand-alone component, QOPCHDAServer.exe, supports OPC Historical Data Access
(HDA) to Exaquantum. The creatable version dependent ProgId for the HDA server object
is:

QOPCHDAServer.HDAServer.1

A second object is implemented which returns filtered data rather than raw data to allow
more efficient operation for OPC clients that could require this behavior. See
IOPCHDA_SyncRead::ReadRaw. The creatable version dependent ProgId for the HDA
server object is:

QOPCHDAServer.HDAServerEx.1

In the following pages, the Exaquantum-specific behavior is noted for each method. For a
fuller discussion of OPC HDA functionality, and definition of interface behavior, refer to the
OPC Foundation document, OPC Historical Data Access Custom Interface Standard
Version 1.1.

IOPCHDA_Server::GetItemAttributes
Exaquantum behaviour:

Exaquantum can return data for the following six attributes:

OPCHDA_ITEMID

OPCHDA_DATA_TYPE

OPCHDA_DESCRIPTION

OPCHDA_ENG_UNITS

OPCHDA_NORMAL_MAXIMUM

OPCHDA_NORMAL_MINIMUM

Exaquantum OPC HDA Server browsing supports filtering on Item path

(OPCHDA_ITEMID) only.

IOPCHDA_Server::GetAggregates
Exaquantum behaviour:

Exaquantum can return data for the following aggregate only:

OPCHDA_INTERPOLATIVE

IM 36J04A14-01E 7th Edition Issue 1 December 28 2005-08

23-6 Chapter 23 Exaquantum OPC Server API

IOPCHDA_Server::GetHistorianStatus
Exaquantum behaviour:

Status is returned as OPCHDA_UP if the Exaquantum server is running and HDAServer has
successfully connected, otherwise OPCHDA_DOWN.

StartTime is returned as FILETIME 0 (1st January 1601).

MaxReturnValues is set to zero as the number of values returned is limited only by available
memory.

StatusString is always returned as an empty string.

IOPCHDA_Server::GetItemHandles
Exaquantum behaviour:

This method expects the ItemIDs will be specified as an array of full Exaquantum Item Path
names, for example:

Root.Folder1.Function Block1.Tag1.Value

Root.Folder1.Function Block1.Tag1.Description

Root.Folder1.Function Block1.Tag1.HighEng

Root.Folder1.Function Block1.Tag1.LowEng

Root.Folder1.Function Block1.Tag1.Units

Root.Folder1.Function Block1.Tag1.Aggregations.Hour.Mean.Value

Root.Folder1.Function Block1.Tag1.Aggregations.Day.Minimum.Value

Server handles returned are an array of corresponding Exaquantum Item IDs as unique long
integers. The Server Handles are ordered corresponding to the input ItemIDs array.

Any Item path not found will have Server Handle returned as 0 and the corresponding Error
set to the standard OPC error OPC_E_UNKNOWNITEMID.

Returns E_Q_OPCHDA_NOTCONNECTED if Exaquantum server is not running.

IOPCHDA_Server::ReleaseItemHandles
Exaquantum behaviour:

This method removes the association of the specified Exaquantum Item ID with a previously
supplied Client Handle. If the Exaquantum ItemID is not associated with a registered Client
Handle, the corresponding error is set to the standard OPC error
OPC_E_INVALIDHANDLE

IM 36J04A14-01E 7th Edition Issue 1 December 28 2005-08

Exaquantum API Reference Manual 23-7

If GetItemHandles() is called multiple times for the same Item path, the server will not
remove the server handle until ReleaseItemHandles() has been called a corresponding
number of times. Subsequent calls to read methods succeed until the server handle is
removed.

IOPCHDA_Server::ValidateItemIDs
Exaquantum behaviour:

This method expects the ItemIDs will be specified as an array of full Exaquantum Item Path
names, for example:

Root.Folder1.Function Block1.Tag1.Value

Any Item path not found will have the corresponding Error set to the standard OPC error
OPC_E_UNKNOWNITEMID.

Returns E_Q_OPCHDA_NOTCONNECTED if Exaquantum server is not running.

IOPCHDA_Server::CreateBrowse
Exaquantum behaviour:

Exaquantum OPC browsing presents a flattened view of the Exaquantum folder hierarchy.
HDA browsing supports only a single filter on full Item Path name.

If a filter other than OPCHDA_ITEMID is specified, or more than one filter is specified, the
corresponding Error code is set to the standard OPC error OPC_W_NOFILTER.

The single filter operator may be specified as any one of:

OPCHDA_EQUAL

OPCHDA_LESS

OPCHDA_LESSEQUAL

OPCHDA_GREATER

OPCHDA_GREATEREQUAL

OPCHDA_NOTEQUAL

The single filter value must be supplied as a string with optional wildcards, for example;
Root.Folder1.*

The list of item paths returned includes all raw items matching the specified filter. Reference
item paths (Description, Units, HighEng and LowEng) are not returned.

Wildcards supported are:

* Zero or more characters in that position

IM 36J04A14-01E 7th Edition Issue 1 December 28 2005-08

23-8 Chapter 23 Exaquantum OPC Server API

? One character at that position

The Exaquantum OPC Server does not support # as a wildcard due to the possible valid
inclusion of the # character as part of an item path. The pattern [0-9] can be used to provide
the same functionality.

In addition Microsoft SQL Server pattern matching may be used:

% Zero or more characters in that position

_ One character at that position

[] Any single character within the specified range or set, e.g. [0-9], [abc]

[^] Any single character not within the specified range or set, e.g. [^abc]

Aggregation result items may be returned by changing the registry value:

HKLM\Software\Quantum\OPC Server\BrowseAggregations

Type=DWORD

Default Value = 0 (do not return aggregation)

A Non-zero value will include aggregation result items matching the filter.

IM 36J04A14-01E 7th Edition Issue 1 December 28 2005-08

Exaquantum API Reference Manual 23-9

23.5 IOPCHDA_Browser interface

This is a required interface implemented by the HDABrowser object that is obtained through
the IOPCHDA_Server::CreateBrowse() method.

IOPCHDA_Browser::GetEnum
Exaquantum behaviour:

If BrowseType of OPCHDA_BRANCH is requested, the enumerator is set to NULL and the

return code is S_FALSE.

For all other values of BrowseType the returned enum set contains a list of the full paths of
all historized Value or Aggregation result Items that match the filter criterion supplied in the
IOPCHDA_Server::CreateBrowse() method, starting at the current browse position. Item
paths are in ascending alphabetical order. The initial browse position is always set to the first
alphabetical Item path.

IOPCHDA_Browser::ChangeBrowsePosition
Exaquantum behaviour:

This method has no effect as Exaquantum presents a flat address space for browsing. The
return code is set to E_FAIL.

IOPCHDA_Browser::GetItemID
Exaquantum behaviour:

As the enumerated string set obtained from the GetEnum() method already contains the full
Item path, a copy of the NodeName is made to the output ItemID parameter. No check for
validity is made.

IOPCHDA_Browser::GetBranchPosition
Exaquantum behaviour:

This method sets the output BranchPos parameter to the hard coded string Root.

IM 36J04A14-01E 7th Edition Issue 1 December 28 2005-08

23-10 Chapter 23 Exaquantum OPC Server API

23.6 IOPCHDA_SyncRead interface

This is a required interface implemented by the HDAServer object. The only methods
implemented are ReadRaw(), ReadProcessed() and ReadAttribute() all other methods
return E_NOTIMPL.

IOPCHDA_SyncRead::ReadRaw
Exaquantum behaviour:

Exaquantum never returns trailing bound values.

The OPCHDA_QUALITY bits (bits 16-31) of the quality DWORD are always set to
OPCHDA_RAW, or OPCHDA_NODATA if not available. The Data Access quality bits are
returned directly from Exaquantum (bits 0-15). If the Exaquantum primary quality is
ASSUMED (i.e. the tag has been set offline) bits 0-15 are set to
OPC_QUALITY_UNCERTAIN.

If data does not exist in the requested time period, a valid point is returned with Data Access
quality set to BAD and the error return is S_OK.

Exaquantum does not support calculation of StartTime which must therefore always be
specified.

Returns E_Q_OPCHDA_NOTCONNECTED if Exaquantum server is not running.

In most cases, if the HDAServerEx object is used, a call to ReadRaw() is converted to a call
to ReadProcessed(), in order to return filtered data. However, when dwNumValues is
specified to be less than or equal to 8, raw data is returned. To give as close a representation
of the trend data as possible, the number of points requested will be returned as minimum
and maximum values. OPC_S_MOREDATA will never be returned.

IOPCHDA_SyncRead::ReadProcessed
Exaquantum behaviour:

Exaquantum only supports the OPCHDA_INTERPOLATIVE aggregate. If any other

aggregate is requested, the error E_Q_OPCHDA_INVALIDAGGREGATE is returned. If a
time range is specified the ResampleInterval must be less than the requested time range and
greater than 0, otherwise the error E_Q_OPCHDA_INVALIDRESAMPLEINTERVAL is
returned. If a spot time is requested the ResampleInterval is ignored.

If OPCHDA_INTERPOLATIVE is requested, the Exaquantum OPC HDA server requests

filtered History data with the number of periods set to the number of ResampleIntervals
within the requested start and end times. Historian returns a minimum and a maximum value
for each ResampleInterval with the raw data timestamps. If no point is returned at the
requested start time the timestamp of the leading bounding value is modified to the requested
start time. If no point is returned at the requested end time a point is added at the end time
with value and quality cast forward from the previous point. Exaquantum never sets the
OPCHDA_EXTRADATA quality flag.

IM 36J04A14-01E 7th Edition Issue 1 December 28 2005-08

Exaquantum API Reference Manual 23-11

The OPCHDA_QUALITY bits (bits 16-31) of the quality DWORD are always set to
OPCHDA_RAW, or OPCHDA_NODATA if not available. The Data Access quality bits are
returned directly from Exaquantum (bits 0-15). If the Exaquantum primary quality is
ASSUMED (i.e. the tag has been set offline) bits 0-15 are set to
OPC_QUALITY_UNCERTAIN.

Returns E_Q_OPCHDA_NOTCONNECTED if Exaquantum server is not running.

IOPCHDA_SyncRead::ReadAtTime
Exaquantum behaviour:

An optional method Exaquantum returns E_NOTIMPL.

IOPCHDA_SyncRead::ReadModified
Exaquantum behaviour:

An optional method Exaquantum returns E_NOTIMPL.

IOPCHDA_SyncRead::ReadAttribute
Exaquantum behaviour:

Exaquantum never returns trailing bound values.

If no attribute data is available for a requested item, the error code for each requested
attribute is set to OPC_E_UNKNOWNITEMID.

If a specific attribute is not available for a requested item, the error code for that attribute is
set to OPC_E_NOT_AVAIL.

If an attribute is requested that is not supported by Exaquantum, the error code for that
attribute is set to OPC_E_UNKNOWNATTRID.

Only current data is available for attributes OPCHDA_ITEMID and

OPCHDA_DATA_TYPE.

Returns E_Q_OPCHDA_NOTCONNECTED if Exaquantum server is not running.

IM 36J04A14-01E 7th Edition Issue 1 December 28 2005-08

23-12 Chapter 23 Exaquantum OPC Server API

23.7 Exaquantum OPC HDA Service

This service is provided to allow continuous running of the QOPCHDAServer.exe process
for attachment by clients that do not have launch permissions.

If the service is entered as a key under the Quantum\Services registry key, the service will be
started automatically after Exaquantum is started and stopped on shutdown.

Sample registry file

Windows Registry Editor Version 5.00

[HKEY_LOCAL_MACHINE\SOFTWARE\Quantum\Services\0]
@="Exaquantum OPC HDA"
"HaltStartup"=dword:00000000

IM 36J04A14-01E 7th Edition Issue 1 December 28 2005-08

Exaquantum API Reference Manual 23-13

23.8 IOPCHDA_SyncUpdate Interface

This is an interface implemented by the HDAServer object. Only the QueryCapabilities(),
InsertReplace(), DeleteAtTime(), and DeleteRaw() methods are implemented. All other
methods return E_NOTIMPL.

IOPCHDA_SyncUpdate::QueryCapabilities
Exaquantum behaviour:

Exaquantum returns the following bit sums.

OPCHDA_INSERTREPLACECAP=0x04

OPCHDA_DELETERAWCAP=0x08

OPCHDA_DELETEATTIMECAP=0x10

IOPCHDA_SyncUpdate::Insert
Exaquantum behaviour:

Method is not implemented Exaquantum returns E_NOTIMPL.

IOPCHDA_SyncUpdate::Replace
Exaquantum behaviour:

Method is not implemented Exaquantum returns E_NOTIMPL.

IOPCHDA_SyncUpdate::InsertReplace
Exaquantum behaviour:

Nothing can be written to data that has been archived.

IOPCHDA_SyncUpdate::DeleteAtTime
Exaquantum behaviour:

Archived data cannot be deleted.

IOPCHDA_SyncUpdate::DeleteRaw
Exaquantum behaviour:

Archived data cannot be deleted.

IM 36J04A14-01E 7th Edition Issue 1 December 28 2005-08

23-14 Chapter 23 Exaquantum OPC Server API

23.9 Data Access

The Exaquantum OPC DA server is implemented as an Exaopc cassette running within the
ZOPDA.exe Exaopc server process. Availability of this component is controlled by the Exa
Bossd service which is normally started automatically. The ProgID of the OPC Server object
is:

Yokogawa.ExaopcDAEXQ.1

Descriptions of interface behaviour are as defined in the OPC Foundation document OPC
Data Access Custom Interface Specification Version 2.05A which should be read for a
fuller discussion of OPC DA functionality. Exaquantum-specific behaviour is noted for each
method.

The Exaquantum OPC DA server caches all requested item paths and holds metadata for
each item for enhanced performance. This cache is monitored and managed periodically.
Changes in the namespace are reflected if necessary. The frequency of monitoring is defined
by the registry value:

HKLM\Software\Quantum\Client\NamespaceCheckPeriod

Type = DWORD

DefaultValue = 10000 (milliseconds)

IOPCServer::AddGroup
Exaquantum behaviour:

No Exaquantum-specific behaviour defined.

DeadBand is ignored for Items that have no Engineering Range configured.

IOPCServer::GetErrorString
Exaquantum behaviour:

This method should not be called from within a callback method (for example;
OnDataChange) or the server may be locked.

IOPCServer::GetGroupByName
Exaquantum behaviour:

No Exaquantum-specific behaviour defined.

IOPCServer::GetStatus
Exaquantum behaviour:

No Exaquantum-specific behaviour defined.

IM 36J04A14-01E 7th Edition Issue 1 December 28 2005-08

Exaquantum API Reference Manual 23-15

IOPCServer::RemoveGroup
Exaquantum behaviour:

No Exaquantum-specific behaviour defined.

IOPCServer::CreateGroupEnumerator
Exaquantum behaviour:

The Exaquantum OPC DA server does not support Public Groups.

IM 36J04A14-01E 7th Edition Issue 1 December 28 2005-08

23-16 Chapter 23 Exaquantum OPC Server API

23.10 IOPCItemProperties interface

IOPCItemProperties::QueryAvailableProperties

This is a required interface on the OPCServer object. It is used to return selected metadata
for items.

The LookupItemIDs method is not implemented.

Exaquantum behaviour:

Exaquantum supports the following properties:

Table 23-2

Symbolic name Property Data Type Description

ID

OPC_PROP_CDT 1 VT_I2 Item Canonical Data Type

(VARTYPE)

OPC_PROP_VALUE 2 VT_VARIANT Latest Item Value the type of

the value returned is as defined
by Item Canonical Data Type

OPC_PROP_QUALITY 3 VT_I2 Latest Item Quality

OPC_PROP_TIME 4 VT_DATE Latest Item Timestamp

OPC_PROP_RIGHTS 5 VT_I4 Item Access Rights always

set to OPC_READABLE |
OPC_WRITEABLE

OPC_PROP_SCANRATE 6 VT_R4 Server Scan Rate always set

to 1000 milliseconds

OPC_PROP_UNIT 100 VT_BSTR EU Units

OPC_PROP_DESC 101 VT_BSTR Item Description

OPC_PROP_HIEU 102 VT_R8 High EU the highest value

likely to be read in normal
operation

OPC_PROP_LOEU 103 VT_R8 Low EU the lowest value

likely to be read in normal
operation

Some items may not have Engineering Units and/or Engineering Range defined.

IM 36J04A14-01E 7th Edition Issue 1 December 28 2005-08

Exaquantum API Reference Manual 23-17

Exaquantum supports only the following data types:

VT_I2
VT_I4
VT_R4
VT_R8
VT_BSTR

IOPCItemProperties::GetItemProperties
Exaquantum behaviour:

If the Exaquantum server is unavailable, individual item error codes are set to E_FAIL and
the method returns S_FALSE.

IOPCItemProperties::LookupItemIDs
Exaquantum behaviour:

This method is not implemented for Exaquantum E_NOTIMPL is returned.

IM 36J04A14-01E 7th Edition Issue 1 December 28 2005-08

23-18 Chapter 23 Exaquantum OPC Server API

23.11 IOPCBrowseServerAddressSpace interface

This optional interface on the OPCServer object is partially supported.

IOPCBrowseServerAddressSpace:: QueryOrganization
Exaquantum behaviour:

Exaquantum supports only a FLAT address space.

IOPCBrowseServerAddressSpace:: ChangeBrowsePosition
Exaquantum behaviour:

Exaquantum supports only a FLAT address space but returns E_FAIL if called.

IOPCBrowseServerAddressSpace:: BrowseOPCItemIDs
Exaquantum behaviour:

Exaquantum only filters on ItemPath datatype and access rights filters are ignored.

If a filter value is specified, it must be supplied as a string to match ItemPath with optional
wildcards, for example:

Root.Folder1.*

The list of item paths returned includes all raw items matching the specified filter. Reference
item paths (Description, Units, HighEng and LowEng) are not returned.

Wildcards supported are:

* Zero or more characters in that position

? One character at that position

The Exaquantum OPC Server does not support # as a wildcard due to the possible valid
inclusion of the # character as part of an item path. The pattern [0-9] can be used to provide
the same functionality.

In addition Microsoft SQL Server pattern matching may be used:

% Zero or more characters in that position

_ One character at that position

[] Any single character within the specified range or set, e.g. [0-9], [abc]

[^] Any single character not within the specified range or set, e.g. [^abc]

Aggregation result items may be returned by changing the registry value:

IM 36J04A14-01E 7th Edition Issue 1 December 28 2005-08

Exaquantum API Reference Manual 23-19

HKLM\Software\Quantum\OPC Server\BrowseAggregations

Type=DWORD

Default Value = 0 (do not return aggregation)

A Non-zero value will include aggregation result items matching the filter.

IOPCBrowseServerAddressSpace:: GetItemID
Exaquantum behaviour:

As the enumerated string set obtained from the GetEnum() method already contains the full
Item path, a copy of the ItemDataID string is made to the output ItemID parameter. No
check for validity is made.

IOPCBrowseServerAddressSpace:: BrowseAccessPaths
Exaquantum behaviour:

This method is not implemented for Exaquantum E_NOTIMPL is returned.

IM 36J04A14-01E 7th Edition Issue 1 December 28 2005-08

23-20 Chapter 23 Exaquantum OPC Server API

23.12 IOPCItemMgt interface

The IOPCItemMgt required interface on the OPCGroup object allows a client to add, remove
and control the behaviour of items in a group.

IOPCItemMgt::AddItems
Exaquantum behaviour:

Exaquantum always returns OPC_E_UNKNOWNITEMID rather than

OPC_E_INVALIDITEMID if an invalid item path is specified.

IOPCItemMgt::ValidateItems
Exaquantum behaviour:

Exaquantum always returns OPC_E_UNKNOWNITEMID rather than

OPC_E_INVALIDITEMID if an invalid item path is specified.

IOPCItemMgt::RemoveItems
Exaquantum behaviour:

Exaquantum returns S_OK rather than S_FALSE if one or more invalid handles is specified.

IOPCItemMgt::SetActiveState
Exaquantum behaviour:

Exaquantum returns S_OK rather than S_FALSE if one or more invalid handles is specified.

IOPCItemMgt::SetClientHandles
Exaquantum behaviour:

No Exaquantum-specific behaviour is defined.

IOPCItemMgt::SetDatatypes
Exaquantum behaviour:

No Exaquantum-specific behaviour is defined.

IOPCItemMgt::CreateEnumerator
Exaquantum behaviour:

No Exaquantum-specific behaviour is defined.

IM 36J04A14-01E 7th Edition Issue 1 December 28 2005-08

Exaquantum API Reference Manual 23-21

23.13 IOPCGroupStateMgt interface

The required IOPCGroupStateMgt interface allows the client to manage the overall state of
the group. Primarily this allows changes to the update rate and active state of the group. This
interface is implemented within Exaopc.

IOPCGroupStateMgt::GetState
Exaquantum behaviour:

No Exaquantum-specific behaviour is defined.

IOPCGroupStateMgt::SetState
Exaquantum behaviour:

No Exaquantum-specific behaviour is defined.

IOPCGroupStateMgt::SetName
Exaquantum behaviour:

No Exaquantum-specific behaviour is defined.

IOPCGroupStateMgt::CloneGroup
Exaquantum behaviour:

No Exaquantum-specific behaviour is defined.

IM 36J04A14-01E 7th Edition Issue 1 December 28 2005-08

23-22 Chapter 23 Exaquantum OPC Server API

23.14 IOPCSyncIO interface

IOPCSyncIO allows a client to perform synchronous read and write operations to a server.
The operations will run to completion.

IOPCSyncIO::Read
Exaquantum behaviour:

If the Exaquantum primary quality for an item is ASSUMED (i.e. the tag has been set
offline), the returned quality is set to OPC_QUALITY_UNCERTAIN.

If the Exaquantum server is unavailable, individual item error codes are set to E_FAIL and
the method returns S_FALSE.

IOPCSyncIO::Write
Exaquantum behaviour:

The user running the EXA Bossd service must be a member of the QDataWriteGroup or
QAdministratorGroup in order to be able to write to Exaquantum items.

If the Exaquantum server is unavailable, individual item error codes are set to E_FAIL and
the method returns S_FALSE..

IM 36J04A14-01E 7th Edition Issue 1 December 28 2005-08

Exaquantum API Reference Manual 23-23

23.15 IOPCAsyncIO2 interface

IOPCAsyncIO2 allows a client to perform asynchronous read and write operations to a
server. The operations will be queued and the function will return immediately so that the
client can continue to run. Each operation is treated as a transaction and is associated with a
transaction ID. As the operations are completed, a callback will be made to the
IOPCDataCallback in the client. The information in the callback will indicate the transaction
ID and the results of the operation.

IOPCAsyncIO2::Read
Exaquantum behaviour:

If the Exaquantum primary quality for an item is ASSUMED because the tag has been set
offline, the returned quality is set to OPC_QUALITY_UNCERTAIN.

If the Exaquantum server is unavailable, individual item error codes are set to E_FAIL and
the method returns S_FALSE.

IOPCAsyncIO2::Write
Exaquantum behaviour:

The user running the EXA Bossd service must be a member of the QDataWriteGroup or
QAdministratorGroup in order to be able to write to Exaquantum items.

If the Exaquantum server is unavailable, individual item error codes are set to E_FAIL and
the method returns S_FALSE.

IOPCAsyncIO2::Refresh2
Exaquantum behaviour:

No Exaquantum-specific behaviour is defined.

IOPCAsyncIO2::Cancel2
Exaquantum behaviour:

No Exaquantum-specific behaviour is defined.

IOPCAsyncIO2::SetEnable
Exaquantum behaviour:

No Exaquantum-specific behaviour is defined.

IOPCAsyncIO2::GetEnable
Exaquantum behaviour:

No Exaquantum-specific behaviour is defined.

IM 36J04A14-01E 7th Edition Issue 1 December 28 2005-08

23-24 Chapter 23 Exaquantum OPC Server API

23.16 IOPCDataCallback client callback interface

This interface will be called on a client which is connected through the OPC Group object
IOPCDataCallback connection point, as a result of changes in the data of the group
(OnDataChange) and also as a result of calls to the IOPCAsyncIO2 interface.

IOPCDataCallback::OnDataChange
Exaquantum behaviour:

If the Exaquantum primary quality for an item is ASSUMED, because the tag has been set
offline, the returned quality is set to OPC_QUALITY_UNCERTAIN.

IOPCDataCallback::OnReadComplete
Exaquantum behaviour:

If the Exaquantum primary quality for an item is ASSUMED, because the tag has been set
offline, the returned quality is set to OPC_QUALITY_UNCERTAIN.

IM 36J04A14-01E 7th Edition Issue 1 December 28 2005-08

Exaquantum API Reference Manual 23-25

23.17 Exaquantum Server-specific error codes

The Exaquantum OPC Server components return some server-specific error codes. Errors are
also logged to the Application Event Log for debugging purposes.

The table below lists some of the most common errors and their possible causes:

Table 23-3

Error Message Probable cause

Event log error only: Either:

FAILED TO CONNECT TO The Exaquantum server is not running.

EXAQUANTUM
The user running the client process is not a
Event Log and returned error: member of QUserGroup.

EXAQUANTUM IS UNAVAILABLE

Event log error only: The user running the client process is not a
member of QUserGroup.
FAILED TO CREATE SESSION
EVENT SINK OR REGISTER FOR
EXAQUANTUM SESSION EVENTS

Either:

The Exaquantum historian is very loaded and

the data read request was cancelled see
Qhistorian messages in EventLog for details.

The read request has taken longer than the

READ OF HISTORY DATA TIMED
timeout specified in the registry under:
OUT
HKLM\Software\Quantum\Client\QDataAcces
sSyncReadTimeout

This timeout is specified in milliseconds and

may be changed it will be re-read when
QOPCHDAServer is re-started.

TIME STRING HAS INVALID The string representation of time specified in

FORMAT the OPCHDA_TIME structure is not correct.
See section 23.6
IOPCHDA_SyncRead::ReadRaw for further
details.

INVALID REQUEST PARAMETERS As error message

- AT LEAST TWO OF STARTTIME,

IM 36J04A14-01E 7th Edition Issue 1 December 28 2005-08

23-26 Chapter 23 Exaquantum OPC Server API

Error Message Probable cause

ENDTIME AND
NUMBEROFVALUES MUST BE
SPECIFIED. STARTTIME MUST
ALWAYS BE SPECIFIED FOR
EXAQUANTUM.

RESAMPLEINTERVAL MUST BE Invalid parameters supplied for

LESS THAN REQUESTED TIME ReadProcessed().
RANGE AND GREATER THAN 0.

UNSUPPORTED AGGREGATE Exaquantum only supports the

REQUESTED OPCHDA_INTERPOLATIVE aggregate.

IM 36J04A14-01E 7th Edition Issue 1 December 28 2005-08

Exaquantum API Reference Manual 24-1

Chapter 24 Exaquantum.NET API

The Exaquantum .NET API is a suite of Components that operate under the .NET v1.1
Framework. The API connects with Exaquantum via the Common .Net Library (see table
below). Functionality provided in the Admin Tools UI, can be executed programmatically,
providing the Developer with:

Management of Production Calendar information

Management of Tag Templates

Management of Folders and Tags

In addition, the API provides programmatic control over the Startup and Shutdown of the
Exquantum Server.

Access to the API is performed through the following libraries:

Table 24-1

Library Name Description

Yokogawa.Exa.Exaquantum.Common Enumerations and Structures are defined.

Yokogawa.Exa.Exaquantum Interfaces and Methods are defined.

The Exaquantum .NET API files are as follows:

<Exaquantum Installation Folder>\System\Yokogawa.Exa.Exaquantum.Common.dll

<Exaquantum Installation Folder>\System\ Yokogawa.Exa.Exaquantum.dll

The following table shows details of the Exaquantum.NET API Library.

Table 24-2

Interface Name Method / Property Name Description

Session ServerName Setting and acquisition of connected

server name

ExaquantumAPI Session Setting and acquisition of Session

AggregationPeriodManger Acquisition of
AggregationPeriodManager

IM 36J04A14-01E 7th Edition Issue 1 December 28 2005-08

24-2 Chapter 24 Exaquantum.NET API

Interface Name Method / Property Name Description

TemplateManager Acquisition of TemplateManager

TagManager Acquisition of TagManager

Operation Acquisition of Operation

AggregationPeriodManager GetAggregationPeriod Acquisition of production calendar

AddAggregationPeriod Addition of production calendar

ModifyAggregationPeriod Modification of production calendar

DeleteAggregationPeriod Deletion of production calendar

CheckAggregationPeriod Check of production calendar

QueryAggregationPeriod Acquisition of production calendar list

TemplateManager GetTagTemplate Acquisition of tag template

AddTagTemplate Addition of tag template

ModifyTagTemplate Modification of tag template

DeleteTagTemplate Deletion of tag template

CheckTagTemplate Check of tag template

QueryTagTemplate Acquisition of tag template list

TagManager GetTag Acquisition of tag

AddTag Addition of tag

ModifyTag Modification of tag

DeleteTag Deletion of tag

CheckTag Check of tag

FindTag Search of tag

GetFolder Acquisition of folder list

AddFolder Addition of folder

ModifyFolder Modification of folder

IM 36J04A14-01E 7th Edition Issue 1 December 28 2005-08

Exaquantum API Reference Manual 24-3

Interface Name Method / Property Name Description

DeleteFolder Deletion of folder

CheckFolder Check of folder

Operation Startup Start-up

Status Changed Event that occurs status changed

Shutdown Shutdown

OnShutdown Event Event that occurs after shutdown

completion

IsMonitoring Status Change Monitoring Flag

IM 36J04A14-01E 7th Edition Issue 1 December 28 2005-08

24-4 Chapter 24 Exaquantum.NET API

24.1 Installation Types for .NET API

The .NET API is installed by default on:

Exaquantum Server

Combined Server

It is not installed on

Exaquantum Web Server

Exaquantum Client

To install the Exaquantum .NET API on an Exaquantum Client or Web Server, please refer
to Chapter 8 Installing the .NET API on an Exaquantum Client or Web Server in the
Exaquantum Installation Guide (IM 36J04A13-01E).

24.2 Exaquantum .NET API

The Exaquantum .NET API manages connections and provides the properties to return
various Interfaces.

Note: users must be in QAdministratorGroup to gain access to the .NET API.

Session Property

Description

Gets/sets a Session object from/on the Exaquantum API. The session object gives the API:

Access to remote Exaquantum servers

Monitoring of the connection to Exaquantum.

Signature
Session Session{get;set;}
AggregationPeriodManager Property

Description

Get the Production Calendar Manager API

Signature
AggregationPeriodManager AggregationPeriodManager{get;}

IM 36J04A14-01E 7th Edition Issue 1 December 28 2005-08

Exaquantum API Reference Manual 24-5

TemplateManager Property

Description

Get the Template Manager API

Signature
TemplateManager TemplateManager{get;}

TagManager Property

Description

Get the Tag Manager API

Signature
TagManager TagManager{get;}

Operation Property

Description

Get the Operation API

Signature
Operation Operation{get;}

Sample Code

This section gives example of how to access the Exaquantum API objects.
using Yokogawa.Exa.Exaquantum;
using Yokogawa.Exa.Exaquantum.Common;

ExaquantumAPI api = null ;

Session QSession = null ;
TagManager Qtm = null;
TemplateManager Tm = null;
AggregationPeriodManager Ap = null ;
Operation op = null ;

api = new ExaquantumAPI();

QSession = api.Session ;
QSession.ServerName = MyServer ;
Qtm = api.TagManager ;
Tm = api.TemplateManager ;
Ap = api.AggregationPeriodManager ;
op = api.Operation ;

IM 36J04A14-01E 7th Edition Issue 1 December 28 2005-08

24-6 Chapter 24 Exaquantum.NET API

24.3 Session Interface

Setting and acquisition of connected server name.

ServerName Property ()

Signature
string ServerName{get;set;}

24.4 AggregationPeriodManager interface

Allows management of the Production Calendar.

Namespace: Yokogawa.Exa.Exaquantum.

GetAggregationPeriod Method

Description

This returns the Production Calendar Period detail, in the output QAggregationPeriod()
object, corresponding to the supplied handles.

Signature
GetAggregationPeriod(int handles, _
out QAggregationPeriod[] aggregationPeriod, _
out int[] errors)

Parameters

Handles - Array of IDs

AggregationPeriod - Array of QAggregationPeriod Objects

Errors - Array of errors, corresponds to each handle.

Errors Returned

S_OK - Succeeded

EQ_E_INVALID_HANDLE - Invalid Handle

AddAggregationPeriod Method

Description

Adds one or more Production Calendar Periods. If a Production Calendar already exists, an
error occurs.

IM 36J04A14-01E 7th Edition Issue 1 December 28 2005-08

Exaquantum API Reference Manual 24-7

Signature
AddAggregationPeriod (QAggregationPeriod[] aggregationPeriods, _
out int[] handles, _
out int[] errors)

Parameters

AggregationPeriods - Array of QAggregationPeriod object(s) to be added

Handles - Array of returned handles

Errors - Array of errors, corresponds to each element in the AggregationPeriods array.

Note: In the instance where two or more elements have the same name in
AggregationPeriods, the EQ_E_DUPLICATE_NAME error is returned for all
elements having this condition, except for the initial one.

Errors Returned

S_OK - Succeeded

EQ_E_INVALID_NAME - Invalid Name

EQ_E_INVALID_DESCRIPTION - Invalid Description

EQ_E_INVALID_PERIOD - Invalid Period

EQ_E_INVALID_OFFSET - Invalid Offset

EQ_E_INVALID_PARENTHANDLE - Invalid Parent Handle

EQ_E_DUPLICATE_NAME - Duplicate in AggregationPeriods array

EQ_E_ITEMEXIST Aggregation period already exists

API Exception

ArgumentOutOfRangeException The bounds of the AggregationPeriods array are

incorrect.

ArgumentNullException One or more of the parameters is NULL.

ModifyAggregationPeriod Method

Description

Allows modification of one or more Production Calendar periods. When the target
production calendar period does not exist, an error occurs.

IM 36J04A14-01E 7th Edition Issue 1 December 28 2005-08

24-8 Chapter 24 Exaquantum.NET API

Signature
ModifyAggregationPeriod (int[] handles, _
in QAggregationPeriod[] aggregationPeriods, _
out int[] errors)

Parameters

Handles - Array of the production calendar period handle to be modified

AggregationPeriods - Array of the QAggregationPeriod object(s) to be modified

Errors - Array of errors, corresponds to each handle.

Errors Returned

S_OK - Succeeded

EQ_E_INVALID_NAME - Invalid Name

EQ_E_INVALID_DESCRIPTION - Invalid Description

EQ_E_INVALID_PERIOD - Invalid Period

EQ_E_INVALID_OFFSET - Invalid Offset

EQ_E_INVALID_PARENTHANDLE - Invalid Parent Handle

EQ_E_DUPLICATE_NAME - Duplicate Name

EQ_E_INVALID_HANDLE - Invalid Handle

EQ_E_DUPLICATE_NAME - Duplicate in AggregationPeriods array

EQ_E_ITEMEXIST Aggregation period already exists

API Exception

ArgumentOutOfRangeException The bounds of the AggregationPeriods or Handles

array are incorrect.

ArgumentNullException One or more of the parameters is NULL.

DeleteAggregationPeriod Method

Description

Allows deletion of the specified Production Calendar(s).

IM 36J04A14-01E 7th Edition Issue 1 December 28 2005-08

Exaquantum API Reference Manual 24-9

Signature
DeleteAggregationPeriod(int[] handles, _
out int[] errors)

Parameter

Handles - Array of the production calendar period handle(s) to be deleted.

Errors - Array of errors corresponds to each handle

Errors Returned

S_OK - Succeeded

EQ_E_INVALID_HANDLE - Invalid Handle

EQ_E_DUPLICATE_HANDLE - Duplicate Handle

EQ_E_INUSE The production calendar period is used with the tag template.

API Exception

ArgumentOutOfRangeException The bounds of the Handles array are incorrect.

ArgumentNullException One or more of the parameters is NULL.

CheckAggregationPeriod Method

Description

Validates the contents of the QAggregationPeriod array. The result of each array entry is
returned in the errors array.

Signature
CheckAggregationPeriod(QAggregationPeriod[] aggregationPeriods, _
out int[] errors)

Parameter

AggregationPeriods - Array of the QAggregationPeriod object(s) to be checked

Errors - Array of errors, corresponds to each handle.

Note: In the instance where two or more elements have the same name in
AggregationPeriods, the EQ_E_DUPLICATE_NAME error is returned for all
elements having this condition, except for the initial one.

Errors Returned

IM 36J04A14-01E 7th Edition Issue 1 December 28 2005-08

24-10 Chapter 24 Exaquantum.NET API

S_OK - Succeeded

EQ_E_INVALID_NAME - Invalid Name

EQ_E_INVALID_DESCRIPTION - Invalid Description

EQ_E_INVALID_PERIOD - Invalid Period

EQ_E_INVALID_OFFSET - Invalid Offset

EQ_E_INVALID_PARENTHANDLE - Invalid Parent Handle

EQ_E_DUPLICATE_NAME - Duplicate in AggregationPeriods array

EQ_E_ITEMEXIST Aggregation period already exists

API Exception

ArgumentOutOfRangeException The bounds of the AggregationPeriods array are

incorrect.

ArgumentNullException One or more of the parameters is NULL.

QueryAggregationPeriod Method

Description

Returns a list of all of the Production Calendars.

Signature
QueryAggregationPeriod(out int[] handles, _
out QAggregationPeriod[] aggregationPeriod)

Parameter

Handles - Array of production calendar period handle(s)

AggregationPeriod - Array of the production calendar periods

Sample Code

This section gives example of how to use the AggregationPeriodManager methods().

GetAggregationPeriod
AggregationPeriodManager Agg =
new ExaquantumAPI().AggregationPeriodManager;

QAggregationPeriod[] aggregationPeriod;
int[] handles = new int[2];
int[] errors;

IM 36J04A14-01E 7th Edition Issue 1 December 28 2005-08

Exaquantum API Reference Manual 24-11

// get
handles[0] = 97;
handles[1] = 1;
Agg.GetAggregationPeriod(handles, out aggregationPeriod, out errors);
AddAggregationPeriod
AggregationPeriodManager Agg =
new ExaquantumAPI().AggregationPeriodManager;

QAggregationPeriod[] ParaOfAgPd = new QAggregationPeriod[2];

int[] handles;
int[] errors;

ParaOfAgPd[0].Name = "aaa";
ParaOfAgPd[0].Description = "";
ParaOfAgPd[0].Period = 2;
ParaOfAgPd[0].Offset = 2;
ParaOfAgPd[0].ParentHandle = 0;

ParaOfAgPd[1].Name = "bbb";
ParaOfAgPd[1].Description = "";
ParaOfAgPd[1].Period = 3;
ParaOfAgPd[1].Offset = 5;
ParaOfAgPd[1].ParentHandle = 0;

// add calender
Agg.AddAggregationPeriod(ParaOfAgPd, out handles, out errors);

IM 36J04A14-01E 7th Edition Issue 1 December 28 2005-08

24-12 Chapter 24 Exaquantum.NET API

AddAggregationPeriod/CheckAggregationPeriod/ModifyAggregationPeriod/De
leteAggregationPeriod
AggregationPeriodManager Agg =
new ExaquantumAPI().AggregationPeriodManager;

// parameter set
QAggregationPeriod[] ParaOfAgPd = new QAggregationPeriod[1];
int[] handles;
int[] errors;

int i = 0;
ParaOfAgPd[i].Name = "ccc";
ParaOfAgPd[i].Description = "";
ParaOfAgPd[i].Period = 2;
ParaOfAgPd[i].Offset = 1;
ParaOfAgPd[i].ParentHandle = 0;

// add calender
Agg.AddAggregationPeriod(ParaOfAgPd, out handles, out errors);

i = 0;
ParaOfAgPd[i].Name = "ddd";
ParaOfAgPd[i].Description = "";
ParaOfAgPd[i].Period = 2;
ParaOfAgPd[i].Offset = 2;
ParaOfAgPd[i].ParentHandle = 0;

// check
Agg.CheckAggregationPeriod(ParaOfAgPd, out errors);

// change calander
Agg.ModifyAggregationPeriod(handles, ParaOfAgPd, out errors);

// delete
Agg.DeleteAggregationPeriod(handles, out errors);
QueryAggregationPeriod
AggregationPeriodManager Agg =
new ExaquantumAPI().AggregationPeriodManager;

int[] Handles;
QAggregationPeriod[] AggPeriods;

Agg.QueryAggregationPeriod(out Handles, out AggPeriods);

IM 36J04A14-01E 7th Edition Issue 1 December 28 2005-08

Exaquantum API Reference Manual 24-13

24.5 TemplateManager interface

The TemplateManager allows management of the Tag Templates.

Namespace: Yokogawa.Exa.Exaquantum.

GetTagTemplate Method

Description

The Tag Template(s) for the specified handle(s) is returned the error
EQ_E_INVALID_HANDLE is returned if the handle does not exist.

Signature
GetTagTemplate(int[] handles, _
out QTagTemplate[] tagTemplates,_
out int[] errors)

Parameter

Handles - Array of TagTemplate handles

tagTemplates - Array of QTagTemplates

Errors - Array of errors, corresponds to each handle.

Errors Returned

S_OK - Succeeded

EQ_E_INVALID_HANDLE - Invalid Handle

AddTagTemplate Method

Signature
AddTagTemplate(QTagTemplate[] tagTemplates, _
out int[] handles, _
out int[] errors)
Parameter

TagTemplates - Array of QTagTemplates

Handles - Array of handles for templates that get added

Errors - Array of errors, corresponds to each handle.

IM 36J04A14-01E 7th Edition Issue 1 December 28 2005-08

24-14 Chapter 24 Exaquantum.NET API

Errors Returned

S_OK - Succeeded

EQ_E_INVALID_NAME - Invalid Name

EQ_E_INVALID_TAGTYPE - Invalid Tag Type

EQ_E_INVALID_DATATYPE - Invalid Data Type

EQ_E_INVALID_AGGREGATIONTYPE - Invalid Aggregation Type

EQ_E_INVALID_HISTORIANINTERVAL - Invalid Historian Interval

EQ_E_INVALID_UNITS - Invalid Units

EQ_E_INVALID_RANGE - Invalid Range

EQ_E_INVALID_PERIOD_ID - Invalid Period ID

EQ_E_INVALID_OPCGATEWAY - Invalid OPC Gateway

EQ_E_INVALID_OPCPERIOD - Invalid OPC Period

EQ_E_INVALID_DEADBAND - Invalid Deadband

EQ_E_INVALID_CALCFLAG - Invalid Flag of Aggregation supplied by calculation

EQ_E_INVALID_AGGREGATIONINFO - Invalid Aggregation Calculations

EQ_E_DUPLICATE_NAME - Duplicate in TagTemplates array

EQ_E_ITEMEXIST Tag Template already exists

API Exception

ArgumentOutOfRangeException The bounds of the TagTemplates array are incorrect.

ArgumentNullException One or more of the parameters is NULL.

ModifyTagTemplate Method

Description

Modify one or more Tag Templates. If the template is already in use, then a new version of
the template is added. This new version will be applied when the tag(s) that are built to the
template are rebuilt (or upgraded).

Signature
ModifyTagTemplate(int[] handles, _

IM 36J04A14-01E 7th Edition Issue 1 December 28 2005-08

Exaquantum API Reference Manual 24-15

QTagTemplate[] tagTemplates, _
out int[] errors)

Parameter

Handles - Array of handles

TagTemplates - Array of tag template information

Errors - Array of errors, corresponds to each handle

Errors Returned

S_OK - Succeeded

EQ_E_INVALID_NAME - Invalid Name

EQ_E_INVALID_TAGTYPE - Invalid Tag Type

EQ_E_INVALID_DATATYPE - Invalid Data Type

EQ_E_INVALID_AGGREGATIONTYPE - Invalid Aggregation Type

EQ_E_INVALID_HISTORIANINTERVAL - Invalid Historian Interval

EQ_E_INVALID_UNITS - Invalid Units

EQ_E_INVALID_RANGE - Invalid Range

EQ_E_INVALID_PERIOD_ID - Invalid Period ID

EQ_E_INVALID_OPCGATEWAY - Invalid OPC Gateway

EQ_E_INVALID_OPCPERIOD - Invalid OPC Period

EQ_E_INVALID_DEADBAND - Invalid Deadband

EQ_E_INVALID_CALCFLAG - Invalid Flag of Aggregation supplied by calculation

EQ_E_INVALID_AGGREGATIONINFO - Invalid Aggregation Calculations

EQ_E_INVALID_HANDLE - Invalid Handle

EQ_E_DUPLICATE_NAME - Duplicate in TagTemplates array

EQ_E_ITEMEXIST Tag Template already exists

EQ_E_INUSE One or more parameters cannot be changed, as the template has been
used to create tags (for example tag type).

IM 36J04A14-01E 7th Edition Issue 1 December 28 2005-08

24-16 Chapter 24 Exaquantum.NET API

API Exception

ArgumentOutOfRangeException The bounds of the TagTemplates or Handles array

are incorrect

ArgumentNullException One or more of the parameters is NULL.

DeleteTagTemplate Method

Description

Delete an existing tag template. This will fail if the template is in use.

Signature
DeleteTagTemplate (int[] handles, _
out int[] errors)

Parameter

Handles - Array of Tag Template Handle(s) to be deleted

Errors - Array of errors, corresponds to each handle.

Errors Returned

S_OK - Succeeded

EQ_E_INVALID_HANDLE - Invalid Handle

EQ_E_DUPLICATE_HANDLE - Duplicate Handle

EQ_E_INUSE - TagTemplate is in use.

API Exception

ArgumentOutOfRangeException The bounds of the Handles array is incorrect.

ArgumentNullException One or more of the parameters is NULL.

CheckTagTemplate Method

Description

The content of the

Signature
CheckTagTemplate (QTagTemplate[] tagTemplates, _
out int[] errors)

IM 36J04A14-01E 7th Edition Issue 1 December 28 2005-08

Exaquantum API Reference Manual 24-17

Parameter

TagTemplates - Array of Tag Templates

Errors - Array of errors, corresponds to each element in the tagTemplates array.

Errors Returned

S_OK - Succeeded

EQ_E_INVALID_NAME - Invalid Name

EQ_E_INVALID_TAGTYPE - Invalid Tag Type

EQ_E_INVALID_DATATYPE - Invalid Data Type

EQ_E_INVALID_AGGREGATIONTYPE - Invalid Aggregation Type

EQ_E_INVALID_HISTORIANINTERVAL - Invalid Historian Interval

EQ_E_INVALID_UNITS - Invalid Units

EQ_E_INVALID_RANGE - Invalid Range

EQ_E_INVALID_PERIOD_ID - Invalid Period ID

EQ_E_INVALID_OPCGATEWAY - Invalid OPC Gateway

EQ_E_INVALID_OPCPERIOD - Invalid OPC Period

EQ_E_INVALID_DEADBAND - Invalid Deadband

EQ_E_INVALID_CALCFLAG - Invalid Flag of Aggregation supplied by calculation

EQ_E_INVALID_AGGREGATIONINFO - Invalid Aggregation Calculations

EQ_E_DUPLICATE_NAME - Duplicate in TagTemplates array

EQ_E_ITEMEXIST Tag Template already exists

API Exception

ArgumentOutOfRangeException The bounds of the tagTemplates array is incorrect.

ArgumentNullException One or more of the parameters is NULL.

IM 36J04A14-01E 7th Edition Issue 1 December 28 2005-08

24-18 Chapter 24 Exaquantum.NET API

QueryTagTemplate Method

Description

A list of TagTemplates is returned.

Signature
QueryTagTemplate(out int[] handles, _
out QTagTemplate[] tagTemplates)

Parameter

Handles - Array of TagTemplate Handles

tagTemplates - Array of TagTemplates

API Exception

ApplicationException This is thrown if an error occurred during the reading of the Tag
Templates. The detail of the error is described in the Message property of the exception..

SampleCode

This section gives some examples on how to use the TemplateManager methods..

GetTagTemplate
TemplateManager templateManager = new ExaquantumAPI().TemplateManager;

QTagTemplate[] TaT;
int[] handles = new int[]{1};
int[] errors;

templateManager.GetTagTemplate(handles, out TaT, out errors);

AddTagTemplate/CheckTagTemplate/ModifyTagTemplate/DeleteTagTemplate
TemplateManager templateManager = new ExaquantumAPI().TemplateManager;
QTagTemplate[] AddTemp = new QTagTemplate[1];

int[] handles;
int[] errors;
int[] APid = new int[1];
QAggregationInfo[] AInfo = new QAggregationInfo[1];

APid[0] = 3;
AInfo[0].aggregation =
AggregationCalcType.AGGREGATION_MAX;
AInfo[0].parameter = null;
AddTemp[0].Name = "CALC-R4";
AddTemp[0].TagType = TagType.TAG_TYPE_CALC;
AddTemp[0].DataType = DataType.DATA_TYPE_FLOAT;
AddTemp[0].AggregationType =
AggregationType.AGGREGATION_TYPE_CONTINUOUS;

IM 36J04A14-01E 7th Edition Issue 1 December 28 2005-08

Exaquantum API Reference Manual 24-19

AddTemp[0].RawHistorianInterval =
RawHistorianIntervalType.RAW_INTERVAL_ONCHANGE;
AddTemp[0].EngUnitsFlag = false;
AddTemp[0].EngRangeFlag = false;
AddTemp[0].DescriptionFlag = false;
AddTemp[0].AggregationPeriodIDs = APid; // AggregationPeriodID(array)
AddTemp[0].WriteToOPCGatewayFlag = false;
AddTemp[0].OPCPeriod = OPCPeriodType.OPC_PERIOD_NOUSE;
AddTemp[0].PercentDeadband = QTagTemplate.PercentDeadbandNoUse;
AddTemp[0].AggregationSuppliedByCalculationFlag = new bool[] {false};
AddTemp[0].AggregationInfo = AInfo;

templateManager.AddTagTemplate(AddTemp, out handles, out errors);

AddTemp[0].EngUnitsFlag = true;
AddTemp[0].EngRangeFlag = true;
AddTemp[0].DescriptionFlag = true;
templateManager.CheckTagTemplate(AddTemp, out errors);

templateManager.ModifyTagTemplate(handles, AddTemp, out errors);

templateManager.DeleteTagTemplate(handles, out errors);
QueryTagTemplate
TemplateManager templateManager = new ExaquantumAPI().TemplateManager;

int[] handles;
QTagTemplate[] TaT;

templateManager.QueryTagTemplate(out handles, out TaT);

IM 36J04A14-01E 7th Edition Issue 1 December 28 2005-08

24-20 Chapter 24 Exaquantum.NET API

24.6 TagManager interface

Allows management of the Tag and Folders.

Namespace: Yokogawa.EXA.Exaquantum

GetTag Method

Description

Get one or more Tags under the specified path(s).

Signature
GetTag(string[] paths, _
out int[] handles, _
out QTag[] tags, _
out int[] errors)

Parameter

Paths - Array of full tag path(s).

Handles - Array of tag handles; these correspond to the specified paths.

Tags - Array of tag information.

Errors - Array of errors, corresponds to each handle.

Errors Returned

S_OK - Succeeded

EQ_E_INVALID_PATH - Invalid Path

AddTag Method

Description

Adds one or more tags. Where folders do not exist, they are created prior to adding of the
tags..

Signature
AddTag (QTag[] tags, _
out int[] handles, _
out int[] errors)

IM 36J04A14-01E 7th Edition Issue 1 December 28 2005-08

Exaquantum API Reference Manual 24-21

Parameter

Tags - Array of Tag Information.

Handles - Array of corresponding tag handles.

Errors - Array of errors correspond to each handle and each tags.

Errors Returned

S_OK - Succeeded

EQ_E_INVALID_NAME - Invalid Name

EQ_E_INVALID_PATH - Invalid Path

EQ_E_INVALID_TEMPLATENAME no Template Name is specified

EQ_E_INVALID_DESCRIPTION - Invalid Description

EQ_E_INVALID_UNITS - Invalid Units

EQ_E_INVALID_LOWENG - Invalid Lower limit of engineering range

EQ_E_INVALID_HIGHENG - Invalid Higher limit of engineering range

EQ_E_INVALID_RANGE - Invalid engineering range

EQ_E_INVALID_VALUE - Invalid Initial Value

EQ_E_INVALID_QUALITY - Invalid Quality

EQ_E_INVALID_OPC_GATEWAY - Invalid OPC Gateway

EQ_E_INVALID_OPC_ITEMID - Invalid OPC Item ID

EQ_E_INVALID_SCRIPT - Invalid Script

EQ_E_ANALYZE - Analyze Error

EQ_E_DUPLICATE_NAME - Duplicate in Tags array

EQ_E_ITEMEXIST Tag already exists

API Exception

ArgumentOutOfRangeException The bounds of the Tags array is incorrect.

ArgumentNullException One or more of the parameters is NULL.

IM 36J04A14-01E 7th Edition Issue 1 December 28 2005-08

24-22 Chapter 24 Exaquantum.NET API

ModifyTag Method

Description

Modification of one or more tags. If the tag template is to be changed, the only case where
this will succeed is if the new template has the same tag type and data type to which the tag
is currently built.

Signature
ModifyTag (int[] handles, _
QTag[] tags,_
out int[] errors)

Parameter

Handles - Array of tag handles

Tags - Array of tag information

Errors - Array of errors, corresponds to each handle.

Errors Returned

S_OK - Succeeded

EQ_E_INVALID_NAME - Invalid Name

EQ_E_INVALID_PATH - Invalid Path

EQ_E_INVALID_TEMPLATENAME - Invalid Template Name

EQ_E_INVALID_DESCRIPTION - Invalid Description

EQ_E_INVALID_UNITS - Invalid Units

EQ_E_INVALID_LOWENG - Invalid Lower limit of engineering range

EQ_E_INVALID_HIGHENG - Invalid Higher limit of engineering range

EQ_E_INVALID_RANGE - Invalid engineering range

EQ_E_INVALID_VALUE - Invalid Initial Value

EQ_E_INVALID_QUALITY - Invalid Quality

EQ_E_INVALID_OPC_GATEWAY - Invalid OPC Gateway

EQ_E_INVALID_OPC_ITEMID - Invalid OPC Item ID

IM 36J04A14-01E 7th Edition Issue 1 December 28 2005-08

Exaquantum API Reference Manual 24-23

EQ_E_INVALID_SCRIPT - Invalid Script

EQ_E_ANALYZE - Analyze Error

EQ_E_INVALID_HANDLE - Invalid Handle

EQ_E_DUPLICATE_HANDLE - Duplicate Handle

EQ_E_DUPLICATE_NAME - Duplicate in Tags array

EQ_E_ITEMEXIST Tag already exists

API Exception

ArgumentOutOfRangeException The bounds of the Tags or Handles array is incorrect.

ArgumentNullException One or more of the parameters is NULL.

DeleteTag Method

Description

Deletion of one or more tags.

Signature
DeleteTag (int[] handles, _
out int[] errors, _
bool force)
Parameter

Handles - Array of tag handles

Errors - Array of errors, corresponds to each handle.

Force - If this flag is true, then the tag(s) will be deleted, even if they are being referenced
by other tags (for example, by a calculation tag script).

Errors Returned

S_OK - Succeeded

EQ_E_INVALID_HANDLE - Invalid Handle

EQ_E_DUPLICATE_HANDLE - Duplicate Handle

EQ_E_INUSE Tag is referenced by calculation tag, and cannot be deleted.

API Exception

ArgumentOutOfRangeException The bounds of the Handles array is incorrect.

IM 36J04A14-01E 7th Edition Issue 1 December 28 2005-08

24-24 Chapter 24 Exaquantum.NET API

ArgumentNullException One or more of the parameters is NULL.

CheckTag Method

Description

This method is used for the verification of the content of the QTag array.

Signature
CheckTag (QTag[] tags, _
out int[] errors)
Parameter

Tags - Array of tag information

Errors - Array of errors, corresponds to each tag.

Errors Returned

S_OK - Succeeded

EQ_E_INVALID_NAME - Invalid Name

EQ_E_INVALID_PATH - Invalid Path

EQ_E_INVALID_TEMPLATENAME - Invalid Template Name

EQ_E_INVALID_DESCRIPTION - Invalid Description

EQ_E_INVALID_UNITS - Invalid Units

EQ_E_INVALID_LOWENG - Invalid Lower limit of engineering range

EQ_E_INVALID_HIGHENG - Invalid Higher limit of engineering range

EQ_E_INVALID_RANGE - Invalid engineering range

EQ_E_INVALID_VALUE - Invalid Initial Value

EQ_E_INVALID_QUALITY - Invalid Quality

EQ_E_INVALID_OPC_GATEWAY - Invalid OPC Gateway

EQ_E_INVALID_OPC_ITEMID - Invalid OPC Item ID

EQ_E_INVALID_SCRIPT - Invalid Script

EQ_E_ANALYZE - Analyze Error

EQ_E_DUPLICATE_NAME - Duplicate in Tags array

IM 36J04A14-01E 7th Edition Issue 1 December 28 2005-08

Exaquantum API Reference Manual 24-25

EQ_E_ITEMEXIST Tag already exists

API Exception

ArgumentOutOfRangeException The bounds of the Tags array is incorrect.

ArgumentNullException One or more of the parameters is NULL.

FindTag Method

Description

Returns a list of tags that match the specified filter(s).

Signature
FindTag (QTagFilter[] TagFilters, _
out int[] handles, _
out QTag[] tags)

Parameter

Filters - Array of one of more QTagFilters.

*: represents a character string.

?: represents a character.

[]: represents a character string in a specified character range: [0-9],[abc]

Handles - Array of tag handles

Tags Array of tag information

API Exception

ArgumentOutOfRangeException - The bounds of the TagFilters array is incorrect.

ArgumentException One or more of the filter parameters is set incorrectly.

ApplicationException This is thrown if an unexpected error occurred during the

processing of the FindTag method. The detail of the error is described in the Message
property of the exception.

GetFolder Method

Description

Returns a list of folder information, for the specified path(s).

IM 36J04A14-01E 7th Edition Issue 1 December 28 2005-08

24-26 Chapter 24 Exaquantum.NET API

Signature
GetFolder (string[] paths, _
out int[] handles, _
out QFolder[] folders, _
out int[] errors)
Parameter

Paths - Array of paths

Handles Array of folder handles

Folders - Array of folder information.

Errors - Array of errors, corresponds to each path, handle and folder.

Errors Returned

S_OK - Succeeded

EQ_E_INVALID_PATH - Invalid Path

AddFolder Method

Description

Adds one or more folders.

Signature
AddFolder (QFolder[] folders, _
out int[] handles, _
out int[] errors)

Parameter

Folders - Array of folder information

Handles - Array of folder handles.

Errors - Array of errors, corresponds to each folder and each handle.

Errors Returned

S_OK - Succeeded

EQ_E_INVALID_NAME - Invalid Name

EQ_E_INVALID_PATH - Invalid Path

IM 36J04A14-01E 7th Edition Issue 1 December 28 2005-08

Exaquantum API Reference Manual 24-27

EQ_E_DUPLICATE_NAME - Duplicate in Folders array

EQ_E_ITEMEXIST Folder already exists

API Exception

ArgumentOutOfRangeException The bounds of the Folders array is incorrect.

ArgumentNullException One or more of the parameters is NULL.

ModifyFolder Method

Description

Modifies one or more folders.

Signature
ModifyFolder (int[] handles, _
QFolder[] folders, _
out int[] errors)

Parameter

Handles - Array of folder handles

Folders - Array of folder information

Errors - Array of errors, corresponds to each handle and each folder.

Errors Returned

S_OK - Succeeded

EQ_E_INVALID_NAME - Invalid Name

EQ_E_INVALID_PATH - Invalid Path

EQ_E_INVALID_HANDLE - Invalid Handle

EQ_E_DUPLICATE_HANDLE - Duplicate Handle

EQ_E_DUPLICATE_NAME - Duplicate in Folders array

EQ_E_ITEMEXIST Folder already exists

API Exception

ArgumentOutOfRangeException The bounds of the Folders or Handles array is

incorrect.

IM 36J04A14-01E 7th Edition Issue 1 December 28 2005-08

24-28 Chapter 24 Exaquantum.NET API

ArgumentNullException One or more of the parameters is NULL.

DeleteFolder Method

Description

Deletes one or more folders.

Signature
DeleteFolder (int[] handles, _
out int[] errors, _
bool force)

Parameter

Handles - Array of folder handles

Errors - Array of errors correspond to each handle.

Force - If this flag is true, tags under the folder will be deleted even if they are being
referenced by other tags.

Errors Returned

S_OK - Succeeded

EQ_E_INVALID_HANDLE - Invalid Handle

EQ_E_DUPLICATE_HANDLE - Duplicate Handle

EQ_E_INUSE A tag being referenced exists under the folder.

API Exception

ArgumentOutOfRangeException The bounds of the Handles array is incorrect.

ArgumentNullException One or more of the parameters is NULL.

CheckFolder Method

Description

This method is used for the verification of the content of the QFolder array.

Signature
CheckFolder (QFolder[] folders, _
out int[] errors)

IM 36J04A14-01E 7th Edition Issue 1 December 28 2005-08

Exaquantum API Reference Manual 24-29

Parameter

Folders - Array of folder information

Errors - Array of errors, corresponds to each folder.

Errors Returned

S_OK - Succeeded

EQ_E_INVALID_NAME - Invalid Name

EQ_E_INVALID_PATH - Invalid Path

EQ_E_DUPLICATE_NAME - Duplicate in Folders array

EQ_E_ITEMEXIST Folder already exists

API Exception

ArgumentOutOfRangeException The bounds of the Folders array is incorrect.

ArgumentNullException One or more of the parameters is NULL.

Sample Code

This section gives some examples of sample code, showing how to use the TagManager API.

Sample Code for the management of Tags

AddTag/DeleteTag
TagManager tagManager = new ExaquantumAPI().TagManager;

QTag[] tags = new QTag[3];

int[] handles;
int[] errors;

// tag create
//OPC R4
int i = 0;
tags[i].Name = "OPC-TAG";
tags[i].Path = "Root.Test.OPC";
tags[i].TemplateName = "OPC-R4";
tags[i].Description = "";
tags[i].Units = "";
tags[i].LowEng = 0;
tags[i].HighEng = 0;
tags[i].InitValue = 0;
tags[i].InitQuality = QualityType.qdaQualityGood;
tags[i].OPCGateWay = "Gateway1";
tags[i].OPCItemID = "F001.PV";
tags[i].Script = "";
tags[i].LockStatus = false;
tags[i].Online = true;

IM 36J04A14-01E 7th Edition Issue 1 December 28 2005-08

24-30 Chapter 24 Exaquantum.NET API

//MAN R4
i = 1;
tags[i].Name = "MAN-TAG";
tags[i].Path = "Root.Test.Man";
tags[i].TemplateName = "MAN-R4";
tags[i].Description = "float";
tags[i].Units = "l";
tags[i].LowEng = 0;
tags[i].HighEng = 9999;
tags[i].InitValue = 100;
tags[i].InitQuality = QualityType.qdaQualityGood;
tags[i].OPCGateWay = "";
tags[i].OPCItemID = "";
tags[i].Script = "";
tags[i].LockStatus = false;
tags[i].Online = true;

//CAL String
i = 2;
tags[i].Name = "CAL-TAG";
tags[i].Path = "Root.Test.CAL";
tags[i].TemplateName = "CAL-STR";
tags[i].Description = "";
tags[i].Units = "";
tags[i].LowEng = 0;
tags[i].HighEng = 0;
tags[i].InitValue = 0;
tags[i].InitQuality = QualityType.qdaQualityGood;
tags[i].OPCGateWay = "";
tags[i].OPCItemID = "";
tags[i].Script = "[Result] = CStr(0)";
tags[i].LockStatus = false;
tags[i].Online = true;

// add
tagManager.AddTag(tags, out handles, out errors);

// delete
tagManager.DeleteTag(handles, out errors);

GetTag/CheckTag/ModifyTag
TagManager tagManager = new ExaquantumAPI().TagManager;

QTag[] tags = new QTag[1];

int[] handles;
int[] errors;

string[] paths = new string[1];

paths[0] = "Root.Test.MAN-R4";

// Get
tagEditor.GetTag(paths, out handles, out tags, out errors);

tags[0].Name = "MAN-REAL";
tags[0].InitValue = 0;

IM 36J04A14-01E 7th Edition Issue 1 December 28 2005-08

Exaquantum API Reference Manual 24-31

// Check
tagManager.CheckTag(tags, out errors);
if(errors[0] != 0)
{
return; // error
}

// Modify
tagManager.ModifyTag(handles, tags, out errors);

FindTag
TagManager tagManager = new ExaquantumAPI().TagManager;

QTagFilter[] tagFilters = new QTagFilter[1];

QTag[] tags;
int[] handles;

tagFilters[0].tagFilterID = FilterIDType.FILTER_PATH;
tagFilters[0].filter = "Root.Test.*";

tagManager.FindTag(tagFilters, out handles, out tags);

Sample Code for the management of Folders

GetFolder
TagManager tagManager = new ExaquantumAPI().TagManager;

string[] paths = new string[1];

QFolder[] folders;
int[] handles;
int[] errors:

paths[0] = "Root.Test";

tagManager.GetFolder(paths, handles, folders, errors);

AddFolder/CheckFolder/ModifyFolder/DeleteFolder
TagManager tagManager = new ExaquantumAPI().TagManager;

// parameter set

QFolder[] f_folders = new QFolder[3];

int[] f_handles;
int[] f_errors;

// folder create
f_folders[0].Name = "OPC";
f_folders[0].Path = "Root.Test";
f_folders[0].Online = true;
f_folders[1].Name = "MAN";
f_folders[1].Path = "Root.Test";
f_folders[1].Online = true;
f_folders[2].Name = "CAL";
f_folders[2].Path = "Root.Test";
f_folders[2].Online = true;

IM 36J04A14-01E 7th Edition Issue 1 December 28 2005-08

24-32 Chapter 24 Exaquantum.NET API

tagManager.AddFolder(f_folders, out f_handles, out f_errors);

f_folders[0].Name = "OPC-TEST";
// folder check
tagManager.CheckFolder(f_folders, out f_errors);

// folder modify
tagManager.ModifyFolder(f_handles, f_folders, out f_errors);

// folder delete
tagManager.DeleteFolder(f_handles, out f_errors);

IM 36J04A14-01E 7th Edition Issue 1 December 28 2005-08

Exaquantum API Reference Manual 24-33

24.7 Operation interface

The Operation object allows the control over the startup and shutdown of the Exaquantum
server.

Namespace: Yokogawa.EXA.Exaquantum

Startup Method

Description

Startup Exaquantum. This is an asynchronous call.

Signature
Startup()

StatusChanged Event

Description

This event is fired on the completion of Exaquantum startup or shutdown.

Signature
Event EventHandler StatusChanged;

Shutdown Method

Description

Stop Exaquantum. This is an asynchronous call.

Signature
Shutdown()

Status Property

Description

Get the Exaquantum Service Status. The returned value is one of the following:
ContinuePending
Paused
PausePending
Running
StartPending
Stopped
StopPending

IM 36J04A14-01E 7th Edition Issue 1 December 28 2005-08

24-34 Chapter 24 Exaquantum.NET API

Signature
System.ServiceProcess.ServiceControllerStatus Status{get;}

IsMonitoring Property

Description

Set the notification of Exaquantum Service status change. In case of TRUE, notice
Exaquantum Service status changed.

Signature
bool IsMonitoring(get; set;)

Sample Code for Startup and Shutdown

ExaquantumAPI m_api = new ExaquantumAPI();

Operation m_ope;

public void StartUp()

{
if(m_ope == null)
{
m_ope = m_api.Operation;
m_ope.StatusChanged += new EventHandler(EventChange);
}
m_ope.Startup();
}

public void ShutDown()

{
if(m_ope == null)
{
m_ope = m_api.Operation;
m_ope.StatusChanged += new EventHandler(EventChange);
}
m_ope.Shutdown();
}

private void EventChange(object e, EventArgs arg) {

Console.WriteLine(m_ope.Status.ToString());
}

IM 36J04A14-01E 7th Edition Issue 1 December 28 2005-08

Exaquantum API Reference Manual 24-35

24.8 Enumerations
This section defines the Enumerations user in the Exaquantum .NET API.

TagType

DataType

AggregationType

AggregationCalcType

SummationTimeFactorType

RawHistorianIntervalType

OPCPeriodType

TagFilterType

QualityType

TagType Enumeration

Enumeration for the tag type

enum TagType{
TAG_TYPE_MAN = 1,
TAG_TYPE_OPC = 2,
TAG_TYPE_CALC = 3,
TAG_TYPE_SHORTCUT = 4
};

Table 24-3

Member name Description

TAG_TYPE_OPC OPC Tag

TAG_TYPE_MAN Manual Tag

TAG_TYPE_CALC Calc Tag

TAG_TYPE_SHORTCUT Shortcut Tag

DataType Enumeration

Enumeration for the data type

enum DataType{
DATA_TYPE_INTEGER = 2,

IM 36J04A14-01E 7th Edition Issue 1 December 28 2005-08

24-36 Chapter 24 Exaquantum.NET API

DATA_TYPE_LONG = 3,
DATA_TYPE_FLOAT = 4,
DATA_TYPE_DOUBLE = 5,
DATA_TYPE_STRING = 8
}
Table 24-4

Member name Description

DATA_TYPE_INTEGER Interger (VT_I2)

DATA_TYPE_LONG Long (VT_I4)

DATA_TYPE_FLOAT Float (VT_R4)

DATA_TYPE_DOUBLE Double (VT_R8)

DATA_TYPE_STRING String (VT_BSTR)

AggregationType Enumeration

Enumeration for the Aggregation Type

enum AggregationType{
AGGREGATION_TYPE_CONTINUOUS,
AGGREGATION_TYPE_DESCRETE
}
Table 24-5

Member name Description

AGGREGATION_TYPE_CONTINUOUS Continuous

AGGREGATION_TYPE_DISCRETE Discrete

AggregationCalcType Enumeration

Enumeration for the aggregation calculation

enum AggregationCalcType{
AGGREGATION_MAX = 4,
AGGREGATION_MIN = 5,
AGGREGATION_MEAN = 2,
AGGREGATION_STDDEV = 6,
AGGREGATION_SUM = 3,
AGGREGATION_SPOT = 7,
AGGREGATION_STATUSCOUNT = 8,
AGGREGATION_ONSTATUS = 9
}

IM 36J04A14-01E 7th Edition Issue 1 December 28 2005-08

Exaquantum API Reference Manual 24-37

Table 24-6

Member name Description

AGGREGATION_MAX Maximum

AGGREGATION_MIN Minumum

AGGREGATION_MEAN Mean

AGGREGATION_STDDEV Standard Deviation

AGGREGATION_SUM Summation

AGGREGATION_SPOT Spot Value

AGGREGATION_STATUSCOUNT Status Count

AGGREGATION_ONSTATUS State on Time

IM 36J04A14-01E 7th Edition Issue 1 December 28 2005-08

24-38 Chapter 24 Exaquantum.NET API

SummationTimeFactorType Enumeration

Enumeration for the Summation Time Factor.

enum SummationTimeFactorType{
SUMMATION_TIME_FACTOR_NONE = 0,
SUMMATION_TIME_FACTOR_SECOND = 1,
SUMMATION_TIME_FACTOR_MINUTE = 60,
SUMMATION_TIME_FACTOR_HOUR = 3600
}
Table 24-7

Member name Description

SUMMATION_TIME_FACTOR_NONE Time Factor is none

SUMMATION_TIME_FACTOR_SECOND Time Factor is 1 second

SUMMATION_TIME_FACTOR_MINUTE Time Factor is 1 minute

SUMMATION_TIME_FACTOR_HOUR Time Factor is 1 hour

RawHistorianIntervalType Enumeration

Enumeration for the raw interval

enum RawHistorianIntervalType{
RAW_INTERVAL_NONE = -1,
RAW_INTERVAL_ONCHANGE = 0,
RAW_INTERVAL_1SEC = 1000,
RAW_INTERVAL_2SEC = 2000,
RAW_INTERVAL_5SEC = 5000,
RAW_INTERVAL_10SEC = 10000,
RAW_INTERVAL_30SEC = 30000,
RAW_INTERVAL_1MIN = 60000,
RAW_INTERVAL_2MIN = 120000,
RAW_INTERVAL_5MIN = 300000,
RAW_INTERVAL_10MIN = 600000,
RAW_INTERVAL_30MIN = 1800000,
RAW_INTERVAL_1HOUR = 3600000
}
Table 24-8

Member name Description

RAW_INTERVAL_NONE Dont write values to Historian

RAW_INTERVAL_ONCHANGE Write a value when the value changes

RAW_INTERVAL_1SEC Write a value at 1 second if the value has changed

IM 36J04A14-01E 7th Edition Issue 1 December 28 2005-08

Exaquantum API Reference Manual 24-39

Member name Description

RAW_INTERVAL_2SEC Write a value at 2 seconds if the value has

changed

RAW_INTERVAL_5SEC Write a value at 5 seconds if the value has

changed

RAW_INTERVAL_10SEC Write a value at 10 seconds if the value has

changed

RAW_INTERVAL_30SEC Write a value at 30 seconds if the value has

changed

RAW_INTERVAL_1MIN Write a value at 1 minute if the value has changed

RAW_INTERVAL_2MIN Write a value at 2 minutes if the value has

changed

RAW_INTERVAL_5MIN Write a value at 5 minutes if the value has

changed

RAW_INTERVAL_10MIN Write a value at 10 minutes if the value has

changed

RAW_INTERVAL_30MIN Write a value at 30 minutes if the value has

changed

RAW_INTERVAL_1HOUR Write a value at 1 hour if the value has changed

OPCPeriodType Enumeration

Enumeration for the OPC update period

enum OPCPeriodType{
OPC_PERIOD_NONE = -1,
OPC_PERIOD_1SEC = 1000,
OPC_PERIOD_2SEC = 2000,
OPC_PERIOD_5SEC = 5000,
OPC_PERIOD_10SEC = 10000,
OPC_PERIOD_30SEC = 30000,
OPC_PERIOD_1MIN = 60000,
OPC_PERIOD_2MIN = 120000,
OPC_PERIOD_5MIN = 300000,
OPC_PERIOD_10MIN = 600000,
OPC_PERIOD_1HOUR = 3600000
}

IM 36J04A14-01E 7th Edition Issue 1 December 28 2005-08

24-40 Chapter 24 Exaquantum.NET API

Table 24-9

Member name Description

OPC_PERIOD_NONE Except OPC tag

OPC_PERIOD_1SEC OPC update period is 1 second

OPC_PERIOD_2SEC OPC update period is 2 seconds

OPC_PERIOD_5SEC OPC update period is 5 seconds

OPC_PERIOD_10SEC OPC update period is 10 seconds

OPC_PERIOD_30SEC OPC update period is 30 seconds

OPC_PERIOD_1MIN OPC update period is 1 minute

OPC_PERIOD_2MIN OPC update period is 2 minutes

OPC_PERIOD_5MIN OPC update period is 5 minutes

OPC_PERIOD_10MIN OPC update period is 10 minutes

OPC_PERIOD_1HOUR OPC update period is 1 hour

IM 36J04A14-01E 7th Edition Issue 1 December 28 2005-08

Exaquantum API Reference Manual 24-41

TagFilterType Enumeration

Enumeration for the tag filter

enum TagFilterType{
TAG_FILTER_PATH = 1,
TAG_FILTER_NAME = 2,
TAG_FILTER_OPC_ITEM_ID = 3
TAG_FILTER_GATEWAY = 4
}
Table 24-10

Member name Description

TAG_FILTER_PATH Filtering by path

TAG_FILTER_NAME Filtering by tag name

TAG_FILTER_OPC_ITEM_ID Filtering by OPC item ID

TAG_FILTER_GATEWAY Filtering by OPC Gateway

QualityType Enumeration

Enumeration for tag quality

enum QualityType{
QUALITY_BAD = 0,
QUALITY_UNCERTAIN = 64,
QUALITY_GOOD = 192
}
Table 24-11

Member name Description

QUALITY_BAD Bad

QUALITY_UNCERTAIN Uncertain

QUALITY_GOOD Good

IM 36J04A14-01E 7th Edition Issue 1 December 28 2005-08

24-42 Chapter 24 Exaquantum.NET API

24.9 Definition of Structures

This section details the content of the data structures that are used in the .NET API.

QAggregationPeriod

QTagTemplate

QAggregationInfo

QTag

QFolder

QTagFilter

QAggregationPeriod Structure

Structure of Production calendar period information.

Table 24-12

Member name Type Range Description

Name string [1-32] characters Production calendar period name

Description string [0-256] characters Description of the aggregation

period

Period Int !*1 Period in minutes

Offset Int !*2 Offset from the period boundary,

in minutes

ParentHandle Int !*3 Handle of the parent Production

Calendar (or 0 if Raw data)

*1: Must be one of the following:

2,3,4,5,6,10,12,15,20,30,60,90,120,180,240,360,480,720,1440

*2: Must be less than the Period

*3: See the following

List of effective value of aggregation source data handles

IM 36J04A14-01E 7th Edition Issue 1 December 28 2005-08

Exaquantum API Reference Manual 24-43

Table 24-13

Aggregation Period Effective value of aggregation source data handles

Hour Raw

Day Raw, Hour, Custom

Month Raw, Hour, Data, Custom

Custom Raw

IM 36J04A14-01E 7th Edition Issue 1 December 28 2005-08

24-44 Chapter 24 Exaquantum.NET API

QTagTemplate Structure

Structure for Tag Template operation

Table 24-14

Member name Type Range Description

Name String [1-32] Tag template name

character
s

Version Int Version

TagType TagType Tag type

DataType DataType Data type

AggregationType AggregationType Aggregation type

RawHistorianInterva RawHistorianInterval Raw Historian Interval

l Type

EngUnitsFlag Bool Engineering Unit

EngRangeFlag Bool Engineering range

DescriptionFlag Bool True Tag Description

AggregationPeriodI Int[] *1 Array of Aggregation

Ds period ID(s)

Set to NULL if no
aggregations are used

WriteToOPCGatewa Bool *2 Writes to OPC

yFlag gateway.

OPCPeriod OPCPeriodType *3 OPC update period ID

PercentDeadband Float *3 Deadband

*4

AggregationSupplie Bool[] *5 Aggregation is made

d_ with the computational
expression.
ByCalculationFlag

IM 36J04A14-01E 7th Edition Issue 1 December 28 2005-08

Exaquantum API Reference Manual 24-45

Member name Type Range Description

AggregationInfo QAggregationInfo[] Detail of aggregation

information

*1: Get valid value using QueryAggregationPeriod

*2: Always False when TagType is not OPC.

*3: Must be set to OPC_PERIOD_NONE when not OPC tag.

*4: Must be one of the following values: 0,0.01,0.1,0.2,0.5,1,1.5,2,5,100

*5: The contents of AggregationSuppliedByCalculationFlag should correspond to the

contents of AggregationPeriodIDs. If TagType is not CALC, the contents should be
all FALSE. The content can be TRUE, only if the size is 1 (one).

IM 36J04A14-01E 7th Edition Issue 1 December 28 2005-08

24-46 Chapter 24 Exaquantum.NET API

List of Parameter used by each TagType

These are used by Tag Template

Table 24-15

Parameter Name Description OPC MAN Calc

Tag Tag Tag

Name Tag Template Name X X X

TagType Tag Type X X X

DataType Data Type X X X

AggregationType Aggregation Type X X X

RawHistorianInterval Raw Historian

X X X
Interval

EngUnitsFlag Engnieering Units XX*1 XX*1 XX*1

EngRangeFlag Engineering Range XX XX XX

DescriptionFlag Descriptions X*3 X*3 X*3

AggregationPeriods Aggregation Periods XX*2 XX*2 XX*2

Write to OPC Gateway Writes to OPC

XX Blank Blank
gateway

Period OPC update period X Blank Blank

Percent Deadband Dead band X Blank Blank

AggregationSuppliedByCalculation Aggregation period

determined with
Blank Blank XX
computed
expressions

AggregationInfo Detailed aggregation

XX*2 XX*2 XX*2
informtion

X: Mandatory

XX: Optional

Blank: Not settable

*1: Not settable when the DataType is string.

IM 36J04A14-01E 7th Edition Issue 1 December 28 2005-08

 Exaquantum API Reference Manual 24-47

*2: If AggregationPeriods has one or more elements (i.e. one or more aggregation
periods defined), then AggregationInfo must also have one or more elements (one
or more aggregation types defined).

*3: It must always be true.

QAggregationInfo Structure

Structure of aggregation information.

Table 24-16

Member Type Range Description

name

Aggregation AggregationCalcType Aggregation type (set by

enumeration see Table
24-17).

Parameter Object *1 Parameters required for

certain aggregations - see
Table 24-17.

Table 24-17

Aggregation Enum Value Parameter Continuous Discrete

Type

Maximum AGGREGATION_MAX NULL X Blank

Minumum AGGREGATION_MIN VT_ NULL X Blank

Mean AGGREGATION_MEAN NULL X Blank

Standard AGGREGATION_STDDEV NULL

X Blank
Deviation

Summation AGGREGATION_SUM Object[5]: (*2)

[0] Summation Time

Factor
(SummationTimeFactor
Type value) X Blank

[1] Differential
Summation Flag

[2] Decimal Places

IM 36J04A14-01E 7th Edition Issue 1 December 28 2005-08

 24-48 Chapter 24 Exaquantum.NET API

Aggregation Enum Value Parameter Continuous Discrete

Type

[3] Maximum Value

[4] Percentage
Difference

Spot Value AGGREGATION_SPOT NULL X Blank

Status Count AGGREGATION_STATUSCOUNT On Status *1 Blank X

State on AGGREGATION_ONSTATUS On Status *1

Blank X
Time

*1: These must have the same value. The value must be a string, with a maximum of 32
characters

*2: This parameter must be a 5 element array of type Object.

IM 36J04A14-01E 7th Edition Issue 1 December 28 2005-08

Exaquantum API Reference Manual 24-49

QTag Structure

Structure used with Tag management functions.

Table 24-18

Member Type Range Description

name

Name String [1-32] Tag name

characters

Path String [1-256] Parent path of tag

Characters

(Including Name,
where
applicable)

TemplateName String [1-32] Template name

characters

Description String [0-256] Tag Description

characters

Units String [0-256] Unit

characters

LowEng Double *1 Engineering lower limit

HighEng Double *1 Engineering upper limit

InitValue As appropriate *2 Initial value (Used in Man tag)

for data type

InitQuality QualityType Initial quality (Used in Man tag)

OPCGateWay String 32 (*3) OPC gateway name (Used in

OPC tags)

OPCItemID String 244(*3) OPC item ID (Used in OPC tags)

Script String No HighRange Script (Used in Calculation tags)

limit(*4)

LockStatus Bool Lock status (Template is not

IM 36J04A14-01E 7th Edition Issue 1 December 28 2005-08

24-50 Chapter 24 Exaquantum.NET API

Member Type Range Description

name
reflected.)

Online Bool TRUE if tag is to be set online.

*1: Only applicable for numeric tags.

*2: Only applicable to Manual tags. When using a numeric data type, and the tag
template calls for LowEng and HighEng, then the value must be between LowEng
and HighEng, and within the range of the data type. When using a string data type,
the value can be up to, and including 256 characters. For tag types other than
Manual, this should be set to NULL.

*3: This is only applicable to OPC tags. For non-OPC tags, this should be set to NULL.

*4: This is only applicable to Calculated tags. For non-Calculated tags, this should be
set to NULL.

IM 36J04A14-01E 7th Edition Issue 1 December 28 2005-08

Exaquantum API Reference Manual 24-51

List of Parameter used by each TagType

Table 24-19

Parameter Name Description OPC MAN Calc

Tag Tag Tag

Name Tag Name X X X

Path Parent Path X X X

TemplateName Template Name X X X

Description Description XX XX XX

Units Units XX*1 XX*1 XX*1

LowEng Low Range XX*2 XX*2 XX*2

HighEng High Range XX*2 XX*2 XX*2

InitValue Value Blank X Blank

InitQuality Data Quality Blank X*3 Blank

OPCGateway OPC Gateway X Blank Blank

OPCItemID OPC Item ID X Blank Blank

Script Script Blank Blank X

LockStatus Lock Status XX XX XX

Online Online XX Blank XX

*1: Only required when Engineering Units are defined by the Tag Template.

*2: Only required when Engineering Range is defined by the Tag Template.

*3: When adding a tag, the initial quality is always set to Good, regardless of what is
specified. This value is used when modifying the tag.

IM 36J04A14-01E 7th Edition Issue 1 December 28 2005-08

24-52 Chapter 24 Exaquantum.NET API

QFolder Structure

Structure used for Folder management functions.

Table 24-20

Member Type Range Description

name

Name String [1-32] Folder name

Characters

Path String [1-256] Parent Path of Folder

Characters

(Including folder
name, where
applicable)

Online Bool True or False Online flag *1

*1: Exaquantum R2.20 always returns TRUE.

IM 36J04A14-01E 7th Edition Issue 1 December 28 2005-08

Exaquantum API Reference Manual 24-53

QTagFilter Strucure

Structure used for retrieving tags

Table 24-21

Member Type Range Description

name

tagFilterType QTagFilterType Filter type

filter String Filtering conditions

24.10 Error Code List

Error code list API was defined following name space.

Yokogawa.Exa.Exaquantum.Common.ErrorCode

Table 24-22

Member name Description

EQ_E_ANALYZE Analyze Error

EQ_E_DUPLICATE_HANDLE Duplicate handle(s)

EQ_E_DUPLICATE_NAME Duplicate name in array parameter.

EQ_E_FAIL Failure

EQ_E_INTERNAL_ERROR Internal Error

EQ_E_INUSE One or more objects are being referenced

EQ_E_INVALID_AGGREGATIONINF Invalid Aggregation Calculation

O

EQ_E_INVALID_AGGREGATION_PE Invalid Aggregation Period

RIOD

EQ_E_INVALID_AGGREGATIONTYP Invalid Aggregation Type

E

EQ_E_INVALID_ARGUMENT Invalid Argument

EQ_E_INVALID_CALCFLAG Invalid Calculation Flag

IM 36J04A14-01E 7th Edition Issue 1 December 28 2005-08

24-54 Chapter 24 Exaquantum.NET API

Member name Description

EQ_E_INVALID_CALLING_SP Error calling an internal Stored Procedure

EQ_E_INVALID_CONSTRUCT Error in Construct

EQ_E_INVALID_DATATYPE Invalid DataType

EQ_E_INVALID_DEADBAND Invalid DeadBand

EQ_E_INVALID_DESCRIPTION Invalid Description

EQ_E_INVALID_HANDLE Invalid Handle

EQ_E_INVALID_HIGHENG Invalid High Range

EQ_E_INVALID_HISTORIANINTERV Invalid Historian Interval

AL

EQ_E_INVALID_LOWENG Invalid Low Range

EQ_E_INVALID_NAME Invalid Name

EQ_E_INVALID_OFFSET Invalid Offset

EQ_E_INVALID_OPC_GATEWAY Invalid OPC Gateway

EQ_E_INVALID_OPC_ITEMID Invalid ItemID

EQ_E_INVALID_OPCPERIOD Invalid OPC Period

EQ_E_INVALID_PARENTHANDLE Invalid Handle Parameter

EQ_E_INVALID_PATH Invalid Path

EQ_E_INVALID_PERIOD Invalid Period

EQ_E_INVALID_QUALITY Invalid Quality

EQ_E_INVALID_RANGE Invalid Range

EQ_E_INVALID_SCRIPT Invalid Script

EQ_E_INVALID_TAGTYPE Invalid TagType

EQ_E_INVALID_TEMPLATE Invalid TagTemplate

EQ_E_INVALID_TEMPLATENAME Invalid TagTemplate name

EQ_E_INVALID_UNITS Invalid Units

IM 36J04A14-01E 7th Edition Issue 1 December 28 2005-08

Exaquantum API Reference Manual 24-55

Member name Description

EQ_E_INVALID_VALUE Invalid Initial Value

EQ_E_INVALID_WRITE_OPCGATE Invalid Write To OPC Gateway flag

WAY

EQ_E_ITEMEXIST This object already exists

EQ_E_OTHERS_ANALYSE_ERROR Error caused by other analyze error

EQ_E_TRANSACTIONOPERATION Transaction Error

S_OK SUCCEED

IM 36J04A14-01E 7th Edition Issue 1 December 28 2005-08

24-56 Chapter 24 Exaquantum.NET API

This page intentionally left blank

IM 36J04A14-01E 7th Edition Issue 1 December 28 2005-08