9akk101130d1385 - PGP API Manual

Power Generation Portal
Version 4.1
API Manual
Version 4.1
API Manual
NOTICE
The information in this document is subject to change without notice and should not be
construed as a commitment by ABB. ABB assumes no responsibility for any errors that
may appear in this document.
In no event shall ABB be liable for direct, indirect, special, incidental or consequential
damages of any nature or kind arising from the use of this document, nor shall ABB be
liable for incidental or consequential damages arising from use of any software or hard-
ware described in this document.
This document and parts thereof must not be reproduced or copied without written per-
mission from ABB, and the contents thereof must not be imparted to a third party nor used
for any unauthorized purpose.
The software or hardware described in this document is furnished under a license and
may be used, copied, or disclosed only in accordance with the terms of such license.
This product meets the requirements specified in EMC Directive 89/336/EEC and in Low
Voltage Directive 72/23/EEC.
Copyright © 2007 by ABB.

All rights reserved.
Release: October 2007

Document number: 9AKK101130D1385
TRADEMARKS
Registrations and trademarks used in this document include:
Acrobat Registered trademark of Adobe Systems, Incorporated.
Adobe Registered trademark of Adobe Systems, Incorporated.
Advant Registered trademark of ABB Inc.
AdvaBuild Registered trademark of ABB Inc.
Industrial IT Trademark of ABB Inc.
Microsoft Registered trademark of Microsoft Corporation.
Windows Registered trademark of Microsoft Corporation

TABLE OF CONTENTS
About This Book
Scope ..............................................................................................................................13
Intended User...................................................................................................................13
Document Structure .........................................................................................................13
Use of Warning, Caution, Information, and Tip Icons ....................................................13
Document Conventions ...................................................................................................14
Related Documentation ...................................................................................................15
On-line Documentation ........................................................................................15
Section 1 - Application Program Interface

Programming Environment .............................................................................................17
Program Implementation Outline.........................................................................17
Include Files .........................................................................................................18
Libraries .............................................................................................................19
Unicode .............................................................................................................19
Error Codes ..........................................................................................................20
Program Activation ..............................................................................................22
Installation .......................................................................................................................24
Installation on the Server .....................................................................................24
Installation on the Client ......................................................................................25
Connecting to the API Server..........................................................................................26
Accessing the Tag Database ............................................................................................27
Tag Information....................................................................................................28
Read/Write Tag Dynamic Data ............................................................................35
Interfacing the Alarm Subsystem ....................................................................................38
Queueing Alarms .................................................................................................39
Alarm Action Programs .......................................................................................42
Accessing Historical Data ...............................................................................................43
9AKK101130D1385 7
Table of Contents
Historical Databases Definition ........................................................................... 43

Retrieving Historical Data ................................................................................... 45
Time Management........................................................................................................... 46
System Information ......................................................................................................... 47
Miscellaneous Functions ................................................................................................. 50
Bit Manipulation .................................................................................................. 50
Support for Multi-Language Messages................................................................ 51
Direct Access File System .............................................................................................. 52
File Allocation Procedure .................................................................................... 53
Program Interface ................................................................................................ 54
Section 2 - API Functions

Alphabetical List of Functions ........................................................................................ 57
AlarmMessageLog............................................................................................... 57
AlarmMessageQueue........................................................................................... 60
ApmsApiGetClientNbr ........................................................................................ 62
ApmsApiSrvConnect ........................................................................................... 63
ApmsApiSrvDisconnect ...................................................................................... 65
CheckSecurity ...................................................................................................... 65
CheckTagSecurity ................................................................................................ 66
ConvertFromApmsTimeEx.................................................................................. 68
ConvertToApmsTimeEx ...................................................................................... 69
FileLock ............................................................................................................ 71
FileRead ............................................................................................................ 72
FileUnlock ........................................................................................................... 73
FileWrite ............................................................................................................ 74
FileWriteEx.......................................................................................................... 76
GetAlacMessage .................................................................................................. 77
GetApmsInfo ....................................................................................................... 80
GetApmsTime...................................................................................................... 81
GetApmsTimeEx ................................................................................................. 81
GetApmsTimeString ............................................................................................ 82
GetFileFinfo......................................................................................................... 85
8 9AKK101130D1385
Table of Contents
GetFileInfoEx.......................................................................................................86
GetHistoricData....................................................................................................88
GetTagIdx.............................................................................................................90
GetTagIdxFromIndex ...........................................................................................91
GetTagInfo ...........................................................................................................92
IsNationalLanguage .............................................................................................94
MessageErrorLog .................................................................................................95
MultiLanguage .....................................................................................................96
PeekAlacMessage ................................................................................................97
ReadHistoricValue................................................................................................99
ReleaseAlarmAction ..........................................................................................100
SetApmsInfo ......................................................................................................101
SetApmsTimeEx ................................................................................................102
SetTagInfo ..........................................................................................................103
TagListRead .......................................................................................................105
TagListWrite.......................................................................................................107
TagRead ...........................................................................................................109
TagReadString ....................................................................................................110
TagWrite ...........................................................................................................112
WriteHistoricValues ...........................................................................................115
The Demo Programs......................................................................................................117
Section 3 - Dynamic Data Exchange

Introduction ...................................................................................................................119
DDE Syntax...................................................................................................................119
ACCFIL ...........................................................................................................120
ALARM ...........................................................................................................121
LOCKFIL ...........................................................................................................122
SYSINFO ...........................................................................................................123
TAGCNF ...........................................................................................................124
TAGHIS ...........................................................................................................126
TAGINFI ...........................................................................................................128
TAGRTD ...........................................................................................................129
9AKK101130D1385 9
Table of Contents
TAGWTD .......................................................................................................... 129

WRIFIL .......................................................................................................... 130
The Demo Spreadsheet ................................................................................................. 131
Section 4 - Component Object Model (COM)

Library........................................................................................................................... 133
TNTAPI COM Objects.................................................................................................. 133
Construction and Destruction Behavior ........................................................................ 134
Common Interface......................................................................................................... 134
ConnectToTNT .................................................................................................. 134
DisconnectFromTNT ......................................................................................... 135
GetClientNumber............................................................................................... 136
GetLastRetCond................................................................................................. 136
IsConnectionAlive ............................................................................................. 137
IsSystemActive .................................................................................................. 137
Object TntSystem.......................................................................................................... 138
ApmsSysInfo ..................................................................................................... 138
CheckSysSecurity .............................................................................................. 139
ConvertFromApmsSysTimeEx.......................................................................... 140
ConvertToApmsSysTimeEx .............................................................................. 141
GetApmsSysInfo................................................................................................ 143
GetApmsSysTime .............................................................................................. 144
GetApmsSysTimeEx.......................................................................................... 144
GetApmsSysTimeString .................................................................................... 145
GetSysFileInfo ................................................................................................... 148
GetSysFileInfoEx............................................................................................... 149
IsNationaLanguage ............................................................................................ 150
SetApmsSysInfo ................................................................................................ 151
SetApmsSysTimeEx .......................................................................................... 152
SysFileLock ....................................................................................................... 153
SysFileRead ....................................................................................................... 154
SysFileUnlock.................................................................................................... 156
SysFileWrite....................................................................................................... 157
10 9AKK101130D1385
Table of Contents
SysMultiLanguage .............................................................................................159
WriteMsgErrorLog.............................................................................................160
Object TntTagDB ..........................................................................................................161
CheckDBTagSecurity.........................................................................................161
DBTagListRead..................................................................................................162
DBTagListWrite .................................................................................................164
DBTagRead ........................................................................................................166
DBTagReadString ..............................................................................................167
DBTagWrite .......................................................................................................168
GetDBTagIdx .....................................................................................................170
GetDBTagIdxFromIndex ...................................................................................171
GetDBTagInfo....................................................................................................172
SetDBTagInfo.....................................................................................................173
TagValueEx ........................................................................................................175
Object TntAlarm............................................................................................................175
AlmAlarmMessageLog ......................................................................................176
AlmAlarmMessageQueue ..................................................................................177
GetAlmAlacMessage .........................................................................................178
PeekAlmAlacMessage .......................................................................................179
ReleaseAlmAlarmAction ...................................................................................180
Object TntHistory ..........................................................................................................181
ClearHistBuffer ..................................................................................................181
GetHistData........................................................................................................182
ReadHistValue....................................................................................................184
WriteHistValues..................................................................................................186
............................................................................................................................188
Appendix A - Tables
Alarm Processing Options .............................................................................................189
Alarm Processing Macros..............................................................................................190
General Security Privileges ...........................................................................................190
Tag Security Privileges..................................................................................................191
9AKK101130D1385 11
Table of Contents
12 9AKK101130D1385
About This Book
Scope
The Power Generation Portal API Manual provides a general description and a
guide for developing and integrating application programs in Power Generation
Portal (PGP).
Intended User
This manual is chiefly addressed to programmers, process technicians, and the
personnel responsible for developing and integrating application programs into the
PGP.
A strong skill in Windows program development is required to the readers of this
manual. A general knowledge of PGP architecture and functionality is also
recommended.
Document Structure
The Power Generation Portal API Manual includes both the general information for
a User Application Program to interact with PGP functions and a reference list of
the provided Application Programming Interface (API) functions.
The manual also provides information for an Application Program to interact with
PGP by using the standard Microsoft Dynamic Data Exchange (DDE) protocol.
Use of Warning, Caution, Information, and Tip Icons

This publication includes Warning, Caution, and Information, where appropriate,
to point out safety related or other important information. It also includes Tip to
9AKK101130D1385 13
Document Conventions About This Book
point out useful hints to the reader. The corresponding symbols should be
interpreted as follows:
Electrical warning indicates the presence of a hazard which could result in

electrical shock.
Warning indicates the presence of a hazard which could result in personal injury.
Caution indicates important information or warning related to the concept

discussed in the text. It might indicate the presence of a hazard which could result
in corruption of software or damage to equipment/property.
Information alerts the reader to pertinent facts and conditions.
Tip indicates advice on, for example, how to design your project or how to use a
certain function.
Although Warning hazards are related to personal injury, and Caution hazards are
associated with equipment or property damage, it should be understood that
operation of damaged equipment could, under certain operational conditions, result
in degraded process performance leading to personal injury or death. Therefore,
comply fully with all Warning and Caution notices.
Document Conventions
The following conventions are used for the presentation of material:
• The words in names of screen elements (for example, the title in the title bar of
a window, the label for a field of a dialog box) are initially capitalized.
• Capital letters are used for the name of a keyboard key if it is labeled on the
keyboard. For example, press the ENTER key.
• Lowercase letters are used for the name of a keyboard key that is not labeled on
the keyboard. For example, the space bar, comma key, and so on.
14 9AKK101130D1385
About This Book Related Documentation
• Press CTRL+C indicates that you must hold down the CTRL key while
pressing the C key (to copy a selected object in this case).
• Press ESC E C indicates that you press and release each key in sequence (to
copy a selected object in this case).
• The names of push and toggle buttons are boldfaced. For example, click OK.
• The names of menus and menu items are boldfaced. For example, the File
menu.
– The following convention is used for menu operations: MenuName >
MenuItem > CascadedMenuItem. For example: choose File > New >
Type.
– The Start menu name always refers to the Start menu on the Windows
Task Bar.
• System prompts/messages are shown in the Courier font, and user
responses/input are in the boldfaced Courier font. For example, if you enter a
value out of range, the following message is displayed:
Entered value is not valid. The value must be 0 to 30.
You may be told to enter the string TIC132 in a field. The string is shown as follows
in the procedure:
TIC132
Variables are shown using lowercase letters.
sequence name
Related Documentation
On-line Documentation
All documentation is supplied in Adobe® Acrobat® reader (.pdf) format.
The Power Generation Portal User Manual is also available as online Help.
9AKK101130D1385 15
On-line Documentation About This Book
Table 1. Related Documents
Category Title Description

How to install Power Generation Portal.
Installation Manual
Software
Installation Power Generation Portal Release Known problems, fixed problems and other
Notes release information.
Power Generation Portal Shows you how to configure and use Power
Configuration Manual Generation Portal.
Configuration Power Generation Portal Display Provides instructions for building custom
Builder Manual graphic displays using the Display Builder.
Power Generation Portal User Provides instructions for using Power
Manual Generation Portal features.
Power Generation Portal Information on how to create application
Application Programmer programs that execute Power Generation
Interface Portal functions.
Operation
Power Generation Portal Quick A handy list of commonly used features and
Reference Guide commands.
16 9AKK101130D1385
Section 1 Application Program Interface
Programming Environment
PGP provides very powerful support for developing application programs that
interact very deeply with the basic functions provided.
This section presents general information about the environment, and the tools
supplied for integrating user application programs within PGP.
The main features provided to user applications programs are listed below:
• Support to access most of fields of the Realtime Database,
• Capability to read/write tag value and quality,
• Interaction with the Alarm Subsystem,
• Access to Historical Database,
• The possibility to define application files.
The API allows implementation of application programs that run on the same
computer where PGP is located, or application programs that run on remote
computers, connected to the PGP computer in a Client/Server architecture.
Program Implementation Outline

This guide outlines the general procedure for adding a new process to the system.
The guide is intended only as a reference for expert programmers and refers to
concepts contained in other parts of this manual, PGP documentation, Windows and
Compiler documentation.
Use the standard tools the development environment provides to write, compile and
test a program. The supported compiler is the Microsoft VisualC++, release 5.0 and
release 6.0.
9AKK101130D1385 17
Include Files Section 1 Application Program Interface
Include Files
The include files are located into a dedicated directory within the PGP folders.
By default, the PGP installation procedure sets this variable to the directory
C:\Program Files\ABB Industrial IT\Power Generation Portal\Sources\Include.
However you can change both the disk and the path. Make sure that this directory is
included into the default search path of the Compiler.
The main header file for PGP API functions is named APMSAPI.H. These header
files, listed in Table 2, include some other files that are required for the parameter
definitions, while some other files must be included directly.
Table 2. Header Files.
File Description
APMSAPI.H The file defines the API function prototypes.
SYSPRM.H The file defines system parameters and sizes.
APMSTYPE.H The file defines the data structures.
The file defines the function prototypes for the some very basic
APMSUTILITY.H
functions.
FILPRM.H The file defines the file identification numbers.
BALMPRM.H The file defines the alarm message numbers.
The file defines the error message numbers (reserved for internal
BEMFPRM.H
use).
ALMPRM.H The file defines the alarm codes.
The file defines the API function prototypes for multi-language
MULTILANGUAGE.H
translation.
APMSSECURITY.H The file defines the security rights codes.
Refer to these files to check the current implemented type definition and function
prototypes, in case this manual is not an updated release.
18 9AKK101130D1385
Section 1 Application Program Interface Libraries
Libraries
A user application program interfaces the PGP API functions through a Dynamic
Link Library (DLL) named ApmsApi.
The definition file for this DLL, ApmsApi.lib, is located in a directory defaulted to
C:\Program Files\ABB Industrial IT\Power Generation Portal\Lib by the installation
procedure. Both the disk and the directory path can be changed. Be sure that this
directory is included in the default path for the search library of the linker.
The DLL file is contained in a directory that is defaulted to C:\Program Files\ABB
Industrial IT\Power Generation Portal\Bin by the PGP installation procedure. Be
sure that this directory is included in the default path for the executable files (this
corresponds to the environment variable named PATH).
The basic functions, described in the Miscellaneous section of this manual are
located in the Uti1090.dll file and are described by the Uti1090.lib file. Be sure that
also these files are located into the correct paths.
The support for translating texts, according to a different language selection, is
contained in the Mlt1090.dll file and is described by the Mlt1090.lib file.
Unicode
PGP internally manages all character string using the UNICODE convention, which
is a specification for supporting character sets, like Japanese and Chinese, that
cannot be represented in a single byte.
Refer to the Windows documentation for details on this standard and its usage.
To maintain compatibility with already existing non-unicode compliant application
program, however, the API provides entry points for both unicode and non unicode
compilations.
The functions that are listed in the remainder of this document, have a dual
implementation, in a way similar to many Windows and MFC functions. The non-
unicode implementation translate character from/to unicode before/after accessing
the PGP internal strings.
Note that translation is not performed when bulk data (such as unformatted records
from a file) is accessed.
9AKK101130D1385 19
Error Codes Section 1 Application Program Interface
Error Codes
Unless explicitly noted for some particular function, all API functions return a
status code to the caller. Status codes are described in Table 3.
Table 3. Error Codes.
Value Description
R_NORMAL Successful exit.
General failure in the routine.
R_FAILED
See specific routine for meaning.
Invalid tag.
R_INVTAG An invalid tag name or tag ID was passed to the RDTB or TAG
access routine.
Invalid file key.
R_INVKEY The file key passed to the file access routine does not exist in the
PGP application.
Invalid record.
R_INVREC The record number specified to the file access routine is outside
the specific file limits.
Invalid number of records.
R_INVNREC The numbers of consecutive records passed to the file read or
write routine exceed the file limits.
Invalid record size.
R_INVRSIZ
The size of the record exceeds the file system limit (16384 words).
Invalid CRT.
R_INVCRT The CRT number passed to a MMI routine is outside the system
limits.
R_INVPARAM Invalid parameter.
No entry found.
R_NOENTR
An entry for this program was not found in the alarm action queue.
20 9AKK101130D1385
Section 1 Application Program Interface Error Codes
Value Description
Invalid program.
R_INVPGM An invalid program number was specified to the alarm action get
routine.
Invalid time.
R_INVTIM
An invalid time was specified to a time manipulation routine.
Activation failed.
R_ACTFAIL
The program requested to be activated failed.
Server not connected.
R_NOCONN A call to an API routine was executed before connecting the
appropriate Server by ApmsApiConnect.
Invalid License.
R_NOLICENSE The license to execute User Application Interface routines was not
purchased or was not loaded.
No data is returned.
R_NODATA
The retrieval routine does not return any data.
Undefined tag.
R_UNDTAG
The specified tag is not defined.
R_NOLOCK Resource lock failure.
Out of memory.
R_OUTOFMEM
Some request needs to allocate more memory than the available.
Not in simulation mode.
R_NOTSIMUL The requested action is valid only when the system is in
“Simulation mode”.
Not in frozen mode.
R_NOTFROZEN The requested action is valid only when the system is in
“Simulation mode” and in the “Frozen status”.
9AKK101130D1385 21
Program Activation Section 1 Application Program Interface
Value Description
Invalid type.
R_INVTYP
An invalid item type was specified.
R_RMSERR Error performing file access.
R_MAPERR Error mapping dynamic memory.
R_EOF End of file detected.
R_WARNING Generic warning.
R_NOPRIV No privileges.
R_INPROGRESS Operation in progress.
R_ABORTED Operation aborted.
R_SHUTDOWN PGP is shutting down.
R_NOACTIVE PGP is not active.
R_QUEFULL The queue is full.
R_FROZEN PGP is in “Simulation mode” and “Frozen status”.
R_NOLOGON Any user is not currently logged on.
R_SRVFAIL Server failed. The API Server process failed.
R_CHKLST Check status list. Reserved for internal usage.
Program Activation
The application programs that make use of the Apms API libraries are standard
Windows executable files. They can be activated, as any other program, from
Explorer or from shortcuts in any startup menu.
The PGP system also provides the capability to:
• Request the activation of a program from a key or menu item in the PGP
toolbar,
• Request the activation of a program from an active field in a display,
22 9AKK101130D1385
Section 1 Application Program Interface Program Activation
• Automatically activate a program at PGP startup.
Activation from Menu

The activation of a program from an item of the menu or from a key in the PGP
toolbar may be defined by editing the menu definition file.
This file gives the possibility to define the layout of the Human Machine Interface
and allows the association of specific actions to menu items and to keys.
The type of action associated to the menu item, the name of the program that will be
activated and the command line that will be passed to this program can be defined in
the menu file.
Refer to the InformIT Power Generation Portal Configuration Manual for the
details on the syntax of the menu definition file.
Activation from Display

The activation of a program from a display requires configuring in the display itself
a “key” which will perform this action. This key may be associated to any display
object such as a variable or a transparent rectangle.
The standard SODG Display translator provides the program activation feature via
the display command “ei 108 - user task activation”.
Refer to the InformIT Power Generation Portal Display Builder Manual for details.
Configuring the displays by using the Graphic Display Builder, edit the DIAG_F
file of the display to define the program activation.
Assuming that activation key is associated to an object named varxx and the
program to activate is named MyProgram, use the following syntax to define the
program activation.
$DIAG "varxx"
$ACT $EVENT $V_BUTTONPRESS 1
GFX_ExtAct("MyProgram" $ASCII_EXTRA "Command Line")
$END_ACT
$DKEY
9AKK101130D1385 23
Installation Section 1 Application Program Interface
$END_DIAG
Automatic Activation
After all the standard tasks have been activated (either in the Server or in the Client
machines), the PGP activation procedure (performed by the program named
ADAM) offers the possibility to activate user application programs.
The list of programs to be automatically activated is created by defining keys into
the Windows registry. The location to enter a new key, corresponding to the name
of the program to be activated, is:
HKEY_LOCAL_MACHINE\Software\ABB\Power Generation Portal\Startup
Add a new key with the name of the program, under the previous path. Then, add a
new string value named “CommandLine” which will define the command line
passed to the program.
Define as many keys as the user application programs to be activated at startup time.
Installation
The installation and setup of the API software, in a distributed environment, mainly
consists of two separated parts.
Installation on the Server

The installation of the API software on the Server is part of the general installation
of the PGP software.
The API Server process accept connections to clients. It must be configured, in
order to accomplish its job. A dedicated process named SysSetup that must be
executed before initiating the activities performs this activity.
This process mainly defines the list of Servers which participates to a distributed
system environment.
24 9AKK101130D1385
Section 1 Application Program Interface Installation on the Client
This process also allows you to define and modify an optional list of remote clients’
nodes, which is maintained into the System Registry and is used by the API Server
process to validate the incoming connections.
In case the Client list is not defined the Server accepts the connections from any
client, assigning dynamically the connection number.
The SysSetup Program display a list of node names. By selecting an item in this list,
it is possible to modify or to delete the name that is associated to the remote node.
The SysSetup program allows selecting the type of activation of the PGP processes
on the current computer. The choice can be:
• Client only.
– The Human Machine Interface programs will be activated on this
computer. A Client must connect a APMS Server to properly operate.
• Server only.
– The APMS Server will be activated on this computer. Other Client nodes
shall connect the Server.
• Client and Server.
– The APMS Server and the Human Machine Interface programs will be
activated on this computer. Other Client nodes shall connect the APMS
Server.
By selecting the OK button, when the configuration is terminated, the entered data
is written into the System Registry. The program also takes care of registering the
software, which perform the Distributed Communications, consisting in a
Proxy/Stub DLL and in an application server process.
Installation on the Client

