Vous êtes sur la page 1sur 30

SurvalentONE

ND-400
Network Database
Access
API USER GUIDE

Version 1.4
ND-400 NDA API User Guide

Copyright, Notices and Trademarks


Copyright © Survalent Technology Corporation. All rights reserved. The
software described in this document is furnished under license and can
only be used or copied in accordance with the terms of such license. The
content of this manual has been carefully checked for accuracy.
However, if you find any errors, please notify the Survalent Technology
Corporation.

Survalent Technology Corporation


7965 Heritage Road
Brampton, Ontario L6Y 5X5

(905) 826 5000

(905) 826 7144

support@survalent.com

www.survalent.com
FAX (905) 826-7144

The software described in this document is furnished under


license and may only be used or copied in accordance with the
terms of such license.

About This Publication

This manual describes how to install and use the Network Database Access
API (Application Programming Interface) for SCADA
ND-400 NDA API User Guide

Revisions

Version Description
1.0 Initial version for Windows SCADA.
1.1 Add NdaConnectUser
1.2 Correct description of NdaGetIpn
1.3 Updated cover and logo.
1.4 Correct returned data sizes for the NdaGet function
ND-400 NDA API User Guide

Contents

1 Introduction 1-1

1.1 Overview of NDA API ............................................................................................................... 1-1


1.2 Function List .............................................................................................................................. 1-2
1.3 Error Codes................................................................................................................................. 1-3

2 Installation 2-1

2.1 Setup ........................................................................................................................................... 2-1


2.2 Files Created By Setup ............................................................................................................... 2-2

3 Network Connection Functions 3-1

3.1 NdaGetEnv ................................................................................................................................. 3-1


3.2 NdaFreeEnv ................................................................................................................................ 3-2
3.3 NdaConnect, NdaConnectUser .................................................................................................. 3-2
3.4 NdaDisconnect ........................................................................................................................... 3-3

Network Database Access Contents i


ND-400 NDA API User Guide

4 Database Access Functions 4-1

4.1 NdaGet........................................................................................................................................ 4-1


4.2 NdaPut ........................................................................................................................................ 4-5
4.3 NdaGetall.................................................................................................................................... 4-6
4.4 NdaGetipn .................................................................................................................................. 4-7
4.8 NdaAnaExc and NdaStaExc ....................................................................................................... 4-8

5 Control Functions 5-1

5.1 NdaContro .................................................................................................................................. 5-1

6 Alarm Functions 6-1

6.2 NdaAlarm ................................................................................................................................... 6-1

7 Error Handling Functions 7-1

7.1 NdaErrorToText.......................................................................................................................... 7-1

8 NDA Com Interface 8-1

Network Database Access Contents ii


ND-400 NDA API User Guide

1 Introduction

Network Database Access (NDA) is a client/server protocol that was developed by Survalent Technology
Corporation. This protocol is used by the Survalent SCADA system to link the operator workstations to the
host computers.

The Network Database Access API (application programming interface) is a library of functions that allow PC
application programs to access the SCADA system using the NDA protocol. This API is provided to you in
the form of a DLL (dynamically linked library) that you install on the PC. The underlying network protocol
used is TCP/IP.

1.1 Overview of NDA API


The NDA API library is provided as a 32-bit DLL that can be installed on a Windows machine. Installation of
the library onto your PC is described in chapter 2, Installation.

PC application programs that call NDA API functions act as clients to the Survalent NDA server subsystem.

An NdaConnect function is provided to allow a client program to connect to the SCADA system. When a
connection is established, a server process is created on the SCADA system to service the client’s requests.
The connection is maintained until an NdaDisconnect function is called.

If the connection fails while the client application is running (e.g. because of failover), the API automatically
attempts to reconnect several times. If the connection cannot be re-established, and if attempts to access
the second machine of a dual master system also fail, the API returns a connection error indication to the
client application.

Network Database Access Introduction 1-1


ND-400 NDA API User Guide

The following categories of functions are available in the NDA API:

• Connect functions

These functions, which allow applications to connect and disconnect from the SCADA host computer, are
described in chapter 3, Network Connection Functions.

• Database Access functions

These functions, which allow application programs to read and write selected fields from the SCADA
point database, are described in chapter 4, Database Access Functions.

• Control functions

These functions, which allow application programs to issue control requests and monitor the results of
controls, are described in chapter 5, Control Functions.

