Professional Documents
Culture Documents
ND-400 NDA API User Guide PDF
ND-400 NDA API User Guide PDF
ND-400
Network Database
Access
API USER GUIDE
Version 1.4
ND-400 NDA API User Guide
support@survalent.com
www.survalent.com
FAX (905) 826-7144
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
2 Installation 2-1
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.
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.
• Connect functions
These functions, which allow applications to connect and disconnect from the SCADA host computer, are
described in chapter 3, Network Connection 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.
This function, which translates NDA error codes into corresponding error message text strings, is
described in chapter 7, Error Handling Functions.
The following tables contain a list of the NDA API functions that are available:
Function Description
NdaGetEnv Create Nda environment object
NdaFreeEnv ENENVIRONMENTcENVIRON
Delete Nda environment object
MENT
Connectobject
to host
NdaConnect
NdaDisconnec Disconnect from host
t
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
Function Description
NdaContro Issue a control
Function Description
NdaAlarm Raise momentary alarm
Function Description
NdaErrorToText Convert error code to text string
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.
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.
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)
File Description
NdaCom.dll COM version of the NDA access functions
ScadaProvider.dll OLEDB data provider for SCADA
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.
3.2 NdaFreeEnv
The NdaFreeEnv function deallocates the memory occupied by an Nda environment object.
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.
The “node” parameter is used to specify a list of SCADA host node names or IP addresses.
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.
status = NdaDisconnect(nda);
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 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:
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.
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
Condition Condition
Code
1 Normal
2 Telemetry Failed
3 Manually set
4 Calculated from manually set data
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
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.
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.
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:
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.
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.
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.
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.
Global
Error Code Meaning
FDB_SUC Success
FDB_BAD Bad parameters
FDB_NSF At least one point in “id” does not exist
Individual
Error Code Meaning
FDB_SUC Success
FDB_NSF Point does not exist
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:
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.
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.
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 “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.
Command Meaning
Code
0 Open
1 Close
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.
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.
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.
arg_len = sizeof(data);
status = NdaAlarm (nda, id, skeleton, pri,
(UWord *)otherdata, arg_len, &error]);
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.
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:
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”.
.LastError
Returns string version of the last error
.Host
Returns the current host (string)
.IsConnected
Returns TRUE if currently connected
.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 )
.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