The installation of the API software on the Client can be performed after the
installation of the PGP on the Server.
In the case that the Client refers to a shared directory on a disk of the Server, the
necessary files are already available and the installation can continue with the setup
activity.
In case the disk is not shared it is necessary to create a directory on the disk of the
Client and copy the following files from the ...PGP\Bin directory:
9AKK101130D1385 25
Connecting to the API Server Section 1 Application Program Interface
ApmsApi.dll
ApmsApiServerPs.dll
Uti1090.dll
Mlt1090.dll
SysSetup.exe
and to copy the following files from the ...PGP\Lib directory:
ApmsApi.lib
Uti1090.lib
Mlt1090.lib
Make sure that this directory is included into the search path for the executable files,
and that the library files are in the search path of the linker.
The API Client process must be configured, in order to accomplish its job, by
defining the name of the Server node. A dedicated process named SysSetup must be
executed before initiating the activities to register the names of the Server.
This process allows you to define, and to modify, the name of the remote server
node, which is maintained into the System Registry and which does the API Client
process to initiate the connection use. Note that it is possible to overwrite this
default name, by explicitly defining the name of the Server to the
ApmsApiServerConnect function.
The SysSetup program allows you to initialize or modify the name that is associated
to the remote Server node.
By selecting the OK button, when the configuration is terminated, the entered data
is written into the System Registry. The program also takes care of registering the
software, which perform the Distributed Communications, consisting in a
Proxy/Stub DLL.
Connecting to the API Server

Before using the API functions, a user application program must connect with the
API Server process, which will take care of performing local or remote access to the
API Server.
26 9AKK101130D1385
Section 1 Application Program Interface Accessing the Tag Database
The function that performs the connection is named ApmsApiSrvConnect. This

function takes, as input parameter, the name of the server node and returns a value
that uniquely identifies the client node, within the node definition structure
maintained in the server. This number may be useful to application programs, that
run on the client, to access information defined on a per client basis.
By default, this number is assigned in a dynamic way and may change from a
connection to another. However, a fixed number can be forced for each client by
defining a Client list on the Server.
If the name of the Server is not supplied to this function, then the name of the node
defined during the Client setup procedure is used for the remote connection.
If the Client node is not properly configured or is not enabled to run the PGP
distributed API, the function returns an error.
The number which identifies the Client node may also be obtained by calling the
ApmsApiGetClientNbr function.
Before exiting, the user application program must disconnect itself form the API
server by calling the ApmsApiSrvDisconnect function.
Accessing the Tag Database

This section describes the functions that retrieve data from the Database related to
the tags. These functions mainly give the capability to retrieve static attributes of the
tags (Database fields) and to retrieve dynamic values and qualities (Real-time
information). Moreover, there is the capability to write dynamic data for tags.
The user generally refers a Tag by using a name (character string corresponding to
the Database field TAGNAME) or by using an index (integer value corresponding
to the Database field TAGINDEX).
A Tag is internally referred, by API routines, using a structure commonly referred
as Tag Identification Index, defined by the following structure:
typedef struct
{
unsigned int num : 18 ;
unsigned int hnm : 8 ;
9AKK101130D1385 27
Tag Information Section 1 Application Program Interface
unsigned int node: 6 ;

} TAGIDX, *LPTAGIDX;
The hnm field refers to TAGTYPE parameter defines the Database type of the tag
HNMPV = Process Variable (Analog)
HNMDI = Digital Input (Digital or diagnostic)
Any other value is reserved.
The TAGNUM parameter defines the item number that corresponds to the index of
the tag into the relevant Database.
The TAGNODE parameter identifies the Server node that implements the tag.
Any other field is intended for internal use only.
User application programs should not take any assumptions on these values, nor
manipulate them, in order to ensure compatibility with future PGP releases. Notice
that the strcuture was slightly changed from the one used in former releases of PGP,
to increase the “num” field, thus increasing the tag address space.
The TAGIDX item number does not correspond to the TAGINDEX field value,
which is implemeted in the Tag Database.
The functions in Table 4 are used to retrieve the internal TAGIDX of a certain tag
given either the Tag Name or the Tag Index.
.
Table 4. Accessing Tag Database.
Name Description
GetTagIdx Retrieves the TAGIDX corresponding to a certain TAGNAME.
GetTagIdxFromIndex Retrieves the TAGIDX corresponding to a certain TAGINDEX.
Tag Information
The functions in Table 5 allow a user program to retrieve and to modify tag
attributes from the Tag Database.
28 9AKK101130D1385
Section 1 Application Program Interface Tag Information
.
Table 5. Tag Attributes.
Name Description
GetTagInfo Retrieves one Database field for a certain tag.
SetTagInfo Modifies one Database field for a certain tag.
Check whether the logged user has the securuty rights to perform
CheckTagSecurity
actions on a certain tag.
The tag information is manipulated by using the structure TAGINFO, which is a

union of different fields:
typedef union
{
int iValue;
float rValue;
BOOL bValue;
TIME1090 tValue;
TAGIDX tagidx;
TCHAR szValue[SZTINF+1];
TOTVAL totValue;
} TAGINFO, *LPTAGINFO;
where:
the field iValue is used to contain numerical and Boolean data;
the field rValue is used to contain floating point numbers;
the filed bValue is used to contain boolean values;
the field tValue is used to contain time;
the field totValue is used to contain totalized values;
the field tagidx is used to contain tag indexes;
the field szValue is used to contain zero terminated character strings;
any other field is reserved for internal usage.
9AKK101130D1385 29
Table 6 specifies the fields that can be accessed by user programs. For each field the
table specifies:
• the field symbol name (defined by TAGINFOTYPE),
• the type of returned value,
• the possibility to modify the field by using the SetTagInfo routine,
• the description of the tag info type.
Table 6. Tag Info Types.
TAGINFOTYPE Type Set Description

DB_TAGINDEX iValue no The index of the tag.
DB_TAGNAME szValue no The name of the tag.
DB_TAGDESC szValue no The description of the tag.
DB_TAGTYPE iValue no The type of the tag.
The secondary name (customer name) of the
DB_CUSTTAGID szValue yes
tag.
DB_PRIMDISP szValue yes The display associated to the tag.
DB_SEC_LEVEL iValue yes The Security level.
DB_SEC_GROUP iValue yes The Security group.
DB_AAP_NUM iValue no The alarm action program triggered.
DB_AL_REM iValue no Flag for remote/local alarm processing.
DB_TRIG_CALC iValue no The number of the triggered calculation.
DB_ICI_NUM iValue no The number of ICI (for C-NET tags).
DB_ICI_NDX iValue no The number of ICI Index (for C-NET tags).
DB_LOOP iValue no The number of Ring (for C-NET tags).
DB_PCU iValue no The number of PCU (for C-NET tags).
DB_MODULE iValue no The number of Module (for C-NET tags).
30 9AKK101130D1385

DB_BLOCK iValue no The number of Block (for C-NET tags).
The number of the Sequence of Events
DB_SER_NUMBER iValue no Recorder (for C-NET tags used for SOE
function).
The index within the Sequence of Events
DB_SER_INDEX iValue no Recorder (for C-NET tags used for SOE
function).
DB_EXT_MS_NUM iValue no The number of Master (for external tags).
DB_EXT_SL_NUM iValue no The number of Slave (for external tags).
DB_EXT_CH_NUM iValue no The number of Channel (for external tags).
DB_AL_PRI iValue yes The alarm priority index.
DB_ALMGROUP iValue yes The alarm group index.
DB_ALMINHTAG tagidx no The alarm inhibit tag.
DB_CTRLINHTAG tagidx no The control inhibit tag.
DB_EUDESC szValue no The engineering units descriptor.
DB_EUINDEX iValue yes The engineering units index.
DB_NUMDECPL iValue yes The number of decimals (for PV only).
DB_I4_DATA iValue yes Flag indicating I4/float format for PV values.
DB_SCA_VAL_0 rValue yes The low limit scale for tag presentation.
DB_SCA_VL_100 rValue yes The high limit scale for tag presentation.
DB_UT_TEXT szValue yes The user application defined text parameter.
DB_UT_TEXT1 szValue yes The user application defined text 1 parameter.
DB_UT_TEXT2 szValue yes The user application defined text 2 parameter.
The user application defined integer 1
DB_UT_IN1 iValue yes
parameter.
9AKK101130D1385 31

parameter.
parameter.
parameter.
DB_UT_RE1 rValue yes The user application defined real 1 parameter.
DB_VAL100 rValue yes The low instrument limit.
DB_VAL0 rValue yes The high instrument limit.
DB_LALARM rValue yes The low alarm limit.
DB_L2ALARM rValue yes The second low alarm limit.
DB_L3ALARM rValue yes The third low alarm limit.
DB_HALARM rValue yes The high alarm limit.
DB_H2ALARM rValue yes The second high alarm limit.
DB_H3ALARM rValue yes The third high alarm limit.
DB_LROC_LIMIT rValue yes The low rate of change alarm limit.
DB_HROC_LIMIT rValue yes The high rate of change alarm limit.
DB_H_ACTIVE iValue yes Flag indicating high alarm check active.
32 9AKK101130D1385

Flag indicating second high alarm check
DB_H2_ACTIVE iValue yes
active.
DB_H3_ACTIVE iValue yes Flag indicating third high alarm check active.
DB_L_ACTIVE iValue yes Flag indicating low alarm check active.
Flag indicating second low alarm check
DB_L2_ACTIVE iValue yes
active.
DB_L3_ACTIVE iValue yes Flag indicating third low alarm check active.
Flag indicating high rate of change alarm
DB_HR_ACTIVE iValue yes
check active.
Flag indicating low rate of change alarm check
DB_LR_ACTIVE iValue yes
active.
Flag indicating low instrument limit check
DB_LI_ACTIVE iValue yes
active.
Flag indicating high instrument limit check
DB_HI_ACTIVE iValue yes
active.
DB_ALARMDB rValue yes Alarm dead band, in engineering units.
DB_ALARMDB_PERC rValue no Alarm dead band in engineering units.
DB_EVENTTAG iValue no Flag indicating alarm/event only tag (for DI).
DB_REFSTAT iValue yes Value of alarm/normal state (for DI only).
DB_MAX_ROC iValue yes Maximum rate of change (for DI only).
DB_TOTALIZER_NUM iValue no The index of totalizer associated to the tag.
DB_TOTALIZER_1_MIN tValue no The totalized value over last minute.
DB_TOTALIZER_10_MIN tValue no The totalized value over last 10 minutes.
DB_TOTALIZER_30_MIN tValue no The totalized value over last 30 minutes.
DB_TOTALIZER_1_HOUR tValue no The totalized value over last hour.
9AKK101130D1385 33

DB_TOTALIZER_8_HOUR tValue no The totalized value over last 8 hours.
DB_TOTALIZER_1_DAY tValue no The totalized value over last day.
DB_TOTALIZER_1_MONTH tValue no The totalized value over last month.
DB_TOTALIZER_1_YEAR tValue no The totalized value over last year.
DB_TOTALIZED_1_MIN tValue no The totalized value over last minute.
DB_TOTALIZED_10_MIN tValue no The totalized value over last 10 minutes.
DB_TOTALIZED_30_MIN tValue no The totalized value over last 30 minutes.
DB_TOTALIZED_1_HOUR tValue no The totalized value over last hour.
DB_TOTALIZED_8_HOUR tValue no The totalized value over last 8 hours.
DB_TOTALIZED_1_DAY tValue no The totalized value over last day.
DB_TOTALIZED_1_MONTH tValue no The totalized value over last month.
DB_TOTALIZED_1_YEAR tValue no The totalized value over last year.
DB_ZEROSTATE tValue no The zero state descriptor of a digital tag.
DB_ONESTATE to The i-th (1 to 15) state descriptor of a digital
tValue no
DB_FVTEESTATE tag.
DB_FB1_0STATE and
tValue no Zero and one status of feedback 1.
DB_FB1_1STATE
DB_FB2_0STATE and
DB_FB2_1STATE
DB_FB3_0STATE and
DB_FB3_1STATE
DB_FB4_0STATE and
DB_FB4_1STATE
34 9AKK101130D1385
Section 1 Application Program Interface Read/Write Tag Dynamic Data

DB_LAST_UPDATE time yes The time of last database update.
DB_QUALITY iValue no The current quality of the tag.
Refer to the Database section in InformIT Power Generation Portal Configuration

Manual for a more complete description of the various database fields.
Other symbols defined in the TAGINFOTYPE are intended for internal use only.
Read/Write Tag Dynamic Data

Dynamic data for tags correspond to live data maintained into the Realtime
Database. This data is manipulated by using a structure defined as TAGVALEX. It
is composed by the fields described in the following description.
typedef struct
{
QUAL qual;
VALBUF value;
EXTIME time;
TAGTYPE type;
} TAGVALEX, *LPTAGVALEX;
The VALBUF structure is a union of several fields and describes the current value
of the tag. According to the point type, it may be a floating point or an integer type
for Process Variables or a bit map for Digital Inputs. Other fields are intended for
internal use only.
The selection of the format for PV values, which may be float or integer, can be
done according to the q2i4 bit defined in the quality status.
The VALBUF structure is defined as following:
typedef union
{
9AKK101130D1385 35
Read/Write Tag Dynamic Data Section 1 Application Program Interface
float val_float;// PV float value

long int val_long;// PV integer value
DWORD val_di;// DI bit mapped value
} VALBUF, *LPVALBUF;
The QUAL field is an array of status bytes whose bits are associated to a particular
condition. The structure is defined as following:
typedef union
{
unsigned long int l;// long quality
unsigned short int qf[2];// 2 word quality
struct
{
unsigned short q1app2 : 1;// application specific 2
unsigned short q1app1 : 1; // application specific 1
unsigned short q1hcfv : 1; // hardware channel failure
unsigned short q1rtag : 1; // red tagged
unsigned short q1b11 : 1; // reserved
unsigned short q1bad : 1; // bad calculated value
unsigned short q1alia : 1; // alarm inhibit active
unsigned short q1alin : 1; // alarm monitoring inhibited
unsigned short q1insv : 1; // operator inserted value
unsigned short q1ofsc : 1; // off scan
unsigned short q1oldd : 1; // old data
unsigned short q1alrm : 1;// alarm
unsigned short q1unak : 1; // unacknowledged
unsigned short q1imp : 1; // implemented
unsigned short q2dumm : 1;// reserved for playback

unsigned short q2b15 : 1;// reserved
unsigned short q2slav : 1;// significant low alarm (3-Low
alarm)
unsigned short q2shav : 1;// significant high alarm (3-High
alarm)
unsigned short q2trak : 1; // tracking
36 9AKK101130D1385
Section 1 Application Program Interface Read/Write Tag Dynamic Data
unsigned short q2i4 : 1;// i4 format if 1, floating point

format if 0
unsigned short q2ldev : 1; // low deviation alarm
unsigned short q2hdev : 1; // high deviation alarm
unsigned short q2droc : 1; // decreasing rate of change
unsigned short q2iroc : 1; // increasing rate of change
unsigned short q2lirv : 1; // low instrument range
unsigned short q2llav : 1; // low-low alarm (2-Low alarm)
unsigned short q2lav : 1; // low alarm
unsigned short q2hav : 1; // high alarm
unsigned short q2hhav : 1;// high-high alarm (2-High alarm)
unsigned short q2hirv : 1;// high instrument range
} b; // quality bits
} QUAL, t_qual, *LPQUAL;
The EXTIME field is a structure that contains the time stamp, which is the time of
the last change or the last Database update.
The TYPE field contains the point type definition (Analog / Digital).
The Realtime Database (RTDB) maintains the most updated value and status
information for all implemented tags. The user application programs retrieve and
modify the Realtime Database, for a certain tag, by means of the routines listed in
Table 7.
Table 7. Read/Write Tag Dynamic Data.
Name Description
Read the current value of the tag.
TagRead
The result is returned in floating or integer format.
9AKK101130D1385 37
Interfacing the Alarm Subsystem Section 1 Application Program Interface
Table 7. Read/Write Tag Dynamic Data.
Name Description
Read the current value of the tag.
The result is returned converted in string format.
TagReadString This routine can also be used to convert into string format, for
display and print purposes, any data contained into a TAGVALEX
structure.
Write a new value into the Realtime Database.
This routine queue data to the Data Input Processor program
which perform alarm processing and data validation or directly
writes data into the RTDB without any checking or processing. In
TagWrite this last case the user program must perform data validation and
alarm checking.
Options associated to this function allow further processing on the
tag, such as triggering an user application program or queuing the
new value to an external database.
The routines in Table 8 allow accessing the Realtime Database for a list of tags.
Table 8. RTDB Read/Write Tag List.
Name Description
TagListRead Read the current value of tags.
TagListWrite Write the current values of tags.
Interfacing the Alarm Subsystem

The alarm subsystem is devoted to the management of either alarms or event
information. This includes:
• Presenting chronologically ordered lists.
• Printing.
• Archive messages into alarm history files.
38 9AKK101130D1385
Section 1 Application Program Interface Queueing Alarms
• Maintain group summary information.

• Activating horns.
The alarm subsystem manages a queue of incoming messages, and processes each
entry according to the alarm management configuration of individual tags.
Furthermore the alarm subsystem is able to trigger a user application program when
an alarm is generated for a tag (according to tag configurable options), passing to
this program information related to the tag that generated the alarm.
Special functions are provided to user application programs to retrieve information
from the Alarm History archive. The functions give the possibility to filter the
messages, according to various characteristics.
Queueing Alarms
User application programs may interface the PGP alarm subsystem mainly queuing
messages, by using the functions of Table 9.
Table 9. Queueing Alarms to Alarm Subsystem.
Name Description
Queue an alarm, using an index defined into the System Alarm
AlarmMessageQueue
Message File.
Queue a message to be displayed, printed and/or recorded into
AlarmMessageLog
the Alarm History File.
The difference between the two functions is that:

• AlarmMessageQueue sends binary data to the alarm subsystem.
• AlarmMessageLog can send a formatted text message.
In the first case the message text is generated by the alarm subsystem by reading and
using the text conversion information defined in the Alarm Message Text file.
The AlarmMessageLog also provides the possibility to record a user-defined record
into the alarm archive file. The buffer that normally contains the message text is
used, in this case, to contain binary data as defined by the application program.
9AKK101130D1385 39
Queueing Alarms Section 1 Application Program Interface
The AlarmMessageLog function does not display or print this information, but only
archives it. The alarm retrieving function is able to select the messages according to
the specified message type.
At time of this writing the standard application that retrieves and displays the alarm
messages ignores the application defined messages.
• Support for this kind of messages will be included in future PGP releases.
The structure, which defines the data passed to the AlarmMessageQueue function,
is the following:
typedef struct
{
DWORD cbSize; // Size of the structure
EXTIME AlarmTime; // Time of the alarm
TAGIDX TagIdx; // Tag generating or associated
DWORD AlarmProcessing;// Processing Mask
WORD ClientNbr; // Number of the client queuing
WORD AlarmCode; // Code of the alarm
WORD AlarmGroup; // Alarm group
WORD AlarmPriority; // Alarm priority
WORD AudibleAlarm;// Audible Alarm index
WORD AlarmPrinter;// Alarm Printer index
WORD AlarmMessageNbr; // Message Number (F_ALM)
WORD AlarmData[ALQDBS]; // Specific formatting data
WORD UserParam[ALQUPR]; // Specific user parameters
// for retrieval filtering
} ALAQUE, *LPALAQUE; // Alarm message to be formatted
The structure, which defines the data passed to the AlarmMessageLog function, is
the following:
typedef struct
{
EXTIME AlarmTime; // Time of the alarm
TAGIDX TagIdx; // Tag generating or associated
DWORD AlarmProcessing; // Processing mask
40 9AKK101130D1385
Section 1 Application Program Interface Queueing Alarms
WORD AlarmCode; // Code of the alarm

WORD AlarmGroup; // Group
WORD AlarmPriority; // Priority
WORD AudibleAlarm; // Audible Alarm index
WORD AlarmPrinter;// Alarm Printer index
WORD MessageType; // Type of the following message
WORD UserParam[ALQUPR]; // Specific user parameters
// for retrieval filtering
TCHAR MessageText[S_ALDB]; //Formatted message
// Application Data
} ALALOG, *LPALALOG; // Alarm message to be logged
The alarm message numbers, that correspond to the records of the file F_ALM, are
defined into the BALMPRM.H include file.
The alarm codes that are defined into the file ALMPRM.H are summarized in
Table 10. The table also specifies which kinds of item type are accepted for that
particular code.
Table 10. Alarm Codes.
Code Valid type Description

ALEINF All item types Information event.
ALERTN HNMPV, HNMDI, HNMALA Return to normal.
ALEOPE HNMNOI, HNMPV, HNMDI Operator action.
ALEACK HNMPV, HNMDI Acknowledge event.
ALEEVT HNMDI Digital event.
ALEDIA HNMDI Digital alarm.
ALESHA HNMPV Significant-high alarm.
ALESLA HNMPV Significant-low alarm.
ALEHIR HNMPV High instrument alarm.
ALEHHA HNMPV High-high alarm.
9AKK101130D1385 41
Alarm Action Programs Section 1 Application Program Interface
Table 10. Alarm Codes.
Code Valid type Description

ALEHAL HNMPV High alarm.
ALELAL HNMPV Low alarm.
ALELLA HNMPV Low-low alarm.
ALELIR HNMPV Low instrument alarm.
ALERCP HNMPV Positive rate alarm.
ALERCN HNMPV Negative rate alarm.
ALEHCF HNMPV, HNMDI Hardware failure.
ALEALA HNMALA Generic Alarm.
Alarm Action Programs