• Alarm functions

These functions, which allow application programs to read and write SCADA alarms and display fault
messages to the operators, are described in chapter 6, Alarm Functions.

• Error Handling function

This function, which translates NDA error codes into corresponding error message text strings, is
described in chapter 7, Error Handling Functions.

1.2 Function List

The following tables contain a list of the NDA API functions that are available:

Table 1.2-1 Network Connection Functions

Function Description
NdaGetEnv Create Nda environment object
NdaFreeEnv ENENVIRONMENTcENVIRON
Delete Nda environment object
MENT
Connectobject
to host
NdaConnect
NdaDisconnec Disconnect from host
t

Table 1.2-2 Database Access Functions

Function Description
NdaGet Get value from database
NdaPut Put value into database
NdaGetall Get all data for point
NdaGetipn Get point ID
NdaAnaExc Get analog values by exception
NdaStaExc Get status values by exception

Network Database Access Introduction 1-2


ND-400 NDA API User Guide

Table 1.2-3 Control Functions

Function Description
NdaContro Issue a control

Table 1.2-4 Alarm Functions

Function Description
NdaAlarm Raise momentary alarm

Table 1.2-5 Error Handling Functions

Function Description
NdaErrorToText Convert error code to text string

1.3 Error Codes


The error codes returned by the NDA API functions are summarized in Table 1.3-1 below. The names in the
Symbol column of the table are defined in Ndaapi.h (see section 2.2, Files Created by Setup).

Note that in some of the NDA API functions, the returned error codes may have a somewhat different
meaning from the general meanings given in Table 1.3-1. These special meanings are described in chapters
3 to 6.

Table 1.3-1 NDA API Error Codes

Symbol Error Code General Meaning


FDB_SUC 1 Success
FDB_IIV 201 Inconsistent limits
FDB_ODR 202 Value out of range
FDB_DBX 203 Deadband too large
FDB_NDB 204 Negative deadband not allowed
FDB_NST 205 Invalid limit nesting
FDB_ILL_ARGN 0808801C Incorrect number of arguments
FDB_ILL_SCRN 0808802C Invalid screen number
FDB_BAD_FUNC_CODE 0808803C Unknown function code
FDB_BAD 08088054 Bad parameters
FDB_NSF 08088064 No such file/point
FDB_IFC 0808806C Invalid function code
FDB_TMO 08088074 Timeout
FDB_DAO 0808807C Setpoint out of range
FDB_SNC 08088084 Checkback error

Network Database Access Introduction 1-3


ND-400 NDA API User Guide

Symbol Error Code General Meaning


FDB_ONP 0808808C Communication line or RTU undefined
FDB_RSU 08088094 Point already selected

Error codes can be translated into error message text strings by the NdaErrorToText function. See section
7.1, NdaErrorToText.

Network Database Access Introduction 1-4


ND-400 NDA API User Guide

2 Installation

2.1 Setup

This section describes how to install the NDA API onto your PC. Your PC must satisfy the following
requirements:
• It must be running Windows 2xxx or above.
• It must have a network card.
• It must have a TCP/IP stack that conforms to WinSock 1.1 (or later).

If you have all of this, then load the CD labeled “NDA Client API” into your CD-ROM drive and run the
SETUP.EXE program that’s on the CD.

Follow the instructions in the setup window as they appear.

Network Database Access Installation 2-1


ND-400 NDA API User Guide

2.2 Files Created By Setup


If you take the default locations during setup, the setup program creates the following directories and files:

Directory C:\Program Files\Quindar\NDA Client

File Description
Ndaapi.h Header file containing prototypes and error code
definitions
Ndaclient.lib Your application must link to this library
NdaClientWin.dll NDA run time (usually placed in folder with your
application)

Directory C:\Program Files\Quindar\SCADACOMMON

File Description
NdaCom.dll COM version of the NDA access functions
ScadaProvider.dll OLEDB data provider for SCADA

Network Database Access Installation 2-2


ND-400 NDA API User Guide

3 Network Connection Functions

The network connection functions allow application programs to establish and delete connections to a
Survalent SCADA system.

3.1 NdaGetEnv
In an NDA client application, the NDA API maintains context between NDA function calls in an Nda
environment object. This object must be created, using the NdaGetEnv function, before using any other
Nda functions. A pointer to this Nda environment object is a required parameter of all Nda functions other
than NdaGetEnv.

