ND-400 NDA API User Guide

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

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

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

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

Table 1.2-3 Control Functions
NdaContro Issue a control
Table 1.2-4 Alarm Functions
NdaAlarm Raise momentary alarm
Table 1.2-5 Error Handling Functions
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

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.

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

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

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

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:

char *node; // host node name
ULong bufsiz; // maximum packet size (bytes)
status = NdaConnect (nda,node,bufsiz);
NdaConnectUser is called as follows:

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.

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:

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

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

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

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

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

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

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

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_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:

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

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_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:

UWord arg_len; // number of point IDs in “id”
char *epn[n]; // array of point names
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.

Table 4.4-1 Global Error Codes for NdaGetipn
Global
Error Code Meaning
FDB_SUC Success
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.

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:

ULong id; // point ID
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

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:

ULong command; // command code (see Table 5.1-1)
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

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

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:

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

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
Network Database Access Alarm Functions 6-2

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:

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

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

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

ND-400 NDA API User Guide

Hochgeladen von

Dokumentinformationen

Copyright

Verfügbare Formate

Dieses Dokument teilen

Dokument teilen oder einbetten

Freigabeoptionen

Stufen Sie dieses Dokument als nützlich ein?

Sind diese Inhalte unangemessen?

Copyright:

Verfügbare Formate

ND-400 NDA API User Guide

Hochgeladen von

Copyright:

Verfügbare Formate

SurvalentONE

Copyright, Notices and Trademarks

Survalent Technology Corporation

(905) 826 5000

(905) 826 7144

The software described in this document is furnished under

About This Publication

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

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

3 Network Connection Functions 3-1

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

Network Database Access Contents i

4 Database Access Functions 4-1

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

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

1.1 Overview of NDA API

Network Database Access Introduction 1-1

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

• Database Access functions

• Error Handling function

1.2 Function List

Table 1.2-1 Network Connection Functions

Table 1.2-2 Database Access Functions

Network Database Access Introduction 1-2

Table 1.2-3 Control Functions

Table 1.2-4 Alarm Functions

Table 1.2-5 Error Handling Functions

1.3 Error Codes

Table 1.3-1 NDA API Error Codes

Symbol Error Code General Meaning

Network Database Access Introduction 1-3

Symbol Error Code General Meaning

Network Database Access Introduction 1-4

Follow the instructions in the setup window as they appear.

Network Database Access Installation 2-1

2.2 Files Created By Setup

Directory C:\Program Files\Quindar\NDA Client

Directory C:\Program Files\Quindar\SCADACOMMON

Network Database Access Installation 2-2

3 Network Connection Functions

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

NdaFreeEnv is called as follows:

Ndaclient *nda; // nda environment pointer

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

3.3 NdaConnect, NdaConnectUser

NdaConnect is called as follows:

Ndaclient *nda; // nda environment pointer

status = NdaConnect (nda,node,bufsiz);

NdaConnectUser is called as follows:

Ndaclient *nda; // nda environment pointer

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

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

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

Network Database Access Network Connection Functions 3-2