In the PGP terminology, Alarm Action Programs are programs activated whenever
a PV or DI tag goes into an alarm state.
In the tag configuration there is the possibility to define if an alarm action program
must be activated or not, in the case of a certain exceeded alarm level.
An individual tag may trigger only one action program. The Alarm Action
Programs are numbered from 1 to 63.
The Alarm Action Programs may retrieve information about the activation point and
the exceeded limit by de-queueing a message from a specific queue. The functions
in Table 11 are available.
Table 11. Alarm Action Program.
Name Description
Get information from alarm action queue, waiting until a message
GetAlacMessage
will be available.
42 9AKK101130D1385
Section 1 Application Program Interface Accessing Historical Data
Table 11. Alarm Action Program.
Name Description
ReleaseAlarmAction Release a thread waiting for an alarm action message.
Get information from alarm action queue, if any message is
PeekAlacMessage
present.
The structure, which defines the data returned to the caller, is the following:
typedef struct
{
TAGIDX TagIdx; // Index of the tag
TAGVALEX TagVal;// Value, quality and time of the alarm
DWORD dwProgramNbr;// Number of Alarm Action Program
USHORT wPrevDiVal; // Previous value (DI only)
QUAL dwPrevDiQual; // Previous quality (DI only)
} ALAC, *LPALAC ;
Accessing Historical Data

This section describes the functions that retrieve data from the various historical
databases.
While there are some different databases, keeping historical data sampled according
to different requirements, the intent of these functions is to provide a common
interface for retrieving data.
Historical Databases Definition

A Database type (defined as HDBTYPE), that is specified in Table 12, internally
defines the historical databases.
9AKK101130D1385 43
Historical Databases Definition Section 1 Application Program Interface
Table 12. Historical Database Types.
Code Description
Playback.
These files contain snapshots of the current playback archive
HDB_PLB taken at regular intervals or upon operator requests. The time
limits are defined by the MAXORE parameter, while the number of
files is defined by the MXCONG parameter. Both are system
registry options.
Post-Trip Logs.
These files contain snapshots of the current playback archive
HDB_PTL taken for a subset of tags whenever a certain trigger event occurs.
There is the possibility to configure various groups of tags and to
define the trigger signals and the time intervals.
Periodic Groups.
These files contain the data sampled and archived at regular time
HDB_HIS intervals (such as hourly, daily, monthly, etc.). Different groups of
tags can be configured defining for each group: sampling and
archiving frequency and various archiving processing.
Alarm History.
This archive maintains a circular list of all alarms, events, and
HDB_ALM operator actions chronologically ordered. The data types on this
archive are ‘text’, while in other archives are ‘values’; for such
reason special access routines are provided.
44 9AKK101130D1385
Section 1 Application Program Interface Retrieving Historical Data
Table 12. Historical Database Types.
Code Description
Maintenance Totalization.
This archive maintains totalizations, especially for plant
HDB_HRT maintenance purposes, for the number of running hours and the
number of transactions for machinery described by digital tags.
Use the GETTAGINFO API function to retrieve the data from this
Database.
Energy Totalization.
This archive maintains the value of totalizers, sampled hourly, daily
HDB_ENE and monthly and maximum and minimum values during these
intervals. Use the GetTagInfo API function to retrieve the data from
this Database.
Using groups, which are indicated to the API functions using the TAGIDX
definition, can access the historical data inside the Database. The type field within
the TAGIDX structure defines the archive, according to the previous definition,
while the num field defines the number of the archive.
User application programs should not take any assumptions on these values, nor
manipulate or test them, in order to ensure compatibility with future PGP releases.
Retrieving Historical Data

The routines in Table 13 are used to access the Historical Database related to
Playback, Post Trip Logs and Historic (periodic) groups.
Table 13. Retrieving Historical Data.
Name Description
GetHistoricData Retrieve data from Historical Database.
ReadHistoricValue Read the values retrieved from Historical Database.
WriteHistoricValues Write a list of values into a Historical Database.
9AKK101130D1385 45
Time Management Section 1 Application Program Interface
The data archived into the different historical files is made available to the user
application programs by using the following procedure.
1. Read all historical data into a local buffer. The GetHistoricData function
retrieves all the data, for a certain list of tags related to a certain time interval
into a local storage buffer.
2. Perform a loop to read all the values related to a certain tag for each time
interval. The ReadHistoricValue function retrieves from the local storage the
values corresponding to the previously defined list of tags at a certain time
interval. This function must be called as many times as necessary to de-queue
all the data.
The historical data for a tag is returned into a structure that is the same to the one
used to access Realtime data, which means that the returned buffer contains the
value, the quality and the time-stamp information.
Time Management
The PGP internal time format is an integer representing the number of seconds
which have elapsed since 00:00:00 of January 1, 1991. This format is used as a
parameter to time functions and to functions interacting with the historical archives.
This format will be referred in the following description of this document as “Apms
Time”.
Moreover the time-tag used to maintain the time information into the Realtime and
Historical Databases is accurate up to the millisecond. The Extended Time structure
used to pass time information to API routines is defined as EXTIME. It foresees the
following fields.
typedef struct
{
TIME1090 dwTime; // seconds since 1/1/1991
DWORD dwMilsec;// milliseconds since last second
} EXTIME, *LPEXTIME;
46 9AKK101130D1385
Section 1 Application Program Interface System Information
The PGP internal time is maintained as an absolute value, it means that there are no
adjustments for Daylight Saving Time. This adjustment (adding or subtracting one
hour when DST) is provided by the time manipulation routines listed below.
The time handling routines in Table 14 are available for time management.
Table 14. Time Handling Routines.
Name Description
GetApmsTime Retrieve the PGP internal time (ApmsTime format)
GetApmsTimeEx Retrieve the internal time (Extended time format).
SetApmsTimeEx Set the internal time (Extended time format).
Read the current time or convert a time into a zero terminated
string, for display and print purposes.
GetApmsTimeString
Several formats can be selected. This routine perform Daylight
Saving Time adjustment, i.e. add one hour during summer time.
Convert date and time to PGP extended time format.
ConvertToApmsTimeEx This routine perform Daylight Saving Time adjustment, i.e. subtract
one hour during summer time
Convert a PGP extended time format to date and time information.
ConvertFromApmsTimeEx This routine perform Daylight Saving Time adjustment, i.e. subtract
one hour during summer time.
System Information
PGP provides a routine that allows reading various system definition parameters.
Another routine allows you to set some of them.Routines are listed in Table 15.
9AKK101130D1385 47
System Information Section 1 Application Program Interface
Table 15. System Information Routines.
Name Description
GetApmsInfo Retrieve the PGP parameter definition.
SetApmsInfo Modify the PGP parameter definition.
MessageErrorLog Write a message into the PGP error log file.
The parameters are described by the APMSINFOTYPE definition, while the

information manipulated by these routines have an integer format.
Table 16 lists the parameter that can be manipulated, specifying if one parameter
can be modified or not. The Set column asserts the possibility to modify the
parameter by an application program. Other parameters found in the
APMSINFOTYPE definition are intended for internal use only.
Table 16. User Manipulable Parameters.
APMSINFOTYPE Set Description

SYI_MaximumCrts no Maximum number of clients.
SYI_MaximumPV no Maximum number of Process Variables.
SYI_MaximumDI no Maximum number of Digital Inputs.
SYI_MaximumPlaybacks no Number of playback snapshot files.
Flag indicating if Remote I/O alarms for INFI module
SYI_IgnoreRio yes
status must be ignored.
Flag indicating if a Daylight Saving Time must be sent
SYI_DstOnInfi yes
when synchronizing the C-NET.
SYI_InfiTimeSynch yes Flag indicating if the C-NET must be synchronized.
SYI_UnackAlarm yes Flag indicating whether the Unack bit must be set.
Flag indicating if user data entry must be saved on
SYI_DataEntrySaved yes
files.
48 9AKK101130D1385
Section 1 Application Program Interface System Information

Percentage of Alarm History file filled before issuing an
SYI_PercentSaveOJ yes
alarm.
Flag indicating if tags coming form SER must be
SYI_QueueSOEtoDip no
queued to Data Input Processor.
Flag indicating if tags coming from SER must be logged
SYI_QueueSOEtoLog no
on dedicated SOE log.
SYI_DisableAudibleOnAck yes Flag indicating to disable audible alarm annunciation.
Flag indicating weather apply or not playback data
SYI_PlaybackCompress yes
compression algorithm.
Flag indicating if Bad Quality for tags must be treated
SYI_BadQualityAlarms yes
as an alarm.
SYI_MaximumTags no Number of tags.
SYI_RemoteClients no Number of remote clients for the DDE server.
Flag indicating whether millisecond indication must be
SYI_AlarmsWithMillisec yes
included into alarm messages.
SYI_AlarmsAckBroadcast yes Flag enabling alarm acknowledge broadcast.
Flag enabling commands to INFI devices even if they
SYI_RedTagCommands yes
are in Red Tag Status.
SYI_EnableAlarmPrint yes Flag enabling automatic printout of alarms.
SYI_MaximumICI no Number of ICIs.
SYI_MaximumICIIndex no Number of ICI indexes.
SYI_MaximumAlarmPriorities no Number of alarm priorities.
SYI_MaximumAlarmGroups no Number of alarm groups.
SYI_MaximumFiles no Number of files.
SYI_MaxTagPerGroup no Number of tags per group.
9AKK101130D1385 49
Miscellaneous Functions Section 1 Application Program Interface

SYI_IsSystemActive no Flag indicating if the APMS server is currently active.
Flag indicating APMS server shutdown currently NOT
SYI_RundownNotInProgress no
in progress.
SYI_IsRundownInProgress yes Flag indicating APMS server shutdown in progress.
Flag indicating APMS server running in Simulation
SYI_IsSimulationActive no
Mode.
Flag indicating the “Freeze Status” when the APMS
SYI_IsSimulationFrozen no
server is running in Simulation mode.
SYI_DemoSystem no Flag indicating APMS server running in Demo mode.
SYI_MaximumIndexNo no Number of Tag Indexes.
Flag enabling international formatting of the data in
SYI_InternationalDate no
alarm messages.
Application parameters (integers).
SYI_UserPar1 to
yes Can be freely set and reset by application programs.
SYI_UserPar8
They are set to 0 at PGP start-up.
Miscellaneous Functions
Bit Manipulation
PGP provides a set of routines for bit manipulation. This feature is mainly intended
for compatibility with application developed using the API functions available with
the 1090 APMS released before 5.0
The PGP convention for numbering the bits inside the word is opposite to the
standard bit numbering, i.e. the most significant bit is defined as bit 0 and the least
significant bit is bit 15.
50 9AKK101130D1385
Section 1 Application Program Interface Support for Multi-Language Messages
In the following description the available routines are described, specifying the
syntax to call them. These routines will not be described into the alphabetical list of
APMS APIs.
To get the value of a bit, inside a bitmap word:
short GtBit (unsigned short Iword, short NumBit);
To clear a bit inside a bitmap word:
void ClBit (unsigned short *Iword, short NumBit);
To set the value of a bit inside a bitmap word:
void StBit (unsigned short *Iword, short NumBit);
To get the value of a bit field inside a bitmap word:
short GtFld (unsigned short *Iarray, short StartBit,

short NumBit);
To store the value of a bit field inside a bitmap word:
void StFld (unsigned short *Iarray, short StartBit,

short NumBit, short FldVal);
Support for Multi-Language Messages

By default, the Human Machine Interface on the Client computers is provided in
English. However, PGP provides the possibility to interface to use a different
national language.
All messages, menu items and other text generated are translated before they are
displayed on the screen or recorded to log files.
The translation is made available through a language dictionary that contains all the
text strings used.
9AKK101130D1385 51
Direct Access File System Section 1 Application Program Interface
The dictionary, written in the BLANGDECK.XML file, contains each string in

English and the corresponding translation to the alternate national languages. Each
client user has the possibility to select, before starting the PGP application, if the
messages must be presented in English or translated in the national language.
The selection on a Client is independent from the selection on the other clients.
The possibility to on-line translate messages is made available to application
programs by means of an application dictionary (the file BLANG2DECKXML) and
the API functions listed in Table 17.
Table 17. API Functions.
Name Description
Multilanguage Translate a text message.
IsNationalLanguage Check if english or national language is selected on this client.
Direct Access File System

The Direct Access File Subsystem (DAFS) implemented into the PGP provides an
enhanced method of defining files either on the disk or in a global shared memory
and an enhanced method of direct access through a set of C/C++ callable interface
routines.
DAFS defines a “file” as a consecutive array of records and provides methods to:
• Read 1 to “n” records,
• Write 1 to “n” records,
• Lock and unlock files,
• Retrieve file directory information.
DAFS provides a transparent interface to access files that may be stored in different
way (see Table 18).
52 9AKK101130D1385
Section 1 Application Program Interface File Allocation Procedure
Table 18. Direct Access File System.
Name Description
Disk files They are located on the hard disk.
They are located in memory (in the Global Shared Region).
Core files Core files provide faster access than disk files but data stored on
them is not saved among consecutive system activations. (This file
type is not supported for User Application Programs).
They are located in memory (in a Pool Shared Region).
Unnamed core files provide faster access than disk files, but data
Unnamed Core files stored on them is not saved among consecutive system activation.
The difference from the standard core files is that they do not
necessitate the definition of a Common into the Global Shared
Region.
They have a copy on the disk and a copy on memory.
The main scope is to provide fast read access to memory copy and
Parallel files permanent data storage on the disk copy. DAFS provides
automatic updating of the two copies. (This file type is not
supported for User Application Programs).
They are the same of the previous files, except that they do not
Unnamed Parallel files necessitate the definition of a Common into the Global Shared
Region.
DAFS is an add-on to the operating system and uses standard services, which does
not require any modification to the standard operating system.
File Allocation Procedure

DAFS uses the standard services provided by the Operating System for allocation of
disk and memory space. The File System Configuration module within the BUILD
process is used to define the allocated disk space as well as global common regions
as logical files to the DAFS.
9AKK101130D1385 53
Program Interface Section 1 Application Program Interface
DAFS uses a fixed format input form for defining logical file parameters. The
format of the form, processed by BFIL builder, is given in file configuration section
of the PGP Configuration Manual.
This guide outlines the general procedure of adding a new disk file to the PGP. Note
that numbers from 350 (corresponding to a symbol F.USER) to 399 (corresponding
to the symbol F.LUSE) are reserved to define application specific files.
Edit the file FIL2PRM.INS and add equates for new files (i.e., logical file key, file
record size, and number of records in file), according to the following indications:
<DAFS_FILES action = “replace”>
<defs_file name = “F.USER” records = “10”/>
</DAFS_FILES>
Edit the BFIL2DECK.XML file, under the PGP\Config folder, adding the new file
information.
Build the file by running the BUILD program and selecting to build the File System.
Program Interface
This section defines the usage of the DAFS by means of C/C++ callable interface
routines.
The files are accessed, by the API functions by using a file index, as defined by the
FILEIDX structure, which is similar to the structure used to access the tags.
typedef struct
{
TAGNUM num ;// Index as defined in FILPRM
TAGTYPE type ;// Currently not used
TAGNODE node ;// Node on which
// the file is implemented
} FILEIDX, *LPFILEIDX;// File index structured type
The functions in Table 19 are available for accessing DAFS files.
54 9AKK101130D1385
Section 1 Application Program Interface Program Interface
:
Table 19. Direct Access File System Accessing Routines.
Name Description
FileRead Read 1 to n consecutive records from a DAFS file.
FileWrite Writes 1 to n consecutive records to a DAFS file.
Write 1 to n consecutive records to a DAFS file, and trigger
FileWriteEx
external actions.
FileLock Lock one file for exclusive access.
FileUnlock Unlock one file, allowing shared access.
The functions in Table 20 allow the user to get information about a DAFS file.
:
Table 20. Direct Access File System Getting Information Routines.
Name Description
GetFileInfo Read the characteristics of a DAFS file.
GetFileInfoEx Read extended information about a DAFS file.
9AKK101130D1385 55
Program Interface Section 1 Application Program Interface
56 9AKK101130D1385
Section 2 API Functions
Alphabetical List of Functions

AlarmMessageLog
Purpose
The AlarmMessageLog is the interface for any user application program to queue an
event to be processed by the Alarm Processors (within the Alarm Subsystem). This
module is responsible for displaying, printing, recording alarms into the Alarm
History file (also called Operator Journal), activating horns and maintaining alarm
summaries.
The AlarmMessageLog function queues the entry of events onto the Alarm Queue,
returning an error if the Queue is full.
This function also provides the way for archiving, into the Alarm History file,
binary data specific to the application. In this case the messages can only be
archived but cannot generate any other action.
The text message queued by this function is not translated for multi-language Client
interfaces.
The alarm processing options of Table A-1 in the Appendix A may be selected for
alarms, events and information.
The macros listed in the Table A-2 of the Appendix A define the most commonly
selected options.
The AlarmMessageLog may queue a message associated to a certain tag or may
queue a generic alarm not associated to tags. In this case the field TagIdx.hnm must
be set with the parameter HNMALA. If the field TagIdx.num is set to 0 then the
alarm will be acknowledged only when the complete alarm page is acknowledged
9AKK101130D1385 57
AlarmMessageLog Section 2 API Functions
else, if this field contains a valid integer number, it will be possible to acknowledge
the single alarm.
Syntax
RETCOND AlarmMessageLog( LPALALOG pAlalog );
58 9AKK101130D1385
Section 2 API Functions AlarmMessageLog
Parameters
Name Description
Pointer to an ALALOG structure with the following structure
cbSize - The size of the structure.
It acts as a protection for version changes, it must be
initialized to sizeof(ANALOG) prior to calling the
AlarmMessageLog function.
AlarmTime - The time of the alarm.
It is represented in the Extended time format (including
milliseconds).
TagIdx - The tag that generated the alarm or which may be
associated to the alarm itself.
ClientNbr - The number of the Client calling this function, as
returned by the ApmsApiSrvConnect.
Set to 0 (zero) if the alarm message information does not
take care of the sending Client.
AlarmProcessing - The processing applied to the message
according to the masks defined in the APMSTYPE.H file.
pAlalog
AlarmCode - The alarm classification, according to the
definitions specified into the General API description
section.
The codes are defined into the ALMPRM.H file.
AlarmGroup - The group of the alarm.
AlarmPriority - The priority of the alarm.
AudibleAlarm - The index of the audible horn that may be
associated to the alarm.
UserParam - An array of parameters, whose meaning is
specific to the application, recorded into the alarm history
file.
These parameters are used to perform specific filtering
when alarms are retrieved.
MessageText - A zero terminated character string, which
defines the text of the message that will be printed and
archived, or contains application defined data.
9AKK101130D1385 59
AlarmMessageQueue Section 2 API Functions
Return Code
Value Description
R_NORMAL Success.
R_NOCONN The API Server was not connected.
Internal failure in the API function.
R_FAILED
Error connecting to the Alarm Queue.
API Server failed.
R_SRVFAIL
Failure in the Client/Server communication.
R_NOACTIVE The PGP Server is not active.
R_QUEFULL The Alarm Message Queue is full.
AlarmMessageQueue
Purpose
The AlarmMessageQueue is the interface for any user application process to queue
an alarm/event information to be processed by the Alarm Processors. The
AlarmMessageQueue function queues an entry containing binary data to the Alarm
Queue. The function also activates the Alarm Processor to force the processing of
the message. It returns an error if the Alarm Queue is full.
The format of the alarm message text, produced by a call to this function, is
generated by the information contained in the System Alarm Message File
(F_ALMS). This file is loaded by the off-line builder procedure via the information
contained in the BALMDECK.INS script.
The alarms produced by this call are subject to the alarm handling processing. That
is, they may be displayed, printed, archived, may activate horns or trigger external
applications.
Before being formatted, the message texts defined by the AlarmMessageNbr
parameter are translated according to the language selected by the Client.
Syntax
RETCOND AlarmMessageQueue( LPALAQUE pAlaque );
60 9AKK101130D1385
Section 2 API Functions AlarmMessageQueue
Parameters
Name Description
Pointer to an ALALOG structure with the following structure
initialized to sizeof(ANALOG) prior to calling the
AlarmMessageLog function.
AlarmTime - The time of the alarm.
It is represented in the Extended time format (including
milliseconds).
TagIdx - The tag that generated the alarm or which may be
associated to the alarm itself.
ClientNbr - The number of the Client calling this function, as
returned by the ApmsApiSrvConnect.
Set to 0 (zero) if the alarm message information does not
take care of the sending Client.
AlarmProcessing - The processing applied to the message
according to the masks defined in the APMSTYPE.H file.
pAlaque
AlarmCode - The alarm classification, according to the
definitions specified into the General API description
section.
The codes are defined into the ALMPRM.H file.
AlarmGroup - The group of the alarm.
AlarmPriority - The priority of the alarm.
AudibleAlarm - The index of the audible horn that may be
associated to the alarm.
UserParam - An array of parameters, whose meaning is
specific to the application, recorded into the alarm history
file.
These parameters are used to perform specific filtering
when alarms are retrieved.
MessageText - A zero terminated character string, which
defines the text of the message that will be printed and
archived, or contains application defined data.
9AKK101130D1385 61
ApmsApiGetClientNbr Section 2 API Functions
Return Code
Value Description
R_NORMAL Success.
Internal failure in the API function.
R_FAILED
Error connecting to the Alarm Queue.
API Server failed.
R_SRVFAIL
R_QUEFULL The Alarm Message Queue is full.
ApmsApiGetClientNbr
Purpose
This function returns an information which identify the number of the client, as
defined in the server registry. This function must be called after the user application
program has connected to the API Server.
The function returns the same value as returned by the ApmsApiSrvConnect
function. It returns 0 if the ApmsApiSrvConnect has not been called yet, or if the
Server has been disconnected.
Syntax
DWORD ApmsApiGetClientNbr ( );
Parameters
None.
62 9AKK101130D1385
Section 2 API Functions ApmsApiSrvConnect
Return Code
Name Description
The number of the Client.
iOpsta
A zero value is returned if the Server was not connected.
ApmsApiSrvConnect
Purpose
This function connects the user application program to the API Server performing
the necessary initialization of the variables used to establish and to maintain the
connection with the local or the remote APMS server.
This function must be called before any other APMS API function.
This function internally call the system function CoInitialize to initialize the OLE
environment.
Avoid further calls to this function in case the application program needs to use
other OLE/COM features, unless to call it for multi-thread environment, by
requesting COINIT_MULTITHREAD.
Syntax
RETCOND API1090 ApmsApiSrvConnect
( LPTSTR szServerName, LPDWORD dwClientNbr,
LPDWORD dwReserved );
9AKK101130D1385 63
ApmsApiSrvConnect Section 2 API Functions
Parameters
Name Description
Name of the node implementing the PGP API server
functionality.
szServerName It is a Zero-terminated string.
If this parameter is NULL, the name defined in the Client
Setup Procedure is used to identify the server node.
Returned information which identify the number of the
client, as assigned by the server or defined in the server
dwClientNbr
registry. If the parameter is NULL, the function will return no
value.
dwReserved Must be NULL.
Return Code
Value Description
R_NORMAL Success.
R_NOACTIVE Successful connection, but the Server is not active.
R_INPROGRESS Successful connection; the Server is starting up.
R_SHUTDOWN Successful connection, but the Server is shutting down.
API Server failed.
R_SRVFAIL
No entry for this Client.
R_NOENTR
All licensed Clients have already been connected.
64 9AKK101130D1385
Section 2 API Functions ApmsApiSrvDisconnect
ApmsApiSrvDisconnect
Purpose
This function disconnects the user application program from the API Server,
properly terminating the communications.
This function must be called before the user application program termination.
This function internally call the system function CoUninitialize which terminates
the connections with the OLE environment.
Syntax
RETCOND ApmsApiSrvDisconnect( );
Parameters
None.
Return Code
Value Description
R_NORMAL Success. (Even if the node was not previously connected).
CheckSecurity
Purpose
CheckSecurity performs a check on the security rights of the user currently logged.
The checks are performed against the required permissions for performing a general
function.
The security privilege mask is defined in the file ApmsSecurity.h and listed in the
Table A-3 of Appendix A.
9AKK101130D1385 65
CheckTagSecurity Section 2 API Functions
Syntax
BOOL CheckSecurity
( DWORD dwOpstation, DWORD dwSecurityPriv,
int iSecurityLevel, int iSecurityGroup );
Parameters
Name Description
Client operator station number.
dwOpstation It corresponds to the number returned by the
ApmsApiSrvConnect.
Security privilege to be checked, as defined in the
dwSecurityPriv
ApmsSecurity.h file.
Level of security (0 to 16) requested to the logged user to
iSecurityLevel
perform the function.
Security group requested to the logged user to perform the
iSecurityGroup
function.
Return Code
Value Description
TRUE The privilege is granted to the user.
The privilege is not granted to the user or there was some
FALSE
failure in the Client/Server communication.
CheckTagSecurity
Purpose
CheckTagSecurity performs a check on the security right of the currently logged
user.
66 9AKK101130D1385
Section 2 API Functions CheckTagSecurity
The checks are performed against the required permissions for operating onto a tag
as defined into the tag database. The currently logged user must own the privilege
right required to perform an operation on a tag.
The privilege masks are defined in the file ApmsSecurity.h and listed in the
Table A-4 of Appendix A.
Syntax
BOOL CheckSecurity
(DWORD dwOpstation, DWORD dwSecurityPriv,
LPTAGIDX pTagIdx);
Parameters
Name Description
Client operator station number.
dwOpstation It corresponds to the number returned by the
ApmsApiSrvConnect.
dwSecurityPriv Security privilege as defined in the ApmsSecurity.h file.
Index of the tag for which the security rights must be
checked.
pTagIdx
If NULL, then the general rights of the logged user are
checked.
Return Code
TRUE The requested privilege is granted to the logged user.