The NdaGetEnv function creates an Nda environment object and returns a pointer to the object. If there is
an error, the function returns zero.

NdaGetEnv is called as follows:

Ndaclient *nda; // pointer to Nda environment object

nda = NdaGetEnv(); // create Nda environment object

Network Database Access Network Connection Functions 3-1


ND-400 NDA API User Guide

3.2 NdaFreeEnv
The NdaFreeEnv function deallocates the memory occupied by an Nda environment object.

NdaFreeEnv is called as follows:

Ndaclient *nda; // nda environment pointer


ULong status; // connection status

status = NdaFreeEnv(nda); // deallocate nda environment


// object

3.3 NdaConnect, NdaConnectUser


The NdaConnect and NdaConnectUser function attempts to connect to the currently active SCADA host
computer.

NdaConnect is called as follows:

Ndaclient *nda; // nda environment pointer


ULong status; // connection status
char *node; // host node name
ULong bufsiz; // maximum packet size (bytes)

status = NdaConnect (nda,node,bufsiz);

NdaConnectUser is called as follows:

Ndaclient *nda; // nda environment pointer


ULong status; // connection status
char *node; // host node name(s)
ULong bufsiz; // maximum packet size (bytes)
char *username; // null-terminated string, user name
char *password; // null terminated string, password

status = NdaConnectUser (nda,node,bufsiz,username,password);

The NdaConnect function is depreciated, as it uses a built in account with greatly reduced privileges.

NdaConnectUser allows the application to connect as a certain user. The user account may be restricted in
the account management of the Scada Explorer.

If the connection is successful, a “1” is returned in “status”. When the connection is established, a server for
client database requests is created on the active SCADA host computer.

If no connection occurs, an error code is returned in “status”.

The “node” parameter is used to specify a list of SCADA host node names or IP addresses.

The list is semicolon delimited. For example “hosta;hostb;hostc”.


If you specify 0 for this parameter, the NdaConnect function uses the default node name of “HOST”. The A or
B suffix of the node name is automatically appended by the NdaConnect function, to accommodate dual-host
configurations.

Network Database Access Network Connection Functions 3-2


ND-400 NDA API User Guide

The “bufsiz” parameter declares the maximum packet size (in bytes) that will be used by the client and server
processes. This value provides some flexibility for tuning the performance of the data transfer over the
network. The default value may be selected by specifying 0 for this parameter. The buffer size parameter
will be most effective when very large amounts of data are being passed back and forth.

In the present release of the NDA API, the bufsiz parameter is accepted but not used. NdaConnect always
uses a default value.

Note that once a connection has been established, the client software attempts to keep the connection open
until the NdaDisconnect function has been called. If the link fails while the application is running, the client
software attempts to reconnect several times. If the link cannot be reconnected, and if attempts to access
the second machine of a dual-host configuration also fail, any NDA request active at the time will return an
error status.

3.4 NdaDisconnect
The NdaDisconnect function is used to disconnect from the currently active SCADA host computer.

NdaDisconnect is called as follows:

Ndaclient *nda; // nda environment pointer


ULong status; // disconnect status

status = NdaDisconnect(nda);

If the disconnect is successful, a “1” is returned in “status”.

If no connection exists, an error code is returned in “status”.

Network Database Access Network Connection Functions 3-3


ND-400 NDA API User Guide

4 Database Access Functions

The database access functions make many fields in both the disk and memory resident SCADA database
available to application programs.

4.1 NdaGet
The NdaGet function takes as inputs a function code and an array of point IDs. It returns a global error code
and arrays of point values, point condition codes and individual point error codes.

The NdaGet function is called as follows:

Ndaclient *nda // nda environment pointer


ULong status; // connection status
UWord arg_len; // number of elements in id, value,
// cond and error arrays
ULong func; // function code (see Table 4.1-1,
// Functions for NdaGet)
ULong ierror; // global error code
Ulong id[n]; // array of point IDs
Ubyte value[n]; // array of bytes to receive
// returned values
Ubyte cond[n]; // array of elements to receive
// returned condition codes
ULong error[n]; // array of elements to receive
// individual point error codes

status = NdaGet (nda, arg_len, func, &ierror, id, value,


cond, error);