The requested privilege is not granted to the user or there
FALSE
was some failure in the Client/Server communication.
9AKK101130D1385 67
ConvertFromApmsTimeEx Section 2 API Functions
ConvertFromApmsTimeEx
Purpose
The routine computes time and date values starting from a given PGP Extended
Time (number of seconds since midnight 12/31/1990 and milliseconds).
The conversion is performed in such a way that the result is adjusted for Day Light
Saving Time periods. Assuming that the supplied information is a wall clock time
(subject to Day Light Saving Time compensation) and that the returned information
is an internal 1090 Time (not subject to DST), this function subtracts one hour to the
result during summer periods.
The definition of “summer” and “winter” periods can be configured, during the off-
line system build procedures, using the information contained in the
BDSTDECK.XML file.
Syntax
RETCOND ConvertFromApmsTimeEx
( LPEXTIME pExtime,
LPDWORD dwYear, LPDWORD dwMonth, LPDWORD dwDay,
LPDWORD dwHour, LPDWORD dwMinute, LPDWORD dwSecond,
LPDWORD dwMillisecond );
Parameters
Name Description
Pointer to a EXTIME structure, which defines the time as
dwTime - Seconds since midnight 12/31/1990.
pExtime
dwMilsec - Milliseconds since the last second.
This is the input value.
68 9AKK101130D1385
Section 2 API Functions ConvertToApmsTimeEx
Name Description
dwYear,
dwMonth,
dwDay,
Time and date information that has been converted.
dwHour,
These are the returned values.
dwMinute,
dwSecond,
dwMillisecond
Return Code
Value Description
R_NORMAL Success.
API Server failed.
R_SRVFAIL
ConvertToApmsTimeEx
Purpose
The routine compute the PGP Extended Time (number of seconds since midnight
12/31/1990 and milliseconds) given the specified time and date values.
The conversion is performed in such a way that the result is adjusted for Day Light
Saving Time periods. Assuming that the supplied information is a wall clock time
(subject to Day Light Saving Time compensation) and that the returned information
is an internal Apms Time (not subject to DST), this function subtracts one hour to
the result during summer periods.
BDSTDECK.XML file.
9AKK101130D1385 69
ConvertToApmsTimeEx Section 2 API Functions
Syntax
RETCOND ConvertToApmsTimeEx
( LPEXTIME pExtime,
DWORD dwYear, DWORD dwMonth, DWORD dwDay,
DWORD dwHour, DWORD dwMinute, DWORD dwSecond,
DWORD dwMillisecond );
Parameters
Name Description
Pointer to a EXTIME structure, which defines the time as
dwTime - Seconds since midnight 12/31/1990.
pExtime
This is the returned value.
DwYear,
dwMonth,
dwDay, Represent the time and date information that must be
dwHour, converted.
dwMinute, These are the input values.
dwSecond,
dwMillisecond
Return Code
Value Description
R_NORMAL Success.
Invalid time (some of the input parameters are not
R_INVTIM compliant with the time definition or the converted time is
previous to 1/1/1991).
70 9AKK101130D1385
Section 2 API Functions FileLock
Value Description
API Server failed.
R_SRVFAIL
FileLock
Purpose
FileLock locks the accesses to a file defined within the PGP Direct Access File
System to prevent the concurrent usage by different application programs.
The file is locked for write and read accesses. The usage of the file is allowed only
to the process that has locked the file.
The application program must take care of releasing the file by the FileUnlock
function. Otherwise, the file becomes unusable to other processes. Keeping a file
locked indefinitely may seriously compromise the normal operation of the whole
system.
Syntax
RETCOND FileLock ( LPFILEIDX pFileIdx, LPDWORD dwCookie );
Parameters
Name Description
Pointer to a structure defining the file
pFileIdx num - The index of the file as defined in FILPRM.INS.
node - The node which implements the file.
dwCookie Not used. (Reserved for future use).
Return Code
Value Description
R_NORMAL Success.
9AKK101130D1385 71
FileRead Section 2 API Functions
Value Description
R_INVKEY Invalid file key (the file does not exist).
API Server failed.
R_SRVFAIL
FileRead
Purpose
FileRead reads consecutive records from a file defined within the PGP Direct
Access File System.
The file is locked during the read access.
Syntax
RETCOND FileRead
(LPFILEIDX pFileIdx,
DWORD dwRecord, DWORD dwNumRecords,
LPVOID pBuffer, DWORD dwSize );
Parameters
Name Description
dwRecord The first record to be accessed.
The number of consecutive records to be accessed within
dwNumRecords
file.
Pointer to the buffer that receives the read information.
pBuffer The user application program must allocate a buffer to fit all
the required records.
72 9AKK101130D1385
Section 2 API Functions FileUnlock
Name Description
The size of the requested information, in bytes.
dwSize It must correspond to the sizeof(RECORD) multiplied by
the number of records.
Return Code
Value Description
R_NORMAL Success.
Invalid record (the first record to access is outside the
R_INVREC
records in the file).
Invalid number of records (some of the records to access is
R_INVNREC
outside the records in the file).
Invalid record size (the size of the buffer is not enough
R_INVRSIZ
large to contain all the requested records).
R_RMSERR Error accessing the file on the disk.
API Server failed.
R_SRVFAIL
FileUnlock
FileUnlock releases a previous lock to a file defined within the PGP Direct Access
File System. It allows again the concurrent usage of file by different application
programs.
After unlocking, any other process or thread within the system has write and read
access to the file.
The function does not check if the calling process has previously locked the file.
Syntax
RETCOND FileUnlock ( LPFILEIDX pFileIdx, DWORD dwCookie );
9AKK101130D1385 73
FileWrite Section 2 API Functions
Parameters
Name Description
dwCookie Not used. (Reserved for future use).
Return Code
Value Description
R_NORMAL Success.
API Server failed.
R_SRVFAIL
FileWrite
Purpose
FileWrite writes consecutive records to a file defined within the PGP Direct Access
File System. Data to be written are allocated within an array of record structures.
The file is locked during the write access and is unlocked when the operation
completes.
Syntax
RETCOND FileWrite
( LPFILEIDX pFileIdx,
LPVOID lpBuffer, DWORD dwSize );
74 9AKK101130D1385
Section 2 API Functions FileWrite
Parameters
Name Description
dwNumRecords
file.
Pointer to the buffer that contains the information to be
written on file.
pBuffer
The user application program must allocate a buffer
properly sized to allocate all the required records.
The size, in bytes, of the supplied information.
Return Code
Value Description
R_NORMAL Success.
R_INVREC
R_INVNREC
Invalid record size (the size of the buffer is not enough to
R_INVRSIZ
contain all the requested records).
API Server failed.
R_SRVFAIL
9AKK101130D1385 75
FileWriteEx Section 2 API Functions
FileWriteEx
Purpose
FileWriteEx writes consecutive records to a file defined within the PGP Direct
Access File System. Data to be written are allocated within an array of record
structures.
Additional processing may be requested by specifying an appropriate option mask.
completes.
Syntax
RETCOND FileWrite
LPVOID lpBuffer, DWORD dwSize,
DWORD dwOptions );
Parameters
Name Description
dwNumRecords
file.
Pointer to the buffer that contains the information to be
pBuffer written on file. The user application program must allocate
a buffer properly sized to allocate all the required records.
76 9AKK101130D1385
Section 2 API Functions GetAlacMessage
Name Description
The size, in bytes, of the supplied information.
Additional processing mask.
It may contain an ORed combination of the following bits
dwOptions FILEWRITE_SPECIFIC_APPL - A user written function that
performs post-processing is activated.
FILEWRITE_EXPORT_DB - The information buffer is
exported to an external database as BLOB data.
Return Code
Value Description
R_NORMAL Success.
R_INVREC
R_INVNREC
Invalid record size (the size of the buffer is not enough to
R_INVRSIZ
contain all the requested records).
API Server failed.
R_SRVFAIL
GetAlacMessage
Purpose
GetAlacMessage retrieves the oldest alarm action entry for the referenced alarm
action program from the alarm action queue.
9AKK101130D1385 77
GetAlacMessage Section 2 API Functions
If an alarm action entry for the referenced alarm action program is not currently
queued in the alarm action queue, the function will hibernate in a wait status waiting
for an incoming message. So, the user application program will also wait for a
message. A tag going into an alarm condition and triggering the corresponding
program will resume the waiting condition.
The wait condition can be asynchronously terminated by a call to the
ReleaseAlarmAction function. Another thread or another user application program
must issue such a function call.
See also the corresponding PeekAlacMessage function, which does not wait for a
message becoming available.
Syntax
RETCOND GetAlacMessage
( DWORD dwProgramNbr, LPALAC pAlac );
Parameters
Name Description
Number of the Alarm Action Program, within the range 1 to
dwProgramNbr
63, requesting the Alac message.
78 9AKK101130D1385
Section 2 API Functions GetAlacMessage
Name Description
Pointer to the returned ALAC structure, which has the
following fields
initialized to sizeof(ALAC) prior to calling the
GetAlacMessage function.
TagIdx - The tag that generated the alarm and triggered the
Action Program.
pAlac
TagVal - The value, quality and time stamp of the tag that
generated the alarm.
dwProgramNbr - The number of associated Action
Program.
wPrevDiVal - The previous value of tag (valid only for
Digital Input tags).
dwPrevDiQual - The previous quality of the tag (valid only
for Digital Input tags).
Return Code
Value Description
R_NORMAL Success.
Invalid Program number (the Action Program number is
R_INVPGM
outside the range 1 to 63).
The operation was aborted by the ReleaseAlacMessage
R_ABORTED
function.
No entries for this program were found in the Alarm Action
R_NOENTR
Queue.
API Server failed.
R_SRVFAIL
9AKK101130D1385 79
GetApmsInfo Section 2 API Functions
GetApmsInfo
Purpose
This function retrieves the definition of some parameters, which are used internally
by the PGP. Some parameters refers to “static” characteristics, such as sizes and
maximum allowed values. Other parameters refer to “dynamic” information related
to the status of different components of the system.
Syntax
DWORD GetApmsInfo ( APMSINFOTYPE dwWhat );
Parameters
Name Description
The requested parameter.
dwWhat The list of parameters is defined in the previous section of
this manual concerning the general presentation of this API
function.
Return Code
Name Description
Value of the requested information.
iValue In case of any error (invalid parameter requested or failure
in communication with the Server) the returned value will
be 0 (zero).
80 9AKK101130D1385
Section 2 API Functions GetApmsTime
GetApmsTime
Purpose
This routine retrieves the value of current PGP time, which corresponds to the
number of seconds since January 1st 1991.
The PGP time internally is not adjusted for daylight saving time compensation, that
means it is a value continuously growing.
Syntax
TIME1090 GetApmsTime ( );
Parameters
None.
Return Code
Name Description
Current PGP time, in the simplified format.
iTime In case of any error (such as a failure in communications
with the PGP server) the returned value will be 0 (zero).
GetApmsTimeEx
Purpose
This routine retrieves the value of current PGP time, in extended format that
corresponds to the number of seconds since January 1st 1991 and to the number of
milliseconds since the current second.
While the millisecond information is set to 0 in the PGP, the usage of this extended
time format is suggested for compatibility with the tag time stamp. The time
conversion routines use this time format instead of the plain time format.
9AKK101130D1385 81
GetApmsTimeString Section 2 API Functions
The PGP time is not internally adjusted for daylight saving time compensation that
means it is a value continuously growing.
Syntax
RETCOND API1090 GetApmsTimeEx ( LPEXTIME pExtime );
Parameters
Name Description
Returned value of current PGP time, in the extended format
dwTime - Seconds since 1/1/1991.
pExtime
dwMilsec - Milliseconds since the last second (PGP
releases before 1.2 sets this field to zero).
Return Code
Value Description
R_NORMAL Success.
API Server failed.
R_SRVFAIL
GetApmsTimeString
Purpose
This function converts a time value in Extended time format (seconds since Jan. 1,
1991 and milliseconds) and returns the local time and date in ASCII format for
display and print purposes. The function provides several possibilities of formatting
the string.
Adjustment for Daylight Saving Time is provided by this routine, i.e. during
summer time one hour is added to the provided time value.
82 9AKK101130D1385
Section 2 API Functions GetApmsTimeString
In case a time value is not supplied to this function, the function returns the current
PGP time converted into an ASCII string.
Syntax
RETCOND GetApmsTimeString
( LPEXTIME pExtime, LPTSTR szApmsTime, DWORD dwFormat );
Parameters
Name Description
Pointer to a structure defining the PGP time to be
converted, in the extended format
dwTime - Seconds since 1/1/1991.
pExtime
dwmilsec - Milliseconds since the last second.
If this value is set to NULL, then the current APMS time will
be converted.
The returned, zero terminated, character string containing
the result of the conversion.
szApmsTime
The Application Program must allocate a string sized to fit
the formatted time/date.
9AKK101130D1385 83
GetApmsTimeString Section 2 API Functions
Name Description
Type of required conversion according to the following
definition
TIMEFRMT_SHORT -
Convert time to DD.MM.YY HH:MM:SS.CCC.
TIMEFRMT_STD -
Convert time to DD MMM YYYY HH:MM:SS.CCC.
TIMEFRMT_WEEK -
Convert time to WWW DD MMM YYYY HH:MM:SS.
TIMEFRMT_LONGWEEK -
Convert time to WWWWWWWWW DD MMM YYYY
HH:MM:SS.
The following values may be ORed to the dwFormat above
to better specify the result of the conversion
dwFormat TIMEFRMT_EXCLUDE_MIL -
Exclude the milliseconds from the output string.
TIMEFRMT_EXCLUDE_DATE -
Exclude the date from the output string.
TIMEFRMT_EXCLUDE_TIME -
Exclude the time from the output string.
The following values may be ORed to the dwFormat above
to specify the language used in the conversion
TIMEFRMT_STD_LANGUAGE -
Translate the date/time in English.
TIMEFRMT_NATIONAL_LANGUAGE -
Translate the date/time to the National Language.
If none of the previous values was set, the language
selected on the Server is used for the translation.
84 9AKK101130D1385
Section 2 API Functions GetFileFinfo
Return Code
Value Description
R_NORMAL Success.
API Server failed.
R_SRVFAIL
GetFileFinfo
Purpose
GetFileInfo retrieves essential file information for a file defined in the PGP Direct
Access File System. This routine is mainly used to check if a file exists and to
retrieve information used for subsequent file access functions, while GetFileInfoEx
provides complete information on the file.
Syntax
RETCOND GetFileInfo
LPDWORD dwRecordSize, LPDWORD dwNumRecords );
Parameters
Name Description
Pointer to a structure defining the file for which the
information is required
pFileIdx
num - The index of the file as defined in FILPRM.INS.
The returned size of the record, in WORD.
dwRecordSize This value corresponds to the value of sizeof(RECORD)
divided by 2.
9AKK101130D1385 85
GetFileInfoEx Section 2 API Functions
Name Description
dwNumRecords The returned number of records of the file.
Return Code
Value Description
R_NORMAL Success.
API Server failed.
R_SRVFAIL
GetFileInfoEx
Purpose
GetFileInfoEx retrieves file information for a file defined in the PGP Direct Access
File System. This function provides a complete information on file characteristics.
Syntax
RETCOND GetFileInfoEx
( LPFILEIDX pFileIdx, LPFILEINFO pFileInfo );
Parameters
Name Description
Pointer to a structure defining the file for which the
information is required
pFileIdx
num - The index of the file as defined in FILPRM.INS.
86 9AKK101130D1385
Section 2 API Functions GetFileInfoEx
Name Description
Pointer to the returned FILEINFO structure, which fields are
as follow
initialized to size of (FILEINFO) prior to calling this function.
key - File key.
typ - File type.
nrc - Number of records.
sym - File symbolic name.
rsz - Record size.
pFileInfo pof - Page offset.
wof - Word offset.
cmn - Common name.
flg - Backup flags.
clb - Offset for common call-back.
lok - Backup flag/lock bit.
pid - Owner process pid.
rdcnt - File read counter.
wrcnt - File write counter.
nam - File name.
dsc - File description.
Return Code
Value Description
R_NORMAL Success.
API Server failed.
R_SRVFAIL
9AKK101130D1385 87
GetHistoricData Section 2 API Functions
GetHistoricData
Purpose
This function is used to read the data from the Historical Database (which is
maintained on a disk of the Server), into a buffer which is local to the User
Application Program. This is the most time consuming function, because the values
are searched through all the archive and organized in a buffer, which is allocated
into the Client process.
The retrieved data is then made available to the caller by using the
ReadHistoricValue routine. This routine must be called until there are available
data, in order to free all the allocated packets for the local buffer and to properly
release the memory.
Syntax
RETCOND GetHistoricData
( HDBTYPE hdbType, LPTAGIDX pGrpIdx,
DWORD dwItemCount, LPTAGIDX pTagIdx,
TIME1090 tStartTime, TIME1090 tEndTime,
TIME1090 tTripTime, DWORD dwFrequency,
DWORD dwOptions, LPHISTDPT pHistDpt,
LPHISTPROGRESS pProgress );
Parameters
Name Description
hdbType Identification of the Historical Database.
Pointer to a structure defining the historical group.
pGrpIdx The type of this structure is similar to the one defining the
tags.
dwItemCount Number of entries in the pTagIdx list.
88 9AKK101130D1385
Section 2 API Functions GetHistoricData
Name Description
Pointer to an array of indexes for which values are to be
pTagIdx returned.
Each index is defined as a structure TAGIDX.
Initial time for data retrieval.
tStarTime If this time is prior to the first valid data into the archive,
then the first valid data is returned.
Final time for data retrieval.
tEndTime If this time is following the last valid data into the archive,
then the last valid data is returned.
Time of the trip, valid only for Post Trip Log archives.
tTripTime This field is ignored when other historical archives are
accessed.
Sampling frequency.
Interval, in seconds, used to sample the data. This field is
dwFrequency significant only when accessing the Playback (Current and
Frozen) and the Post-Trip Log archives. For any other
archive the sample recording frequency is used to retrieve
the data.
Retrieval option.
The following options can be selected
HDB_NONE - Perform standard retrieval.
dwOptions HDB_SAMPLE - Get sampled data (otherwise get native
exceptions).
HDB_INTERPOLATE - Interpolate values (valid only during
the access to current Playback archive).
Returned buffer of values.
pHistDpt The allocation of this buffer is made in the dynamic
memory.
pProgress Reserved. Must be NULL.
9AKK101130D1385 89
GetTagIdx Section 2 API Functions
Return Code
Value Description
R_NORMAL Success.
R_NODATA No data was retrieved.
The Server was not able to allocate the memory to retrieve
R_OUTOFMEM
the data.
R_INVPARAM Invalid parameter specified in the dwOption field.
R_FAILED Invalid Historical Database or internal failure in the function.
API Server failed.
R_SRVFAIL
GetTagIdx
Purpose
This function retrieves the Tag Identification Numbers (internal TAGIDX structure)
starting from an ASCII string, which corresponds to the name of a tag.
The function is the main entry point for converting information as known by the end
user (tag names) to information used by all API functions (TAGIDX structure).
Syntax
RETCOND GetTagIdx ( LPCTSTR szTagName, LPTAGIDX pTagIdx );
90 9AKK101130D1385
Section 2 API Functions GetTagIdxFromIndex
Parameters
Name Description
Pointer to the returned structure defining the internal Tag
Index, which correspond to the given name
pTagIdx num - The index of the tag, into the specific Database.
hnm - The Database type of the tag (Analog/Digital).
node - The node which implements the tag.
Name of the tag identified by a zero-terminated character
string.
szTagName Tag names may have a maximum of SZNAM characters.
Currently the parameter SZNAM is defined in
SYSPRM.INS as 20.
Return Code
Value Description
R_NORMAL Success.
R_INVTAG Invalid tag (tag does not exist).
Undefined tag (the tag name was defined as a number
R_UNDTAG
which does not correspond to any TagIndex).
API Server failed.
R_SRVFAIL
GetTagIdxFromIndex
Purpose
This function retrieves the Tag Identification Numbers (internal TAGIDX structure)
starting from a number, which correspond to the TAGINDEX Database field.
The TAGIDX number, used by the API, is not the same as the TAGINDEX field in
the tag Database.
9AKK101130D1385 91
GetTagInfo Section 2 API Functions
Syntax
RETCOND API1090 GetTagIdxFromIndex
( DWORD dwTagindex, LPTAGIDX pTagIdx );
Parameters
Name Description
Pointer to the returned structure defining the internal Tag
Index, which correspond to the given name
hnm - The database type of the tag (Analog/Digital).
Index of the tag as defined in the TAGINDEX field of the tag
dwTagindex
Database.
Return Code
Value Description
R_NORMAL Success.
API Server failed.
R_SRVFAIL
GetTagInfo
Purpose
This function retrieves various parameters from the tag Database. A parameter at a
time is retrieved for a certain tag. The result is returned to the caller into a structure
that is an union of various fields. According to the required parameter the caller will
select the appropriate field.
92 9AKK101130D1385
Section 2 API Functions GetTagInfo
The naming of the fields of the structure corresponds to the naming of the fields into
the PGP Database Configuration manual.
Syntax
RETCOND API1090 GetTagInfo
( LPTAGIDX pTagIdx, TAGINFOTYPE dwWhat,
LPTAGINFO pTagInfo );
Parameters
Name Description
Pointer to the structure defining the internal Tag Index, for
which correspond to the information is requested
hnm - The database type of the tag (Analog/Digital).
Requested information specification as defined by
dwWhat
TAGINFOTYPE enumeration.
Pointer to the returned structure which contains the
selected information. According to the type of information
requested, the result may be obtained in the field
iValue - Used to contain numerical and boolean data.
rValue - Used to contain floating point numbers.
pTagInfo
tValue - Used to contain time.
totValue - Used to contain totalized values.
tagidx - Used to contain tag indexes.
szValue - Used to contain zero terminated character
strings.
9AKK101130D1385 93
IsNationalLanguage Section 2 API Functions
Return Code
Value Description
R_NORMAL Success.
Invalid parameter.
R_INVPARAM The requested information does not correspond to an
internal supported code or cannot be retrieved for that type
of the tag.
API Server failed.
R_SRVFAIL
IsNationalLanguage
Purpose
This function checks the language selected on a particular client for the logged user,
and return TRUE if a national language has been selected of FALSE if English has
been selected fro the currently logged user.
The function provides additional support for the language translation; however the
MultiLanguage function described in the following detects by itself which kind of
language has been selected.
The Human-Machine Interface language may be selected on each client by setting
the Regional and Language Option from the Windows Control Panel.
The prototype of this function is defined in the header file MULTILANGUAGE.H
Syntax
BOOL IsNationalLanguage ( );
Parameters
None.
94 9AKK101130D1385
Section 2 API Functions MessageErrorLog
Return Code
Name Description
Boolean value specifying if the national language has been
selected on the particular client.
bValue
If the selected language is English the returned value is
FALSE.
MessageErrorLog
Purpose
This function writes an application message into the system Error Log Message
File.
The file is located under the directory whose name is defined by the
HKEY_LOCAL_MACHINE\SOFTWARE\ABB\Power Generation
Portal\Directories\Logs.
registry. It is set by default to \Power Generation Portal\Logs. The name of the file
is ErrorLog.txt.
The MessageErrorLog function appends the application message to the end of the
error log file and time-stamps the message with the current time.
Syntax
RETCOND MessageErrorLog
( LPTSTR lpszProcessName, LPTSTR lpszMessageText );
Parameters
Name Description
Pointer to a character string which contains the name of the
lpszProcessName
application process.
9AKK101130D1385 95
MultiLanguage Section 2 API Functions
Name Description
Pointer to a character string which contains the message to
lpswMessageText
be logged.
Return Code
Value Description
R_NORMAL Success.
R_FAILED Error writing in the Error Log file.
API Server failed.
R_SRVFAIL
MultiLanguage
Purpose
This function translates an English text message to the national language selected on
the client. PGP uses this function before the presentation of messages, texts and
menu items on the screen.
System messages, in English and in the national languages, are defined in the
BLANGDECK.XML file. Application specific messages can be defined (with the
same syntax) in the BLANG2DECK.XML file.
the Regional and Language Option from the Windows Control Panel.
In case the Language is set to ENGLISH then the translation is not performed and
the returned string is the same as the input string. If the string to be translated is not
found in the dictionary the returned string is the original English string.
The prototype of this function is defined in the header file MULTILANGUAGE.H.
Syntax
LPTSTR MultiLanguage
96 9AKK101130D1385
Section 2 API Functions PeekAlacMessage
( LPCTSTR lpszToBeTranslated, BOOL bForceTranslation );
Parameters
Name Description
Pointer to a character string defining the English text of the
lpszToBeTranslated
message.
Flag specifying if the translation must be performed even if
bForceTranslation the national language is not selected on the particular
client.
Return Code
Name Description
Pointer to a character string translated.
Pointer No error is generated if the string does not exist in the
dictionary. The original English string is returned
PeekAlacMessage
Purpose
PeekAlacMessage retrieves the oldest alarm action entry for the referenced alarm
action program from the alarm action queue.
queued in the alarm action queue, the function returns an error code.
See also the corresponding GetAlacMessage function, which waits for a message
becoming available in the alarm action queue.
Syntax
RETCOND PeekAlacMessage
( DWORD dwProgramNbr, LPALAC pAlac );
9AKK101130D1385 97
PeekAlacMessage Section 2 API Functions
Parameters
Name Description
Number of Alarm Action Program, within the range 1 to 63,
dwProgramNbr
requesting the Alac message.
Represents the pointer to the returned ALAC structure,
which have the following fields
cbSize - The size of the structure. It acts as a protection for
version changes. It must be initialized to sizeof(ALAC) prior
to calling the GetAlacMessageQ function.
TagIdx - The tag that generated the alarm and triggered the
Action Program.
pAlac TagVal - The value, quality and time stamp of the tag that
generated the alarm.
dwProgramNbr - The number of associated Action
Program.
wPrevDiVal - The previous value of tag (valid only for
Digital Input tags).
dwPrevDiQual - The previous quality of the tag (valid only
for Digital Input tags).
Return Code
Value Description
R_NORMAL Success.
R_NOACTIVE ThePGP Server is not active.
R_INVPGM
No entries for this program were found in the Alarm Action
R_NOENTR
Queue.
API Server failed.
R_SRVFAIL
98 9AKK101130D1385
Section 2 API Functions ReadHistoricValue
ReadHistoricValue
Purpose
This function is used to retrieve the values previously read from an historical
database into a local buffer of the Client process.
Typically, it is used within a loop structure after the successful completion of the
GetHistoricData function.
The function de-queues from the historical buffer provided by GetHistoricData, one
sample at a time, for a tag defined in the tag list. The function must be called as
many times as necessary to de-queue all the data retrieved and to properly free the
memory allocated to read the data.
The function must be called until it returns R_NORMAL in order to be sure that all
the memory buffers are released. Otherwise, there will be allocated memory not
released. That may cause serious problems to the whole system.
Syntax
RETCOND ReadHistoricValue
( HDBTYPE hdbType, LPTAGVALEX pTagValue,
DWORD dwOptions, LPHISTDPT pHistDpt );
Parameters
Name Description
hdbType Identification of the Historical Database.
Pointer to a TAGVALEX structures where values are
pTagValue
returned.
dwOptions Retrieval options.
pHistDpt Pointer to the data buffer on which the data is stored.
9AKK101130D1385 99
ReleaseAlarmAction Section 2 API Functions
Return Code
Value Description
R_NORMAL Success.
R_OUTOFMEM
the data.
API Server failed.
R_SRVFAIL
ReleaseAlarmAction
Purpose
This function is necessary to terminate the call to the GetAlacMessage, which may
stay forever waiting for alarms.
Since a call to the GetAlarmAction function locks indefinitely the calling thread, the
release function must be posted by a different thread or by another program.
Syntax
RETCOND ReleaseAlarmAction ( DWORD dwProgramNbr );
Parameters
Name Description
Number of Alarm Action Program, within the range 1 to 63,
dwProgramNbr for which is requested to release an outstanding
GetAlacMessage call.
100 9AKK101130D1385
Section 2 API Functions SetApmsInfo
Return Code
Value Description
R_NORMAL Success.
R_INVPGM
API Server failed.
R_SRVFAIL
SetApmsInfo
Purpose
This routine changes the definition of some parameters that are used internally by
the PGP.
The routine does not perform any validation, checking and logging. The user
application program may impact the running programs. Settings performed by the
user application program remains in effect until the PGP shuts down. The PGP start-
up procedure (ADAM) will set again the parameters as defined in the registry file.
Syntax
RETCOND API1090 SetApmsInfo
(APMSINFOTYPE dwWhat, DWORD dwInfo );
9AKK101130D1385 101
SetApmsTimeEx Section 2 API Functions
Parameters
Name Description
Requested parameter as specified in the APMSINFOTYPE
enumeration.
dwWhat
Refer to the general description of this API for a list of the
parameters.
dwInfo The value of the parameter to set.
Return Code
Value Description
R_NORMAL Success.
Invalid parameter.
R_INVPARAM The parameter requested does not correspond to the
internal codes or the value cannot be set.
API Server failed.
R_SRVFAIL
SetApmsTimeEx
Purpose
This function sets the time of the Operating System. Setting is then automatically
propagated to the internal PGP time and, if so configured, to the C-NET (for
INFINET based systems).
The time provided to this function is intended to be independent from Day Light
Saving Time compensation.
The Windows user logged in needs to have special privileges, in order to force the
Operating System time to change.
102 9AKK101130D1385
Section 2 API Functions SetTagInfo
Syntax
RETCOND API1090 SetApmsTimeEx ( LPEXTIME pExtime );
Parameters
Name Description
New APMS time in the extended format
pExtime dwTime - Seconds since 1/1/1991.
Return Code
Value Description
R_NORMAL Success.
R_INVTIM Invalid time specified, or failure in setting the system time.
API Server failed.
R_SRVFAIL
SetTagInfo
Purpose
This routine allows writing various parameters from the tag Database. A parameter
at a time can be written for a certain tag. The parameter is fetched from a structure
that is a union of various fields.
According to the required parameter the caller select the appropriate field.
The naming of fields in the structure corresponds to the naming of fields listed in the
PGP Database Configuration manual.
9AKK101130D1385 103
SetTagInfo Section 2 API Functions
Currently only the main Database fields are supported and handled by this function.
This function does not perform any validation of the parameters and does not log the
modifications. Invalid parameters passed to the function may invalidate the
consistency of the Database.
Syntax
RETCOND API1090 SetTagInfo
( LPTAGIDX pTagIdx, TAGINFOTYPE dwWhat,
LPTAGINFO pTagInfo, DWORD dwOption );
Parameters
Name Description
Pointer to the structure defining the internal Tag Index, for
which correspond to the information is supplied
hnm - The type of the tag (Analog/Digital).
Supplied information as defined by TAGINFOTYPE
enumeration.
dwWhat
Refer to the general description of this API for a list of
available parameters.
Pointer to the structure which contains the supplied
information. According to the type of information requested,
the data may be defined in the field
iValue - Used to contain numerical and boolean data.
rValue - Used to contain floating point numbers.
pTagInfo
tValue - Used to contain time.
totValue - Used to contain totalized values.
tagidx - Used to contain tag indexes.
szValue - Used to contain zero terminated character
strings.
104 9AKK101130D1385
Section 2 API Functions TagListRead
Name Description
The option allows running a specific application function
after the write action has completed.
0 - Normal tag write without any specific function activation.
dwOption
SETTAGINFO-SPECIFICAPPL -
A specific application function is called after the tag write
completes.
Return Code
Value Description
R_NORMAL Success.
Invalid parameter.
R_INVPARAM The requested information does not correspond to an
internal supported code or cannot be set for that type of the
tag.
API Server failed.
R_SRVFAIL
TagListRead
Purpose
TagListRead is used to access the memory resident Realtime Database for a list of
Process Variables (PVs) and Digital Inputs (DIs).
The function returns the dynamic data for a list of tag identification indexes. The
returned data are the live values of the tags. The values are returned in the data
structure that contains the union of several different point types and the appropriate
union member must be selected based on the TAGVALEX member type.
Values that originate in the field or by Calculation programs may have bad quality
that could result in an unreliable value. This can be detected by checking the
9AKK101130D1385 105
TagListRead Section 2 API Functions
TAGVALEX member Quality. The Quality element also provides information about
alarms.
Furthermore, the function also returns the time stamp of each variable. This time
information is referred to the time when the value of the tag was changed (tags
coming from the field) or was updated into the Database (internally generated tags).
Syntax
RETCOND API1090 TagListRead
( DWORD dwItemCount, LPTAGIDX pTagIdx,
LPTAGVALEX pTagValue );
Parameters
Name Description
dwItemCount The counter of the tags contained in the list.
Pointer to an array of the structure defining the list of Tag
Index
Pointer to the returned array of structure which contains the
read Data. For each tag the data will contain
Valbuf - The value formatted according to the point type.
It can be floating point or integer for Process Variable tags
pTagValue or bit map for Digital Input Tags.
Qual - The quality of the tag.
Time - The field used to allocate the time stamp.
Tagtype - The type of the tag according to the TAGTYPE
field of the Database.
106 9AKK101130D1385
Section 2 API Functions TagListWrite
Return Code
Value Description
R_NORMAL Success.
R_NOACTIVE The PGP server is not active.
R_FAILED The function failed for some of the tags.
API Server failed.
R_SRVFAIL
TagListWrite
Purpose
TagListWrite is used to access the Realtime Database for a list of tags, which may
be either Process Variables (PVs) or Digital Inputs (DIs).
The function writes the dynamic data for a list of tag identification indexes. These
values become the live values of tags. The values are written into the data structure
TAGVALEX that contains the union of several different point types and the
appropriate union member must be selected based on the TAGVALEX member
type.
There are mainly two alternatives offered by this function, which are selected by the
Option parameter.
The standard processing is done in such a way the standard PGP Data Input
Processor processes data to be written into the Realtime Database. This program
provides data validation and alarm limit checking and it is able to generate alarm
messages and to initiate any necessary action.
With the second possibility, the user application program directly writes the value
into the Realtime Database without passing through the standard input processing.
The user application program must perform validation and alarm limit checking and
to generate the proper quality settings for the tag before writing it into the Database.
9AKK101130D1385 107
TagListWrite Section 2 API Functions
Data written in the Database is also queued to the playback historical archive, but
cannot generate any alarm message or trigger any other program.
The function also sets the time stamp of the tag according to the information
contained into the TAGVALEX structure.
Syntax
RETCOND API1090 TagListWrite
( DWORD dwItemCount, LPTAGIDX pTagIdx,
LPTAGVALEX pTagValue, DWORD dwOption );
Parameters
Name Description
dwItemCount Number of tags in the tag list.
Pointer to an array of the structure defining the list of tag
indexes
Pointer to the array of structures which contains the read
Data. For each tag the data will contain
Mode for writing data in the Database.
dwOption Refer to the TagWrite function for a description of this
parameter.
108 9AKK101130D1385
Section 2 API Functions TagRead
Return Code
Value Description
R_NORMAL Success.
R_FAILED The function failed for some of the tags.
API Server failed.
R_SRVFAIL
TagRead
Purpose
TagRead is used to access the Realtime Database for a tag, which may be a Process
Variable (PV) or Digital Input (DI).
The routine returns the dynamic data for a tag identification index. The returned
data is the live value of the tag. The value is returned in the data structure that
contains the union of several different point types and the appropriate union
member must be selected based on the TAGVALEX member type.
Values that originate in the field modules or by Calculation programs may have bad
quality that could result in an unreliable value. This can be detected by checking the
TAGVAL member Quality. The Quality element also provides information about
alarms.
Furthermore, the function also returns the time stamp of the variable. This time
coming from the field) or was updated into the Database (internally generated tags).
Syntax
RETCOND API1090 TagRead
( LPTAGIDX pTagIdx, LPTAGVALEX pTagValue );
9AKK101130D1385 109
TagReadString Section 2 API Functions
Parameters
Name Description
Pointer to a structure defining the internal tag index
num - The index of the tag, into the specific Database.
pTagIdx
Pointer to the returned structure which contains the read
data. The data will contain
Return Code
Value Description
R_NORMAL Success.
API Server failed.
R_SRVFAIL
TagReadString
Purpose
This routine converts the value of a tag into a string of character formatted for
standard PV and DI display or print purposes.
110 9AKK101130D1385
Section 2 API Functions TagReadString
Values are formatted in the most suitable way for the tag. PV values can be
formatted either in Real or Integer format (depending on the configuration setting).
DI values are formatted using the status descriptor string defined for the tag.
Furthermore, the function generates a 2-character status quality descriptor string
which is appended to the value and a string which contains the formatted time
stamp. Several formats can be chosen to format the time information.
Syntax
RETCOND API1090 TagReadString
( LPTAGIDX pTagIdx, LPTAGVALEX pTagValue,
LPTSTR szValue, LPTSTR szQuality,
LPTSTR szTime, DWORD dwFormat );
Parameters
Name Description
Pointer to a structure defining the internal of tag index
pTagIdx
Pointer to the structure which contains the data. The data
will contain
9AKK101130D1385 111
TagWrite Section 2 API Functions
Name Description
Returned zero-terminated character string which contains
the formatted value.
szValue
The User Application Programs must allocate a string at
least 15 characters long.
the formatted quality.
szQuality
The User Application Programs must allocate a string at
least 3 characters long.
the formatted time stamp.
szTime The User Application Programs must allocate a string
properly sized to fit the time as specified by the dwFormat
conversion option.
Time stamp conversion option.
dwFormat
Refer to GetApmsTimeString for possible options.
Return Code
Value Description
R_NORMAL Success.
API Server failed.
R_SRVFAIL
TagWrite
Purpose
TagWrite is used to access the Realtime Database for a tag, which may be either a
Process Variable (PV) or Digital Input (DI).
112 9AKK101130D1385
Section 2 API Functions TagWrite
The function writes the dynamic data for a tag identification index. This value
becomes the live value of the tag. The value is written into the data structure
type.
Option parameter.
to generate the proper quality for the tag before writing it into the Database. Data
written in the Database is also queued to the playback historical archive, but cannot
generate any alarm message or trigger any other program.
Syntax
RETCOND API1090 TagWrite
( LPTAGIDX pTagIdx, LPTAGVALEX pTagValue,
DWORD dwOption );
Parameters
Name Description
Pointer to a structure defining the internal of tag index
pTagIdx
9AKK101130D1385 113
TagWrite Section 2 API Functions
Name Description
Pointer to the structure which contains the data to write into
the Database. The data will contain
Writing mode of data in the Database
TAGWRITE_STD - Standard processing, the value is
queued to the Data Input Processor.
TAGWRITE_DIRECT- Directly update value, quality and
time stamp into the Realtime Database.
TAGWRITE_WRITEONDISK - Update the value into the
Realtime Database and update the value of the tag kept on
dwOption the disk. This disk value will be used as ‘initial value’ at next
PGP restart.
TAGWRITE_SPECIFICAPPL - Trigger an application
specific function.
TAGWRITE_USEDST - Use Daylight Saving Time
compensation in the time stamp definition. Normally the
time stamp PGP expects is in absolute format not adjusted
for DST (i.e. winter time).
Return Code
Value Description
R_NORMAL Success.
R_INVPARAM Invalid parameter specified as dwOption.
114 9AKK101130D1385
Section 2 API Functions WriteHistoricValues
Value Description
API Server failed.
R_SRVFAIL
WriteHistoricValues
Purpose
WriteHistoricValues is used to access the Historical DataBase for a list of tags,
which may be either Process Variables (PVs) or Digital Inputs (DIs).
The function writes the data for a list of tag identification indexes at a certain
period. These values overwrite the recorded values of the tags. Values are written
into the data structure TAGVALEX that contains the union of several different
point types and the appropriate union member must be selected based on the
TAGVALEX member type.
The possibility to overwrite values is provided only for the periodic historical
archived (type HDB_HIS). An attempt to overwrite Playback and Post Trip Log
archives causes the routine returns an error.
All values must be referred to the same time stamp. The time stamp specified for the
first tag will be applied to all tags.
If there are derived groups or calculations such as averages, maximum, minimum
applied to the historical group, values overwritten using this function may cause
inconsistencies. The derivation and the calculations are NOT performed again after
overwriting. So, the new values written within the group are not taken into account.
The user application program must take care of updating any possible derived group
and to perform any possible calculation.
Syntax
RETCOND API1090 WriteHistoricValues
( HDBTYPE hdbType,LPTAGOIDX pGrpIdx,
DWORD dwItemCount, LPTAGIDX pTagIdx,
9AKK101130D1385 115
WriteHistoricValues Section 2 API Functions
LPTAGVALEX pTagValue );
Parameters
Name Description
hdbType Identification of the Historical Database
Pointer to a structure defining the historical group.
pGrpIdx The type of this structure is similar to the one defining the
tags.
dwItemCount Number of entries in the pTagIdx list.
Pointer to an array of indices for which values is to be
pTagIdx written.
Each index is defined as a structure TAGIDX.
Pointer to the structure which contains the data to write into
the Database. The data will contain
Time - Used to contain the time stamp.
Tagtype - The type of the tag.
Return Code
Value Description
R_NORMAL Success.
R_OUTOFMEM
the data.
116 9AKK101130D1385
Section 2 API Functions The Demo Programs
Value Description
API Server failed.
R_SRVFAIL
The Demo Programs