The array size “arg_len” must be at least one, and the size of the arrays “id”, “value”, “cond” and “error”
should all be equal to “arg_len”. If the size of “id” is smaller than “arg_len”, then “point not found” errors will
result. If the size of the “value”, “cond” or “error” arrays are smaller than “arg_len”, then other data structures
will be over-written.

Although the “value” buffer is necessarily a byte array, you may use a more convenient array and cast it into a
UByte array. To bring back an array of three analog point values, for example, you can do:

Network Database Access Database Access Functions 4-1


ND-400 NDA API User Guide

double a_values[3]; // array of three analog point


// values (doubles)

status = NdaGet (nda, 3, 41, &ierror, id, (Ubyte *)a_values,


cond, error);

Both network and CPU overhead are much lower with one multi-point call (where “arg_len” is greater than 1)
than with a corresponding number of single point calls (where “arg_len” is 1).

If the global error code is success, all the returned point values may be assumed to have been successfully
retrieved.

If the global error code is FDB_BAD or FDB_IFC, then none of the returned point values may be used.

If the global error code is FDB_NSF, some of the returned point values may be used and some may not. The
FDB_NSF code is returned if one or more of the point IDs supplied in the “id” array were found to be invalid.
The individual point error array “error” may be examined to determine which points had errors. Returned
values for points whose individual point error code is “success” may safely be used.

Table 4.1-1 identifies the valid function codes for the NdaGet function and the corresponding number of bytes
returned per point in the “value” array.

A point’s zones are returned as a 15-character text string (not null-terminated) in the same format that you
see on the Station Editor .

A status point’s alarm severity codes are returned in four consecutive bytes (byte 0 contains the severity code
for state 0, etc.). An analog point’s alarm severity codes are returned in eight consecutive bytes as listed in
Table 4.1-8.

Table 4.1-1 Function Codes for NdaGet

Bytes
Functio Returned
n Per Point Description of data returned for each point
Code
2 64 Point name, station name in first 32 bytes, left justified and blank padded,
point name in last 32 bytes, left justified and blank padded
4 1 Point type code (see Table 4.1-2)
5 128 Point description, left justified and blank padded
7 1 Condition code (see Table 4.1-3)
23 16 Engineering units
41 8 Analog point value
42 1 Status point value
43 128 Text point value, left justified and blank padded

Network Database Access Database Access Functions 4-2


ND-400 NDA API User Guide

Table 4.1-2 Point Type Codes

Point Type Point Type


Code
1 Station
2 Text
3 Unused
4 Analog
5 Unused
6 Status
7 Unused

Table 4.1-3 Condition Codes

Condition Condition
Code
1 Normal
2 Telemetry Failed
3 Manually set
4 Calculated from manually set data

Table 4.1-4 Device Class Codes for Status Points

Device Class Code Device Class


1 Momentary Alarm
2 Sustained Alarm
3 Non-Alarm
4 Dual-Bit Valve
5 Breaker
6 Trip Alarm

Table 4.1-5 Device Class Codes for Analog Points

Device Class Code Device Class


1 Analog Input
2 Parameter
3 Setpoint
4 Lead/Lag Point

Network Database Access Database Access Functions 4-3


ND-400 NDA API User Guide

Table 4.1-6 Tag State Codes

Tag State Tag State


Code
0 Normal
1 Tagged
2 Selected for control
3 Selected, checkback received
4 Opening
5 Closing
6 Interlocked

Table 4.1-7 Limit State Codes

Limit State Limit State


Code
7 Above upper reasonability limit
6 Above upper emergency limit
5 Above upper pre-emergency limit
4 Normal
3 Below lower pre-emergency limit
2 Below lower emergency limit
1 Below lower reasonability limit

Table 4.1-8 Alarm Severity Codes Returned for Analog Point

Byte Severity Code


0 Upper pre-emergency
1 Lower pre-emergency
2 Upper emergency
3 Lower emergency
4 Upper reasonability
5 Lower reasonability
6 Return-to-normal
7 Rate-of-change

Table 4.1-9 Global Error Codes for NdaGet

Global Error
Code Meaning
FDB_SUC Success
FDB_BAD Bad parameters
FDB_IFC Invalid function code
FDB_NSF At least one point in “id” does not exist or is of the wrong type

Network Database Access Database Access Functions 4-4


ND-400 NDA API User Guide

Table 4.1-10 Individual Point Error Codes for NdaGet

Individual
Error Code Meaning
FDB_SUC Success
FDB_NSF Point does not exist or is of the wrong type

4.2 NdaPut
The NdaPut function takes as inputs a function code, an array of point IDs, and a corresponding array of
values to be written into the points. It returns a global error code and individual point error codes. Points
whose values are updated by this function are not marked “manually set”, but they are subject to the normal
SCADA alarm processing.

The NdaPut function is called as follows:

Ndaclient *nda // nda environment pointer


UWord arg_len; // number of point IDs in “id”
ULong func; // function code (see Table 4.2-1,
// Functions for NdaPut)
ULong ierror; // global error code
ULong id[n]; // array of “arg_len” point IDs
UByte value[m]; // array of bytes containing data
// to be written
ULong error[n]; // array to receive individual point
// error codes

status = NdaPut (nda, arg_len, func, &ierror, id, value,


error);

If the global error code is FDB_SUC, all the point values may be assumed to have been successfully stored.

If the global error code is FDB_BAD or FDB_IFC, then none of the point values have been stored.

If the global error code is FDB_NSF, some of the point values have been stored while some have not. The
FDB_NSF code is returned if one or more of the point IDs supplied in the “id” array were found to be invalid.
The individual point error array “error” may be examined to determine which points were in error. Values for
points whose individual point error code is success have been stored.

Table 4.2-1 identifies the valid function codes for the NdaPut function and the type of data stored.

Table 4.2-1 Function Codes for NdaPut

Functio Bytes
n Written Description of Data Stored
Code Per Point
41 8 Analog point value (unless manually set)
42 1 Status point value (unless manually set)
43 128 Text point value (unless manually set), left justified and blank padded

Network Database Access Database Access Functions 4-5


ND-400 NDA API User Guide

For tables of legal condition and tag state codes that may be written via function codes 7, 8 and 39, see the
following tables in section 4.1, NdaGet:

• Table 4.1-3 Condition Codes


• Table 4.1-6 Tag State Codes

Table 4.2-2 Global Error Codes for NdaPut

Global Error Code Meaning


FDB_SUC Success
FDB_BAD Bad parameters
FDB_IFC Invalid function code
FDB_NSF At least one point in “id” does not exist or is of the wrong type

Table 4.2-3 Individual Point Error Codes for NdaPut

Individual
Error Code Meaning
FDB_SUC Success
FDB_NSF Point does not exist or is of the wrong type

4.3 NdaGetall
The NdaGetall function can be used to obtain all of the available data (except value) about a single point in
one call. It accesses both disk and memory resident data.

NdaGetall may be called as follows:

Ndaclient *nda; // nda environment pointer


Ulong id; // point ID
char *epn; // point name
ULong error; // error code
ULong type; // point type code
char *desc; // point description
UByte cnd; // condition code (UNUSED)
char *s0; // status string for state 0 (UNUSED)
char *s1; // status string for state 1 (UNUSED)
char *s2; // status string for state 2 (UNUSED)
char *s3; // status string for state 3 (UNUSED)
char *eng; // engineering units (UNUSED)
UByte b1,b2; // application data on disk (UNUSED)
UWord w1,w2; // application data on disk (UNUSED)
float f1,f2; // application data on disk (UNUSED)

status = NdaGetall (nda,id, epn, &error, &type, desc, NULL,


&cnd, NULL, NULL, NULL, NULL, NULL,
NULL, NULL, NULL, NULL, NULL, NULL);

The seventh argument in the NdaGetall function is a placeholder for a presently unused parameter and may
be set to zero.

Network Database Access Database Access Functions 4-6


ND-400 NDA API User Guide

For tables of point type and condition codes that may be returned in the “type” and “cnd” arrays, see section
4.1, NdaGet.

Note that the NdaGetall function requires disk access on the SCADA host computer and should be used
carefully.

Table 4.3-1 Error Codes for NdaGetall

Error Code Meaning


FDB_SUC Success
FDB_BAD Bad parameters
FDB_NSF Point does not exist

4.4 NdaGetipn
The NdaGetipn function obtains the point IDs for a set of point names. Each point name is specified in a
ten-character ASCII string. For each point name, the database server on the SCADA host searches the
symbol table for a match. If the point name is found, the point’s ID and point type code are returned. If no
match is found, an FDB_NSP error is reported.

The NdaGetipn function is called as follows:

Ndaclient *nda; // nda environment pointer