The released PGP package includes the source code and the executable files of two
application programs, intended to be a Demo for the usage of most of the API
functions.
The names of these programs are ApiDemo and ApiHistDemo. The first program is
mainly dedicated to demonstrate the usage of the basic API functions, while the
second one is dedicated to demonstrate the usage of the historical functions.
They are simple Application Wizard generated programs, which implement a Form
View with some edit boxes to enter data and some push buttons. The user defines
the parameters that are passed to the API functions through the edit boxes and then
activates one function at a time, by pressing the corresponding push button.
The call-back functions associated to the push-button, mainly retrieve the
parameters and the options from the controls, call the appropriate API function,
check the returned status code and display the result in a very simple way.
The implementation code for these functions can be found in the module
ApiDemoView.cpp
9AKK101130D1385 117
The Demo Programs Section 2 API Functions
118 9AKK101130D1385
Section 3 Dynamic Data Exchange
Introduction
The APMS DDE package, which is part of the PGP Client environment, enables a
Windows client application that is compliant with the DDE standards to exchange
information with the PGP Server.
The package is designed to transfer the following data types:
• Realtime Data: Tag value, quality, time stamp (read and write).
• Tag Database parameters (read only).
• Historical Data: tag value, quality, time stamp (Read Only).
• DAFS Files (read and write).
• Data from Alarm History Database (read only).
• APMS general information (read only).
DDE Syntax
Microsoft has defined the DDE request to have a three level address scheme.
The top level describes the application, or “SERVER” of interest (in the PGP DDE
package this name is by default ApmsDde, but it can be changed according to user
needs).
The next level defines a “TOPIC” within the selected server.
The final level specifies an “ITEM” within the topic. Each level is separated from
the others by a unique separator character to form the general syntax
ServerName|TopicName!’ItemName’
9AKK101130D1385 119
ACCFIL Section 3 Dynamic Data Exchange
or, specifically, the PGP syntax:

ApmsDde|TopicName!’ItemName’
In the following sections all the supported topics are described in detail.
Each topic refers to the Node field, which is the TCP/IP name of the PGP Process
Computer node. This name has been maintained for compatibility with previous
1090 APMS installations, but is not longer used in PGP.
ACCFIL
Purpose
This topic is used to retrieve data from the DAFS files.
ItemName
Node;FileNumber;RecordNumber;WordNumber;Type;p1;p2; Refresh
Where\p
Item Name Description
Node Remote Host Node Name (not used).
FileNumber Number of the DAFS file to be accessed.
RecordNumber Number of the record.
WordNumber Offset of the item, in words, starting from 1.
Format of the retrieved data
Type
Allowed formats are STRING, WORD, LONG, FLOAT, FIELD.
Number of characters for String type.
p1 Start Bit for Field type.
0 for all other types.
p2 Number of bits for Field type and 0 for other types.
Refresh Refresh period in seconds.
120 9AKK101130D1385
Section 3 Dynamic Data Exchange ALARM
ALARM
Purpose
This topic is used to retrieve data from the Alarm History Database.
ItemName
Node;StartTime;EndTime;Option;Refresh;
Where:

Initial time for data retrieving.
The allowed formats are
StartTime
DD-MM-YYY hh:mm:ss (start date and time specification)
NOW (from the current time).
Final time for data retrieving.
The allowed formats are
EndTime
DD-MM-YYY hh:mm:ss (end date and time specification)
DD:hh:mm:ss (delta time).
Retrieval option as listed below
ReverseSearch - Search data from oldest,
MaxRecords - Maximum number of records returned,
SkipRecords - Number of records to skip for time,
MatchType - Alarm types to match (ALARMACK, ALARM, EVENT,
CHANFAIL, OPERACT, INFO, DIAGNOSTIC),
Option
ExcludeType - Alarm types to exclude,
MatchGroup - Number of alarm groups to match,
ExcludeGroup - Number of alarm groups to exclude,
MatchPriority - Number of priorities to match,
ExcludePriority - Number of priorities to exclude,
MatchTag - Number of tags to match.
9AKK101130D1385 121
LOCKFIL Section 3 Dynamic Data Exchange

Refresh Refresh period in seconds.
Supported combinations of Start Time, End Time and Refresh Time are listed in the
table below.
Table 21. Alarm Time Combinations.

Start Time End Time Refresh Explanation
DD-MM-YY DD-MM-YY Get requested alarms from initial date/time to
sss
hh:mm:ss hh:mm:ss end date/time each sss seconds.
DD-MM-YY Get requested alarms from initial date/time to
NOW sss
hh:mm:ss now each sss seconds.
DD-MM-YY Get requested alarms from initial date/time for
+DD:hh:mm:ss sss
hh:mm:ss a delta time interval each sss seconds.
DD-MM-YY Get requested alarms from initial date/time
-DD:hh:mm:ss sss
hh:mm:ss back for a delta time each sss seconds.
Get requested alarms from last delta time
NOW -DD:hh:mm:ss sss
each sss seconds.
LOCKFIL
Purpose
This topic is used to lock and unlock DAFS files. Take care of using this feature:
local PGP files may prevent normal usage of the system and seriously influence the
PGP operations.
ItemName
Node;FileNumber;Option
Where:

122 9AKK101130D1385
Section 3 Dynamic Data Exchange SYSINFO

FileNumber Number of the DAFS file to be locked/unlocked.
Code of the Operation.
Option 0 - Unlock,
1 - Lock.
SYSINFO
Purpose
This topic is used to retrieve generic information about some APMS elements.
ItemName
Node;Option;Refresh
Where:

Option.
Allowed options are
MASTER - Master/Slave indicator (not used),
Option
TIME - Time and date of the host,
NUMTAGS - Number of implemented tags,
TAGLIST - List of implemented tags.
Refresh period in seconds.
In case of TAGLIST option, this parameter has the meaning of starting
Refresh
index for tag enumeration.
Up to 100 tags are enumerated.
9AKK101130D1385 123
TAGCNF Section 3 Dynamic Data Exchange
TAGCNF
Purpose
This topic is used to retrieve various parameters from the Tag Database.
A parameter at a time can be retrieved.
ItemName
Node;Option;TagName;
124 9AKK101130D1385
Section 3 Dynamic Data Exchange TAGCNF
Where:

Name of the requested parameter according to the Tag Database Field names.
For compatibility with previous installations also the following names are
supported
DB_TYPE_TAG - Type of the tag; managed as DB_TAGTYPE,
DB_AL_GRP - Alarm group; managed as DB_ALMGROUP,
DB_PRALDI_NAM - Primary display; managed as DB_PRIMDISP,
DB_EU - Engineering Unit index; managed as DB_EUDESC,
DB_TAGNUM - Tag Index; managed as DB_TAGINDEX,
DB_PLANT_TAG - Customer tag name; managed as
DB_CUSTTAGID,
DB_HINS_LIMIT - High Instrument Limit; managed as DB_VAL100,
DB_LINS_LIMIT - Low Instrument Limit; managed as DB_VAL0,
DB_LOW_LIMIT Low Alarm Limit; managed as DB_LALARM,
Option
DB_LL_LIMIT - Low-Low Alarm Limit; managed as DB_L2ALARM,
DB_SL_LIMIT - Significant Low Alarm Limit; managed as
DB_L3ALARM,
DB_HIGH_LIMIT - High Alarm Limit; managed as DB_HALARM,
DB_HH_LIMIT - High-High Alarm Limit; managed as
DB_H2ALARM,
DB_SH_LIMIT - Significant High Alarm Limit; managed as
DB_H3ALARM,
DB_ICI - ICI number; managed as DB_ICI_NUM,
DB_RING - Ring; managed as DB_LOOP,
DB_MOD - Module; managed as DB_MODULE,
DB_BLK - Block; managed as DB_BLOCK,
DB_NUMBER ICI - ICI index; managed as DB_ICI_NDX.
Tagname Name of the tag.
9AKK101130D1385 125
TAGHIS Section 3 Dynamic Data Exchange
TAGHIS
Purpose
This topic is used to retrieve the values from the historical archives
ItemName
Node;DataBaseName;StartTime;EndTime;
Sample;Option;Refresh;TagName;
Where:

Historical Database Name.
DataBaseName
It can be PLAYBACK or the name of any configured historical group.
Initial time for data retrieving.
Allowed formats are
StartTime DD-MM-YYY hh:mm:ss (start date and time specification),
NOW (from the current time),
hh:mm:ss (instant time).
Final time for data retrieving.
Allowed formats are
DD-MM-YYY hh:mm:ss (end date and time specification),
EndTime
NOW (to the current time),
DD:hh:mm:ss (delta time),
hh:mm:ss (instant time).
Sample Sampling frequency in seconds.
126 9AKK101130D1385
Section 3 Dynamic Data Exchange TAGHIS

Format of the retrieved data according to the following selection
DB_VALUE - Numerical tag value,
DB_RVALUE - On/Off value (only for DI tag),
Option
DB_QUALITY: Tag quality,
DB_STATUS: Tag value and quality,
DB_TIME: Time stamp.
Refresh period in the following formats
sss - Number of seconds,
Refresh DAY [hh:mm] - Instant time each days,
HOUR [mm:ss] - Instant time each hour,
MINUTE [mm] - Instant time each minute.
TagName Name of the tag.
Supported combinations of Start Time, End Time and Refresh Time are listed in the
table below.
Table 22. Historical ArchiveTime Combinations.

DD-MM-YY DD-MM-YY Get requested data from initial date/time to
sss
hh:mm:ss hh:mm:ss end date time each sss seconds.
DD-MM-YY Get requested data from initial date/time to
NOW sss
hh:mm:ss now each sss seconds.
DD-MM-YY Get requested data from initial date/time for a
+DD:hh:mm:ss sss
hh:mm:ss delta time each sss seconds.
DD-MM-YY Get requested data from initial date/time back
-DD:hh:mm:ss sss
hh:mm:ss for a delta time each sss seconds.
Get requested data from last delta time each
NOW -DD:hh:mm:ss sss
sss seconds.
DAY Get requested data from initial instant time to
hh:mm:ss hh:mm:ss
[hh:mm] end instant time each day at hh:mm.
HOUR Get requested data from initial instant time to
hh:mm:ss hh:mm:ss
[mm:ss] end instant time each hour at mm:ss.
9AKK101130D1385 127
TAGINFI Section 3 Dynamic Data Exchange
Table 22. Historical ArchiveTime Combinations.

MINUTE Get requested data from initial instant time to
hh:mm:ss hh:mm:ss
[mm] end instant time each minute at mm.
TAGINFI
Purpose
This topic is used to retrieve the parameters of tags associated to the Symphony
hardware modules.
The topic is maintained only for compatibility with previous installations. Use the
TAGCNF topic to access the various Database fields.
ItemName
Node;Options;TagName;
Where:

Option.
Allowed options are
DB_ICI - Number of the ICI,
DB_RING - Number of the Ring,
Option
DB_PCU - Number of the PCU within the Ring,
DB_MOD - Number of the Module within the PCU,
DB_BLK: Number of the Block within the Module,
DB_NUMBER - Tag ID.
128 9AKK101130D1385
Section 3 Dynamic Data Exchange TAGRTD
TAGRTD
Purpose
This topic is used to read the current value of a tag from the PGP Realtime
Database.
ItemName
Node;Option;Refresh;TagName;
Where:

Option.
Allowed options are
DB_VALUE - Tag value (in numeric format),
DB_RVALUE - Tag value (in text format, only for DI tag),
Option
DB_QUALITY - Tag quality,
DB_STATUS - Tag value and quality,
DB_TSTAMP_VALUE_QUALITY - Time stamp, value and quality of
tag.
Refresh Refresh time in seconds.
TAGWTD
Purpose
This topic is used to write a value to a tag in the PGP Realtime Database.
ItemName
Node;Option;TagName;TagValue
9AKK101130D1385 129
WRIFIL Section 3 Dynamic Data Exchange
Where:

Option.
Option The allowed option is
DB_VALUE.
TagValue Value of the tag (in numeric format).
WRIFIL
Purpose
This topic is used to modify data contained into DAFS files. The user must be
logged in as a privileged PGP User to perform this function.
ItemName
Node;FileNumber;RecordNumber;WordNumber;Type;p1;p2;Value
Where:

FileNumber Number of the DAFS file to be modified.
RecordNumber Number of the record.
WordNumber Offset of the item, in words, starting from 1.
Format of the data to be written.
Type
Allowed formats are: STRING, WORD, LONG, FLOAT, FIELD.
Number of characters for String type.
p1 Start Bit for Field type.
0 for all other types.
p2 Number of bits for Field type or 0 for other types.
130 9AKK101130D1385
Section 3 Dynamic Data Exchange The Demo Spreadsheet

Value Value to be written.
The Demo Spreadsheet

The PGP distribution package contains a sample spreadsheet for EXCEL in order to
provide some examples of the DDE syntax. The name of the spreadsheet is
DEMO.XLS, it is located under the \PGP\Config directory.
When EXCEL will load the spreadsheet, it will inform you that the document
contains links and will ask you if you want to re-establish them.
If you answer YES then EXCEL will connect to the ApmsDde to retrieve the data.
Until the data has not been received from the PGP Server the value of the fields is
set to #N/A.
The sample spreadsheet contains two sheets:
• Sheet 1 - contains many fields that refer to information for a single tag.
• Sheet 2 - contains some examples of retrieving data for a group of tags.
The first sheet provides the possibility to select a tag in the system, entering the tag
name into a dedicated box or selecting it among the list containing the first 100 tags.
The sheet presents real-time value of the tag (value, quality in numeric and trend
format), information from the tag configuration DataBase and information from the
Alarm History DataBase.
9AKK101130D1385 131
The Demo Spreadsheet Section 3 Dynamic Data Exchange
132 9AKK101130D1385
Section 4 Component Object Model (COM)
Library
The TNTAPI Active Template Library (ATL) extends PGP API functions to every
developer tool-kit designed for Windows which supports MS COM technology.
The PGP API functions are interfaced to user application programs through an
Active Template Library (ATL) named TNTAPI.DLL.
This file is contained in a directory that is set and registered by default by the PGP
installation procedure to [<drive>\<path>]\PGP\bin.
The location of the TntApi.dll can be changed, but before changing the location the
DLL must be manually unregistered and then registered again from the new
location.
TNTAPI COM Objects

The TNTAPI.DLL provides four COM objects encapsulating standard PGP API
calls
• TntSystem, including time functions, system information retrieval functions,
application files functions;
• TntTagDB, including Realtime Database access functions, read/write tag
values functions;
• TntAlarm, including alarms subsystem functions;
• TntHistory, including Historical Database access functions.
• A fifth COM object collects common interfaces
• Common Interface, including connection and disconnection functions, test
connection functions and connection inquiry functions.
9AKK101130D1385 133
Construction and Destruction Behavior Section 4 Component Object Model (COM)
Furthermore, the library includes all PGP type definitions and several constant
enumerations.
Construction and Destruction Behavior

When an COM object is created (not just declared), the object attempts to
automatically connect with the APMS Server. If the connection fails, the object still
exists but every call to any property or method will fail until a manual connection is
successfully established.
In the same way the COM object automatically closes the connection with the
APMS Server even if it was established manually.
The syntax of functions in the following refers to MS Visual Basic.
Common Interface
All the COM objects have some common properties and methods which returns
information about the connection with the APMS Server, or enable the application
to establish or close the connection with the APMS Server.
ConnectToTNT
Method
This method connects manually the user application to the APMS Server. Use this
method if the automatic connection in the object constructor fails. Calling this
method when the connection is already established will return simply without do
anything.
Syntax
object.ConnectToTNT
( bsServerName As String,
plClient As Long, [lCode As Long = 0] ) As RetCond
134 9AKK101130D1385
Section 4 Component Object Model (COM) DisconnectFromTNT
Parameters
Name Description
bsServerName Name of the node implementing the PGP API server functionality.
Returned information which identify the number of the client, as assigned by
plClient
the server or defined in the server registry.
lCode Must be 0. Optional parameter.
Return Code
Value Description
rcNORMAL Success.
rcNOCONN The Api Server was not connected.
rcNOACTIVE Successful connection, but the Server is not active.
rcINPROGRESS Successful connection; the Server is starting up.
rcSHUTDOWN Successful connection, but the Server is shutting down.
API Server failed.
rcSRVFAIL
No entry for this Client.
rcNOENTR
All licensed Clients have already been connected.
DisconnectFromTNT
Method
This function disconnects the User Application Program from the API Server,
properly terminating the communications.
This function should be called before the user application terminates, even if the
COM object destructor closes automatically the connection.
Syntax
object.DisconnectFromTNT ( )
9AKK101130D1385 135
GetClientNumber Section 4 Component Object Model (COM)
Parameters
None.
Return Code
None.
GetClientNumber
Property - Read only

This property returns an information which identify the number of the client, as
defined in the server registry.
The function returns the same value as returned by the ConnectToTNT method in
the lpClient parameter.
Syntax
object.GetClientNumber As Long
Parameters
None.
Return Code
Value Description
Long >= 0 The number of the client.
Long < 0 An error occurred (no connection active).
GetLastRetCond
Method
This method returns the return code of the last method or property call.
136 9AKK101130D1385
Section 4 Component Object Model (COM) IsConnectionAlive
Syntax
object.GetLastRetCond As RetCond
Parameters
None.
Return Code
The returned code depends on the last called property or method.
IsConnectionAlive

This property checks if the connection with the APMS Server is still in operation.
Syntax
object.IsConnectionAlive As Boolean
Parameters
None.
Return Code
Value Description
True The connection with the APMS Server is still alive.
False No connection with APMS Server.
IsSystemActive

This property checks if PGP is currently running.
9AKK101130D1385 137
Object TntSystem Section 4 Component Object Model (COM)
Syntax
object.IsSystemActive As Boolean
Parameters
None.
Return Code
Value Description
True The system is running.
False The system is down.
Object TntSystem
Use this object to retrieve information about the system, to convert time value into
PGP format and to manage application files.
ApmsSysInfo
Property - Read & Write