UWord arg_len; // number of point IDs in “id”
char *epn[n]; // array of point names
ULong ierror; // global error code
ULong id[n]; // array to receive point IDs
ULong error[n]; // array to receive individual point
// error codes
ULong type[n]; // array to receive point type codes

status = NdaGetipn (nda, arg_len, epn, &ierror, id, error,


type);

Each element of the point name array “epn” is a pointer to a string consisting of the station name, a comma,
and the point name.

For a table of possible point type codes that may be returned in the “type” array, see Table 4.1-2, Point Type
Codes, in section 4.1, NdaGet.

A global error code of FDB_SUC means that all of the point names were successfully looked up and
translated into point IDs.

If the global error code is FDB_BAD, then none of the point names were looked up.

If the global error code is FDB_NSF, some of the point names have been successfully looked up while some
have not. The individual point error array may be examined to determine which point names were not found.
Returned IDs for points whose individual point error code is success may safely be used.

Note that the NdaGetipn function requires disk access on the SCADA host and should be used carefully. If
the application intends to access points frequently, it should use the NdaGetipn function at startup to collect
the required point IDs for later use.

Network Database Access Database Access Functions 4-7


ND-400 NDA API User Guide

Table 4.4-1 Global Error Codes for NdaGetipn

Global
Error Code Meaning
FDB_SUC Success
FDB_BAD Bad parameters
FDB_NSF At least one point in “id” does not exist

Table 4.4-2 Individual Point Error Codes for NdaGetipn

Individual
Error Code Meaning
FDB_SUC Success
FDB_NSF Point does not exist

4.8 NdaAnaExc and NdaStaExc


These two functions take a buffer address and a buffer length as arguments and return as many exceptions
as will fit in the buffer. If there are more exceptions, a “more” flag is returned to prompt the client to call
again. The NdaAnaExc function returns only analog exceptions. The NdaStaExc function returns only status
exceptions.

A point is considered to have changed (be in exception) if either its value or its condition code has changed
since the last call. On the first call after an initial connection and on any subsequent re-connection, the server
will treat all points as being in exception.

Each exception entry contains a point ID, a value, a condition code and a timestamp. The structure of
each exception entry is defined as follows:

typedef struct ExcBuffer {


ULong id: // point id
union
{
long stat; // status value
float floater; // analog value
} values;
long cond; // condition code
NumTime timestamp; // timestamp
} ExcBuffer;

The status values are integers in the range 0 to 3. The analog values are floats in engineering units. The
condition code values are the same as those described for NdaGet in Table 4.1-3.

Network Database Access Database Access Functions 4-8


ND-400 NDA API User Guide

The timestamp is a structure called NumTime, which is defined as:

typedef struct NumTime {


Word year;
Word month;
Word day;
Word minute;
Word second;
Word tick;
Word ticks_per_second;
} NumTime;

Both of these structures are defined in the Ndaapi.h include file, which is included in the kit.

The buffer length is specified as a number of exception entries that can fit into the buffer. It is therefore
convenient to specify your buffer as an array of “n” ExcBuffer structures, and specify “n” (or something less)
as the length of your buffer.

The NdaAnaExc and NdaStaExc functions may be called as follows:

Ndaclient *nda; // nda environment pointer


ULong id; // point ID
ULong error; // error code
ExcBuffer buf[500]; // buffer (contains 500 exception
// entries)
UWord buflen = 500; // buffer length
UWord excNum; // number of returned exceptions
UWord more; // “more” flag

status = NdaAnaExc (nda, &ierror, buf, &buflen, &excNum, &more)


status = NdaStaExc (nda, &ierror, buf, &buflen, &excNum, &more)

Table 4.8-1 Error Codes for NdaAnaExc and NdaStaExc

Error Code Meaning


FDB_SUC Success
FDB_BAD Invalid calling parameters
FDB_NSF Point does not exist or is not an analog point

Network Database Access Database Access Functions 4-9


ND-400 NDA API User Guide

5 Control Functions

The control functions provide application programs the ability to issue control requests and monitor the
results of controls.

5.1 NdaContro
The NdaContro function allows an application program to perform control operations. It accepts a point ID, a
command code and a reply code, and returns an error indication. The reply code tells the SCADA control
software what kind of result notification the application program wants to have.

The NdaContro function may be called as follows:

Ndaclient *nda; // nda environment pointer


ULong id; // point ID
ULong command; // command code (see Table 5.1-1)
ULong error; // error code
ULong reply; // reply code (see Table 5.1-2)
Ulong screen; // screen number