This property retrieves and sets some parameter internally used by PGP.
No validation, checking and logging are performed when a parameter is set. Setting
parameters, the user application program may impact the running programs.
Settings performed by the user application program remain in effect until the PGP is
shut down. The PGP start-up procedure (ADAM) will set again the parameters as
defined in the registry file.
Use GetLastRetCond to retrieve any error condition.
Syntax
object.ApmsSysInfo ( sipInfoType As SysInfoParam ) As Long
138 9AKK101130D1385
Section 4 Component Object Model (COM) CheckSysSecurity
Parameters
Name Description
sipInfoType Parameter to be retrieved or set.
Return Code
Value Description
Long Value of the specified parameter.
CheckSysSecurity
Method
This method performs a check on the security right of the currently logged user. The
checks are performed against the required permissions for performing a general
function.
The security privilege mask is defined in the file ApmsSecurity.h and listed in
Appendix A.
Syntax
object.CheckSysSecurity
( usSecurityPriv As UserSecurity, iSecurityLevel As Long,
iSecurityGroup As Long, [lOpStation As Long = -1] ) As Boolean
Parameters
Name Description
usSecurityPriv Security privilege to be checked (see Table A-3. of Appendix A).
Level of security (0 to 16) requested to the logged user to perform the
iSecurityLevel
check.
9AKK101130D1385 139
ConvertFromApmsSysTimeEx Section 4 Component Object Model (COM)
Name Description
iSecurityGroup Security group requested to the logged user to perform the check.
Client operator station number. Managed automatically by the object.
lOpStation
Optional parameter.
Return Code
Value Description
True The privilege is granted to the user.
The privilege is not granted to the user or there was some failure in the
False
Client/Server communication.
ConvertFromApmsSysTimeEx
Method
The method computes time and date values starting from a given PGP Extended
Time (number of seconds since midnight 12/31/1990 and milliseconds).
The conversion is performed in such a way the result is adjusted for Daylight Saving
Time periods. Assuming that the supplied information is a wall clock time (subject
to Daylight Saving Time compensation) and that the returned information is an
internal APMS Time (not subject to DST), this function subtracts one hour to the
BDSTDECK.INS file.
Syntax
object.ConvertFromApmsSysTimeEx
( etTime As ExTime, lYear As Long, lMonth As Long,
lDay As Long, lHour As Long, lMinute As Long,
lSecond As Long, lMillisec As Long ) As RetCond
140 9AKK101130D1385
Section 4 Component Object Model (COM) ConvertToApmsSysTimeEx
Parameters
Name Description
A EXTIME structure, which defines the time as
lTime - Seconds since midnight 12/31/1990.
exTime
lMilsec - Milliseconds since the last second.
This is the input value.
lYear,
lMonth,
lDay,
Time and date information that has been converted.
lHour,
These are the returned values.
lMinute,
lSecond,
lMillisec
Return Code
Value Description
rcNORMAL Success.
API Server failed.
rcSRVFAIL
ConvertToApmsSysTimeEx
Method
The method computes the PGP Extended Time (number of seconds since midnight
12/31/1990 and milliseconds) given the specified time and date values.
The conversion is performed in such a way the result is adjusted for Daylight Saving
Time periods. Assuming that the supplied information is a wall clock time (subject
to Daylight Saving Time compensation) and that the returned information is an
9AKK101130D1385 141
ConvertToApmsSysTimeEx Section 4 Component Object Model (COM)
internal Apms Time (not subject to DST), this function subtracts one hour to the
BDSTDECK.INS file.
Syntax
object.ConvertToApmsSysTimeEx
( etTime As ExTime,
lYear As Long, lMonth As Long, lDay As Long,
lHour As Long, lMinute As Long, lSecond As Long,
lMillisec As Long ) As RetCond
Parameters
Name Description
A EXTIME structure, which defines the time as
lTime - Seconds since midnight 12/31/1990.
exTime
This is the returned value.
lYear,
lMonth,
lDay,
lHour, The time and date information that must be converted.
lMinute,
lSecond,
lMillisec
142 9AKK101130D1385
Section 4 Component Object Model (COM) GetApmsSysInfo
Return Code
Value Description
rcNORMAL Success.
Invalid time (some of the input parameters are not compliant with the time
rcINVTIM
definition or the converted time is previous to 1/1/1991).
API Server failed.
rcSRVFAIL
GetApmsSysInfo
Method
This method retrieves the definition of some parameters, which are used internally
by the PGP. Some parameters refers to “static” characteristics, such as sizes and
maximum allowed values. Other parameters refer to “dynamic” information related
to the status of different component of the system.
Syntax
object.GetApmsSysInfo ( sipInfoType As SysInfoParam ) As Long
Parameters
Name Description
sipInfoType Parameter to be retrieved
Return Code
Value Description
Value of the requested information.
Long Value In case of any error (invalid parameter requested or failure in
communication with the Server) the returned value will be 0 (zero).
9AKK101130D1385 143
GetApmsSysTime Section 4 Component Object Model (COM)
GetApmsSysTime
Method
This method retrieves the value of current Apms time, which corresponds to the
number of seconds since January 1st 1991.
The APMS time is not adjusted for Daylight Saving Time compensation. It is a
value continuously growing.
Syntax
object.GetApmsSysTime ( ) As Long
Parameters
None.
Return Code
Value Description
Current APMS time, in the simplified format.
Long Value In case of any error (such as a failure in communications with the APMS
server) the returned value will be 0 (zero).
GetApmsSysTimeEx
Method
This method retrieves the value of current Apms time, in extended format that
corresponds to the number of seconds since January 1st 1991 and to the number of
milliseconds since the current second.
While the millisecond information is set to 0 in the 1090 APMS, the usage of this
extended time format is suggested for compatibility with the tag time stamp. The
time conversion routines use this time format instead of the plain APMS time
format.
144 9AKK101130D1385
Section 4 Component Object Model (COM) GetApmsSysTimeString
The APMS time internally is not adjusted for Daylight Saving Time compensation,
that means, it is a value continuously growing.
Syntax
object.GetApmsSysTimeEx ( etTime As ExTime ) As RetCond
Parameters
Name Description
Returned value of current APMS time, in the extended format
exTime lTime - Seconds since midnight 12/31/1990.
Return Code
Value Description
rcNORMAL Success.
API Server failed.
rcSRVFAIL
GetApmsSysTimeString
Method
This method converts a time value in extended time format (seconds since January
1st 1991 and milliseconds) and returns the local time and date in ASCII format for
display and print purposes. The method provides several possibilities of formatting
the string.
Adjustment for Daylight Saving Time is provided by this method (i.e. during
summer time one hour is added to the returned time value).
In case a time value is not supplied to this function, the function returns the current
APMS time converted into an ASCII string.
9AKK101130D1385 145
GetApmsSysTimeString Section 4 Component Object Model (COM)
Syntax
object.GetApmsSysTimeString
( bsApmsTime As String, tcFormat As TimeConstants ) As RetCond
146 9AKK101130D1385
Section 4 Component Object Model (COM) GetApmsSysTimeString
Parameters
Name Description
bsApmsTyme The returned string containing the result of the conversion.
Type of required conversion according to the following definition
TIMEFRMT_SHORT -
Convert time to DD.MM.YY HH:MM:SS.CCC.
TIMEFRMT_STD -
Convert time to DD MMM YYYY HH:MM:SS.CCC.
TIMEFRMT_WEEK -
Convert time to WWW DD MMM YYYY HH:MM:SS.
TIMEFRMT_LONGWEEK -
Convert time to WWWWWWWWW DD MMM YYYY HH:MM:SS.
The following values may be ORed to the dwFormat above to better specify
the result of the conversion
TIMEFRMT_EXCLUDE_MIL -
sipInfoType Exclude the milliseconds from the output string.
TIMEFRMT_EXCLUDE_DATE -
Exclude the date from the output string.
TIMEFRMT_EXCLUDE_TIME -
Exclude the time from the output string.
The following values may be ORed to the dwFormat above to specify the
language used in the conversion
TIMEFRMT_STD_LANGUAGE -
Translate the date/time in English.
TIMEFRMT_NATIONAL_LANGUAGE -
Translate the date/time to the National Language.
If none of the previous values was set, the language selected on the Server
is used for the translation.
9AKK101130D1385 147
GetSysFileInfo Section 4 Component Object Model (COM)
Return Code
Value Description
rcNORMAL Success.
API Server failed.
rcSRVFAIL
GetSysFileInfo
Method
GetSysFileInfo retrieves essential file information of a file defined in the PGP
Direct Access File System. This method is mainly used to check if a file exists and
to retrieve information used for subsequent file access functions, while
GetSysFileInfoEx provides complete information on the file.
Syntax
object.GetSysFileInfo
( fiFileIdx As FileIdx,
lRecordSize As Long, lNumRecords As Long ) As RetCond
Parameters
Name Description
Structure defining the file for which the information is required
fiFileIdx iFileKey - The index of the file, as defined in FILPRM.INS.
nNode - The node which implements the file.
lRecordSize The returned size of the record.
lNumRecords The returned number of records of the file.
148 9AKK101130D1385
Section 4 Component Object Model (COM) GetSysFileInfoEx
Return Code
Value Description
rcNORMAL Success.
rcINVKEY Invalid file key (the file does not exist).
API Server failed.
rcSRVFAIL
GetSysFileInfoEx
Method
GetSysFileInfoEx retrieves file information of a file defined in the PGP Direct
Access File System. This function provides a complete information on file
characteristics.
Syntax
object.GetSysFileInfoEx
( fiFileIdx As FileIdx, fiFileInfo As FileInfo ) As RetCond
Parameters
Name Description
Structure defining the file for which the information is required
fiFileInfo Returned FILEINFO structure.
9AKK101130D1385 149
IsNationaLanguage Section 4 Component Object Model (COM)
Return Code
Value Description
rcNORMAL Success.
API Server failed.
rcSRVFAIL
IsNationaLanguage

This property checks the language selected on a particular client and return TRUE if
a national language has been selected or FALSE if English has been selected.
The property provides additional support for the language translation. However, the
SysMultiLanguage function described in the following detects by itself which kind
of language has been selected.
the following Windows registry variable
HKEY_LOCAL_MACHINE\SOFTWARE\ABB\PGP\General\Language
Syntax
object.IsNationalLanguage As Boolean
Parameters
None.
150 9AKK101130D1385
Section 4 Component Object Model (COM) SetApmsSysInfo
Return Code
Value Description
True The national language is selected.
False The selected language is English.
SetApmsSysInfo
Method
This method changes the definition of some parameters that are used internally by
the PGP.
The method does not perform any validation or checking on the passed information
and does not perform any logging. So, the user application program must perform
consistency checking since an improper call to the method may impact other
running programs, that is the whole system operation.
Settings performed by the user application program remains in effect until the PGP
is shut down. The PGP start-up procedure (ADAM) will set again the parameters as
defined in the registry file.
Syntax
object.SetApmsSysInfo
( sipInfoType As SysInfoParam, lInfoValue As Long ) As RetCond
Parameters
Name Description
sipInfoType Parameter to be set.
lInfoValue Value to be set.
9AKK101130D1385 151
SetApmsSysTimeEx Section 4 Component Object Model (COM)
Return Code
Value Description
rcNORMAL Success.
Invalid parameter. The parameter requested does not correspond to the
rcINVPARAM
internal codes, or the value cannot be set.
API Server failed.
rcSRVFAIL
SetApmsSysTimeEx
Method
This method sets the time of the Operating System. Setting is then automatically
propagated to the internal APMS time and, if so configured, to the C-NET.
The time provided to this function is intended to be independent from Daylight
Saving Time compensation.
The Windows user logged in must have special privileges in order to force the
Operating System time to change.
Syntax
object.SetApmsSysTimeEx ( etTime As ExTime ) As RetCond
Parameters
Name Description
New PGP time in the extended format
exTime lTime - Seconds since midnight 12/31/1990.
152 9AKK101130D1385
Section 4 Component Object Model (COM) SysFileLock
Return Code
Value Description
rcNORMAL Success.
rcINVTIM Invalid time specified, or failure in setting the system time.
API Server failed.
rcSRVFAIL
SysFileLock
Method
This method locks the accesses to a file defined within the PGP Direct Access File
System preventing the concurrent usage by different application programs.
The file is locked both for write and read access. Only to the process currently
locking the file is allowed to access the file.
The application program must take care of releasing a locked file using the
SysFileUnlock method. Otherwise, the file becomes unusable.
Keeping a file locked indefinitely may seriously compromise the normal operation
of the system.
9AKK101130D1385 153
SysFileRead Section 4 Component Object Model (COM)
Syntax
object.SysFileLock
( fiFileIdx As FileIdx, [lCookie As Long = 0] ) As RetCond
Parameters
Name Description
Structure defining the file to lock
lCookie Not used. Optional parameter.
Return Code
Value Description
rcNORMAL Success.
API Server failed.
rcSRVFAIL
SysFileRead
Method
This method reads consecutive records from a file defined within the PGP Direct
Access File System.
The file is locked during the read access.
154 9AKK101130D1385
Section 4 Component Object Model (COM) SysFileRead
Syntax
object.SysFileRead
( fiFileIdx As FileIdx, lRecord As Long, lNumRecord As Long,
pBuffer() As Any, lRecordSize As Long ) As RetCond
Parameters
Name Description
Structure defining the file to read
lRecord The first record that will be accessed.
lNumRecord The number of consecutive records of the file to be accessed.
Array of any type which will receive the records read. If the array is not sized
pBuffer it will be adjusted by the method; else if the array is sized, its number of
elements must be the same as lNumRecord parameter.
lRecordSize Size of a record.
Return Code
Value Description
rcNORMAL Success.
Invalid parameter value (pBuffer elements number different from
rcINVPARAM
lNumRecord).
rcINVREC Invalid record (the first record to access is outside the records in the file).
Invalid number of records (some of the records to access is outside the
rcINVNREC
9AKK101130D1385 155
SysFileUnlock Section 4 Component Object Model (COM)
Value Description
rcINVRSIZ Invalid record size.
rcRMSERR Error accessing the file on the disk.
API Server failed.
rcSRVFAIL
SysFileUnlock
Method
This method releases a previous lock to a file defined within the PGP Direct Access
File System allowing the concurrent usage by different application programs.
After the file has been unlocked, write and read access are allowed to any other
process or thread within the system.
The method does not check if the calling process locked the file.
Syntax
object.SysFileUnlock
( fiFileIdx As FileIdx, [lCookie As Long] = 0 ) As RetCond
Parameters
Name Description
Structure defining the file to unlock
lCookie Not used. Optional parameter.
156 9AKK101130D1385
Section 4 Component Object Model (COM) SysFileWrite
Return Code
Value Description
rcNORMAL Success.
API Server failed.
rcSRVFAIL
SysFileWrite
Method
SysFileWrite writes consecutive records to a file defined within the PGP Direct
Access File System. Data to be written are allocated within an array of record
structures.
completes.
9AKK101130D1385 157
SysFileWrite Section 4 Component Object Model (COM)
Syntax
object.SysFileWrite
( fiFileIdx As FileIdx,
lRecord As Long, lNumRecord As Long,
pBuffer() As Any, lRecordSize As Long,
[frwoOptions As FileRWOptions = frwNone] ) As RetCond
Parameters
Name Description
Structure defining the file to write in
lRecord The first record that will be accessed.
lNumRecord The number of consecutive records to be written.
Array of any type to which contain the records to be written.The array
pBuffer
elements number must be the same of lNumRecord parameter.
lRecordSize Size of a record.
Additional processing mask. May contain an ORed combination of the
following bits
frwWriteSpecificAppl - Activates a user written function that performs post-
frwoOptions processing.
frwWriteExportDB - Export the information buffer to an external database as
BLOB data.
Optional parameter.
158 9AKK101130D1385
Section 4 Component Object Model (COM) SysMultiLanguage
Return Code
Value Description
rcNORMAL Success.
Invalid parameter value (pBuffer elements number different from
rcINVPARAM
lNumRecord).
rcINVREC Invalid record (the first record to access is outside the records in the file).
Invalid number of records (some of the records to access is outside the
rcINVNREC
rcINVRSIZ Invalid record size.
API Server failed.
rcSRVFAIL
SysMultiLanguage
Method
This method translates an English text message to the national language selected on
the client. PGP uses this function before the presentation of messages, texts and
menu items on the screen.
System messages, in English and in the national languages, are defined in the
BLANGDECK.XML file. Application specific messages can be defined (with the
same syntax) in the BLANG2DECK.XML file.
the following Windows registry variable
HKEY_LOCAL_MACHINE\SOFTWARE\ABB\PGP\General\Language
In case the previous key is set to ENGLISH then the translation is not performed
and the returned string is the same as the input string. Also in case the string to be
translated is not found in the dictionary the returned string is the original English
string.
9AKK101130D1385 159
WriteMsgErrorLog Section 4 Component Object Model (COM)
Syntax
object.SysMultiLanguage
( bsToBeTranslated As String,
[fForceTranslation As Boolean = False] ) As String
Parameters
Name Description
bsToBeTranslated String defining the English text of the message.
Flag specifying if the translation must be performed even if the national
fForceTraslation language is not selected on the particular client.
Optional parameter.
Return Code
Value Description
Translated string.
String Value No error is generated if the string does not exist in the dictionary, but in this
case the original English string is returned.
WriteMsgErrorLog
Method
This method writes an application message into the system Error Log Message File.
The file is located under the directory whose name is defined by the
HKEY_LOCAL_MACHINE\SOFTWARE\ABB\PGP\Directories\Logs.
registry. It is set by default to \PGP\Logs. The name of the file is ErrorLog.txt.
The WriteMsgErrorLog method appends the application message to the end of the
error log file and time-stamps the message with the current time.
160 9AKK101130D1385
Section 4 Component Object Model (COM) Object TntTagDB
Syntax
object.WriteMsgErrorLog
( bsProcessName As String, bsMessageText As String ) As RetCond
Parameters
Name Description
bsProcessName String which contains the name of the application process.
bsMessageText String which contains the message to be logged.
Return Code
Value Description
rcNORMAL Success.
rcFAILED Error writing in the Error Log file.
API Server failed.
rcSRVFAIL
Object TntTagDB
Use this object to retrieve information about the Realtime Database of tags.
CheckDBTagSecurity
Method
CheckDBTagSecurity performs a check on the security right of the logged user. The
checks are performed against the required permissions for operating onto a tag as
defined into the tag database. The currently logged user must own the privilege right
required to perform an operation on a tag.
9AKK101130D1385 161
DBTagListRead Section 4 Component Object Model (COM)
Syntax
object.CheckDBTagSecurity
( tsSecurityPriv As TagSecurity,
tiTagIdx As TagIdx, [lOpStation As Long = -1] ) As Boolean
Parameters
Name Description
tsSecurityPriv Security privilege to be checked (see Table A-4. of Appendix A).
tiTagIdx Index of the tag for which the security rights must be checked.
Client operator station number. Managed automatically by the object.
lOpStation
Optional parameter.
Return Code
Value Description
True The privilege is granted to the user.
The privilege is not granted to the user or there was some failure in the
False
Client/Server communication.
DBTagListRead
Method
This method is used to access the memory resident Realtime Database for a list of
Process Variables (PVs) and Digital Inputs (DIs).
The method returns the dynamic data for a list of tag identification indexes. The
returned data are the live values of the tags. The values are returned in the data
162 9AKK101130D1385
Section 4 Component Object Model (COM) DBTagListRead
structure that contains the union of several different point types and the appropriate
union member must be selected based on the TAGVALEX member type.
Values that originate in C-NET modules or by Calculation programs may have bad
TAGVALEX member Quality. The Quality element also provides information
about alarms.
Furthermore, the method also returns the time stamp of each variable. This time
coming from C-NET) or was updated into the DataBase (internally generated tags).
Syntax
object.DBTagListRead
( lItemCount As Long, tiTagIdx() As TagIdx,
tvTagValex() As TagValex ) As RetCond
Parameters
Name Description
lItemCount The number of the tags contained in the list.
tiTagIdx Array containing the indexes of the tags
Array to which the values read will be put. It must be dimensioned as the
tvTagValex
tiTagIdx parameter.
Return Code
Value Description
rcNORMAL Success.
rcINVTAG Invalid tag (tag does not exist).
9AKK101130D1385 163
DBTagListWrite Section 4 Component Object Model (COM)
Value Description
rcNOACTIVE The PGP server is not active.
rcFAILED The function failed for some of the tags.
API Server failed.
rcSRVFAIL
DBTagListWrite
Method
This method is used to access the Realtime Database for a list of tags, which may be
either Process Variables (PVs) or Digital Inputs (DIs).
The method writes the dynamic data for a list of tag identification indexes. These
values become the live values of the tags. The values are written into the data
structure TAGVALEX that contains the union of several different point types and
the appropriate union member must be selected based on the TAGVALEX member
type.
There are mainly two alternatives offered by this method, which are selected by the
Option parameter.
to generate the proper quality for the tag before writing it into the Database. Data
written in the Database is also queued to the playback historical archive, but cannot
generate any alarm message or trigger any other program.
164 9AKK101130D1385
Section 4 Component Object Model (COM) DBTagListWrite
Syntax
object.DBTagListWrite
( lItemCount As Long, tiTagIdx() As TagIdx,
tvTagValex() As TagValex,
twoOptions As TagWriteOptions ) As RetCond
Parameters
Name Description
lItemCount The number of the tags contained in the list.
tiTagIdx Array containing the indexes of the tags.
Array containing the values to be written. It must be dimensioned as the
tvTagValex
tiTagIdx parameter.
twoOptions Specify the mode of writing data in the Database.
Return Code
Value Description
rcNORMAL Success.
rcFAILED The function failed for some of the tags.
API Server failed.
rcSRVFAIL
9AKK101130D1385 165
DBTagRead Section 4 Component Object Model (COM)
DBTagRead
Method
This method is used to access the Realtime Database for a tag, which may be a
Process Variable (PV) or Digital Input (DI).
The method returns the dynamic data for a tag identification index. The returned
data is the live value of the tag. The value is returned in the data structure that
contains the union of several different point types and the appropriate union
member must be selected based on the TAGVALEX member type.
Values that originate in C-NET modules or by Calculation programs may have bad
TAGVAL member Quality. The Quality element also provides information about
alarms.
Furthermore, the function also returns the time stamp of the variable. This time
coming from C-NET) or was updated into the DataBase (internally generated tags).
Syntax
object.DBTagRead
( tiTagIdx As TagIdx, tvValex As TagValex ) As RetCond
Parameters
Name Description
tiTagIdx Internal index of the tag.
tvTagValex Returned structure which contains the read data.
166 9AKK101130D1385
Section 4 Component Object Model (COM) DBTagReadString
Return Code
Value Description
rcNORMAL Success.
API Server failed.
rcSRVFAIL
DBTagReadString
Method
This method converts the value of a tag into a string of character formatted for
standard PV and DI display or print purposes.
Values are formatted in the most suitable way for the tag. PV values can be
formatted either in Real or Integer format (depending on the configuration setting).
DI values are formatted using the status descriptor string defined for the tag.
Furthermore, the method generates a 2-character status quality descriptor string
which is appended to the value, and a string which contains the formatted time
stamp. Several formats can be chosen to format the time information.
Syntax
object.DBTagReadString
( tiTagIdx As TagIdx, tvTagValex As TagValex,
bsValue As String, bsQuality As String,
bsTime As String,
tcFormat As TimeConstants ) As RetCond
9AKK101130D1385 167
DBTagWrite Section 4 Component Object Model (COM)
Parameters
Name Description
tvTagValex Returned structure which contains data.
bsValue Returned string which will contains the formatted value.
bsQuality Returned string which will contains the formatted quality.
bsTime Returned string which will contains the formatted time stamp.
tcFormat The time stamp format option.
Return Code
Value Description
rcNORMAL Success.
API Server failed.
rcSRVFAIL
DBTagWrite
Method
This method is used to access the Realtime Database for a tag, which may be either
a Process Variable (PV) or Digital Input (DI).
The method writes the dynamic data for a tag identification index. This value will
become the live value of the tag. The value is written into the data structure
type.
Option parameter.
168 9AKK101130D1385
Section 4 Component Object Model (COM) DBTagWrite
must generate the proper quality settings for the tag before writing it into the
Database. Data written in the Database is also queued to the playback historical
archive, but cannot generate any alarm message or trigger any other program.
Syntax
object.DBTagWrite
( tiTagIdx As TagIdx, tvTagValex As TagValex,
twoOptions As TagWriteOptions ) As RetCond
Parameters
Name Description
tvTagValex Structure which contains the data to be written.
Return Code
Value Description
rcNORMAL Success.
9AKK101130D1385 169
GetDBTagIdx Section 4 Component Object Model (COM)
Value Description
rcINVPARAM Invalid parameter specified as twoOptions
API Server failed.
rcSRVFAIL
GetDBTagIdx
Method
This method retrieves the tag identification numbers (internal TAGIDX structure),
starting from an ASCII string, which correspond to the name of the tag.
The method is the main entry point for converting information as known by the end
user (tag names) to information used by all API functions (TAGIDX structure).
Syntax
object.GetDBTagIdx
( bsTagName As String, tiTagIdx As TagIdx ) As RetCond
Parameters
Name Description
bsTagName String containing the name of the tag.
Returned structure defining the internal Tag Index, which correspond to the
given name
tiTagIdx nNum - The index of the tag, into the specific Database.
itpHNM - The Database type of the tag.
nNode - The node which implements the tag.
170 9AKK101130D1385
Section 4 Component Object Model (COM) GetDBTagIdxFromIndex
Return Code
Value Description
rcNORMAL Success.
Undefined tag (the tag name was defined as a number which does not
rcUNDTAG
correspond to any TagIndex).
API Server failed.
rcSRVFAIL
GetDBTagIdxFromIndex
Method
This method retrieves the tag identification index (internal TAGIDX structure),
starting from a number, which correspond to the TAGINDEX Database field.
The TAGIDX number, used by the API, is not the same as the TAGINDEX field in
the tag Database.
Syntax
object.GetDBTagIdxFromIndex
( lTagIndex As Long, tiTagIdx As TagIdx ) As RetCond
9AKK101130D1385 171
GetDBTagInfo Section 4 Component Object Model (COM)
Parameters
Name Description
lTagIndex Index of the tag as defined in the TAGINDEX field of the Tag Database.
Returned structure defining the internal Tag Index, which correspond to the
given index
tiTagIdx nNum - The index of the tag, into the specific Database.
itpHNM - The Database type of the tag.
nNode - The node which implements the tag.
Return Code
Value Description
rcNORMAL Success.
API Server failed.
rcSRVFAIL
GetDBTagInfo
Method
This method retrieves various parameters from the tag Database. A parameter at a
time is retrieved for a certain tag. The result is returned to the caller into a structure.
According to the required parameter the caller will select the appropriate field.
The naming of the fields of the structure corresponds to the naming of the fields in
the PGP Database Configuration manual.
172 9AKK101130D1385
Section 4 Component Object Model (COM) SetDBTagInfo
Syntax
object.GetDBTagInfo
( tiTagIdx As TagIdx, itWhat As TagInfoType,
tiTagInfo As TagInfo )As RetCond
Parameters
Name Description
tiTagIdx Structure defining the internal Tag Index
Requested information specification as defined by TagInfoType
itWhat
enumeration.
tiTagInfo Returned structure which contains the selected information.
Return Code
Value Description
rcNORMAL Success.
Invalid parameter.
rcINVPARAM The requested information does not correspond to an internal supported
code or cannot be retrieved for that type of the tag.
API Server failed.
rcSRVFAIL
SetDBTagInfo
Method
This method allows writing various parameters to the tag Database. A parameter at
a time can be written for a certain tag. The parameter is fetched from a structure that
9AKK101130D1385 173
SetDBTagInfo Section 4 Component Object Model (COM)
is a union of various fields. According to the required parameter the caller select the
appropriate field.
The naming of fields in the structure corresponds to the naming of fields listed in the
PGP Database Configuration manual.
Currently only the main Database fields are supported and handled by this function.
This method does not perform any validation of the parameters and does not log
modifications. Invalid parameters passed to the function may invalidate the
consistency of the Database and affect the proper operation of the whole PGP
application.
Syntax
object.SetDBTagInfo
( tiTagIdx As TagIdx, itWhat As TagInfoType,
tiTagInfo As TagInfo, uiUsedInfo As UsedInfo,
twoOption As TagWriteOptions ) As RetCond
Parameters
Name Description
itWhat Information to be set as defined by TagInfoType enumeration.
tiTagInfo Structure which contains the new information value.
uiUsedInfo Specify which field in the tiTagInfo parameter contains the value to be set.
Return Code
Value Description
rcNORMAL Success.
174 9AKK101130D1385
Section 4 Component Object Model (COM) TagValueEx
Value Description
Invalid parameter.
rcINVPARAM The requested information does not correspond to an internal supported
code or cannot be retrieved for that type of the tag.
API Server failed.
rcSRVFAIL
TagValueEx
Property - Read & Write
This property reads and sets the value of a specified tag.
Syntax
object.TagValueEx ( tiTagIdx As TagIdx ) As TagValex
Parameters
Name Description
Return Code
Value Description
TagValex structure Structure containing the read value for the specified tag.
Object TntAlarm
Use the object to interact with the Alarms subsystem.
9AKK101130D1385 175
AlmAlarmMessageLog Section 4 Component Object Model (COM)
AlmAlarmMessageLog
Method
The method is the interface for any user application program to queue an event to
the Alarm Processors (within the Alarm Subsystem). This module is responsible for
displaying, printing, recording alarms into the Alarm History file (also called
Operator Journal), activating horns and maintaining alarm summaries.
This method queues the entry of events onto the Alarm Queue, returning an error if
the queue is full.
It also provides the way for archiving, into the Alarm History file, binary data
specific to the application. In this case the messages can only be archived but cannot
generate any other action.
The text message this function queues is not translated for multi-language Client
interfaces.
The alarm processing options listed in the Table A-1. of Appendix A may be
selected for alarms, events and information.
Syntax
object.AlmAlarmMessageLog ( alAlarmLog As AlarmLog ) As RetCond
Parameters
Name Description
alAlarmLog Structure defining the alarm log information
Return Code
Value Description
rcNORMAL Success.
176 9AKK101130D1385
Section 4 Component Object Model (COM) AlmAlarmMessageQueue
Value Description
rcFAILED Invalid tag (tag does not exist).
API Server failed.
rcSRVFAIL
rcSNOACTIVE The PGP Server is not active.
rcQUEFULL The Alarm Message Queue is full.
AlmAlarmMessageQueue
Method
The method is the interface for any user application process to queue an alarm/event
information to be processed by the Alarm Processors.
The AlmAlarmMessageQueue method queues an entry containing binary data to the
Alarm Queue. The function also activates the Alarm Processor to force processing
of the message. It returns an error if the Alarm Queue is full.
The format of the alarm message text, produced by a call to this function, is
generated by the information contained in the System Alarm Message File
(F_ALMS). This file is loaded by the off-line builder procedure via the information
contained in the BALMDECK.INS script.
The alarms produced by this call are subject to the alarm handling processing. That
is, they may be displayed, printed, archived; they may activate horns or trigger
external applications.
Before being formatted, the message texts defined by the AlarmMessageNbr
parameter are translated according to the language selected by the Client.
Syntax
object.AlmAlarmMessageQueue
( aqAlarmQueue As AlarmQueue ) As RetCond
9AKK101130D1385 177
GetAlmAlacMessage Section 4 Component Object Model (COM)
Parameters
Name Description
aqAlarmQueue Structure defining the alarm information to queue.
Return Code
Value Description
rcNORMAL Success.
rcFAILED Invalid tag (tag does not exist).
API Server failed.
rcSRVFAIL
rcQUEFULL The Alarm Message Queue is full.
GetAlmAlacMessage
Method
This method retrieves the oldest alarm action entry for the referenced alarm action
program from the alarm action queue.
If an alarm action entry for the referenced program is not currently queued in the
alarm action queue, the method will hibernate in a wait status waiting for an
incoming message. So, the user application program will also wait for a message. A
tag going into an alarm condition and triggering the corresponding program will
resume the waiting condition.
The wait condition can be asynchronously terminated by a call to the
ReleaseAlarmAction function. Another thread or another user application program
must issue such a function call.
See also the corresponding PeekAlmAlacMessage method, which does not wait for
a message becoming available.
178 9AKK101130D1385
Section 4 Component Object Model (COM) PeekAlmAlacMessage
Syntax
object.GetAlmAlacMessage
( lProgram As Long, aaAlac As Alac ) As RetCond
Parameters
Name Description
Number of the Alarm Action Program, within the range 1 to 63, requesting
lProgram
the Alac message.
aaAlac Returned structure containing the oldest alarm action entry.
Return Code
Value Description
rcNORMAL Success.
Invalid Program number (the Action Program number is outside the range 1
rcINVPGM
to 63).
rcABORTED The operation was aborted by the ReleaseAlacMessage function.
rcNOENTR No entries for this program were found in the Alarm Action Queue.
API Server failed.
rcSRVFAIL
PeekAlmAlacMessage
Method
This method retrieves the oldest alarm action entry for the referenced alarm action
program.
queued in the alarm action queue, the function returns an error code.
9AKK101130D1385 179
ReleaseAlmAlarmAction Section 4 Component Object Model (COM)
See also the corresponding GetAlmAlacMessage method, which waits for a

message becoming available.
Syntax
object.PeekAlmAlacMessage
( lProgram As Long, aaAlac As Alac ) As RetCond
Parameters
Name Description
Number of the Alarm Action Program, within the range 1 to 63, requesting
lProgram
the Alac message.
aaAlac Returned structure containing the oldest alarm action entry.
Return Code
Value Description
rcNORMAL Success.
rcINVPGM
to 63).
rcNOENTR No entries for this program were found in the Alarm Action Queue.
API Server failed.
rcSRVFAIL
ReleaseAlmAlarmAction
Method
This method is required to terminate the call to the GetAlmAlacMessage, which
may stay waiting forever for alarms.
180 9AKK101130D1385
Section 4 Component Object Model (COM) Object TntHistory
Since a call to the GetAlmAlarmAction function locks indefinitely the calling

thread, the release function must be posted by a different thread or by another
program.
Syntax
object.ReleaseAlmAlarmAction ( lProgram As Long ) As RetCond
Parameters
Name Description
Number of the Alarm Action Program, within the range 1 to 63, for which is
lProgram
requested to release an outstanding GetAlmAlacMessage call.
Return Code
Value Description
rcNORMAL Success.
rcINVPGM
to 63).
API Server failed.
rcSRVFAIL
Object TntHistory
Use this object to access the historical tag Database of PGP.
ClearHistBuffer
This method releases the buffer of data collected using GetHistData and not fully
accessed and de-queued using ReadHistValue.
9AKK101130D1385 181
GetHistData Section 4 Component Object Model (COM)
Syntax
object.ClearHistBuffer
( htDBType As HistType, lItemCount As Long ) As RetCond
Parameters
Name Description
Type of the Database accessed. Must be the same of the one called in
htDBType
GetHistData.
Number of tag which values was retrieved. Must be the same of the one
lItemCount
called in GetHistData.
Return Code
Value Description
rcNORMAL Success.
API Server failed.
rcSRVFAIL
GetHistData
Method
This method is used to read the data from the Historical Database (maintained on a
disk of the Server) to a buffer local to the User Application Program. This is the
most time consuming function, because the values are searched through all the
archive and organized in a buffer, which is allocated into the Client process.
The retrieved data is then made available to the caller by using the
ReadHistoricValue routine. This routine as to be called until there are data
182 9AKK101130D1385
Section 4 Component Object Model (COM) GetHistData
available, in order to free all packets allocated within the local buffer and to
properly release the memory.
Syntax
object.GetHistData
( htDBType As HistType, tiGrpIdx As TagIdx,
lItemCount As Long, tiTagIdx() As TagIdx,
lStartTime As Long, lEndTime As Long,
lTripTime As Long, lFrequency As Long,
[poOptions As PlaybackOptions = poHdbNone] ) As RetCond
Parameters
Name Description
htDBType Identification of the Historical Database.
Structure defining the historical group. The type of this structure is similar to
tiGrpIdx
the one defining the tags. If no group requested leave this parameter empty.
lItemCount Number of entries in the pTagIdx list.
Array of indices for which values are to be returned. Each index is defined
tiTagIdx
as a structure TagIdx.
Initial time for data retrieval. If this time is prior to the first valid data into the
lStartTime
archive, then the first valid data is returned.
Final time for data retrieval. If this time is following the last valid data into the
lEndTime
archive, then the last valid data is returned.
Time of the trip, valid only for Post-Trip logs archives.
lTripTime
This field is ignored when other historical archives are accessed.
9AKK101130D1385 183
ReadHistValue Section 4 Component Object Model (COM)
Name Description
Sampling frequency.
Interval, in seconds, used to sample the data.
lFrequency This field is meaningful only when accessing Playback (current and frozen)
and Post Trip Log archives. For any other archive, the sample recording
frequency is used to retrieve the data.
Retrieval option.
The following options can be selected
poHdbNone - Perform standard retrieval.
poOptions poHdbSample - Get sampled data (otherwise get native exceptions).
poHdbInterpolate - Interpolate values (valid only during access to current
Playback archive).
Optional parameter.
Return Code
Value Description
rcNORMAL Success.
rcNODATA No data was retrieved.
rcOUTOFMEM The Server was not able to allocate the memory to retrieve the data.
rcINVPARAM Invalid parameter specified in the dwOption field.
rcFAILED Inavlid Historical Database or internal failure in the function.
API Server failed.
rcSRVFAIL
ReadHistValue
Method
This method is used to retrieve the values previously read from an historical
database, into a local buffer of the Client process.
184 9AKK101130D1385
Section 4 Component Object Model (COM) ReadHistValue
Typically, it is used within a loop structure after the successful completion of the
GetHistData method.
This method de-queues from the historical buffer provided by GetHistData, a
sample at a time, for one point defined in the tag list. The method must be called as
many times as necessary to de-queue all data and to properly free the allocated
memory.
Call this method until it returns R_NORMAL in order to be sure that all the memory
buffers are released. Otherwise, there will be allocated memory not released. That
may cause serious problems to the whole system operation.
Syntax
object.ReadHistValue
( htDBType As HistType, tvTagValex As TagValex, lItemIdx As Long,
[poOptions As PlaybackOptions = poHdbNone] ) As RetCond
Parameters
Name Description
tvTagValex TagValex structures where values are returned.
Index of the tag belong to the tag list passed in the GetHistData whose
lItemIdx
value must be read.
poOptions Retrieval option. Optional parameter.
Return Code
Value Description
rcNORMAL Success.
9AKK101130D1385 185
WriteHistValues Section 4 Component Object Model (COM)
Value Description
rcFAILED Invalid Historical Database or internal failure in the function.
API Server failed.
rcSRVFAIL
WriteHistValues
Method
This method is used to access the Historical Database for a list of tags, which may
be either Process Variables (PVs) or Digital Inputs (DIs).
The method writes the data for a list of tag identification indexes at a certain period.
These values will overwrite the recorded values of the tags. The values are written
into the data structure TAGVALEX that contains the union of several different
point types and the appropriate union member must be selected based on the
TAGVALEX member type.
The possibility to overwrite values is provided only for the periodic historical
archives (type HDB_HIS). An attempt to overwrite Playback and Post Trip Log
archives causes the routine returns an error.
All the values must be referred to the same time stamp. The time stamp specified for
the first tag will be applied to all the tags.
If there are derived groups or calculations such as averages, maximum, minimum
applied to the historical group, values overwritten using this function may cause
inconsistencies. The derivation and the calculations are NOT performed again after
overwriting. So, the new values written within the group are not taken into account.
The user application program must take care of updating any possible derived group
and to perform any possible calculation.
186 9AKK101130D1385
Section 4 Component Object Model (COM) WriteHistValues
Syntax
object.WriteHistValues
( htDBType As HistType, tiGrpIdx As TagIdx, lItemCount As Long,
tiTagIdx() As TagIdx, tvTagValue() As TagValex ) As RetCond
Parameters
Name Description
Structure defining the historical group. The type of this structure is similar to
tiGrpIdx
the one defining the tags.
lItemCount Number of entries in the pTagIdx list.
Array of indices for which values are to be written. Each index is defined as
tiTagIdx
a structure TagIdx.
tvTagValue TagValex structures containing values to be written.
Return Code
Value Description
rcNORMAL Success.
rcFAILED Invalid Historical Database or internal failure in the function.
API Server failed.
rcSRVFAIL
9AKK101130D1385 187
Section 4 Component Object Model (COM)
188 9AKK101130D1385
Appendix A Tables
Alarm Processing Options
Table 23. Alarm Processing Options.

Name Description
ALMPROC_DISPLAY Display alarm messages.
ALMPROC_PRINT_ALARM Print alarm messages.
ALMPROC_ARCHIVE_ALARM Archive alarm messages.
ALMPROC_AUDIBLE_ALARM Audible alarm messages.
ALMPROC_BOTTOM_ALARM Display alarm messages at bottom of screen.
ALMPROC_DISPLAY_RTN Display return to normal messages.
ALMPROC_PRINT_RTN Print return to normal messages.
ALMPROC_ARCHIVE_RTN Archive return to normal messages.
ALMPROC_PRINT_EVENT Print event messages.
ALMPROC_ARCHIVE_EVENT Archive event messages.
ALMPROC_PRINT_OPERATOR Print operator actions.
ALMPROC_ARCHIVE_OPERATOR Archive operator actions.
ALMPROC_PRINT_INFO Print information messages.
ALMPROC_ARCHIVE_INFO Archive information messages.
ALMPROC_REMOVE_ONACK Remove alarm message on acknowledge.
Queue information message on alarm
ALMPROC_MESSAGE_ONACK
acknowledge.
ALMPROC_MESSAGE_NOFORMAT Do not format message text.
Perform specific application processing, triggering
ALMPROC_SPECIFIC_APPL
on a user written function.
ALMPROC_EXPORT_DB Export the alarm message to an external database.
9AKK101130D1385 189
Alarm Processing Macros Appendix A Tables
Alarm Processing Macros
Table 24. Alarms Processing Macros.

Name Description
ALMPROC_DISPLAY Display alarm and return to normal messages.
Print alarms, events, information and operator
ALMPROC_PRINT
actions.
ALMPROC_ARCHIVE Archive every message.
General Security Privileges
Table 25. General Security Privileges.

Privilege name Description
TNTPRIV_ALARM Alarm management.
TNTPRIV_GRAPHICS Configure graphics.
TNTPRIV_LOGS Configure logs.
TNTPRIV_HISTORY Configure historical.
TNTPRIV_DIAGNOSTIC Diagnostic.
TNTPRIV_SECURITY System security.
TNTPRIV_TIMEANDDATE Time and date.
TNTPRIV_TRENDS Configure trends.
TNTPRIV_PCU PCU and modules.
TNTPRIV_GROUPS Configure groups.
TNTPRIV_UTILITY System utilities.
TNTPRIV_CONFIGURATION Configure miscellanous functions.
TNTPRIV_VIEWCONFIGURATION View configuration.
TNTPRIV_TAGREMOTEWRITEFILE Remote write File.
TNTPRIV_VIEWDISPLAY View display.
TNTPRIV_LONGTERMHISTORY Long term history.
TNTPRIV_CLIENTSERVER Client and server.
TNTPRIV_CALCULATION Configure calculations.
TNTPRIV_VIEWHISTORY View history.
190 9AKK101130D1385
Appendix A Tables Tag Security Privileges
Table 25. General Security Privileges.

Privilege name Description
TNTPRIV_WINDOWS Windows operations.
TNTPRIV_ODBC Relational database (ODBC).
TNTPRIV_APPLICATION1 Application specific 1.
TNTPRIV_APPLICATION2 Application specific 2.
Tag Security Privileges
Table 26. Tag Security Privileges.

Privilege Name Description
TNTPRIV_TAGMONITOR Monitor.
TNTPRIV_TAGCONFIGURE Configure.
TNTPRIV_TAGCONTROL Process control.
TNTPRIV_TAGTUNE Tune.
TNTPRIV_TAGDELETE Delete.
TNTPRIV_TAGENTERDATA Enter data.
TNTPRIV_TAGOFFSCAN Off scan.
TNTPRIV_TAGOFFALARM Off alarm check.
TNTPRIV_TAGLIMIT Change alarm limits.
TNTPRIV_TAGACK Acknowledge.
TNTPRIV_TAGMONITORALL Monitor all.
TNTPRIV_TAGREMOTE Remote access.
TNTPRIV_TAGENTERHISTDATA Enter historic data.
9AKK101130D1385 191
Tag Security Privileges Appendix A Tables
192 9AKK101130D1385
9AKK101130D1385 Litho in Italy October 2007
Copyright © 2007 by ABB. All Rights Reserved
® Registered Trademark of ABB.
™ Trademark of ABB.
http://www.abb.com/powergeneration
Product Responsible Unit ucts@de.abb.com

Via Hermada 6
16154 Genoa- Italy
mail: pgp.supportline@it.abb.com

9akk101130d1385 - PGP API Manual

Uploaded by

Document Information

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

9akk101130d1385 - PGP API Manual

Uploaded by

Copyright:

Available Formats

Power Generation Portal

Copyright © 2007 by ABB.

Release: October 2007

Acrobat Registered trademark of Adobe Systems, Incorporated.

Adobe Registered trademark of Adobe Systems, Incorporated.

Advant Registered trademark of ABB Inc.

AdvaBuild Registered trademark of ABB Inc.

Industrial IT Trademark of ABB Inc.

Microsoft Registered trademark of Microsoft Corporation.

Windows Registered trademark of Microsoft Corporation

Section 1 - Application Program Interface

Historical Databases Definition ........................................................................... 43

Section 2 - API Functions

Section 3 - Dynamic Data Exchange

TAGWTD .......................................................................................................... 129

Section 4 - Component Object Model (COM)

Use of Warning, Caution, Information, and Tip Icons

Electrical warning indicates the presence of a hazard which could result in

Caution indicates important information or warning related to the concept

Information alerts the reader to pertinent facts and conditions.

Table 1. Related Documents

Category Title Description

Program Implementation Outline

Table 2. Header Files.

Table 3. Error Codes.

Table 3. Error Codes.

Table 3. Error Codes.

• Automatically activate a program at PGP startup.

Activation from Menu

Activation from Display

HKEY_LOCAL_MACHINE\Software\ABB\Power Generation Portal\Startup

Installation on the Server

Installation on the Client

Connecting to the API Server

The function that performs the connection is named ApmsApiSrvConnect. This

Accessing the Tag Database

unsigned int node: 6 ;

The tag information is manipulated by using the structure TAGINFO, which is a

Table 6. Tag Info Types.

TAGINFOTYPE Type Set Description

Table 6. Tag Info Types.

TAGINFOTYPE Type Set Description

Table 6. Tag Info Types.

TAGINFOTYPE Type Set Description

Table 6. Tag Info Types.

TAGINFOTYPE Type Set Description

Table 6. Tag Info Types.

TAGINFOTYPE Type Set Description

Table 6. Tag Info Types.

TAGINFOTYPE Type Set Description

Refer to the Database section in InformIT Power Generation Portal Configuration

Read/Write Tag Dynamic Data

float val_float;// PV float value

unsigned short q2dumm : 1;// reserved for playback

unsigned short q2i4 : 1;// i4 format if 1, floating point

Table 7. Read/Write Tag Dynamic Data.

Table 7. Read/Write Tag Dynamic Data.

Table 8. RTDB Read/Write Tag List.

Interfacing the Alarm Subsystem

• Maintain group summary information.

Table 9. Queueing Alarms to Alarm Subsystem.

The difference between the two functions is that:

WORD AlarmCode; // Code of the alarm