status = NdaContro (nda, id, command, &error, reply, screen);

The “screen” parameter is used by the SCADA system’s operator interface software so that event logs of
controls can include the current SCADA login account. In your PC applications, you should set the “screen”
parameter to zero.

Table 5.1-1 Command Codes

Command Meaning
Code
0 Open
1 Close

Network Database Access Control Function 5-1


ND-400 NDA API User Guide

Table 5.1-2 Reply Codes

Reply Meaning
Code
0 No reply is requested
1 Ask for checkback result
2 Ask for both checkback result, and if successful, the status change too

Reply Code 0

Beyond acknowledgement of the control request, the application is not asking for any checkback or
control result status when specifying reply code 0.

Reply Code 1

When specifying reply code 1, the application is asking for and will wait for checkback confirmation
from the SCADA telemetry subsystem (this is done within the NdaContro function). The application
must examine the database itself to determine whether the command completed successfully (e.g.
whether the breaker has in fact opened or closed).

Reply Code 2

When specifying reply code 2, the application is not only asking and waiting for checkback
verification, but in addition asking the telemetry subsystem to notify it when the execution of the
command has either succeeded or timed out.

In the case of reply code 2, the NdaContro function does not itself wait for the result notification. The
application must call either the NdaCcheck or the NdaCwait function to actually pick up the notification. See
sections 5.2, NdaCcheck, and 5.3, NdaCwait.

The timeout value for the command is an attribute of the point involved (defined via the Station Editor). For
points with multiple status change validation, the returned success/failure status will be based on the
success/failure of the entire MSCVAL sequence.

Table 5.1-3 Error Codes for NdaContro

Error Code Meaning


FDB_SUC Success
FDB_BAD Bad calling parameters
FDB_IFC Command code is invalid
FDB_NSF Point does not exist or is not a controllable status point
FDB_RSU Point is tagged or interlocked or already selected for control,
or RTU is busy, or all control timers are in use
FDB_SNC Checkback failure
FDB_ONP Communication line or RTU undefined

Note that if your application issues several control commands in a row and then uses NdaCcheck to validate
their results, the program must be prepared to handle the results coming back in a different order from that in
which the commands were issued.

Network Database Access Control Function 5-2


ND-400 NDA API User Guide

6 Alarm Functions

The alarm functions allow application programs to raise SCADA alarms and display fault messages.

6.2 NdaAlarm
The NdaAlarm function allows an application program to raise a momentary alarm. The function accepts a
point ID, a message format number (alarm skeleton), a priority code and an optional array of other data. The
function sends a message containing the alarm request to the SCADA alarm subsystem, and does not ask
for or wait for a reply.

The NdaAlarm function may be used as follows:

Ndaclient *nda; // nda environment pointer


ULong id; // point ID
ULong skeleton; // alarm skeleton number (0 - 127)
ULong pri; // alarm priority code (0 - 4)
OtherData otherdata; // structure of other data to be
// included in the alarm message
UWord arg_len; // length of “otherdata”
ULong error; // returned error code

arg_len = sizeof(data);
status = NdaAlarm (nda, id, skeleton, pri,
(UWord *)otherdata, arg_len, &error]);

Network Database Access Alarm Functions 6-1


ND-400 NDA API User Guide

The “otherdata” parameter can be any structure cast as an array of UWords. If your alarm data structure is
just a string, for example, you could do:

char* string;
string = “THIS IS AN ALARM MESSAGE”
arg_len = strlen(string);
status = NdaAlarm (nda, id, skeleton, pri, (UWord *)string,
arg_len, &error]);

The alarm skeleton number specifies the alarm skeleton that the SCADA alarm subsystem will use to format
the alarm message. Only skeleton numbers 0-127 may be used with this function.

The alarms skeletons are defined on the Alarm Skeletons editor (ALMSKL), and may be defined to format
data contained in the “otherdata” parameter in this function. When the alarm subsystem encounters certain
format codes in the alarm skeleton, it unpacks the corresponding type and quantity of data from the
“otherdata” area and advances a pointer. For example,

Code Action

In Take the next two bytes from “otherdata”, advance the pointer to “otherdata” by 2, treat the data as a
“Word” and format an n-wide ASCII representation of the integer.

Fm.n Take the next four bytes from “otherdata”, advance the pointer to “otherdata” by 4, treat the data as a
“float” and format an m-wide ASCII representation of the floating point value (with n decimal digits).

Bn Take the next “n” bytes from “otherdata”, advance the pointer to “otherdata” by “n”, and copy the
bytes (text characters) directly into the alarm message.

The alarm raised by the NdaAlarm function is processed by the SCADA alarm subsystem in the same
manner as alarms generated by the SCADA system itself.

Table 6.2-1 Error Codes for NdaAlarm

Error Code Meaning


FDB_SUC Success
FDB_BAD Bad parameters

Network Database Access Alarm Functions 6-2


ND-400 NDA API User Guide

7 Error Handling Functions

7.1 NdaErrorToText
The NdaErrorToText converts NDA error codes to text strings.

The NdaErrorToText function is called with the error code as an input. It returns a pointer to a corresponding
text string as follows:

Ndaclient *nda; // nda environment pointer


ULong error; // error code
char *msg; // string containing returned error
// message text

msg = NdaErrorToText (nda, error);

NdaErrorToText returns a pointer to the string “Success” if the status indicates success. An unknown status
value will return a pointer to the text string “Unknown status”.

The NdaErrorToText function can be used in calls to printf or fprintf, as in:

fprintf(stream, “Connect returned <%s>\n”,


NdaErrorToText(nda, status));

Network Database Access Error Handling Function 7-1


ND-400 NDA API User Guide

8 NDA Com Interface


The following functions are available in the COM version of the NDA interface
This interface is implemented in NDACOM.DLL.

Nda Function .Connect(BSTR szHosts)


Take a semicolon-delimited list of host names or TCP/IP addresses.

.ConnectC(BSTR szHosts, BSTR username, BSTR password)


Take a semicolon-delimited list of host names or TCP/IP addresses.

.LastError
Returns string version of the last error

.Host
Returns the current host (string)

.IsConnected
Returns TRUE if currently connected

.PointNameToPid( sStation, sPoint )


Returns Long Int PID or Zero

.ClearPoints
Clear point list used in LoadPointData

.AddPoint(long nPid)
Add the point is to the list used in LoadPointData

.Disconnect
Disconnect from master

.LoadPointData
Load point data for point is list build by AddPoint

.PointCount
Returns number of point in list used by LoadPointData

.PointPid(long nIndex )
Return the PID used by list entry nIndex

.PointName(long nIndex )
Returns name of the point at the nIndex entry in the list used by LoadPointData

.PointEngUnits(long nIndex)
Returns the engineering units string used by the nIndex point

.PointDescription(long nIndex )

Network Database Access NDA COM Interface 8-1


ND-400 NDA API User Guide

Return the description string used by the nIndex point

.PointTypeCode(long nIndex )
Return the point type code of the nIndex point

.PointConditionCode(long nIndex )
Returns the condition code of the nIndex point

.PointStatus(long nIndex )
Return the point status (small integet) of the nIndex point

.PointValue(long nIndex )
Returns the (double) floating point value of the nIndex point

.PointText(long nIndex )
Returns the text string value of the nIndex point

.PointError(long nIndex)
Returns the error code (0= success) accociated with the data for point nIndex

.PointErrorMessage(long nIndex)
Return the readable string for the nIndex point

.PointStationname(long nIndex)
Return the station name of the point at nIndex

.PointFullName(long nIndex)
Returns the full point name string (“xxxx,yyyyyy”) of the point at nIndex

.PointSetStatus(long nPid, long nValue, long nCondition )


Set the value of status point nPid fo nValue (0-3) with condition nCondition (1-6)

.PointSetValue(long nPid, double nValue, long nCondition )


Set the floating point value of analog point nPid to nValue with condition nCondition (1-6)

.PointSetText(long nPid, BSTR nString, long nCondition )


Set the text string current value of the text point nPid to sString with condition code
nCondition (1-6)

.PointRaiseAlarm(long nPid, long nFormat, long nPriority, BSTR sText )


Raise momentary alarm against point nPid (can be zero) at priority nPriority (0-10), with
additional formatted text sText.

.PointControlStatus(long nPid, long nStatus, long nReplyType)


Attempt to control the point nPid to the state nStatus (0-1) waiting for
( nReplyType 0 = nothing, 1 = control checkback success/fail, 2 = status change
success/timeout )

Network Database Access NDA COM Interface 8-2