Application Development Guide EXDOC XXX5 en 120
Application Development Guide EXDOC XXX5 en 120
Application Development Guide EXDOC XXX5 en 120
EXDOC-XXX5-en-120A
February 2015
Release 120
Document Release Issue Date
EXDOC-XXX5-en-120A 120 0 February 2015
Disclaimer
This document contains Honeywell proprietary information. Information contained herein is to be used solely
for the purpose submitted, and no part of this document or its contents shall be reproduced, published, or
disclosed to a third party without the express permission of Honeywell International Sàrl.
While this information is presented in good faith and believed to be accurate, Honeywell disclaims the implied
warranties of merchantability and fitness for a purpose and makes no express warranties except as may be stated
in its written agreement with and for its customer.
In no event is Honeywell liable to anyone for any direct, special, or consequential damages. The information
and specifications in this document are subject to change without notice.
Copyright 2015 - Honeywell International Sàrl
2 www.honeywell.com
Contents
3
CONTENTS
4 www.honeywell.com
CONTENTS
c_dataio_...() ............................................................................................................................................................ 96
DeassignLrn() ........................................................................................................................................................ 102
c_deltsk() ............................................................................................................................................................... 103
DbletoPV() ............................................................................................................................................................. 104
dsply_lrn() .............................................................................................................................................................. 105
c_ex() ..................................................................................................................................................................... 106
ftocstr() .................................................................................................................................................................. 107
c_gbload() .............................................................................................................................................................. 108
c_gdbcnt() .............................................................................................................................................................. 109
c_getapp() .............................................................................................................................................................. 110
GetGDAERRcode() ............................................................................................................................................... 111
c_geterrno() ............................................................................................................................................................ 112
c_gethstpar_..._2() ................................................................................................................................................. 113
c_getlrn() ................................................................................................................................................................ 116
c_getlst() ................................................................................................................................................................ 117
c_getprm() .............................................................................................................................................................. 118
c_getreq() ............................................................................................................................................................... 120
c_givlst() ................................................................................................................................................................ 122
hsc_asset_get_ancestors() ...................................................................................................................................... 123
hsc_asset_get_children() ........................................................................................................................................ 124
hsc_asset_get_descendents() ................................................................................................................................. 125
hsc_asset_get_parents() ......................................................................................................................................... 126
hsc_em_FreePointList() ......................................................................................................................................... 127
hsc_em_GetLastPointChangeTime() ..................................................................................................................... 128
hsc_em_GetRootAlarmGroups() ........................................................................................................................... 129
hsc_em_GetRootAssets() ...................................................................................................................................... 130
hsc_em_GetRootEntities() ..................................................................................................................................... 131
hsc_enumlist_destroy() .......................................................................................................................................... 132
hsc_GUIDFromString() ......................................................................................................................................... 133
hsc_insert_attrib() .................................................................................................................................................. 134
Attribute Names and Index Values ............................................................................................................ 136
Valid Attributes for a Category .................................................................................................................. 138
hsc_insert_attrib_byindex() ................................................................................................................................... 139
hsc_IsError() .......................................................................................................................................................... 142
hsc_IsWarning() ..................................................................................................................................................... 143
hsc_lock_file() ....................................................................................................................................................... 144
hsc_lock_record() .................................................................................................................................................. 145
hsc_notif_send() .................................................................................................................................................... 146
hsc_param_enum_list_create() .............................................................................................................................. 149
hsc_param_enum_ordinal() ................................................................................................................................... 151
hsc_param_enum_string() ..................................................................................................................................... 152
hsc_param_format() ............................................................................................................................................... 153
hsc_param_limits() ................................................................................................................................................ 155
hsc_param_subscribe() .......................................................................................................................................... 157
hsc_param_list_create() ......................................................................................................................................... 158
hsc_param_name() ................................................................................................................................................. 160
hsc_param_number() ............................................................................................................................................. 161
hsc_param_range() ................................................................................................................................................ 162
hsc_param_type() .................................................................................................................................................. 164
hsc_param_value() ................................................................................................................................................. 166
hsc_param_value_of_type() .................................................................................................................................. 168
hsc_param_values() ............................................................................................................................................... 169
hsc_param_value_put() .......................................................................................................................................... 172
hsc_param_values_put() ........................................................................................................................................ 174
5
CONTENTS
6 www.honeywell.com
CONTENTS
7
CONTENTS
8 www.honeywell.com
About this guide
This guide describes how to write applications for Experion, Release 120.
Revision history
Revision Date Description
A January 2015 Initial release of document.
9
ABOUT THIS GUIDE
10 www.honeywell.com
Server API reference
This section describes how to write applications for Experion using the Server API.
Attention
An application written for the local server is only available locally to the server, and not remotely across a network.
For information about writing applications that can access the server database across a network, see “Network
application programming” on page 263.
For: Go to:
Prerequisites “Prerequisites” on page 12
An introduction to the development environment “About the Server API development environment” on
page 13
An introduction to the types of applications you can “Implementing a Server API application” on page 21
develop: tasks and utilities
Information about integrating your application with “Controlling the execution of a Server API application” on
Experion page 29
A description of the Experion database, and how you access “Accessing server data” on page 39
data
Information about writing applications for Station “Working from a Station” on page 59
Information about writing interfaces for unsupported “Developing user scan tasks” on page 65
controllers (user scan tasks)
Development utilities “Development utilities” on page 75
C application library “Application Library for C and C++” on page 87
Related topics
“Prerequisites” on page 12
11
SERVER API REFERENCE
Prerequisites
Before writing applications for Experion, you need to:
• Install Experion and third-party software as described in .
• Be familiar with user access and file management as described in the Configuration Guide.
Prerequisite skills
This guide assumes that you are an experienced programmer with a good understanding of either C or C++.
Attention
An application written for the local server using the Server API must be written in C or C++, as the Server API does
not support other programming languages such as Visual Basic or the .NET languages
It also assumes that you are familiar with the Microsoft Windows development environment and know how to
edit, compile and link applications.
12 www.honeywell.com
About the Server API development environment
If development is to be conducted on a target system, consideration must be given to the potential impact on the
systems performance during the development.
Use of these facilities requires a high level of expertise in the development tools, including C compiler, C++
compiler, linker, make files and batch files.
Related topics
“Using Microsoft Visual Studio to develop Server API applications” on page 14
“Folder structures for C/C++ applications” on page 16
“Multithreading considerations for Server API applications” on page 17
“Error codes in the Server API” on page 18
“Validating IEEE 754 special values” on page 19
“Using Microsoft Visual Studio to develop Server API applications” on page 14
“Folder structures for C/C++ applications” on page 16
“Multithreading considerations for Server API applications” on page 17
13
ABOUT THE SERVER API DEVELOPMENT ENVIRONMENT
Related topics
“About the Server API development environment” on page 13
“Setting up debugging utilities and tasks” on page 14
Attention
This procedure will only work with C and C++ projects. After compiling and linking, all executable files should be
copied to the run folder.
Related topics
“Setting up debugging utilities and tasks” on page 14
14 www.honeywell.com
ABOUT THE SERVER API DEVELOPMENT ENVIRONMENT
Attention
When using the DBG utility, make sure that no other application executes a gbload() before your application,
otherwise it will be assigned the LRN you specified in step .
Related topics
“Using Microsoft Visual Studio to develop Server API applications” on page 14
“Compiling and linking C and C++ projects” on page 14
“Error codes in the Server API” on page 18
“ETR” on page 81
15
ABOUT THE SERVER API DEVELOPMENT ENVIRONMENT
<server directory>
src
Related topics
“About the Server API development environment” on page 13
16 www.honeywell.com
ABOUT THE SERVER API DEVELOPMENT ENVIRONMENT
Example
// Main code segment
CRITICAL_SECTION serAPI;
/*critical section for calling the Server APIs */
InitializeCriticalSection(&serAPI);
if (c_gbload())
{
/* Could not attach to database */
exit(-1);
}
... Create threads
... Execution continues on
//End of main code segment
Related topics
“About the Server API development environment” on page 13
17
ABOUT THE SERVER API DEVELOPMENT ENVIRONMENT
Attention
Any applications that use the function c_geterrno() must include the M4_err.h header file, that is, #include <src/
M4_err.h>.
Example
This example shows how to check the error status:
if (c_server_api_function(arg1, arg2) == -1)
{
int errcode = c_geterrno();
if (hsc_IsError(errcode))
{
// an error has been issued
// handle error here
// or pass to your error handler
}
else
{
// a warning has been issued
// handle warning here
// or may be safe to ignore
}
}
See also
“c_geterrno()” on page 112
Related topics
“Setting up debugging utilities and tasks” on page 14
18 www.honeywell.com
ABOUT THE SERVER API DEVELOPMENT ENVIRONMENT
Attention
These functions are platform dependent (only valid for an INTEL X86 system).
1 2 3
Element Description
1 Sign
2 Exponent
3 Mantissa
The LSB (Least Significant Bit, the one that if changed would cause the smallest variation of the represented
value) with index 0 is positioned on the right.
19
ABOUT THE SERVER API DEVELOPMENT ENVIRONMENT
Zero The value Zero (0) is represented with an exponent field of zero and a mantissa field of zero.
Depending on the sign bit, it can be a positive zero or a negative zero. Thus, -0 and +0 are distinct
values, though they are treated as equal.
Infinity The value infinity is represented with an exponent of all 1s and a mantissa of all 0s. Depending on
the sign bit, it can be a positive infinity or negative infinity. The infinity is used in case of the
saturation on maximum representable number so that the computation could continue.
NaN The value NaN (Not a Number) is represented with an exponent of all 1s and a non-zero mantissa.
NaN's are used to represent a value that does not represent a real number, and are designed for use in
computations that may generate undefined results, so that the computations can continue without a
numeric value. The NaN value usually propogates to the result, to help indicate that a numeric value
was missing in the calculation.
See also
“Data types” on page 25
20 www.honeywell.com
Implementing a Server API application
Related topics
“Application choices” on page 22
“C/C++ application template” on page 23
“Server redundancy” on page 27
“Developing an OPC client” on page 28
21
IMPLEMENTING A SERVER API APPLICATION
Application choices
Before you can implement a Server API application you will need to make a choice on the programming
language you will use and the type of application you are going to implement.
Related topics
“Programming languages” on page 22
“Type of application” on page 22
Programming languages
The Server Application Programming Library only supports the development of C/C++ applications.
The language you choose to use will largely depend on your experience with these languages. Alternatively, it is
possible to develop an OPC Client to access server data via the Experion OPC Server. The client can be written
in C or C/++.
Type of application
There are two types of application you can develop:
• Utility. A utility runs interactively from the command line using . ( is opened by choosing .)
Utilities typically perform an administrative function or a function that is performed occasionally.
A utility can prompt the user for more information and can display information directly to the user via the
command prompt window.
An example of a utility is an application to dump the contents of a database file to the command prompt
window, for example “FILDMP” on page 82.
• Task. Tasks are usually dormant, waiting for a request to perform some form of function. When they are
activated, they perform the function and then go back to sleep to wait for the next request to come along.
An example of a task is an application that periodically fetches some point values, performs a calculation on
the values and stores the result back in the database.
22 www.honeywell.com
IMPLEMENTING A SERVER API APPLICATION
Related topics
“Definitions” on page 23
“Initialization” on page 23
“Main body of a utility” on page 24
“Main body of a task” on page 24
“Data types” on page 25
“Writing messages to the log file” on page 26
Definitions
A C/C++ application also needs to contain several include files that declare and define items used by the
application programming library routines. These include files should be incorporated in the main source file as
well as any function source files that make calls to the application programming library routines. The include
files used by this template are:
The include folder also contains many other GBxxxxxx.h include files that may be needed if you make calls to
other application programming library routines.
#include <src/defs.h>
#include <src/M4_err.h>
#include <files>
#include <parameters>
#include <src/GBtrbtbl.h>
char *progname='myapp.c';
main()
{
uint2 ierr;
char string[80];
struct prm prmblk;
Initialization
The first function you must call in any application is GBLOAD. This function makes the global common
memory available to the application, allowing it to accesses the memory-resident part of the database. If this call
fails you should terminate the program. This function should only be called once for the whole program.
if (ierr=c_gbload())
{
//The next line number is 137
c_logmsg(progname, '137', 'Common
Load Error %d\n', ierr);
c_deltsk(-1);
23
IMPLEMENTING A SERVER API APPLICATION
c_trmtsk(ierr);
}
24 www.honeywell.com
IMPLEMENTING A SERVER API APPLICATION
}
}
The c_getreq function will return a FALSE (0) if there is has been a request. It will return the error
M4_EOF_ERR (0x21f) if there are no requests pending. If any other error is returned, then this should be
reported and optionally handled.
Data types
In the definitions section, you may have noticed the use of the C/C++ data type uint2. This is one of several
data types that are defined in the header file defs.h. This is necessary because different C and C++ compilers
define the different sizes for: int, long, float, and double.
The following data types are used throughout the application programming library routines:
Macro Description
ldint4(int2_ptr) Load an int4 value from the database (pointed to by int2_ptr).
stint4(int2_ptr, int4_val) Store an int4 value in the database at the position pointed to by int2_ptr.
ldreal(int2_ptr) Load a real value from the database.
streal(int2_ptr,real_val) Store a real value in the database.
lddble(int2_ptr) Load a double value from the database.
stdble(int2_ptr,dble_val) Store a double value in the database.
These macros help to ensure that all types are properly assigned in C/C++ programs, to provide portability
between different computer architectures.
One example of the use of such macros is provided below. This example shows how a C program would assign
a floating point value to a variable, and also how a floating point value may be stored in the database.
#include <src/defs.h>
#include <src/GBsysflg.h>
.
float fval1;
float fval2;
.
.
.
/*load the seconds since midnight into the variable fval1 */
fval1 = ldreal(GBsysflg->syssec);
.
.
/* store the value of fval2 into the seconds since midnight */
streal (&GBsysflt->syssec, fval2);
.
.
.
25
IMPLEMENTING A SERVER API APPLICATION
The other macros mentioned above are used in a similar manner. For the definitions of these macros, consult the
defs.h file.
Instead of:
printf('Point ABSTAT001 PV out of normal range (%d)\n' abpv);
or
fprintf(stderr,'Point ABSTAT001 PV out of normal range (%d)\n',abpv);
or
std::cout <<'Point ABSTAT001 PV out of normal range' <<abpv <<std::endl;
Use:
c_logmsg ('abproc.c', '134', 'Point ABSTAT001 PV out of normal range (%d)',abpv);
Attention
c_logmsg handles all carriage control. There is no need to put line feed characters in calls to c_logmsg.
If c_logmsg is used to write messages in a utility, then the message will appear in the command prompt window.
26 www.honeywell.com
IMPLEMENTING A SERVER API APPLICATION
Server redundancy
If your task follows the guidelines described in this document and only accesses data from user tables and
points, you do not have to do anything special for redundancy. (Your task doesn't need to determine which
server is primary because GBload only allows the task on the primary to run.)
On a redundant system the task is started on both servers. If the server is primary, the task continues normal
operation after GBLoad. However, if the server is backup the task waits at GBLoad.
When the backup becomes primary, the task continues on from GBLoad. In the meantime, what was the primary
will reboot and restart as backup and the task will wait at GBLoad.
27
IMPLEMENTING A SERVER API APPLICATION
28 www.honeywell.com
Controlling the execution of a Server API application
Related topics
“Starting an application” on page 30
“Activating a task” on page 32
“Testing the status of a task” on page 36
“Monitoring the activity of a task” on page 37
29
CONTROLLING THE EXECUTION OF A SERVER API APPLICATION
Starting an application
These topics describe how to start an application.
Related topics
“Running a utility from the command line” on page 30
“Selecting an LRN for a task” on page 30
“Starting a task automatically” on page 30
“Starting a task manually” on page 31
Attention
All LRNs except for the user space (from 111 to 150 inclusive) are reserved by the server for internal use and should
not be used for applications.
To use USRLRN and select one of the numbers it displays, at the Windows Command prompt, type:
usrlrn
When a task is executing, you can identify its LRN by calling the library routine GETLRN. This LRN is
needed in some other library routines and it prevents you from having to hard-code it into your source code.
Related topics
“ADDTSK” on page 76
“CT” on page 77
“DBG” on page 79
“DT” on page 80
“ETR” on page 81
“REMTSK” on page 84
Attention
Configuring the task to start automatically only takes effect after you have stopped and started the server. Also note
that starting and activating a task are two separate activities. Once the task is started, it needs to be activated before
any of its commands are executed.
30 www.honeywell.com
CONTROLLING THE EXECUTION OF A SERVER API APPLICATION
Item Description
name The executable file name of your task.
lrn The LRN for the task, see “Selecting an LRN for a task” on page 30.
priority The priority of task execution (use 0 as a default).
31
CONTROLLING THE EXECUTION OF A SERVER API APPLICATION
Activating a task
After a task has been started it is ready to receive requests to be activated. The server can be configured to
activate your task whenever one or more of the following events occurs.
When your task is woken from its TRM04 call by one of these events you can usually obtain more information
about the event by calling GETREQ. The parameter block returned from GETREQ can provide event specific
information that can used to determine what action your task should take. Note that if GETREQ is not called,
then the request will not be flushed from the request queue and no further requests to the task can be made.
The remainder of this section describes how to configure the server to activate your task for each of these events
and also what event specific information you can obtain from the parameter block.
Related topics
“Activating a task on a regular basis” on page 32
“Activating a task while a point is on scan” on page 33
“Activating a task when a status point changes state” on page 33
“Activating a task when a Station function key is pressed” on page 34
“Activating a task when a Station menu item is selected” on page 34
“Activating a task when a display button is selected” on page 34
“Activating a task when a Station prompt is answered” on page 34
“Activating a task when a display is called up” on page 34
“Activating a task when a report is requested” on page 35
“Activating a task from another task” on page 35
“Running a task from a Station” on page 60
Word Description
1 Set to 0.
2 param1 passed to TMSTRT.
3 param2 passed to TMSTRT.
4-10 Not used.
32 www.honeywell.com
CONTROLLING THE EXECUTION OF A SERVER API APPLICATION
Parameter Description
Block No. Algorithm data block number. For details, see the topic, 'Algorithm blocks' in
the Configuration Guide.
Task LRN The logical resource number of your task.
Task Request Rate The task request rate in seconds, (must be multiple of point scan rate).
Word 1(param1) Must be a non-zero number.
Word 2-10 (param2-10) Numerical parameters that will be passed to your task.
Notes
• The algorithm block can also be configured from the Cyclic Task Request Algorithm display. Using the
Point Detail display, click the Algorithm number to display the Algorithm configuration.
• This algorithm must be attached to either a Status or Analog point with no database or hardware address
(that is, Controller number only).
• Time of the last request (in seconds) is stored by the system in ALG(04).
When activated using this method, your task can call GETREQ to obtain the following information in the
parameter block:
Words 1 -10.
Property Description
Block No. The algorithm block used by this algorithm for this point. Each algorithm attached to each
point should be assigned a unique block number. Use the alglst utility to find a free block.
See the topic titled "Algorithm blocks" in the Station Configuration Guide for more
information.
LRN of Task to Request The Logical Resource Number of the task that is requested when the point changes to the
specified state.
You can specify a system task or a custom task.
Task Request State Select the state (0 to 7) that requests the task, or select ALL for all state transitions.
Parameter Block The numerical parameter(s) passed to the task. Note that Word 1, Word 2, or Word 3 must
be a non-zero number, otherwise the parameter block is not read and all other parameter
values are ignored.
33
CONTROLLING THE EXECUTION OF A SERVER API APPLICATION
Notes
• The algorithm block can also be configured from the Status Change Task Request Algorithm display. Using
the Point Detail display, double-click the Action algorithm number to display the Algorithm configuration.
• This algorithm must be attached to a Status point.
• This algorithm does not queue requests to the task.
The task must call GETREQ to obtain the following information in the parameter block:
Words 1–10
Word Description
1 Parameter 1 passed to the OPRSTR routine.
2-10 Not used.
34 www.honeywell.com
CONTROLLING THE EXECUTION OF A SERVER API APPLICATION
Word Description
1 Station number requesting the report
2 Not used
3 Report number
4–10 Not used
Attention
The report output file will reside in the report folder of the server and will have the name RPTnnn where nnn is
the report number.
Word Description
1-10 Values passed into the requesting tasks call to RQTSKB.
35
CONTROLLING THE EXECUTION OF A SERVER API APPLICATION
36 www.honeywell.com
CONTROLLING THE EXECUTION OF A SERVER API APPLICATION
The tasks may then reset their watchdog timers by calling the watchdog timer pulse routine, WDON, which
resets the countdown timer to the poll interval value.
For details on the routines, see “c_wdstrt()” on page 244 and “c_wdon()” on page 243 (C and C++).
Related topics
“c_wdon()” on page 243
“c_wdstrt()” on page 244
37
CONTROLLING THE EXECUTION OF A SERVER API APPLICATION
38 www.honeywell.com
Accessing server data
Related topics
“Introduction to databases” on page 40
“The server database” on page 41
“Accessing acquired data” on page 47
“Accessing process history” on page 50
“Accessing other data” on page 51
“Accessing user-defined data” on page 53
39
ACCESSING SERVER DATA
Introduction to databases
Databases are a structured store of information to be referenced, altered or deleted at a later date. Many types of
databases exist, but the majority of them can be classified into three main categories:
• Relational. Relational databases are used heavily in business applications where the data is represented as
various tables, each containing a series of records and each record containing a set of fields. Due to the
nature of the relational database structures, their strength lies in their ability to support ad hoc queries and
quick searches.
• Object oriented. Object oriented databases are used more in Computer Aided Design (CAD) applications,
where the data relationships are too complex to map into a table, record and field format. They are usually
bound very closely to an object oriented language and provide better performance than relational databases.
• Real-time. Real-time databases are used in process control applications where the performance of the
database is paramount. These databases usually consist of a memory-resident portion to ensure fast
operation. The tasks that references the memory-resident fields can reference them just as if they were local
variables in the program.
40 www.honeywell.com
ACCESSING SERVER DATA
Physical structure
The term physical structure of the server database is referring to the files that are used by the native operating
system to store data. When using the application programming library routines you will only be referring to the
logical structure of the database, but it is useful to understand how it is physically stored.
To increase performance, some parts of the database are loaded from the hard disk into the computer's memory
when the system starts. Periodically this memory-resident data is written back to the hard disk so that it will not
be lost if the system stops.
The database folder contains the following main files.
File Description
data Holds many of the smaller database tables and all of the memory-resident tables.
history Contains the process history data for each history interval.
events Holds event data.
crtbkr, crtdfd, crtsha Holds the display definition.
points Contains all the point and parameter details.
41
ACCESSING SERVER DATA
Physical Database
data
010101101
01001010010101011
00101001010010101
01010101010101010
01010101010101010
10101010101010101
0101010101010101
historyx
010101101
01001010010101011
00101001010010101
01010101010101010
01010101010101010
10101010101010101
0101010101010101
events
010101101
01001010010101011
00101001010010101
01010101010101010
01010101010101010
10101010101010101
0101010101010101
user tables
other files
Logical structure
When accessing server data, you will typically work with two types of logical files in the server real-time
database:
• “Flat logical files” on page 42
These are arranged as a set of fixed size flat files, containing a fixed number of records, with a fixed number
of words per record.
• “Object-based real-time database files” on page 45
These are flexible data structures for which the underlying structure is hidden from the user and can only be
accessed via functions that manipulate the data.
Related topics
“c_dataio_...()” on page 96
42 www.honeywell.com
ACCESSING SERVER DATA
Data\data
(example, C:hs\server\data\data)
and
43
ACCESSING SERVER DATA
Relative files
Relative files are used where data needs to be stored in a structured way, with each record representing a single,
one off entity. An example of a relative file is the CRTTBL where each record represents a single Station. The
majority of flat logical files in the server are relative files.
Access to a relative file is achieved using specific functions like hsc_param_value or using a generic read and
write function of DATAIO. If you use DATAIO you will need to provide a record number which is relative to
the beginning of the logical file. The record number acts like an index to identify the data—that is, to access
data regarding the third Station you would access record three of the logical file CRTTBL.
Record 1
Record 2
Record 3
read record 3
...
...
Record n
Circular files
Circular files are used where data needs to be recorded on a regular basis, but there is a limit on the amount of
disk space that is to be used. When the circular file is full, and a new record is written to it, the oldest record
will be overwritten. An example of a circular file is a HISTORY file where each record represents a set of point
parameter values at a given time.
Access to a circular file is achieved using specific functions like c_gethstpar_date_2 or using the generic
functions of DATAIO.
44 www.honeywell.com
ACCESSING SERVER DATA
Related topics
“Accessing user-defined data” on page 53
“c_dataio_...()” on page 96
45
ACCESSING SERVER DATA
For example, consider the situation where two tasks are simultaneously accessing the same record in a logical
file. They both read the record into a buffer in memory and proceed to modify its contents. The first task
completes its modification and writes the buffer back to the record in the logical file. A moment later the second
task does the same, but it will overwrite the changes made by the first task.
There are two ways to overcome this problem. The first method is to design your tasks so that only one task is
responsible for changing the record contents. Because this task is the only one changing records, it can safely
read and write as necessary.
The second method is to use file locking. Before performing a read, modify, write sequence your task can call
hsc_lock_file to request permission to change the file. If another task has the file already locked you will be
denied access. If the file is not locked, it will be locked on your behalf and you will be able to read, modify and
write the record. After you are complete you should call hsc_unlock_file to allow other tasks to access the file.
Object-based real-time database files do not require such locking. Instead the methods of the file will ensure
database consistency.
In most cases you will not need to lock and unlock files or records in your application as the server will perform
the necessary locking on your behalf. The exception to this rule is when you are using user tables (see
“Accessing user-defined data” on page 53) with more than one task reading and writing to their records. In this
case you will need to use the file locking functions of hsc_lock_file or hsc_lock_record.
Related topics
“hsc_lock_record()” on page 145
“hsc_unlock_file()” on page 197
“hsc_unlock_record()” on page 198
46 www.honeywell.com
ACCESSING SERVER DATA
Related topics
“Identifying a point” on page 47
“Identifying a parameter” on page 47
“Accessing parameter values” on page 47
“Using point lists” on page 47
“Controlling when data is acquired and processed for standard points” on page 48
Identifying a point
Before you can access the data from a particular point you need to determine its internal point number. This
internal point number is used by several of the application programming library routines to quickly identify the
point.
An application will normally determine the internal point number of several points during initialization. To do
this the application passes the Point Name in ASCII to the library routine hsc_point_number. If the point exists
in the database, this function will return its corresponding internal point number.
Identifying a parameter
A point comprises many individual point parameters, for example, SP, OP, PV and so on. When you want to
refer to one of these parameters in your application you need to use hsc_param_number to resolve the parameter
name to its appropriate number. This routine accepts an ASCII string for the parameter name and the point
number and if the parameter exists for this point then its corresponding number will be returned. Parameter
numbers may vary from point to point (even within the same point type), so parameter names need to be
resolved to parameter numbers on a point by point basis.
Attention
Application point lists only support scan task points.
47
ACCESSING SERVER DATA
After you have created the point list, your application can use the library routine GETLST to read the set of
point parameters, and GIVLST to write the set of point parameters.
For details on the routines, see “c_getlst()” on page 117 and “c_givlst()” on page 122 (C and C++).
Routine Description
SPSW Scan Point Special and Wait for Completion
SPVW Scan Point Value and Wait for Completion
SPS Scan Point Special
SPV Scan Point Value
PPSW Process Point Special and Wait for Completion
PPVW Process Point Value and Wait for Completion
PPS Process Point Special
PPV Process Point Value
The routine SPSW will demand a point parameter to be scanned from the field. If the value scanned has
changed then the point parameter will be processed (that is, checked for alarm conditions, execute algorithms
where necessary, and so on), store the value in the point record, and then return.
The routine SPVW is used when there is no source address for the point parameter. This allows you to point
process a calculated value from your application just as if it were scanned from the field, that is, store the value
in the PV, and process algorithms, alarms etc.
The routines SPS and SPV are exactly the same as SPSW and SPVW respectively but they return immediately
and do not wait for the processing to complete. These are typically used to improve performance if you have
several point parameters on the same Controller to demand scan. Call SPS to quickly queue all the point
parameters except the last one. Then call SPSW to queue the last point parameter and wait for all to be
processed.
The routines PPSW, PPVW, PPS and PPV are again very similar to the previous routines mentioned except that
they will always force the processing of the point parameter even if it has not changed. For performance
reasons, we do not recommend you to use these routines unless absolutely necessary.
48 www.honeywell.com
ACCESSING SERVER DATA
The routine SPV may also effect the performance of the server adversely if used heavily. If you need to perform
a lot of point processing of application values you may consider using the user scan task instead.
49
ACCESSING SERVER DATA
Related topics
“Accessing blocks of history” on page 50
When referencing what history to retrieve you may specify it by either a date and time or by an offset of sample
periods from the current time.
50 www.honeywell.com
ACCESSING SERVER DATA
Attention
Accessing other data in this way requires knowledge of the internal structures used by the server. Although these are
described in the definition files, Honeywell does not guarantee that these formats will not change from release to
release of the server.
Related topics
“Accessing logical files” on page 51
“Accessing memory-resident files” on page 51
“DIRTRY (The first logical file in the server database)” on page 52
Related topics
“c_dataio_...()” on page 96
CAUTION
Accessing other data using shared memory not only requires knowledge of the internal structures but also requires
care. It is very easy to accidentally alter database values just by setting these global variables.
Values are read from the memory-resident file simply by assigning the global variable to another variable.
Values are written to the memory-resident file simply by setting the value of the global variable. The set value
will be written back to disk automatically when the server performs its next checkpoint if the value is stored in a
checkpoint file.
51
ACCESSING SERVER DATA
In C the variables for the memory-resident files are defined in separate include files called GBxxxtbl.h, where
xxx is the name of the logical file. The global variables are arrays of structures (one structure per record) that
have a name of GBxxxtlb[]. For example:
#include 'src/GBtrbtbl.h'
52 www.honeywell.com
ACCESSING SERVER DATA
If you want to configure or modify any of the 150 user tables, you can use the user table builder utility,
UTBBLD.
Related topics
“Displaying and modifying user table data” on page 53
“Setting up user tables using the UTBBLD utility” on page 54
“UTBBLD usage notes” on page 57
“Using the database scanning software” on page 58
“Flat logical files” on page 42
“Setting up user tables using the UTBBLD utility” on page 54
53
ACCESSING SERVER DATA
UTBBLD example
This example shows a session that uses utbbld to carry out its full range of actions, namely:
• Display the existing user table configurations
• Modify the configuration of user table 42
• Add user table 21, with the configuration: CIRCULAR file type, 64 records, 18 words per record
• Delete user table 4
• Display the new user table configurations
The session which carried out these actions is as follows:
utbbld
System status is OFF-LINE
USER TABLE BUILDER
~~~~ ~~~~~ ~~~~~~~
Main Menu.
1. Display current user table configuration
2. Modify existing user tables
3. Add user tables
4. Delete user tables
c. Commit changes
q. Quit
Please choose one of the above (default is q):
1
54 www.honeywell.com
ACCESSING SERVER DATA
55
ACCESSING SERVER DATA
56 www.honeywell.com
ACCESSING SERVER DATA
Related topics
“Accessing user-defined data” on page 53
Attention
This option is not recommended because it may disrupt applications that are running, and changes may not be able to
be made to files that are in use.
57
ACCESSING SERVER DATA
58 www.honeywell.com
Working from a Station
The application interface library provides routines that, when working from a Station, enable you to perform the
following tasks:
• Generate alarms
• Display messages
• Print files
• Control custom built X-Y charts
Related topics
“Running a task from a Station” on page 60
“Routine for generating an alarm” on page 61
“Routine for using the Station Message and Command Zones” on page 62
“Routine for printing to a Station printer” on page 63
59
WORKING FROM A STATION
Related topics
“Activating a task” on page 32
60 www.honeywell.com
WORKING FROM A STATION
61
WORKING FROM A STATION
62 www.honeywell.com
WORKING FROM A STATION
63
WORKING FROM A STATION
64 www.honeywell.com
Developing user scan tasks
To introduce unsupported controller-like devices into your system, you can either create an OPC server for your
device, or you can use the User Scan Task option to write an application which provides an interface between
the device and Experion.
The recommended way is to create an OPC server. This method eliminates the requirement of writing a custom
interface by defining a common, high performance interface that permits this work to be done once, and then
reused.
You will find the OPC specification on the Internet at: “http://www.opcfoundation.org”. The OPC Specification
is a non-proprietary technical specification that defines a set of standard interfaces based upon Microsoft's
OLE/COM technology. The application of the OPC standard interface makes possible interoperability between
automation/control applications, field systems/devices and business/office applications.
However, should you choose to use the User Scan Task to write an interface application, you will find this
option described below.
The link between the server and the User Scan Task is the Experion database user tables. The server provides
database scanning software (DBSCN) to scan data from the user tables into server points. The User Scan Task
reads data from the remote device and writes it into the user tables. Experion can also send controls to the
remote device by way of the User Scan Task.
Controller
Server
User Tables
The option works by using channels defined as 'User Scan Task' type channels. These channels operate in
exactly the same manner as a conventional channel. They interact, however, with 'User Scan Task' controllers
rather than physical controllers.
Point parameters are sourced from these database controllers by specifying the word address within the specific
record.
65
DEVELOPING USER SCAN TASKS
For details about defining a user scan task controller, and its associated channel and points, see the topic
'Creating a user scan task controller' in Quick Builder's help.
Related topics
“Designing the database for efficient scanning” on page 67
“Example user scan task” on page 68
“c_gdbcnt()” on page 109
66 www.honeywell.com
DEVELOPING USER SCAN TASKS
67
DEVELOPING USER SCAN TASKS
Related topics
“C/C++ version” on page 68
“Application Library for C and C++” on page 87
C/C++ version
The C version of the example User Scan Task is included here. For more information regarding any of the
functions called in this program, see 'Application Library for C and C++.'
/************************************************************/
/********* COPYRIGHT © 1996 - 2012 HONEYWELL PACIFIC ********/
/************************************************************/
#include "src/defs.h"
#include "src/environ.h"
#include "src/M4_err.h"
#include "src/dataio.h"
#include "files"
#include "src/trbtbl_def"
#ifndef lint
static char *ident="@(#)c_dbuser.c,v 720.3";
#endif
static char *progname="c_dbuser.c,v";
/*
BEGIN_DOC
-------------------------------------------------------------
C_DBUSER - user scan task for use with DBSCAN
-------------------------------------------------------------
SUMMARY:
Example user scan task
*/
main ()
{
68 www.honeywell.com
DEVELOPING USER SCAN TASKS
/*
DESCRIPTION:
-------------------------------------------------------------
NOTES -
-------------------------------------------------------------
RETURN VALUES:
FUNCTIONS CALLED:
RELATED FUNCTIONS:
DIAGNOSTICS:
EXAMPLES:
END_DOC
*/
69
DEVELOPING USER SCAN TASKS
&cntval
)== -1)
{
// GDBCNT FAILED!
// Only process task requests when
// there are no control requests
70 www.honeywell.com
DEVELOPING USER SCAN TASKS
71
DEVELOPING USER SCAN TASKS
// END switch
}
if(errcode != M4_EOF_ERR)
{
// Log the result
c_logmsg(
progname,
"308",
"DBUSER: GETREQ error 0x%x",
errcode);
}
// END MAIN
}
72 www.honeywell.com
DEVELOPING USER SCAN TASKS
Related topics
“Example user scan task” on page 68
“Application Library for C and C++” on page 87
73
DEVELOPING USER SCAN TASKS
74 www.honeywell.com
Development utilities
Tip
Honeywell will supply detailed information and instructions on how to use this command when required.
Related topics
“ADDTSK” on page 76
“CT” on page 77
“databld” on page 78
“DBG” on page 79
“DT” on page 80
“ETR” on page 81
“FILDMP” on page 82
“FILEIO” on page 83
“REMTSK” on page 84
“TAGLOG” on page 85
“USRLRN” on page 86
75
DEVELOPMENT UTILITIES
ADDTSK
Add application task.
Synopsis
addtsk name lrn [priority]
Part Description
lrn The LRN you have chose for the task, see 'Selecting an LRN for a task.'
priority The priority of task execution (use 0 as a default).
name The executable file name of your task.
Description
This utility loads the executable program identified by name and prepares it for execution. Once loaded the
executable becomes a task with the given LRN and priority ready to be activated.
This utility only works with application LRNs, preventing you from accidentally overwriting a server system
task. Use “CT” on page 77 if you need to use a reserved LRN for your task.
Example
addtsk usrapp 111 0
Related topics
“Selecting an LRN for a task” on page 30
76 www.honeywell.com
DEVELOPMENT UTILITIES
CT
Create task.
Synopsis
ct lrn priority -efn name
Part Description
lrn The LRN you have chose for the task, see 'Selecting an LRN for a task.'
priority The priority of task execution (use 0 as a default).
name The executable file name of your task.
Description
This utility loads the executable program identified by name and prepares it for execution. Once loaded the
executable becomes a task with the given lrn and priority ready to be activated.
Only use this utility if you have run out of application LRNs and you need to use a reserved LRN for your task.
It is preferable to use the “ADDTSK” on page 76 utility because it will check that you are not overwriting
server system tasks.
Example
ct 111 0 -efn usrapp
Related topics
“Selecting an LRN for a task” on page 30
77
DEVELOPMENT UTILITIES
databld
Description
The databld command is used to import and export server configuration data in XML format. databld is
described in detail in the "Server database configuration utility (databld)" section of the Server and Client
Configuration Guide.
78 www.honeywell.com
DEVELOPMENT UTILITIES
DBG
Configure Experion so that the next task started from the command line or Visual Studio that calls gbload() will
automatically be assigned the specified LRN.
Synopsis
dbg lrn
Part Description
lrn The LRN you have chosen for the task, see 'Selecting an LRN for a task.'
Description
This utility sets up Experion so that the next manually started task will run with a specified LRN. This is useful
for debugging purposes, as it allows a task to be run from within Visual Studio.
Example
dbg 111
Related topics
“Selecting an LRN for a task” on page 30
79
DEVELOPMENT UTILITIES
DT
Delete task.
Synopsis
dt lrn
Part Description
lrn The LRN you have chose for the task, see 'Selecting an LRN for a task.'
Description
This utility marks the specified task for deletion. When the task next calls either TRM04 or TRMTSK, the task
will be deleted.
Only use this utility if you have run out of application LRNs and you needed to use a reserved LRN for your
task. It is preferable to use the remtsk utility because it will check that you are not removing server system
tasks.
Example
dt 111
Related topics
“Selecting an LRN for a task” on page 30
80 www.honeywell.com
DEVELOPMENT UTILITIES
ETR
Enter task request
Synopsis
etr lrn [-wait] [-arg arg1]
Part Description
lrn The LRN you have chose for the task, see 'Selecting an LRN for a task.'
-wait Wait for the task to become dormant
-arg arg1 Additional argument passed to the task via rqstsk
Note: The task is requested via rqstsk—the additional argument can only be
an int2.
Description
This utility requests the specified task to be activated.
Example
etr 111 -arg 5
Related topics
“Setting up debugging utilities and tasks” on page 14
“Selecting an LRN for a task” on page 30
81
DEVELOPMENT UTILITIES
FILDMP
Dump/restore the contents of a logical file.
Synopsis
fildmp
Description
This interactive utility is used to dump, restore or compare the contents of server logical files with standard text
files.
When dumping the contents of a logical file to an ASCII operating system file you will need to provide the
operating system file name to dump to, the server file number, the range of records to dump, and the data format
to dump. Note that the logical file can be dumped to the screen by not specifying an operating system file.
The data format to dump defines how the logical file data will be written to the ASCII operating system file.
You can specify INT for integer data, HEX for hexadecimal data, ASC for ASCII data, and FP for floating point
data.
When restoring from an operating system file you will only need to provide the operating system file name. The
utility will overwrite the current contents of the logical file with what is defined in the operating system file.
Attention
Where possible, use the databld command instead of fildmp. databld processes server configuration files in an
easier to read format and performs additional validation of the data. However, it is only available for specific server
configuration types. For more information, refer to the "Server database configuration utility (databld)" section of the
Server and Client Configuration Guide.
Example
System status is OFF-LINE
Reading from disc. Writing to memory,disc,link.
82 www.honeywell.com
DEVELOPMENT UTILITIES
FILEIO
Modify contents of a logical file.
Tip
Honeywell will supply detailed information and instructions on how to use this command when required.
Synopsis
fileio
Description
This interactive utility is used to modify the contents of individual fields in a logical file.
You will need to provide the file number, whether to modify memory/disk/both, the record number and the word
number of the field to modify and the new value.
Example
Database contains 400 files
File number (=0 to exit) ? 251
Use memory image [YES|NO|BOTH(default)] ?
File 1 contains 400 records of size 16 words
Record number (=0 to back up) ? 1
Word offset (=0 to back up) ? 1
Mode =0 to back up
=1 for INTEGER (int2)
=2 for HEX (int2)
=3 for ASCII
=4 for F.P. (real)
=5 for SET bit
=6 for CLR bit
=7 for LONG INTEGER (int4)
=8 for LONG F.P. (dble) ? 1
INTEGER VALUE = -32768 NEW VALUE = 100
Save value [YES|NO(default)] ? YES
Word offset (=0 to back up) ?
Record number (=0 to back up) ?
File number (=0 to exit) ?
83
DEVELOPMENT UTILITIES
REMTSK
Remove application task.
Synopsis
remtsk lrn
Part Description
lrn The LRN you have chose for the task, see 'Selecting an LRN for a task.'
Description
This utility marks the specified task for deletion. When the task next calls either TRM04 or TRMTSK, the task
will be deleted.
This utility only works with application LRNs, preventing you from accidentally removing a server system task.
Use “DT” on page 80 if you need to use a reserved LRN for your task.
Example
remtsk 111
Related topics
“Selecting an LRN for a task” on page 30
84 www.honeywell.com
DEVELOPMENT UTILITIES
TAGLOG
List point information
Synopsis
taglog
Description
This utility lists information associated with the specified points in the server database. This utility is useful to
find out if a point exists and to determine its internal point number.
Example
An example of output from the utility:
Point IPCSTA1 Type 0 Number 1 STALOG PERFORM
TEST 1
CNT file 0000 0000 0005 0030 0000 FF00 FFFF 0000 FF00 FFFF .....0.......
FF00 FFFF 0000 FF00 FFFF FF00 FFFF FF10 0000 .............
DES file 4950 4353 5441 3120 2020 2020 2020 2020 5354 414C IPCSTA1
STAL
4F47 2050 4552 464F 524D 2054 4553 5420 3120 2020 OG PERFORM
TEST 1
2020 2020 2020 0000 0000 0000 0018 3000 0000 0000 ......0.....
0000 0000 0000 0000 0000 0000 0000 0000 0000 0000 ..............
0000 0000 0000 0000 0000 0000 0000 0000 0000 0000 ..............
0000 0000 0000 0000 0000 0000 ............
85
DEVELOPMENT UTILITIES
USRLRN
Lists LRNs. For details about this utility, see the topic, 'usrlrn', in the .
86 www.honeywell.com
Application Library for C and C++
The C/C++ application library contains the functions necessary for writing applications that interact with
Experion.
Related topics
“c_almmsg_...()” on page 91
“AssignLrn()” on page 93
“c_chrint()” on page 94
“ctofstr()” on page 95
“c_dataio_...()” on page 96
“DeassignLrn()” on page 102
“c_deltsk()” on page 103
“DbletoPV()” on page 104
“dsply_lrn()” on page 105
“c_ex()” on page 106
“ftocstr()” on page 107
“c_gbload()” on page 108
“c_gdbcnt()” on page 109
“c_getapp()” on page 110
“GetGDAERRcode()” on page 111
“c_geterrno()” on page 112
“c_gethstpar_..._2()” on page 113
“c_getlrn()” on page 116
“c_getlst()” on page 117
“c_getprm()” on page 118
“c_getreq()” on page 120
“c_givlst()” on page 122
“hsc_asset_get_ancestors()” on page 123
“hsc_asset_get_children()” on page 124
“hsc_asset_get_descendents()” on page 125
“hsc_asset_get_parents()” on page 126
“hsc_em_FreePointList()” on page 127
“hsc_em_GetLastPointChangeTime()” on page 128
“hsc_em_GetRootAlarmGroups()” on page 129
“hsc_em_GetRootAssets()” on page 130
“hsc_em_GetRootEntities()” on page 131
“hsc_enumlist_destroy()” on page 132
“hsc_GUIDFromString()” on page 133
“hsc_insert_attrib()” on page 134
“hsc_insert_attrib_byindex()” on page 139
87
APPLICATION LIBRARY FOR C AND C++
88 www.honeywell.com
APPLICATION LIBRARY FOR C AND C++
89
APPLICATION LIBRARY FOR C AND C++
90 www.honeywell.com
APPLICATION LIBRARY FOR C AND C++
c_almmsg_...()
Sends a general message for an alarm or event by type.
Note that “hsc_notif_send()” on page 146 and “hsc_insert_attrib()” on page 134 supersede c_almmsg_...().
C/C++ synopsis
#include <src/defs.h>
#include <src/almmsg.h>
Arguments
Argument Description
text (in) pointer to a null-terminated string of text to be sent to the alarm system.
priority (in) Message priority (see Description).
name (in) pointer to a null-terminated string containing the alarm name (40 characters in length (alarm
source)).
id (in) pointer to a null-terminated string containing the alarm identifier (for example, PVHI,
SVCHG: 20 characters in length (condition)).
level (in) pointer to a null-terminated string containing the alarm level (for example, U, L, H, STN01).
descr (in) pointer to a null-terminated string containing the alarm descriptor (132 characters in length).
value (in) pointer to a null-terminated string containing the alarm value (24 characters in length).
units (in) pointer to a null-terminated string containing the alarm units (10 characters in length).
area (in) pointer to a null-terminated string containing the desired of the alarm/event.
Description
Sends the structured text message string to the alarm system for storage into the alarm or event file, and for
printing on all printers.
c_almmsg_event will send the message to all printers and log the text to the event file.
91
APPLICATION LIBRARY FOR C AND C++
c_almmsg_alarm will send the message to all printers and log the message to the alarm list or event file. It also
sets the first character of the level field of the alarm to either 'L', 'H' or 'U' depending on the value of priority.
The priority of the alarm is defined as follows:
c_almmsg_event_area and c_almmsq_alarm_area perform the same function as the c_almmsg_event and
c_almmsg_alarm routines, except that the can be specified.
c_almmsg_format will format a message given all the relevant fields. It returns a pointer to a null-terminated
structured message string that can then be passed onto c_almmsg_event or c_almmsg_alarm.
The structured message text string can be broken up into six fields. The starting character of each field is
defined by the following identifiers:
c_almmsg_format2_malloc will format a message given all the relevant fields. It returns a pointer to a null-
terminated string that can then be passed onto c_almmsg_event or c_almmsg_alarm.
For an example of the use of this routine, see example 2 (in the server install folder in user/examples/src
folder).
See also
“c_prsend_...()” on page 225
92 www.honeywell.com
APPLICATION LIBRARY FOR C AND C++
AssignLrn()
Assigns an LRN to the current thread.
C/C++ Synopsis
#include <src/defs.h>
#include <src/trbtbl_def>
int2 AssignLrn(
int2* pLrn // (in/out) lrn to be allocated
// -1 == find an unused lrn
// >0 == allocate the specified lrn
);
Arguments
Argument Description
pLrn (in/out) A pointer to the lrn to be allocated.
If *pLrn == -1 then the system will allocate the first available lrn.
If *pLrn >0 then the system will use the specified lrn.
At the end of a successful call, *pLrn will equal the just assigned lrn number.
Description
This function is designed to assign a particular LRN to the current thread. You may choose your own free LRN
to use, or you may ask the system to select one for you.
Diagnostics
This function returns 0 if successful, and pLrn will then contain the newly assigned LRN.
See also
“DeassignLrn()” on page 102
“c_getlrn()” on page 116
93
APPLICATION LIBRARY FOR C AND C++
c_chrint()
Copies character buffer to integer buffer.
C/C++ synopsis
#include <src/defs.h>
void __stdcall c_chrint(
char* chrbuf,
int chrbuflen,
int2* intbuf,
int intbuflen
);
Arguments
Argument Description
chrbuf (in) source character buffer containing ASCII
chrbuflen (in) size of character buffer in bytes (to allow non null-terminated character buffers)
intbuf (out) destination integer buffer
intbuflen (in) size of destination buffer in bytes
Description
Copies characters from a character buffer into an integer buffer. It will either space fill or truncate so as to
ensure that intbuflen characters are copied into the integer buffer.
If the system stores words with the least significant byte first, then byte swapping will be performed with the
copy.
See also
“c_intchr()” on page 205
94 www.honeywell.com
APPLICATION LIBRARY FOR C AND C++
ctofstr()
Converts a C string to a FORTRAN string.
C/C++ synopsis
#include <src/defs.h>
void ctofstr(
char* Cstr,
char* Fstr,
int Flen
);
Arguments
Argument Description
Cstr (in) null terminated C string
Fstr (out) memory array for C string (Fstr can be the same as Cstr)
Flen (in) length of the Fstr buffer in bytes
Description
Given a null terminated C string and the length of the string, this routine will convert it into a FORTRAN string,
space padding it if necessary.
If the Cstr does not fit, it will be truncated.
See also
“c_intchr()” on page 205
“c_chrint()” on page 94
“ftocstr()” on page 107
95
APPLICATION LIBRARY FOR C AND C++
c_dataio_...()
Routines for accessing the server database logical files.
Tip
For information about logical files, see 'Logical Structure' and 'Accessing logical files.'
The library routine DATAIO is a generic means of reading and writing to any of the 400 or so logical files in the
server database. It allows you to read or write one or more records (in blocks or one at a time) to or from an
int2 type buffer.
You need to refer to the relevant definition file of the record (to determine the internal structure or layout of the
record), to access the individual record fields.
The following library of DATAIO routines are provided to suit most file record access situations.
When accessing individual records in a flat logical file, the record number of each record remains the same in a
relative file (starting with the first record as record 1). However, the record number does not remain the same
within a circular file.
If you need to access a particular record in a circular file, you will need to keep track of its physical record
number. The READ_NEWEST and READ_OLDEST routines are designed to assist in this regard, as they both
write the actual record number to a variable provided for the purpose.
The queueing routines are designed to work with circular files, for quickly adding and deleting records to the
file. Each use of the QUEUE routine will add a new record unless the file is full, in which case it will overwrite
the oldest record with the new record. Each use of the DEQUEUE routine will read and delete the oldest record.
In practice, dequeue is not necessary in a circular file because it will automatically overwrite the oldest record
when full.
C/C++ synopsis
#include <src/defs.h>
#include <src/M4_err.h>
#include <src/dataio.h>
96 www.honeywell.com
APPLICATION LIBRARY FOR C AND C++
Arguments
Argument Description
filenum (in) Server file number.
97
APPLICATION LIBRARY FOR C AND C++
Argument Description
filerecs (out) Pointer to the number of records in the file. The variable referenced in the variable pointer is
written to by the routine.
byreclen (out) Pointer to the number of bytes in each record. The variable referenced in the variable
pointer is written to by the routine.
cirrecnum (in/out) Pointer to a variable holding the record number within a circular-file. The variable
referenced in the variable pointer must be set prior to calling the routine that uses it to determine
which record to access. The variable referenced in the variable pointer is written to by the routine.
recnum (in) Record number or start record number for block transfer.
numrecs (in) Number of records to be block transferred.
location (in) Location of data (see “Location options”).
buffer (in/out) Pointer to the buffer variable. The variable referenced in the variable pointer is written to
by the routine.
bybuflen (in) Size of the buffer in bytes (must be a multiple of 2, because all records are sized in words—2
bytes).
Description
Performs data transactions between an application and the server database logical files. Used to read and write
server database logical files, records and fields.
Tip
For an explanation of relative and circular server database logical files, see 'Flat logical files.'
c_dataio_size Retrieves the size of a server file by writing both the number of records and
the number of bytes per record to the memory variables referenced by the
variable pointers passed-in as arguments.
c_dataio_read Reads a single record from a server file into the buffer, by writing the record
data to the memory variable referenced by the variable pointer passed-in as
an argument.
c_dataio_write Writes a single record from the buffer to a server file.
c_dataio_read_blk Reads a number of contiguous records from a server file into the buffer, by
writing the record data to the memory variable referenced by the variable
pointer passed-in as an argument.
c_dataio_write_blk Writes a number of contiguous records from the buffer to a server file.
c_dataio_queue Appends and writes a new single record in the CIRCULAR file by appending
to the position above the previous newest record. Writes this new record, and
if the file is full, overwrites the oldest record with this new record. Changes
the number of records, unless the file is full, in which case it does not change
the number of records.
c_dataio_dequeue Reads and deletes the oldest record in the CIRCULAR file. Changes the
number of records. The previously second oldest record then becomes the
oldest record. Writes the record data to the memory variable referenced by
the variable pointer passed-in as an argument.
c_dataio_read_newest Reads any single record in the CIRCULAR file by referencing the records
counting from the newest record. Does not change the record data or the
number of records. Writes both the record data and the actual record number
to the memory variables referenced by the variable pointers passed-in as
arguments.
98 www.honeywell.com
APPLICATION LIBRARY FOR C AND C++
c_dataio_read_oldest Reads any single record in the file by referencing the records counting from
the oldest record. Does not change the record data or the number of records.
Writes both the record data and the actual record number to the memory
variables referenced by the variable pointers passed-in as arguments.
Location options
The recommended configuration to use is LOC_ALL for most situations, and especially for applications running on
a redundant system.
LOC_ALL operates in the most efficient manner possible, first to memory, then to local disk, and finally to the
backup server (memory and disk).
LOC_MEMORY and LOC_DISK are only for accessing a file in those specific locations, and that if used, additional file
handling must be provided in the custom application to prevent inconsistencies between files in memory, on
disk, and on the backup server.
Only ever use LOC_MEMORY or LOC_DISK under specific situations in a custom app where system performance
slowdown is occurring, and file access to the local disk or backup server has been identified as the cause of the
slowdown.
The location options are listed in the following table:
LOC_ALL Read/write from/to memory, local disk, and backup server. Does not require
any additional file handling to ensure file consistency.
LOC_MEMORY Read/write from memory only. Requires additional file handling to ensure
file consistency.
LOC_DISK Read/write from the local disk only. Requires additional file handling to
ensure file consistency.
Diagnostics
Returns 0 if successful, otherwise, returns -1 if failed and writes an error code to the system error status.
Subsequently calling “c_geterrno()” on page 112 will return one of the following error codes:
Explanation example
Say, for example, that there was a circular file that contained 10 records numbered 1 to 10 from oldest to
youngest with record number 1 being the oldest through to record number 10 being the youngest.
In this example scenario, a call to READ_OLDEST with a record number argument of "1", would result in
the reading of the oldest record, which in this example is actual record number 1. The variable for the record
number argument would have had to be holding the value of "1" before the call, and will be holding the value
of "1" after the call.
99
APPLICATION LIBRARY FOR C AND C++
Similarly, a call to READ_OLDEST with a record number argument of "3", would result in the reading of
the third oldest record, which in this example is actual record number 3. The variable for the record number
argument would have had to be holding the value of "3" before the call, and will be holding the value of "3"
after the call.
Now compare this with a call to READ_NEWEST with a record number argument of "1", which would
result in the reading of the newest record, which in this example is actual record number 10. The variable for
the record number argument would have had to be holding the value of "1" before the call, and will be
holding the value of "10" after the call.
Similarly, a call to READ_NEWEST with a record number argument of "3", would result in the reading of
the third newest record, which in this example is actual record number 8. The variable for the record number
argument would have had to be holding the value of "3" before the call, and will be holding the value of "8"
after the call.
Code example
The following example demonstrates how to read and write a record in a User table. It first determines the
size of a User table, sizes the buffer appropriately, reads the record, allows for record data manipulation, and
finally writes the record back to the User table.
#include 'files' /* for UTBL01's file number */
#include 'applications' /* for UTBL01's record size */
#include 'src/defs.h'
#include 'src/M4_err.h'
#include 'src/dataio.h'
// ...
// The other code in your application may go here
// ...
// Read one record from the disk resident user table UTBL01
if (c_dataio_read( UTBL01_F,
rec,
LOC_ALL,
buffer,
user_table1_recordsize) == -1)
{
// Failed to read record
// Retrieve latest error number
errcode = c_geterrno();
// Display error message
100 www.honeywell.com
APPLICATION LIBRARY FOR C AND C++
// ...
// Perform data manipulation with 'buffer' here
// ...
// When finished, and if necessary
// Write data back to database
if (c_dataio_write( UTBL01_F,
rec,
LOC_ALL,
buffer,
user_table1_recordsize) == -1)
{
// Failed to write record
// Retrieve latest error number
errcode = c_geterrno();
// Display error message
printf('c_dataio_write error 0x%x', errcode);
}
}
}
// END SERVER FILE ACCESS
// ...
// Do more things in your application here
// ...
See also
“hsc_param_values()” on page 169
“hsc_param_value_put()” on page 172
“c_getlst()” on page 117
“c_givlst()” on page 122
Related topics
“Logical structure” on page 42
“Flat logical files” on page 42
“Accessing logical files” on page 51
101
APPLICATION LIBRARY FOR C AND C++
DeassignLrn()
Removes the current LRN assignment for a thread.
C/C++ Synopsis
#include <src/defs.h>
#include <src/trbtbl_def>
int2 DeassignLrn();
Description
Removes the association between the thread and its LRN.
Diagnostics
Upon successful completion, a value of 0 is returned. Otherwise, -1 is returned, and calling “c_geterrno()” on
page 112 will retrieve the error code.
See also
“AssignLrn()” on page 93
“c_getlrn()” on page 116
102 www.honeywell.com
APPLICATION LIBRARY FOR C AND C++
c_deltsk()
Marks a task for deletion.
C/C++ synopsis
#include <src/defs.h>
#include <src/M4_err.h>
Arguments
Argument Description
lrn (in) Logical resource number of the task to mark for deletion or -1 for the calling task.
Description
Marks a task for deletion. After the marked task terminates (by calling “c_trmtsk()” on page 240 or “c_trm04()”
on page 239) it will be deleted from the system.
Diagnostics
Upon successful completion a value of 0 is returned. Otherwise, -1 is returned, and calling “c_geterrno()” on
page 112 will return the following error code:
Example
#include <lrns> /* for task lrns */
#include <src/M4_err.h>
#include <src/defs.h>
...
int errcode;
...
/* mark the first user task for deletion on next termination */
if (c_deltsk(USR1LRN) == -1)
{
errcode = c_geterrno();
c_logmsg(progname,'123','c_deltsk error 0x%x', errcode);
exit(errcode);
}
See also
“c_trmtsk()” on page 240
“c_trm04()” on page 239
103
APPLICATION LIBRARY FOR C AND C++
DbletoPV()
Inserts a double value into a PARvalue union.
C/C++ synopsis
#include <src/defs.h>
#include <src/almmsg.h>
PARvalue* DbletoPV(
double dble_val,
PARvalue* pvvalue
);
Arguments
Argument Description
pvvalue (in) A pointer to a PARvalue structure.
double_val (in) The double value to insert into the PARvalue structure.
Description
Inserts a double value into a PARvalue, and then returns a pointer to the PARvalue passed in. This function allows
you to set attributes into a notification structure using calls to “hsc_insert_attrib()” on page 134 and
“hsc_insert_attrib_byindex()” on page 139 functions in a single line of code.
Diagnostics
If this function is successful, the return value is a pointer back to the PARvalue passed in, otherwise, the return
value is NULL and calling “hsc_insert_attrib()” on page 134 will retrieve the error code.
Possible errors returned are:
Example
See the examples in “hsc_insert_attrib()” on page 134 and “hsc_insert_attrib_byindex()” on page 139.
See also
“hsc_insert_attrib()” on page 134
“hsc_insert_attrib_byindex()” on page 139
“Int2toPV()” on page 203
“Int4toPV()” on page 204
“PritoPV()” on page 224
“RealtoPV()” on page 226
“StrtoPV()” on page 235
“TimetoPV()” on page 236
104 www.honeywell.com
APPLICATION LIBRARY FOR C AND C++
dsply_lrn()
Determines the LRN of the display task for a Station, based on the Station number.
C/C++ Synopsis
#include <src/defs.h>
int2 dsply_lrn(
int2* pStationNumber // pointer to the Station number
);
Arguments
Argument Description
pStationNumber (in) pointer to the Station number that will be used to find the LRN.
Description
Quickly determines the LRN of a particular Station's display task.
Diagnostics
This function returns the LRN (>0) if successful. Otherwise it returns -1.
See also
“stn_num()” on page 234
105
APPLICATION LIBRARY FOR C AND C++
c_ex()
Executes the command line.
C/C++ synopsis
#include <src/defs.h>
Arguments
Argument Description
command (in) pointer to a null-terminated string containing the command line to execute.
Description
Passes a command line string as input to the command line interpreter and executes it as if the command line
was entered in from a Console Window.
Diagnostics
If successful completion a value of 0 is returned. Otherwise, -1 is returned, and calling “c_geterrno()” on
page 112 will retrieve the error code relevant to the command line that was executed.
106 www.honeywell.com
APPLICATION LIBRARY FOR C AND C++
ftocstr()
Converts a FORTRAN string to a C string.
C/C++ synopsis
#include <src/defs.h>
char* ftocstr(
char* from_str,
int from_len,
char* to_str,
int to_len
);
Arguments
Argument Description
from_str (in) FORTRAN string to convert.
from_len (in) length of FORTRAN string
to_str (out) memory array for C string (to_str can be the same as from_str)
to_len (in) size of array for C string
Description
Given a FORTRAN string and the length of the string, this routine will convert it into a null terminated C string.
The string is returned in data buffer supplied.
A pointer to the string is returned if the conversion was successful and NULL pointer is returned if the string
passed in (minus trailing blanks) is longer than the output buffer length. In this case a truncated string is
returned in the output data buffer.
WARNING
This routine searches from the end of the string for the last non space character. Thus if the string contains
something other than spaces on the end of the string, the routine will not work.
If the name to convert is coming from C, then the strlen should be passed to this routine rather than the size of
the memory allocated for the name.
See also
“c_intchr()” on page 205
“c_chrint()” on page 94
“ctofstr()” on page 95
107
APPLICATION LIBRARY FOR C AND C++
c_gbload()
Loads the global common server database files.
C/C++ synopsis
#include <src/defs.h>
Description
Makes the server database accessible to the calling task.
The memory-resident sections of the database are attached to the calling task. This allows the calling task to
reference the database directly.
Diagnostics
Upon successful completion a value of 0 is returned. Otherwise, the application should report an error and
terminate. The error code can be subsequently retrieved by calling “c_geterrno()” on page 112.
Warnings
Should only be called once per execution of a task, before any other application routines are called.
Example
#include <src/defs.h>
#include <src/M4_err.h>
int errcode;
108 www.honeywell.com
APPLICATION LIBRARY FOR C AND C++
c_gdbcnt()
Gets a database control request.
C/C++ synopsis
#include <src/defs.h>
#include <src/M4_err.h>
Arguments
Argument Description
file (out) file number that was controlled.
record (out) record number that was controlled.
word (out) word number that was controlled.
bit (out) bit number that was controlled.
0-15 for int2 data, 0 for int4, float, dble.
width (out) width of the data that was controlled. 1-16 for int2 data, 32 for int4 and float, 64 for dble.
value (out) value to which the file, record, word, bit, width was controlled.
Description
Used to fetch and decode a control request from the database scan task. See 'Developing user scan tasks.'
Diagnostics
Upon successful completion a value of 0 is returned. Otherwise, -1 is returned, and calling c_geterrno() will
return one of the following error codes:
Related topics
“Developing user scan tasks” on page 65
109
APPLICATION LIBRARY FOR C AND C++
c_getapp()
Gets the application record for a task.
C/C++ synopsis
#include <src/defs.h>
#include <src/apptbl_def>
Arguments
Argument Description
task_name (in) character string containing the name of the task to find
task_lrn (in) logical resource number of the task to find. If -1 then not checked
appbuf (out) application record buffer as defined in APPTBL_DEF
Description
Finds the corresponding application table record that contains a reference to the specified task. If successful, it
will load the record into the supplied appbuf and return.
110 www.honeywell.com
APPLICATION LIBRARY FOR C AND C++
GetGDAERRcode()
Returns the error code from a GDAERR status structure.
C/C++ synopsis
#include <src/defs.h>
#include <src/gdamacro.h>
DWORD GetGDAERRcode(
GDAERR* pGdaError
);
Arguments
Argument Description
pGdaError (in) pointer to the GDAERR structure containing the status.
Description
Returns the error code associated with the GDAERR structure.
See also
“IsGDAwarning()” on page 208
“IsGDAerror()” on page 206
“IsGDAnoerror()” on page 207
111
APPLICATION LIBRARY FOR C AND C++
c_geterrno()
Returns the error code from an Experion Server API function.
C/C++ synopsis
#include <src/defs.h>
#include <src/M4_err.h>
int c_geterrno();
Arguments
None.
Returns
Returns the meaningful error code when a Experion Server API function has been called and has returned TRUE.
This function needs to be called as the first function immediately after a failed Server API call.
Description
Returns the most recent error code of the Server API function calls. Note that this may not be associated with
the most recent Server API function call, but from an earlier call, whichever last returned an error.
You should only ever retrieve the latest Server API error code immediately after testing each Server API
function return value for its error status.
Attention
Any applications that use the function c_geterrno() must include the M4_err.h header file, that is, #include <src/
M4_err.h>.
Example
#include <src/defs.h>
#include <src/M4_err.h>
int errcode;
See also
“Error codes in the Server API” on page 18
112 www.honeywell.com
APPLICATION LIBRARY FOR C AND C++
c_gethstpar_..._2()
Gets the history interface parameters.
C/C++ synopsis
#include <src/defs.h>
#include <src/M4_err.h>
#include <src/gethst.h>
Arguments
Argument Description
type (in) history type (see Description).
date (in) start date of history to retrieve in Julian days (number of days since 1 Jan 1981).
time (in) start time of history to retrieve in seconds since midnight.
offset (in) offset from latest history value in history intervals (where offset=1 is the most recent history
value).
numhst (in) number of history values to be returned per Point.
points (in) array of Point type/numbers to process (maximum of 100 elements).
params (in) array of point parameters to process. Each parameter is associated with the corresponding
entry in the points array. The possible parameters are defined in the file 'parameters' in the def
folder (maximum 100 elements).
numpnt (in) number of Points to be processed.
archive (in) pointer to a null-terminated string containing the folder name of the archive files relative to
the archive folder. A NULL pointer implies that the system will use current history and any
archive files that correspond to the value of the date and time parameters. The archive files are
found in <server folder>\archive.
For example, to access the files in <server folder>\archive\ay2012m09d26h11r008, the
archive argument is ay2012m09d26h11r008.
values (out) two dimensional array large enough to accept history values. If there is no history for the
requested time or if the data was bad, then -0.0 is stored in the array. Sized numpnt * numhst.
113
APPLICATION LIBRARY FOR C AND C++
Description
Used to retrieve a particular type of history values for specified Points and time in history. History will be
retrieved from a specified time or Offset going backwards in time numhst intervals for each Point specified.
The history values are stored in sequence in the values array. values[x][y] represents the yth history value for
the xth point.
The history type is specified by using one of the following values:
Value Description
HST_1MIN one minute standard history
HST_6MIN six minute standard history
HST_1HOUR one hour standard history
HST_8HOUR eight hour standard history
HST_24HOUR twenty four hour standard history
HST_5SECF Fast history
HST_1HOURE one hour extended history
HST_8HOURE eight hour extended history
HST_24HOURE twenty four hour extended history
Diagnostics
Upon successful completion a value of 0 is returned. Otherwise, -1 is returned, and calling c_geterrno() will
return one of the following error codes:
Example
#include <src/defs.h>
#include <src/M4_err.h>
#include <src/gethst.h>
#include "parameters"
#define NHST 50
#define NPNT 3
114 www.honeywell.com
APPLICATION LIBRARY FOR C AND C++
month = 4;
day = 16;
hour = 10;
minute = 0;
. . .
. . .
. . .
/* attach database */
if (c_gbload())
{
errcode = c_geterrno();
c_logmsg(progname,"123","c_gbload error %#x",errcode);
exit(errcode);
}
See also
“hsc_param_values()” on page 169
115
APPLICATION LIBRARY FOR C AND C++
c_getlrn()
Gets a logical resource number.
C/C++ synopsis
#include <src/defs.h>
Arguments
None.
Description
Fetches the calling task's Logical Resource Number (LRN). Each LRN is unique for the thread of each process.
Each thread can only be associated with one LRN and each LRN can only be associated with one thread.
Diagnostics
Upon successful completion, the task's LRN is returned. Otherwise, -1 is returned indicating that the task has
not been created as a server task.
See also
“AssignLrn()” on page 93
“DeassignLrn()” on page 102
116 www.honeywell.com
APPLICATION LIBRARY FOR C AND C++
c_getlst()
Gets values for a list of points.
C/C++ synopsis
#include <src/defs.h>
#include <src/M4_err.h>
#include <src/lstfil_def>
Arguments
Argument Description
list (in) list number (valid list numbers declared in def/src/lstfil_def)
values[ ] (out) real array of values of point\parameter list. Sized GGLNM.
errors[ ] (out) array of returned error codes. Sized GGLNM.
Description
Used to retrieve values for a list of points and parameters. These point lists can be viewed and modified using
the Application Point Lists display.
The arrays values and errors must be large enough to hold the number of items in a list as declared in the
parameter GGLNM in the file def/src/listfil_def.
Diagnostics
Upon successful completion zeros will be returned in all elements of the errors array. Otherwise one of the
following error codes will be returned in the corresponding element of the errors array:
See also
“c_givlst()” on page 122
“c_dataio_...()” on page 96
“hsc_param_values()” on page 169
“hsc_param_value_put()” on page 172
117
APPLICATION LIBRARY FOR C AND C++
c_getprm()
Gets parameters from a queued task request. (Requested via Action Algorithm 92).
C/C++ synopsis
#include <src/defs.h>
#include <src/M4_err.h>
Arguments
Argument Description
paramc (in) Parameter count. For standard use this value must be set to 3.
par1 (out) Parameter 1 value.
rqstblk (out) Pointer to request block buffer.
rqstblk_sz (in) Size of request block buffer in bytes.
Description
Gets parameters from a queued task request. The routine retrieves a parameter block from the request queue.
The words in the parameter block are copied to the argument rqstblk. If the task is expecting data and the
request queue is empty, a value of M4_EOF_ERR (0x21F) is returned and the task should terminate and wait for the
next request. If the parameter block is larger than the size of rqstblk, a value of M4_RECORD_LENGTH_ERR (0x21A)
is returned to indicate the data has been truncated. This routine enables a task to be requested via a point build
with Algorithm 92.
Diagnostics
Upon successful completion a value of 0 is returned. Otherwise, -1 is returned, and calling “c_geterrno()” on
page 112 will return the following error code: M4_ILLEGAL_LRN (0x802). The calling process has not been created
as an Experion task.
Example
#include 'src/defs.h'
#include 'src/M4_err.h'
#define BUFSZ 20
#define FOREVER 1
main()
{
int2 paramc = 3;
int2 par1 = 0;
int2 rqstblk[BUFSZ];
int2 rqstblk_sz;
int2 rqst_status;
int2 status;
while(FOREVER)
{
/* get the parameter block for this request */
rqst_status = c_getprm(¶mc, &par1, (int2 *)rqstblk, &rqstblk_sz);
if ( rqst_status == M4_EOF_ERR )
{
118 www.honeywell.com
APPLICATION LIBRARY FOR C AND C++
/********************************/
/* Main processing loop */
/* */
/********************************/
}
}
See also
“c_rqtskb...()” on page 227
“c_getreq()” on page 120
119
APPLICATION LIBRARY FOR C AND C++
c_getreq()
Gets parameters from task request block.
C/C++ synopsis
#include <src/defs.h>
#include <src/M4_err.h>
#include <src/trbtbl_def>
Arguments
Argument Description
prmblk (out) pointer to parameter block
Description
Retrieves a ten word parameter block from the TRBTBL of the calling task. If no requests are pending, returns
TRUE (-1) and calling “c_geterrno()” on page 112 will retrieve the error code M4_EOF_ERR (0x21F), otherwise, the
ten word parameter block is copied into the argument prmblk. The parameter block in the TRBTBL of the calling
task is then cleared and the function returns FALSE (0).
Diagnostics
Upon successful completion a value of 0 is returned. Otherwise, -1 is returned, and calling “c_geterrno()” on
page 112 will return one of the following error codes:
[M4_ILLEGAL_LRN] The calling process has not been created as a server task.
[M4_EOF_ERROR] There are no requests pending.
Example
#include <src/defs.h>
#include <src/M4_err.h>
#include <src/trbtbl_def>
main()
{
int errcode; /* Error number*/
struct prm prmblk;
if (c_gbload() == -1)
errcode = c_geterrno();
exit(errcode);
while (1)
{
if (c_getreq((int2 *) &prmblk))
{
errcode = c_geterrno();
if (errcode != M4_EOF_ERR)
{
/* Report an error */
}
/* Now terminate and wait for the */
/* next request */
c_trm04(ZERO_STATUS);
}
else
{
/* Perform some function */
/* Perhaps switch on the first */
/* Parameter */
120 www.honeywell.com
APPLICATION LIBRARY FOR C AND C++
switch(prmblk.param1)
{
case 1:
...
break;
case 2:
...
break;
} /* end switch */
} /* if */
} /* end while */
}
See also
“c_rqtskb...()” on page 227
“c_trm04()” on page 239
121
APPLICATION LIBRARY FOR C AND C++
c_givlst()
Gives values to a list of points.
C/C++ synopsis
#include <src/defs.h>
#include <src/M4_err.h>
#include <src/lstfil_def>
Arguments
Argument Description
list (in) list number (valid list numbers declared in lstfil_def)
values[ ] (in) real array of values of point/parameter list. Sized GGLNM
errors[ ] (out) array of returned error codes. Sized GGLNM
Description
Used to store values into a list of points and parameters and controls those parameters if they have a destination
address. Note that each individual parameter control is performed sequentially using a separate scan packet.
These point lists can be viewed and modified using the Application Point Lists display.
The arrays values and errors must be large enough to hold the number of items in a list as declared in the
parameter GGLNM in the file lstfil_def.
Diagnostics
Upon successful completion zeros will be returned in all elements of the errors array. Otherwise one of the
following error codes will be returned in the corresponding element of the errors array:
See also
“c_getlst()” on page 117
“c_dataio_...()” on page 96
“hsc_param_values()” on page 169
“hsc_param_value_put()” on page 172
122 www.honeywell.com
APPLICATION LIBRARY FOR C AND C++
hsc_asset_get_ancestors()
Gets the asset ancestors for an asset.
C/C++ synopsis
#include <src/defs.h>
#include <src/points.h>
int hsc_asset_get_ancestors(
PNTNUM ,
int* piNumAncestors,
PNTNUM** ppAncestors
);
Arguments
Argument Description
(in) asset point number
piNumAncestors (out) number of ancestors
ppAncestors (out) array of ancestors
Description
This functions returns the asset ancestors for the specified asset.
The array must be cleared by calling “hsc_em_FreePointList()” on page 127.
Diagnostics
If successful, 0 is returned, otherwise -1 is returned, and calling “c_geterrno()” on page 112 will retrieve the
error code.
Example
#include <src/defs.h>
#include <src/points.h>
int iNumAncestors = 0;
PNTNUM *pAncestors = NULL;
123
APPLICATION LIBRARY FOR C AND C++
hsc_asset_get_children()
Gets the children of an asset.
C/C++ synopsis
#include <src/defs.h>
#include <src/points.h>
int hsc_asset_get_children(
PNTNUM ,
int* piNumChildren,
PNTNUM** ppChildren
);
Arguments
Argument Description
(in) asset point number
piNumChildren (out) number of children
ppChildren (out) array of children
Description
Returns the asset children for the specified asset.
The array must be cleared by calling “hsc_em_FreePointList()” on page 127.
Diagnostics
If successful, 0 is returned, otherwise -1 is returned, and calling “c_geterrno()” on page 112 will retrieve the
error code.
Example
#include <src/defs.h>
#include <src/points.h>
int iNumChildren = 0;
PNTNUM *pChildren = NULL;
124 www.honeywell.com
APPLICATION LIBRARY FOR C AND C++
hsc_asset_get_descendents()
Gets the descendents of an asset.
C/C++ synopsis
#include <src/defs.h>
#include <src/points.h>
int hsc_asset_get_descendents(
PNTNUM ,
int* piNumDescendents,
PNTNUM** ppDescendents
);
Arguments
Argument Description
(in) asset point number
piNumDescendents (out) number of descendents
ppDescendents (out) array of descendents
Description
Returns the asset descendents for the specified asset.
The array must be cleared by calling “hsc_em_FreePointList()” on page 127.
Diagnostics
If successful, 0 is returned, otherwise -1 is returned, and calling “c_geterrno()” on page 112 will retrieve the
error code.
Example
#include <src/defs.h>
#include <src/points.h>
int iNumDescendents = 0;
PNTNUM *pDescendents = NULL;
if (hsc_asset_get_descendents (point, &iNumDescendents, &pDescendents) ! = 0)
return -1
.
.
.
hsc_em_FreePointList (pDescendents);
125
APPLICATION LIBRARY FOR C AND C++
hsc_asset_get_parents()
Gets the parent asset of an asset.
C/C++ synopsis
#include <src/defs.h>
#include <src/points.h>
int hsc_asset_get_parents(
PNTNUM ,
int* piNumParents,
PNTNUM** ppParents
);
Arguments
Argument Description
(in) asset point number
piNumParents (out) number of parents
ppParents (out) array of parents
Description
Returns the asset parents for the specified asset.
The array must be cleared by calling “hsc_em_FreePointList()” on page 127.
Diagnostics
If successful, 0 is returned, otherwise -1 is returned, and calling “c_geterrno()” on page 112 will retrieve the
error code.
Example
#include <src/defs.h>
#include <src/points.h>
int iNumParents = 0;
PNTNUM *pParents = NULL;
126 www.honeywell.com
APPLICATION LIBRARY FOR C AND C++
hsc_em_FreePointList()
Frees the memory used to hold a list of points.
C/C++ synopsis
#include <src/defs.h>
#include <src/points.h>
int hsc_em_FreePointList(
PNTNUM* pPointList
);
Arguments
Argument Description
pPointList (in) pointer to point list
Description
Frees the memory used to hold a list of points.
Diagnostics
If successful, 0 is returned, otherwise -1 is returned, and calling “c_geterrno()” on page 112 will retrieve the
error code.
127
APPLICATION LIBRARY FOR C AND C++
hsc_em_GetLastPointChangeTime()
Gets the last time a point was changed.
C/C++ synopsis
#include <src/defs.h>
#include <src/points.h>
void hsc_em_GetLastPointChangeTime(
HSCTIME* pTime
);
Description
Returns the last time that a point was changed on the server due to a Quick Builder or Enterprise Model Builder
download.
128 www.honeywell.com
APPLICATION LIBRARY FOR C AND C++
hsc_em_GetRootAlarmGroups()
Gets the point numbers of the root Alarm Groups.
C/C++ synopsis
#include <src/defs.h>
#include <src/points.h>
int hsc_em_GetRootAlarmGroups(
int* pCount,
PNTNUM** ppRootAlarmGroups
);
Arguments
Argument Description
pCount (out) number of root Alarm Groups
ppRootAlarmGroups (out) array of root Alarm Groups
Description
Returns the point numbers for all of the root Alarm Groups.
The array must be cleared by calling “hsc_em_FreePointList()” on page 127.
Diagnostics
If successful, 0 is returned, otherwise -1 is returned, and calling “c_geterrno()” on page 112 will retrieve the
error code.
Example
#include <src/defs.h>
#include <src/points.h>
int iNumRootAlarmGroups = 0;
PNTNUM *pRootAlarmGroups = NULL;
if (hsc_em_GetRootAlarmGroups (&iNumRootAlarmGroups, &pRootAlarmGroups) ! = 0)
return -1
.
.
.
hsc_em_FreePointList (pRootAlarmGroups);
129
APPLICATION LIBRARY FOR C AND C++
hsc_em_GetRootAssets()
Gets the point numbers for root assets.
C/C++ synopsis
#include <src/defs.h>
#include <src/points.h>
int hsc_em_GetRootAssets(
int* pCount,
PNTNUM** ppRoot
);
Arguments
Argument Description
pCount (out) number of root
ppRoot (out) array of root
Description
Returns the point numbers for all of the root assets.
The array must be cleared by calling “hsc_em_FreePointList()” on page 127.
Diagnostics
If successful, 0 is returned, otherwise -1 is returned, and calling “c_geterrno()” on page 112 will retrieve the
error code.
Example
#include <src/defs.h>
#include <src/points.h>
int iNumRoot = 0;
PNTNUM *pRoot = NULL;
if (hsc_em_GetRoot (&iNumRoot, &pRoot) ! = 0)
return -1;
.
.
.
hsc_em_FreePointList (pRoot);
130 www.honeywell.com
APPLICATION LIBRARY FOR C AND C++
hsc_em_GetRootEntities()
Gets the point numbers for all root entities.
C/C++ synopsis
#include <src/defs.h>
#include <src/points.h>
int hsc_em_GetRootEntities;(
int* pCount,
PNTNUM** ppRootEntities
);
Arguments
Argument Description
pCount (out) number of root entities
ppRootEntities (out) array of root entities
Description
Returns the point numbers for all of the root entities in the enterprise model.
The array must be cleared by calling “hsc_em_FreePointList()” on page 127.
Diagnostics
If successful, 0 is returned, otherwise -1 is returned, and calling “c_geterrno()” on page 112 will retrieve the
error code.
Example
#include <src/defs.h>
#include <src/points.h>
int iNumRootEntities = 0;
PNTNUM *pRootEntities = NULL;
if (hsc_em_GetRootEntities (&iNumRootEntities, &pRootEntities) ! = 0)
return -1
.
.
.
hsc_em_FreePointList (pRootEntities);
131
APPLICATION LIBRARY FOR C AND C++
hsc_enumlist_destroy()
Safely destroys an enumlist.
C/C++ synopsis
#include <src/defs.h>
#include <src/points.h>
int hsc_enumlist_destroy(
enumlist** list
);
Arguments
Argument Description
List (in) pointer to an enumeration list.
Description
Deallocates all strings in an enumeration list along with the array itself.
Diagnostic
The return value will be 0 if successful, otherwise -1 is returned, and calling “c_geterrno()” on page 112 will
retrieve the error code.
Example
Retrieve the enumerated list of values for Pntana1's MD parameter and output this list.
#include <src/defs.h>
#include <src/points.h>
PNTNUM point;
PRMNUM param;
enumlist* list;
int i,n;
point = hsc_point_number('Pntana1');
param = hsc_param_number(point,'MD');
n = hsc_param_enum_list_create(point,param, &list);
for(i=0;i<n;i++)
c_logmsg('example','enum_listcall', '%10s\t%d',list[i].text,list[i].value);
/*process enumlist*/
hsc_enumlist_destroy (&list);
132 www.honeywell.com
APPLICATION LIBRARY FOR C AND C++
hsc_GUIDFromString()
Converts a GUID from string format to binary format.
C/C++ synopsis
#include <src/defs.h>
#include <src/points.h>
int hsc_GUIDFromString;(
char* szGUID,
GUID* pGUID
);
Arguments
Argument Description
szGUID (in) GUID in string format
pGUID (out) GUID in binary format
Description
This function converts a GUID from string format to binary format.
Diagnostics
If successful, 0 is returned, otherwise -1 is returned, and calling “c_geterrno()” on page 112 will retrieve the
error code.
133
APPLICATION LIBRARY FOR C AND C++
hsc_insert_attrib()
Sets an attribute value (identified by name) of a notification structure.
Note that this same functionality can be achieved by using index values instead of named attributes through the
use of the “hsc_insert_attrib_byindex()” on page 139 function.
C/C++ synopsis
#include <src/defs.h>
#include <src/almmsg.h>
int hsc_insert_attrib(
NOTIF_STRUCT* notification,
char* attribute_name,
PARvalue* value,
int2 type
);
Arguments
Argument Description
notification (in/out) A pointer to the notification structure.
attribute_name (in) The name of the attribute to set. See “Attribute Names and Index Values” on page 136 for a
list of attribute names.
value (in) A pointer to PARvalue that contains the attribute value. PARvalue is a union of data types
and its definition is (definition from include/src/points.h):
typedef union
{
GDAVARIANT var;
char text[PARAM_MAX_STRING_LEN+1];
short int2;
long int4;
int8 int8;
float real;
double dble;
struct {
long ord;
char text[PARAM_MAX_STRING_LEN+1];
} en;
struct {
ULONG cSize; /* size of serialized variant */
BYTE *pData; /* pointer to serialized variant */
} servar;
HSCTIME time;
} PARvalue;
type (in) The value type being passed.
Description
Sets an attribute in the notification structure for use with the “hsc_notif_send()” on page 146 function to raise or
normalize an alarm, event, or message, as appropriate.
The category attribute must be the first attribute set and can only be set once within a notification structure. If
you do not set category as the first attribute, INV_CATEGORY is the return error and the specified attribute is not
set. Once you have set the category attribute, you can set other attributes.
This function will attempt to convert the attribute value type from the specified type to the default type for that
attribute. If this function cannot convert the specified type to the default type, VALUE_COULD_NOT_BE_CONVERTED is
the return error. If this function does not know the specified type, ILLEGAL_TYPE is the return error.
This function validates the attribute values for asset and category. If the asset attribute value is invalid, INV_AREA
is the return error, and if the category value is invalid, INV_CATEGORY is the return error. This function also
validates the attribute values for station and priority. If these attribute values are invalid, BAD_VALUE is the return
error.
134 www.honeywell.com
APPLICATION LIBRARY FOR C AND C++
Diagnostics
If the function is successful, the return value is HSC_OK, otherwise the return value is HSC_ERROR and calling
“c_geterrno()” on page 112 will retrieve one of the following error codes:
BAD_VALUE The specified attribute value is not valid for this attribute.
BUFFER_TOO_SMALL The pointer to the notification structure buffer is invalid, that is, null.
INV_ATTRIBUTE The specified attribute name does not exist, or you do not have access to
manipulate it.
ILLEGAL_TYPE The specified type does not exist.
INV_AREA The specified asset attribute is not a valid asset.
VALUE_COULD_NOT_BE_CONVERTED The type could not be converted from the specified type to the default type
for that attribute.
ATTR_NOT_IN_CAT The specified attribute does not belong to this category. For a list of valid
attributes for a category, see “Valid Attributes for a Category” on page 138.
INV_CATEGORY The category for this notification has not been set or the passed category
value is not a valid category.
CAT_ALREADY_ASSIGNED The category for this notification has already been set and cannot be reset.
Example
The following example creates a notification structure for a system alarm, setting the description to 'Server
API Alarm,' the priority to ALMMSG_LOW, the sub-priority to 0, and the value to 4.
#include <src/defs.h>
#include "src/almmsg.h"
#include 'src/M4_err.h'
// PARvalue Buffer
PARvalue pvTmp;
135
APPLICATION LIBRARY FOR C AND C++
See also
“hsc_insert_attrib_byindex()” on page 139
“hsc_notif_send()” on page 146
“DbletoPV()” on page 104
“Int2toPV()” on page 203
“Int4toPV()” on page 204
“PritoPV()” on page 224
“RealtoPV()” on page 226
“StrtoPV()” on page 235
“TimetoPV()” on page 236
136 www.honeywell.com
APPLICATION LIBRARY FOR C AND C++
137
APPLICATION LIBRARY FOR C AND C++
138 www.honeywell.com
APPLICATION LIBRARY FOR C AND C++
hsc_insert_attrib_byindex()
Sets an attribute (identified by its index value) of a notification structure.
Note that this same functionality can be achieved by using named attributes instead of index values through the
use of the “hsc_insert_attrib()” on page 134 function.
C/C++ synopsis
#include <src/defs.h>
#include <src/almmsg.h>
int hsc_insert_attrib_byindex(
NOTIF_STRUCT* notification,
int2 attribute_index,
PARvalue* value,
int2 type
);
Arguments
Argument Description
notification (in/out) A pointer to the notification structure.
attribute_index (in) The index value of the attribute to insert. See “Attribute Names and Index Values” on
page 136 for a list of index values.
value (in) A pointer to PARvalue that contains the attribute value. PARvalue is a union of data types
and its definition is (definition from include/src/points.h):
typedef union
{
GDAVARIANT var;
char text[PARAM_MAX_STRING_LEN+1];
short int2;
long int4;
int8 int8;
float real;
double dble;
struct {
long ord;
char text[PARAM_MAX_STRING_LEN+1];
} en;
struct {
ULONG cSize; /* size of serialized variant */
BYTE *pData; /* pointer to serialized variant */
} servar;
HSCTIME time;
} PARvalue;
type (in) The value type being passed.
Description
Sets an attribute in the notification structure for use with the “hsc_notif_send()” on page 146 function to raise or
normalize an alarm, event, or message, as appropriate.
The ALMEVTCATIDX (category) attribute must be the first attribute set and can only be set once within a
notification structure. If you do not set ALMEVTCATIDX as the first attribute, INV_CATEGORY is the return error and
the specified attribute is not set. Once you have set the ALMEVTCATIDX attribute, you can set other attributes.
This function will attempt to convert the attribute value type from the specified type to the default type for that
attribute. If this function cannot convert the specified type to the default type, VALUE_COULD_NOT_BE_CONVERTED is
the return error. If this function does not know the specified type, ILLEGAL_TYPE is the return error.
This function validates the attribute values for asset and category. If the asset attribute value is invalid, INV_AREA
is the return error, and if the category value is invalid, INV_CATEGORY is the return error. This function also
validates the attribute values for station and priority. If these attribute values are invalid, BAD_VALUE is the return
error.
139
APPLICATION LIBRARY FOR C AND C++
Diagnostics
If the function is successful, the return value is HSC_OK, otherwise the return value is HSC_ERROR and calling
“c_geterrno()” on page 112 will retrieve the error code.
The possible errors returned are:
BAD_VALUE The specified attribute value is not valid for this attribute.
BUFFER_TOO_SMALL The pointer to the notification structure buffer is invalid, that is, null.
INV_ATTRIBUTE The specified attribute name does not exist, or you do not have access to
manipulate it.
ILLEGAL_TYPE The specified type does not exist.
INV_AREA The specified asset attribute is not a valid asset.
VALUE_COULD_NOT_BE_CONVERTED The type could not be converted from the specified type to the default type
for that attribute.
ATTR_NOT_IN_CAT The specified attribute does not belong to this category. For a list of valid
attributes for a category, see “Valid Attributes for a Category” on page 138.
INV_CATEGORY The category for this notification has not been set or the passed category
value is not a valid category.
CAT_ALREADY_ASSIGNED The category for this notification has already been set and cannot be reset.
Example
The following example creates a notification structure for a system alarm, setting the description to 'Server
API Alarm,' the priority to ALMMSG_LOW, the sub-priority to 0, and the value to 4.
#include <src/defs.h>
#include "src/almmsg.h"
// PARvalue Buffer
PARvalue pvTmp;
140 www.honeywell.com
APPLICATION LIBRARY FOR C AND C++
See also
“DbletoPV()” on page 104
“hsc_insert_attrib()” on page 134
“hsc_notif_send()” on page 146
“Int2toPV()” on page 203
“Int4toPV()” on page 204
“PritoPV()” on page 224
“RealtoPV()” on page 226
“StrtoPV()” on page 235
“TimetoPV()” on page 236
141
APPLICATION LIBRARY FOR C AND C++
hsc_IsError()
Determines whether a returned status value is an error.
C/C++ synopsis
#include <src/defs.h>
#include <src/M4_err_def>
int hsc_IsError(
int code
);
Arguments
Argument Description
code (in) The status code to check.
Description
Determines whether a particular status code is an error. Most C functions indicate success by returning a 0 in the
return value. If a function returns a non-zero value, calling “c_geterrno()” on page 112 will retrieve the error
code. This value can then be checked to see if it indicates an error or warning.
Status values can indicate an error, a warning, or success. Some functions return a GDAERR structure instead. Use
the macro “IsGDAerror()” on page 206 to check this value for an error.
Diagnostics
This routine returns TRUE (-1) if code indicates an error condition, otherwise it returns FALSE (0).
See also
“hsc_IsWarning()” on page 143
“IsGDAerror()” on page 206
142 www.honeywell.com
APPLICATION LIBRARY FOR C AND C++
hsc_IsWarning()
Determines whether a returned status value is a warning.
C/C++ synopsis
#include <src/defs.h>
#include <src/M4_err.h>
int hsc_IsWarning(
int code
);
Arguments
Argument Description
code (in) The status code to check.
Description
Determines whether a particular status code is warning. Most C functions indicate success by returning a 0 in
the return value. If a function returns a non-zero value, calling “c_geterrno()” on page 112 will retrieve the error
code. This value can then be checked to see if it indicates an error or warning.
Status values can indicate an error, a warning, or success. Some functions return a GDAERR structure instead. Use
the macro “IsGDAerror()” on page 206 to check this value for an error.
Diagnostics
This routine returns TRUE (-1) code indicates an warning condition, otherwise it returns FALSE (0).
See also
“hsc_IsError()” on page 142
“IsGDAwarning()” on page 208
143
APPLICATION LIBRARY FOR C AND C++
hsc_lock_file()
Locks a database file.
C/C++ synopsis
#include <src/defs.h>
#include <src/M4_err.h>
int hsc_lock_file(
int file,
int delay
);
Arguments
Argument Description
file (in) server file number.
delay (in) delay time in milliseconds before lock attempt will fail.
Description
Performs advisory locking of database files. Advisory locking means the tasks which use the file must take
responsibility for setting and removing locks as required.
For more information regarding database locking see “Ensuring database consistency” on page 45.
Diagnostics
Upon successful completion a value of 0 is returned. Otherwise, -1 is returned and calling “c_geterrno()” on
page 112 will retrieve one of the following error codes:
See also
“hsc_lock_record()” on page 145
“hsc_unlock_file()” on page 197
“hsc_unlock_record()” on page 198
144 www.honeywell.com
APPLICATION LIBRARY FOR C AND C++
hsc_lock_record()
Locks a record of a database file.
C/C++ synopsis
#include <src/defs.h>
#include <src/M4_err.h>
int hsc_lock_record(
int file,
int record,
int delay
);
Arguments
Argument Description
file (in) server file number.
record (in) record number (see description).
delay (in) delay time in milliseconds before lock attempt will fail.
Description
Performs advisory locking of database record. Advisory locking means the tasks which use the record must take
responsibility for setting and removing locks as required.
For more information regarding database locking see 'Ensuring database consistency.'
Diagnostics
Upon successful completion a value of 0 is returned. Otherwise, -1 is returned and calling “c_geterrno()” on
page 112 will retrieve one of the following error codes:
See also
“hsc_lock_file()” on page 144
“hsc_unlock_file()” on page 197
“hsc_unlock_record()” on page 198
Related topics
“Ensuring database consistency” on page 45
145
APPLICATION LIBRARY FOR C AND C++
hsc_notif_send()
Sends a notification structure to raise or normalize an alarm, event, or message.
C/C++ synopsis
#include <src/defs.h>
#include <src/almmsg.h>
int hsc_notif_send(
NOTIF_STRUCT* notification,
NOTIF_SEND_MODE mode
);
Arguments
Argument Description
notification (in) A pointer to the notification structure.
mode (in) The mode to send the notification.
• RAISE sends the notification in the unacknowledged and off-normal state.
• RAISE_NORMALIZED sends the notification in the unacknowledged and normal state.
• NORMALIZE changes the state of a previous notification with identical source and condition,
from off-normal to normal.
Description
Sends a notification (as created using the “hsc_insert_attrib()” on page 134 and “hsc_insert_attrib_byindex()”
on page 139 functions), for storing in the alarm file, or event file, or message directory, as appropriate to the
category set in the notification structure.
Note that if a Station printer has been configured to print alarms, events, or messages, this notification will also
be printed as appropriate.
This function validates the attribute values of the notification structure for asset, tagname, and Station. If not
explicitly set, this function sets default values.
Diagnostics
If the function is successful, the return value is HSC_OK, otherwise the return value is HSC_ERROR and calling
“c_geterrno()” on page 112 will retrieve one of the following errors:
Example
This example sends an unacknowledged and off-normal alarm and then returns that alarm to normal.
#include <src/defs.h>
#include <src/almmsg.h>
// PARvalue Buffer
PARvalue pvTmp;
146 www.honeywell.com
APPLICATION LIBRARY FOR C AND C++
See also
“hsc_insert_attrib()” on page 134
“hsc_insert_attrib_byindex()” on page 139
147
APPLICATION LIBRARY FOR C AND C++
148 www.honeywell.com
APPLICATION LIBRARY FOR C AND C++
hsc_param_enum_list_create()
Get an enumerated list of parameter values.
C/C++ synopsis
#include <src/defs.h>
#include <src/points.h>
int hsc_param_enum_list_create
(
PNTNUM point,
PRMNUM param,
enumlist** list
);
Arguments
Argument Description
point (in) point number
param (in) point parameter number
list (in/out) pointer to an enumeration list of parameters enumlist is defined as (definition from
include/src/dictionary.h):
typedef struct
{
int value;
char* text;
} enumlist;
Description
Returns a list of enumeration strings for the point parameter value, where applicable.
Diagnostics
The return value will be the number of entries in the list, otherwise -1 if an error was encountered and calling
c_geterrno() will retrieve the error code.
In all cases the enumlist structure is created by “hsc_param_enum_list_create()” on page 149 with enough space
for the text field in each enumlist element in the enumlist array. Because this memory is allocated by the
function, your user code needs to free this space when you finish using the structure. As these functions always
allocate the memory required for the text field, make sure that you free all memory before calling the routines a
second time with the same enumlist** pointer, otherwise there will be a memory leak. To facilitate freeing this
memory, “hsc_enumlist_destroy()” on page 132 has been added to the API.
Example
Retrieve the enumerated list of values for Pntana1's MD parameter and output this list.
#include <src/defs.h>
#include <src/points.h>
PNTNUM point;
PRMNUM param;
enumlist* list;
int i,n;
point = hsc_point_number('Pntana1');
param = hsc_param_number(point,'MD');
149
APPLICATION LIBRARY FOR C AND C++
n = hsc_param_enum_list_create(point,param, &list);
for(i=0;i<n;i++)
c_logmsg('example',
'enum_listcall',
'%10s\t%d',
list[i].text,
list[i].value);
/*process enumlist*/
hsc_enumlist_destroy (&list);
See also
“hsc_param_enum_ordinal()” on page 151
“hsc_enumlist_destroy()” on page 132
150 www.honeywell.com
APPLICATION LIBRARY FOR C AND C++
hsc_param_enum_ordinal()
Get an enumeration's ordinal value.
C/C++ synopsis
#include <src/defs.h>
#include <src/points.h>
int hsc_param_enum_ordinal(
PNTNUM point,
PRMNUM param,
char* string
);
Arguments
Argument Description
point (in) point number
param (in) point parameter number
string (in) enumeration string
Description
Returns the ordinal value that corresponds to the enumeration string for the point parameter.
Diagnostics
Returns the ordinal number on success and -1 if an error was encountered. The error code can be retrieved by
calling “c_geterrno()” on page 112.
Example
Determine the ordinal number of the enumeration 'AUTO' for 'MD' parameter for point 'Pntana1.'
#include <src/defs.h>
#include <src/points.h>
#include <src/M4_err.h>
PNTNUM point;
PRMNUM param;
int4 ordinal;
point = hsc_point_number('Pntana1');
param = hsc_param_number(point,'MD');
if((ordinal=hsc_param_enum_ordinal (point,param,'AUTO'))<0)
c_logmsg('example', 'ord call',
'call to hsc_param_enum_ordinal failed,
error code = %d',
c_geterrno());
else
c_logmsg('example','ord call',
'Ordinal value for AUTO is %d.',ordinal);
151
APPLICATION LIBRARY FOR C AND C++
hsc_param_enum_string()
Gets an enumeration string.
C/C++ synopsis
#include <src/defs.h>
#include <src/points.h>
char* hsc_param_enum_string(
PNTNUM point,
PRMNUM param,
int4 ordinal
);
Arguments
Argument Description
point (in) point number
param (in) point parameter number
ordinal (in) enumeration ordinal value
Description
Returns the enumeration string that corresponds to the ordinal value for the point parameter.
Diagnostic
Returns the enumeration string, or NULL and calling “c_geterrno()” on page 112 will retrieve the error code.
The enumeration string must be freed by the caller using the system call free().
152 www.honeywell.com
APPLICATION LIBRARY FOR C AND C++
hsc_param_format()
Gets a parameter's format.
C/C++ synopsis
#include <src/defs.h>
#include <src/points.h>
int hsc_param_format (
PNTNUM point,
PRMNUM param
);
Arguments
Argument Description
point (in) point number
param (in) parameter number
Description
This routine will return the format of the specified point parameter, and will be one of the following, or negative
if invalid:
DF_CHAR, /* character */
DF_NUM, /* numeric */
DF_POINT, /* point name */
DF_PARAM, /* parameter name */
DF_ENG, /* engineering units */
DF_PCT, /* percent */
DF_ENUM, /* enumerated */
DF_MODE, /* enumerated mode */
DF_BIT, /* TRUE/FALSE */
DF_STATE, /* state descriptor */
DF_PNTTYPE, /* point type */
DF_TIME, /* time */
DF_DATE, /* date */
DF_DATE_TIME, /* time stamp */
DF_GETVAL /* format as pnt-param */
Example
Determines the data format of the parameter PointDetailDisplayDefault of point 'pntana1' and outputs this
format's value.
#include <src/defs.h>
#include <src/points.h>
PRMNUM param;
PNTNUM point;
int paramFormat;
point = hsc_point_number("pntana1");
param = hsc_param_number(point, "PointDetailDisplayDefault");
if((paramFormat = hsc_param_format(point, param)) < 0)
c_logmsg ("example","param_format call",
"Error getting param format for point %d,
param %d",
point,
param);
else
c_logmsg ("example",
"param_format call",
"Param format of point %d,
parameter %d is %d",
point,
153
APPLICATION LIBRARY FOR C AND C++
param,
paramFormat);
See also
“hsc_param_type()” on page 164
154 www.honeywell.com
APPLICATION LIBRARY FOR C AND C++
hsc_param_limits()
Get parameter data entry limits.
C/C++ synopsis
#include <src/defs.h>
#include <src/points.h>
int hsc_param_limits (
PNTNUM point,
PRMNUM param,
double* min,
double* max
);
Arguments
Argument Description
point (in) point number
param (in) parameter number
min (out) minimum value
max (out) maximum value
Description
Returns the minimum and maximum data entry limits of the specified point parameter.
Diagnostics
This function always returns 0. If an error occurs, min will be set to 0.0 and max to 100.0.
Example
Find the parameter limits for point 'pntana1' and parameter 'SP' and output them.
#include <src/defs.h>
#include <src/points.h>
PRMNUM param;
PNTNUM point;
double limitMin, limitMax;
point = hsc_point_number("pntana1");
param = hsc_param_number(point, "SP");
if(hsc_param_limits(point, param, &limitMin, &limit Max) != 0)
c_logmsg ("example",
"param_limits call",
"Error getting param limits for point %d,
param %d",
point,
param);
else
c_logmsg ("example",
"param_limits call",
"Param limits of point %d,
parameter %d are %f -> %f ",
point,
param,
limitMin,
limitMax);
155
APPLICATION LIBRARY FOR C AND C++
See also
“hsc_param_type()” on page 164
156 www.honeywell.com
APPLICATION LIBRARY FOR C AND C++
hsc_param_subscribe()
Subscribe to a list of point parameters.
C/C++ synopsis
#include <src/defs.h>
#include <src/points.h>
int hsc_param_subscribe(
int number,
PNTNUM* points,
PRMNUM* param,
int period
);
Arguments
Argument Description
number (in) number of entries in lists
points (in) list of point numbers
params (in) list of parameter numbers
period (in) subscription period (msecs)
Description
Declares interest in point parameters so that data will be available in the point record, without the need to fetch
it from the appropriate location.
Diagnostics
This function will return 0 if successful, otherwise the relevant status code will be returned.
See also
“hsc_param_values()” on page 169
157
APPLICATION LIBRARY FOR C AND C++
hsc_param_list_create()
Gets a list of parameters.
C/C++ synopsis
#include <src/defs.h>
#include <src/points.h>
int hsc_param_list_create(
PNTNUM point,
enumlist** list
);
Arguments
Argument Description
point (in) point number, specify 0 for all parameters of all point types
list (in/out) pointer to an enumeration list of parameters enumlist is defined as (definition from
include/src/dictionary.h):
typedef struct
{
int value;
char* text;
} enumlist;
• value is the parameter number if the parameter is currently stored in the server database. A
zero value may indicate a parameter has not previously been accessed. To obtain the
parameter number use hsc_param_number.
• text is the null terminated string containing the parameter name
Description
Returns pointer to a list of names and numbers for the point's parameters.
Diagnostics
The return value of this function indicates the number of parameters stored in the list structure.
In all cases the enumlist structure is created by “hsc_param_list_create()” on page 158 with enough space for
the text field in each enumlist element in the enumlist array. Because this memory is allocated by the function,
your user code needs to free this space when you finish using the structure. As these functions always allocate
the memory required for the text field, make sure that you free all memory before calling the routines a second
time with the same enumlist** pointer, otherwise there will be a memory leak. To facilitate freeing this memory,
“hsc_enumlist_destroy()” on page 132 is included in the API.
Example
Retrieves all the parameters for point 'pntana1', and print out the name.
#include <src/defs.h>
#include <src/points.h>
#define LISTSZ 1000
enumlist* list;
int n,i;
PNTNUM point;
point = hsc_point_number('pntana1');
n = hsc_param_list_create(point, &list);
for (i=0; i<n; i++)
c_logmsg ('example',
'param_list call',
158 www.honeywell.com
APPLICATION LIBRARY FOR C AND C++
See also
“hsc_enumlist_destroy()” on page 132
“hsc_param_number()” on page 161
159
APPLICATION LIBRARY FOR C AND C++
hsc_param_name()
Get a parameter name.
C/C++ synopsis
#include <src/defs.h>
#include <src/points.h>
int hsc_param_name(
PNTNUM point,
PRMNUM param,
char* name,
int namelen
);
Arguments
Argument Description
point (in) point number
param (in) parameter number
name (out) parameter name
namelen (in) length of name string
Description
The parameter name is returned for the parameter number of the point specified. Note that the char buffer needs
to be big enough to store the parameter name in it, and that this length (of the buffer) must be passed in the
function.
Example
The parameter name for the parameter numbered 16 is returned for point 'pntana1', and prints it out.
#include <src/defs.h>
#include <src/points.h>
PNTNUM point;
PRMNUM param;
char paramName[MAX_PARAM_NAME_LEN+1];
point = hsc_point_number("pntana1");
param = 16;
hsc_param_name(point,param,paramName,MAX_PARAM_NAME_LEN+1);
c_logmsg ("example",
"param_list call",
"Parameter %s is parameter number %d for point %s.",
paramName,
param,
point);
See also
“hsc_param_number()” on page 161
160 www.honeywell.com
APPLICATION LIBRARY FOR C AND C++
hsc_param_number()
Gets the parameter's number.
C/C++ synopsis
#include <src/defs.h>
#include <src/points.h>
PRMNUM hsc_param_number(
PNTNUM point,
char* name
);
Arguments
Argument Description
point (in) point number
name (in) parameter name
Description
Returns the number of the named point parameter. If the point number is zero, then ALL point types will be
searched.
Diagnostics
If the parameter can not be found or an error occurs 0 will be returned, and calling “c_geterrno()” on page 112
will retrieve the error code.
If the point number is zero then all points are searched for the corresponding parameter name. This will then
return the first match to any fixed parameters of points in the system. It will not, however, resolve a flexible
parameter name to a number, as this parameter number is specific to a point not all points.
Example
The parameter number for the parameter PointDetailDisplayDefault is returned for point 'pntana1,' and is
output.
#include <src/defs.h>
#include <src/points.h>
PNTNUM point;
PRMNUM param;
char *paramName = "PointDetailDisplayDefault";
point = hsc_point_number("pntana1");
param = hsc_param_number(point, paramName);
c_logmsg ("example",
"param_number call",
"Parameter %s is parameter number %d for point number %d.",
paramName,
param,
point);
See also
“hsc_param_name()” on page 160
161
APPLICATION LIBRARY FOR C AND C++
hsc_param_range()
Get parameter data range.
C/C++ synopsis
#include <src/defs.h>
#include <src/points.h>
int hsc_param_range(
PNTNUM point,
PRMNUM param,
double* min,
double* max
);
Arguments
Argument Description
point (in) point number
param (in) parameter number
min (out) minimum value
max (out) maximum value
Description
Returns the minimum and maximum range of the specified point parameter.
Diagnostics
This function always returns 0. If an error occurs, min will be set to 0.0 and max to 100.0.
Example
Find the parameter ranges for point 'pntana1' and parameter 'SP' and output them.
#include <src/defs.h>
#include <src/points.h>
PRMNUM param;
PNTNUM point;
double rangeMin, rangeMax;
point = hsc_point_number("pntana1");
param = hsc_param_number(point, "SP");
if(hsc_param_range(point, param, &rangeMin, &rangeMax) != 0)
c_logmsg ("example",
"param_range call",
"Error getting param range for point %d,
param %d",
point,
param);
else
c_logmsg ("example",
"param_range call",
"Param range of point %d,
parameter %d is %f -> %f",
point,
param,
rangeMin,
rangeMax);
162 www.honeywell.com
APPLICATION LIBRARY FOR C AND C++
See also
“hsc_param_limits()” on page 155
163
APPLICATION LIBRARY FOR C AND C++
hsc_param_type()
Get a parameter's data type.
C/C++ synopsis
#include <src/defs.h>
#include <src/points.h>
int hsc_param_type(
PNTNUM point,
PRMNUM param
);
Arguments
Argument Description
point (in) point number
param (in) parameter number
Description
This routine will return the data type of the specified point parameter, and will be one of the following, or
negative if invalid:
DT_CHAR /* character string */
DT_INT2 /* 1 to 16 bit short integer */
DT_INT4 /* 1 to 32 bit long integer */
DT_REAL /* short float */
DT_DBLE /* long float */
DT_HIST /* history (-0 => large float) */
DT_VAR /* variant */
DT_ENUM /* enumeration ' */
DT_DATE_TIME /* timestamp (integer*2 day, double sec) */
DT_TIME /* date and time (HSCTIME format) */
DT_INT8 /* 64-bit integer */
DT_SRCADDR /* source address */
DT_DSTADDR /* destination address */
Example
Determine the data type of the parameter PointDetailDisplayDefault of point 'pntana1' and output this type's
value.
#include <src/defs.h>
#include <src/points.h>
PRMNUM param;
PNTNUM point;
int paramType;
point = hsc_point_number("pntana1");
param = hsc_param_number(point, "PointDetailDisplayDefault");
if((paramType = hsc_param_type(point, param)) < 0)
c_logmsg ("example",
"param_type call",
"Error getting param type for point %d,
param %d",
point,
param);
else
c_logmsg ("example",
"param_type call",
"Parameter type of point %d,
parameter %d is %d",
point,
param,
paramType);
164 www.honeywell.com
APPLICATION LIBRARY FOR C AND C++
See also
“hsc_param_format()” on page 153
165
APPLICATION LIBRARY FOR C AND C++
hsc_param_value()
Get a point parameter value.
C/C++ synopsis
#include <src/defs.h>
#include <src/points.h>
int hsc_param_value(
PNTNUM point,
PRMNUM param,
int* offset,
PARvalue* value,
uint2* type
);
Arguments
Argument Description
point (in) point number
param (in) parameter number
offset (in) point parameter offset (for history parameters).
value (out) value union
PARvalue is a union of data types and is defined as follows (definition from include/src/points.h):
typedef union
{
short int2;
long int4;
float real;
double dble;
char text[PARAM_MAX_STRING_LEN+1];
struct {
long ord;
char text[PARAM_MAX_STRING_LEN+1];
} en;
} PARvalue;
type (out) value data type (defined in the parameters file)
Description
The parameter's definition is located and used to access the point record using a common routine which returns
the pointer to the data. The top level routine then extracts the value by type.
It is recommended that “hsc_param_values()” on page 169 be used in preference to this function, as it allows
the subscription period to be specified.
If your system uses dynamic scanning, hsc_param_value() calls from the Server API do not trigger dynamic
scanning.
Diagnostics
0 will be returned if successful, otherwise -1 will be returned, and calling c_geterrno() will retrieve the error
code. The value returned in type will be one of the following constants defined in the parameter file:
DT_CHAR /* character string */
DT_INT2 /* 1 to 16 bit short integer */
DT_INT4 /* 1 to 32 bit long integer */
DT_REAL /* short float */
DT_DBLE /* long float */
DT_HIST /* history (-0 => large float) */
DT_VAR /* variant */
DT_ENUM /* enumeration ' */
DT_DATE_TIME /* timestamp (integer*2 day, double sec) */
166 www.honeywell.com
APPLICATION LIBRARY FOR C AND C++
See also
“hsc_param_values()” on page 169
“hsc_param_number()” on page 161
“hsc_point_number()” on page 194
167
APPLICATION LIBRARY FOR C AND C++
hsc_param_value_of_type()
Get a point parameter value of specified type.
C/C++ synopsis
#include <src/defs.h>
#include <src/points.h>
int hsc_param_value_of_type(
PNTNUM point,
PRMNUM param,
int* offset,
PARvalue* value,
uint2* type
);
Arguments
Argument Description
point (in) point number
param (in) parameter number
offset (in) point parameter offset (for history parameters).
value (out) value union
PARvalue is a union of data types and is defined as follows (definition from include/src/points.h):
typedef union
{
short int2;
long int4;
float real;
double dble;
char text[PARAM_MAX_STRING_LEN+1];
struct {
long ord;
char text[PARAM_MAX_STRING_LEN+1];
} en;
} PARvalue;
type (out) value data type (defined in the parameters file)
Description
The parameter's definition is located and used to access the point record using a common routine which returns
the pointer to the data. The top level routine then extracts the value by type.
If your system uses dynamic scanning, hsc_param_value_of_type() calls from the Server API do not trigger
dynamic scanning.
See also
“hsc_param_values()” on page 169
“hsc_param_number()” on page 161
“hsc_point_number()” on page 194
168 www.honeywell.com
APPLICATION LIBRARY FOR C AND C++
hsc_param_values()
Get multiple point parameter values.
C/C++ synopsis
#include <src/defs.h>
#include <src/points.h>
int hsc_param_values(
int count, // (in) #point-parameters
int period, // (in) subscription period
PNTNUM* points, // (in) point numbers
PRMNUM* params, // (in) point parameter numbers
int* offsets, // (in) point parameter offset
PARvalue* values, // (out) values
uint2* types, // (out) value types
int* statuses // (out) return statuses
);
Arguments
Argument Description
count (in) the number of point parameters in the list to get.
period (in) subscription period in milliseconds for the point parameters. Use the constant
HSC_READ_CACHE if subscription is not required. If the value is in the Experion cache, then
that value will be returned. Otherwise the controller will be polled for the latest value. Use the
constant HSC_READ_DEVICE if you want to force Experion to poll the controller again. The
subscription period will not be applied to standard point types.
points (in) the list of point numbers.
params (in) the list of point parameter numbers.
offsets (in) the list of point parameter offsets (for history parameters).
values (out) the list of values. PARvalue is a union of all possible value data types and is defined as
follows (definition from include/src/points.h):
typedef union
{
short int2;
long int4;
float real;
double dble;
char text[PARAM_MAX_STRING_LEN+1];
struct {
long ord;
char text[PARAM_MAX_STRING_LEN+1];
} en;
} PARvalue;
types the list of value types.
statuses (out) a list containing the status of the get for each point parameter.
Description
Retrieves the values for a list of point parameters and stores the values in the values union array and returns the
data types in types.
If your system uses dynamic scanning, hsc_param_values() calls from the Server API do not trigger dynamic
scanning.
169
APPLICATION LIBRARY FOR C AND C++
Diagnostics
0 will be returned from this function upon successful completion, otherwise -1 will be returned, and calling
c_geterrno() will retrieve the error code. The values returned in types will be one of the following constants
defined in include\parameters:
DT_CHAR /* character string */
DT_INT2 /* 1 to 16 bit short integer */
DT_INT4 /* 1 to 32 bit long integer */
DT_REAL /* short float */
DT_DBLE /* long float */
DT_HIST /* history (-0 => large float) */
DT_VAR /* variant */
DT_ENUM /* enumeration ' */
DT_DATE_TIME /* timestamp (integer*2 day, double sec) */
DT_TIME /* date and time (HSCTIME format) */
DT_INT8 /* 64-bit integer */
DT_SRCADDR /* source address */
DT_DSTADDR /* destination address */
Example
Find the values of the Description and PV of 'pntana1' and output them.
#include <src/defs.h>
#include <src/points.h>
PNTNUM points[2];
PRMNUM params[2];
int offsets[2];
PARvalue values[2];
uint2 types[2];
int statuses[2];
int n;
points[1]=points[0];
offsets[0] = offsets[1] = 0;
if( hsc_param_values(2, ONE_SHOT, points, params, offsets, values, types, statuses) !=0 )
{
printf("Unable to retrieve parameter, error code = 0x%x\n", c_geterrno());
}
else
{
for(n=0;n<2;n++)
{
if(types[n]==DT_CHAR)
{
printf("Point %d param %d is DT_CHAR and the value %s\n",
points[n],params[n],values[n].text);
}
else if(types[n]==DT_REAL)
{
printf("Point %d param %d is DT_REAL and has value %d\n",
points[n],params[n],values[n].real);
}
else
170 www.honeywell.com
APPLICATION LIBRARY FOR C AND C++
{
printf("Unexpected return type %d \n", types[n]);
}
}
}
See also
“hsc_param_value()” on page 166
“hsc_param_number()” on page 161
“hsc_point_number()” on page 194
171
APPLICATION LIBRARY FOR C AND C++
hsc_param_value_put()
Control a point parameter value.
C/C++ synopsis
#include <src/defs.h>
#include <src/M4_err.h>
#include <src/points.h>
int hsc_param_value_put(
PNTNUM point,
PRMNUM param,
int offset,
PARvalue* value,
uint2* type
);
Arguments
Argument Description
point (in) point number
param (in) point parameter number
offset (in) point parameter offset (for history parameters)
value (in) value. PARvalue is a union of data types and defined as (definition from include/src/
points.h):
typedef union
{
short int2;
long int4;
float real;
double dble;
char text[PARAM_MAX_STRING_LEN+1];
struct {
long ord;
char text[PARAM_MAX_STRING_LEN+1];
} en;
} PARvalue;
type (in) value type
Description
Sets a value for a point parameter in the server database and performs any control required by setting/changing
the parameter's value.
Diagnostics
On successful write 0 is returned, else an error code is returned. If CTLOK (0x8220) is returned this is not actually
an error but an indication that some control was executed successfully as a result of setting the parameter value.
Example
Change Pntana1's SP value to 42.0 and perform any required control.
#include <src/defs.h>
#include <src/M4_err.h>
#include <src/points.h>
PNTNUM point;
PRMNUM param;
PARvalue value;
uint2 type;
172 www.honeywell.com
APPLICATION LIBRARY FOR C AND C++
point = hsc_point_number("Pntana1");
param = hsc_param_number(point,"SP");
value.real = (float)42.0;
type = DT_REAL;
if (hsc_param_value_put(point,param,0,&value,&type) == 0)
c_logmsg ("example",
"param_value_put call",
"Pntana1.SP was written and controlled successfully");
else
c_logmsg ("example",
"param_value_put call",
"Unable to write and/or control Pntana1.SP,
error code = 0x%x",
c_geterrno());
See also
“hsc_param_number()” on page 161
“hsc_point_number()” on page 194
“hsc_param_values_put()” on page 174
173
APPLICATION LIBRARY FOR C AND C++
hsc_param_values_put()
Control a list of point parameter values.
C/C++ synopsis
#include <src/defs.h>
#include <src/M4_err.h>
#include <src/points.h>
int hsc_param_values_put(
int count, // (in) number of parameter requests
PNTNUM* points, // (in) point numbers
PRMNUM* params, // (in) point parameter numbers
int* offsets, // (in) point parameter offsets
PARvalue* values, // (in) values
uint2* types, // (in) value types
GDAERR* statuses, // (out) return statuses
GDASECURITY* security // (in) security descriptor
);
Arguments
Argument Description
count (in) the number of point parameters in the list to control
points (in) the list of point numbers
params (in) the list of point parameter numbers
offsets (in) the list of point parameter offsets (for history parameters)
values (in) the list of values. PARvalue is a union of data types and defined as (definition from
include/src/points.h):
typedef union
{
short int2;
long int4;
float real;
double dble;
char text[PARAM_MAX_STRING_LEN+1];
struct {
long ord;
char text[PARAM_MAX_STRING_LEN+1];
} en;
} PARvalue;
types (in) the list of value types.
statuses (out) a list containing the status of the put for each point parameter.
GDAERR is defined in <hsctypes.h>.
security (in) GDASECURITY is defined in <hsctypes.h>.
Use a null pointer for this argument.
Description
Sets a value for an array of point parameters in the server database and performs any control required by setting/
changing the parameter's value.
Diagnostics
On successful write 0 is returned, else an error code is returned.
The status of each control will be contained in the respective GDAERR structure. If CTLOK (0x8220) is returned this
is not actually an error but an indication that some control was executed successfully as a result of setting the
parameter value.
174 www.honeywell.com
APPLICATION LIBRARY FOR C AND C++
See also
“hsc_param_number()” on page 161
“hsc_point_number()” on page 194
“hsc_param_value_put()” on page 172
175
APPLICATION LIBRARY FOR C AND C++
hsc_param_value_save()
Save a point parameter value.
C/C++ synopsis
#include <src/defs.h>
#include <src/points.h>
int hsc_param_value_save(
PNTNUM point,
PRMNUM param,
int offset,
PARvalue* value,
uint2* type
);
Arguments
Argument Description
point (in) point number
param (in) point parameter number
offset (in) point parameter offset (for history parameters)
value (in) value PARvalue is a union of data types and is defined as (definition from include/src/
points.h):
typedef union
{
short int2;
long int4;
float real;
double dble;
char text[PARAM_MAX_STRING_LEN+1];
struct {
long ord;
char text[PARAM_MAX_STRING_LEN+1];
} en;
} PARvalue;
type (in) value type
Description
Sets a value for a point parameter in the server database and does not perform any control which may be
required by setting/changing the parameter's value.
Diagnostics
If the value was written to the parameter correctly then 0 is returned, else -1 is returned, and calling
“c_geterrno()” on page 112 will retrieve the error code.
Example
Change Pntana1's SP value to 42.0.
#include <src/defs.h>
#include <src/points.h>
PNTNUM point;
PRMNUM param;
PARvalue value;
uint2 type;
point = hsc_point_number("Pntana1");
param = hsc_param_number(point,"SP");
176 www.honeywell.com
APPLICATION LIBRARY FOR C AND C++
value.real = (float)42.0;
type = DT_REAL;
if (hsc_param_value_save(point,param,0,&value,&type) == 0)
c_logmsg ("example",
"param_value_save call",
"Pntana1.SP was written to successfully");
else
c_logmsg ("example",
"param_value_save call",
"Unable to write to Pntana1.SP,
error code = 0x%x",
c_geterrno());
See also
“hsc_param_value_put()” on page 172
“hsc_param_values_put()” on page 174
177
APPLICATION LIBRARY FOR C AND C++
hsc_pnttyp_list_create()
List all point types.
C/C++ synopsis
#include <src/defs.h>
#include <src/points.h>
int hsc_pnttyp_list_create(
enumlist** list
);
Arguments
Argument Description
list (in/out) pointer to an enumeration array for point types. enumlist is defined as (definition from
include/src/dictionary.h):
typedef struct
{
int value;
char* text;
} enumlist;
Description
Sets list to contain the point types by name and number in the server.
Diagnostic
The return value of this function will be the number of values in list or -1 if an error occurred. Calling
“c_geterrno()” on page 112 will retrieve the error code.
In all cases the enumlist structure is created with enough space for the text field in each enumlist element in the
enumlist array. Because this memory has been allocated by the function, your user code needs to free this space
when you finish using the structure. As this function always allocates the memory required for the text field,
make sure that you free all memory before calling the routine a second time with the same enumlist** pointer,
otherwise there will be a memory leak. To facilitate freeing this memory, “hsc_enumlist_destroy()” on page 132
is included in the API.
Example
This code segment uses a list size of 10 and retrieves all point types and outputs their names and numbers, or
outputs an error message if the hsc_pnttyp_list_create() call was unsuccessful.
#include <src/defs.h>
#include <src/points.h>
enumlist* list;
int i;
int n;
if((i=hsc_pnttyp_list_create
(&list)) != -1)
{
c_logmsg ("example",
"pnttyp_list call",
"The point types available are:");
for(n=0;n<i;n++)
c_logmsg ("example",
"pnttyp_list call",
"%d\t%s",
list[n].value,
list[n].text);
}
178 www.honeywell.com
APPLICATION LIBRARY FOR C AND C++
else
c_logmsg ("example",
"pnttyp_list call",
"An error occurred getting point type list,
error code = 0x%x",
c_geterrno());
See also
“hsc_point_type()” on page 195
“hsc_param_type()” on page 164
“hsc_enumlist_destroy()” on page 132
179
APPLICATION LIBRARY FOR C AND C++
hsc_pnttyp_name()
Get a point type name.
C/C++ synopsis
#include <src/defs.h>
#include <src/points.h>
int hsc_pnttyp_name(
int number,
char* name,
int namelen
);
Arguments
Argument Description
number (in) point type number
name (out) point type name
namelen (in) length of name string
Description
Returns, in the name char buffer, the name of the specified point type.
Diagnostics
If the call is successful 0 is returned else -1 is returned and calling “c_geterrno()” on page 112 will retrieve the
error code.
Example
This code segment will retrieve all the point type names with each having their name and number output.
#include <src/defs.h>
#include <src/points.h>
int pnttyp;
char szPnttyp[10];
pnttyp=1;
while (hsc_pnttyp_name(pnttyp,szPnttyp,10)
}
c_logmsg ('example','pnttyp_name call',
'the name of pnttyp %d is %s',
pnttyp,szPnttyp);
pnttypp++;
}
See also
“hsc_pnttyp_number()” on page 181
180 www.honeywell.com
APPLICATION LIBRARY FOR C AND C++
hsc_pnttyp_number()
Get a point type number.
C/C++ synopsis
#include <src/defs.h>
#include <src/points.h>
int hsc_pnttyp_number(
char* name
);
Arguments
Argument Description
name (in) point type name
Description
Returns the number of the named point type, or if the point type does not exist or an error occurs, -1 will be
returned and calling “c_geterrno()” on page 112 will retrieve the error code.
Example
This code segment should return the point type number for the STA point type and output it, otherwise an
error message is output.
#include <src/defs.h>
#include <src/points.h>
int pnttyp;
if((pnttyp = hsc_pnttyp_number('STA'))
!= -1)
c_logmsg ('example',
'pnttyp_number call',
'STA is point type %d',
pnttyp);
else
c_logmsg ('example',
'pnttyp_number call',
'An error occurred getting point type STA. 0x%x',
c_geterrno());
See also
“hsc_point_name()” on page 193
181
APPLICATION LIBRARY FOR C AND C++
hsc_point_entityname()
Returns the entity name of a point.
C/C++ synopsis
#include <src/defs.h>
#include <src/points.h>
int hsc_point_entityname(
PNTNUM point,
char* name,
int namelen
);
Arguments
Argument Description
point (in) point number
name (out) entity name
namelen (in) length of name string
Description
Takes a point number and returns the point's entity name in the char buffer provided.
Diagnostic
If successful, 0 is returned. If the point does not exist or some other error occurs, the char buffer is not set and -1
is returned and calling “c_geterrno()” on page 112 will retrieve the error code.
182 www.honeywell.com
APPLICATION LIBRARY FOR C AND C++
hsc_point_fullname()
Returns the full name of the point.
C/C++ synopsis
#include <src/defs.h>
#include <src/points.h>
int hsc_point_fullname(
PNTNUM point,
char* name,
int namelen
);
Arguments
Argument Description
point (in) point number
name (out) full name
namelen (in) length of name string
Description
This function takes a point number and return the point's full name in the char buffer provided.
Diagnostic
If successful, 0 is returned. If the point does not exist or some other error occurs, the char buffer is not set and -1
is returned and calling “c_geterrno()” on page 112 will retrieve the error code.
183
APPLICATION LIBRARY FOR C AND C++
hsc_point_get_children()
Returns all children.
C/C++ synopsis
#include <src/defs.h>
#include <src/points.h>
int hsc_point_get_children(
PNTNUM point,
int* count,
PNTNUM** children
);
Arguments
Argument Description
point (in) point number
count (out) number of children
children (out) array of children
Description
This function returns all children, both containment and reference.
The array must be cleared by calling “hsc_em_FreePointList()” on page 127.
Diagnostics
If successful, 0 is returned, otherwise -1 is returned and calling “c_geterrno()” on page 112 will retrieve the
error code.
Example
#include <src/defs.h>
#include <src/points.h>
int count = 0;
PNTNUM *Children = NULL;
if (hsc_point_get_children (point, &count, &Children) ! = 0)
return -1
.
.
.
hsc_em_FreePointList (Children);
184 www.honeywell.com
APPLICATION LIBRARY FOR C AND C++
hsc_point_get_containment_ancestors()
Returns all containment ancestors above a specified point.
C/C++ synopsis
#include <src/defs.h>
#include <src/points.h>
int hsc_point_get_containment_ancestors(
PNTNUM point,
int* piNumAncestors,
PNTNUM** ppAncestors
);
Arguments
Argument Description
point (in) point number
piNumAncestors (out) number of ancestors
ppAncestors (out) array of ancestors
Description
This function returns all of the containment ancestors in the tree above the specified point.
The array must be cleared by calling “hsc_em_FreePointList()” on page 127.
Diagnostics
If successful, 0 is returned, otherwise -1 is returned and calling “c_geterrno()” on page 112 will retrieve the
error code.
Example
#include <src/defs.h>
#include <src/points.h>
int iNumAncestors = 0;
PNTNUM *pAncestors = NULL
if (hsc_point_get_containment_ancestors (point, &iNumAncestors, &pAncestors) ! = 0)
return -1
.
.
.
hsc_em_FreePointList (pAncestors);
185
APPLICATION LIBRARY FOR C AND C++
hsc_point_get_containment_children()
Returns all containment children for a specified point.
C/C++ synopsis
#include <src/defs.h>
#include <src/points.h>
int hsc_point_get_containment_children(
PNTNUM parent,
int* piNumChildren,
PNTNUM** ppChildren
);
Arguments
Argument Description
parent (in) point number of the parent
piNumChildren (out) number of children
ppChildren (out) array of children
Description
Returns a list of contained children for a specified point.
The array must be cleared by calling “hsc_em_FreePointList()” on page 127.
Diagnostics
If successful, 0 is returned, otherwise -1 is returned and calling “c_geterrno()” on page 112 will retrieve the
error code.
Example
#include <src/defs.h>
#include <src/points.h>
int iNumChildren = 0;
PNTNUM *pChildren = NULL
if (hsc_point_get_containment_children (point, &iNumChildren, &pChildren) ! = 0)
return -1
.
.
.
hsc_em_FreePointList (pChildren);
186 www.honeywell.com
APPLICATION LIBRARY FOR C AND C++
hsc_point_get_containment_descendents()
Returns all containment descendents below a specified point.
C/C++ synopsis
#include <src/defs.h>
#include <src/points.h>
int hsc_point_get_containment_descendents(
PNTNUM point,
int* piNumDescendents,
PNTNUM** ppDescendents
);
Arguments
Argument Description
point (in) point number
piNumDescendents (out) number of descendents
ppDescendents (out) array of descendents
Description
Returns a list of containment descendents in the tree below a specified point.
The array must be cleared by calling “hsc_em_FreePointList()” on page 127.
Diagnostics
If successful, 0 is returned, otherwise -1 is returned and calling “c_geterrno()” on page 112 will retrieve the
error code.
Example
#include <src/defs.h>
#include <src/points.h>
int iNumDescendents = 0;
PNTNUM *pDescendents = NULL;
if (hsc_point_get_containment_descendents (point, &iNumDescendents, &pDescendents) ! = 0)
return -1
.
.
.
hsc_em_FreePointList (pDescendents);
187
APPLICATION LIBRARY FOR C AND C++
hsc_point_get_containment_parents()
Returns all containment parents above a specified point.
C/C++ synopsis
#include <src/defs.h>
#include <src/points.h>
int hsc_point_get_containment_parents(
PNTNUM child,
int* piNumParents,
PNTNUM** ppParents
);
Arguments
Argument Description
child (in) point number of the child point
piNumParents (out) number of parents
ppParents (out) array of parents
Description
Returns a list of containment parents for a specified point.
The array must be cleared by calling “hsc_em_FreePointList()” on page 127.
Diagnostics
If successful, 0 is returned, otherwise -1 is returned and calling “c_geterrno()” on page 112 will retrieve the
error code.
Example
#include <src/defs.h>
#include <src/points.h>
int iNumParents = 0;
PNTNUM *pParents = NULL;
if (hsc_point_get_containment_parents (point, &iNumParents, &pParents) ! = 0)
return -1
.
.
.
hsc_em_FreePointList (pParents);
188 www.honeywell.com
APPLICATION LIBRARY FOR C AND C++
hsc_point_get_parents()
Returns all parents.
C/C++ synopsis
#include <src/defs.h>
#include <src/points.h>
int hsc_point_get_parents(
PNTNUM point,
int* count,
PNTNUM** parents
);
Arguments
Argument Description
point (in) point number
count (out) number of parents
parents (out) array of parents
Description
Returns all parents, both containment and reference.
The array must be cleared by calling “hsc_em_FreePointList()” on page 127.
Diagnostics
If successful, 0 is returned, otherwise -1 is returned and calling “c_geterrno()” on page 112 will retrieve the
error code.
Example
#include <src/defs.h>
#include <src/points.h>
int count = 0;
PNTNUM *Parents = NULL
if (hsc_point_get_parents (point, &count, &Parents) ! = 0)
return -1
.
.
.
hsc_em_FreePointList (Parents);
189
APPLICATION LIBRARY FOR C AND C++
hsc_point_get_references()
Returns a list of points to which the specified point refers.
C/C++ synopsis
#include <src/defs.h>
#include <src/points.h>
int hsc_point_get_references(
PNTNUM point,
int* piNumRefItems,
PNTNUM** ppRefItems
);
Arguments
Argument Description
point (in) point number
piNumRefItems (out) number of references
ppRefItems (out) array of referenced items
Description
Returns a list of points to which the specified point refers.
The array must be cleared by calling “hsc_em_FreePointList()” on page 127.
Diagnostics
If successful, 0 is returned, otherwise -1 is returned and calling “c_geterrno()” on page 112 will retrieve the
error code.
Example
#include <src/defs.h>
#include <src/points.h>
int iNumRefItems = 0;
PNTNUM *pRefItems = NULL
if (hsc_point_get_references (point, &iNumRefItems, &pRefItems) ! = 0)
return -1
.
.
.
hsc_em_FreePointList (pRefItems);
190 www.honeywell.com
APPLICATION LIBRARY FOR C AND C++
hsc_point_get_referers()
Returns a list of points that refer to the specified point.
C/C++ synopsis
#include <src/defs.h>
#include <src/points.h>
int hsc_point_get_referers(
PNTNUM point,
int* piNumRefItems,
PNTNUM** ppRefItems
);
Arguments
Argument Description
point (in) point number
piNumRefItems (out) number of referers
ppRefItems (out) array of referring points
Description
Returns a list of points that refer to the specified point.
The array must be cleared by calling “hsc_em_FreePointList()” on page 127.
Diagnostics
If successful, 0 is returned, otherwise -1 is returned and calling “c_geterrno()” on page 112 will retrieve the
error code.
Example
#include <src/defs.h>
#include <src/points.h>
int iNumRefItems = 0;
PNTNUM *pRefItems = NULL;
if (hsc_point_get_referers (point, &iNumRefItems, &pRefItems) ! = 0)
return -1
.
.
.
hsc_em_FreePointList (pRefItems);
191
APPLICATION LIBRARY FOR C AND C++
hsc_point_guid()
Returns the GUID for the specified point.
C/C++ synopsis
#include <src/defs.h>
#include <src/points.h>
int hsc_point_guid(
PNTNUM point,
GUID* pGUID
);
Arguments
Argument Description
point (in) point number
gGUID (out) GUID in binary format
Description
Returns the GUID for the specified point in binary format.
Diagnostics
If successful, 0 is returned, otherwise -1 is returned and calling “c_geterrno()” on page 112 will retrieve the
error code.
192 www.honeywell.com
APPLICATION LIBRARY FOR C AND C++
hsc_point_name()
Gets a point's name.
C/C++ synopsis
#include <src/defs.h>
#include <src/points.h>
int hsc_point_name (
PNTNUM point,
char* name,
int namelen
);
Arguments
Argument Description
point (in) point number
name (out) parameter name
namelen (in) length of name string
Description
This routine will take a point number and return the point's name in the char buffer provided and have a return
value of 0.
Diagnostic
If the point does not exist or some other error occurs then the char buffer will not be set and -1 will be returned.
The error code can be retrieved by calling “c_geterrno()” on page 112.
Example
Retrieves the point name for the point and outputs it. The char buffer is 41 characters long, which is bigger
than the maximum length of a point name (40 characters).
#include <src/defs.h>
#include <src/points.h>
PNTNUM point;
char szName[MAX_POINT_NAME_LEN+1];
if(hsc_point_name(point,szName,MAX_POINT_NAME_LEN+1) == 0)
c_logmsg ('example',
'point_name call',
'Point %d is named %s',
point,
szName);
else
c_logmsg ('example',
'point_name call',
'An error occurred getting point name. 0x%x',
c_geterrno());
See also
“hsc_point_number()” on page 194
193
APPLICATION LIBRARY FOR C AND C++
hsc_point_number()
Gets a point's number.
C/C++ synopsis
#include <src/defs.h>
#include <src/points.h>
PNTNUM hsc_point_number(
char* name
);
Arguments
Argument Description
name (in) point name
Description
This function returns the point number of the given point name if the point exists else 0 is returned.
Example
The point number is retrieved for the point and output, if the point exists then a message is output.
#include <src/defs.h>
#include <src/points.h>
PNTNUM point;
See also
“hsc_point_name()” on page 193
194 www.honeywell.com
APPLICATION LIBRARY FOR C AND C++
hsc_point_type()
Gets a point's type.
C/C++ synopsis
#include <src/defs.h>
#include <src/points.h>
PNTTYP hsc_point_type(
PNTNUM point
);
Argument
Argument Description
point (in) point number
Description
This routine returns the point type of the point and will be one of the following values (as defined in include
\parameters) or -1 if invalid:
#define STA 1
#define ANA 2
#define ACC 3
#define ACS 4
#define CON 5
#define CDA 6
#define RDA 7
#define PSA 8
Example
Calculates the point number from the point name and then uses this value to determine the point type. The
point number and type are then output.
#include <src/defs.h>
#include <src/points.h>
PNTNUM point;
PNTTYP pnttyp;
point = hsc_point_number('PNTANA1');
if (point != 0)
{
pnttyp = hsc_point_type(point);
c_logmsg ('example','point_type call',
'PNTANA1 is point number %d has point type %d.',
point,pnttyp);
}
195
APPLICATION LIBRARY FOR C AND C++
hsc_StringFromGUID()
Converts a GUID from binary format to string format.
C/C++ synopsis
#include <src/defs.h>
#include <src/points.h>
int hsc_StringFromGUID(
GUID* pGUID,
char* pszGUID
);
Arguments
Argument Description
pGUID (in) GUID in binary format
pszGUID (out) GUID in string format
Description
This function converts a GUID from binary format to string format.
Diagnostics
If successful, 0 is returned, otherwise -1 is returned and calling “c_geterrno()” on page 112 will retrieve the
error code.
Example
#include <src/defs.h>
#include <src/points.h>
GUID guid;
char szGUID[MAX_GUID_STRING_SZ+1];
hsc_StringFromGUID (&guid, szGUID);
if (point == 0)
return -1;
196 www.honeywell.com
APPLICATION LIBRARY FOR C AND C++
hsc_unlock_file()
Unlocks a database file.
C/C++ synopsis
#include <src/defs.h>
#include <src/M4_err.h>
int hsc_unlock_file(
int file
);
Arguments
Argument Description
file (in) server file number.
delay (in) delay time in milliseconds before lock attempt will fail.
Description
Performs advisory unlocking of database files. Advisory locking means that the tasks that use the file take
responsibility for setting and removing locks as needed.
For more information regarding database locking see 'Ensuring database consistency.'
Diagnostics
Upon successful completion a value of 0 is returned. Otherwise, -1 is returned and calling “c_geterrno()” on
page 112 will retrieve one of the following error codes:
See also
“hsc_lock_record()” on page 145
“hsc_unlock_file()” on page 197
“hsc_unlock_record()” on page 198
Related topics
“Ensuring database consistency” on page 45
197
APPLICATION LIBRARY FOR C AND C++
hsc_unlock_record()
Unlocks a record of a database file.
C/C++ synopsis
#include <src/defs.h>
#include <src/M4_err.h>
int hsc_unlock_record(
int file,
int record
);
Arguments
Argument Description
file (in) server file number
record (in) record number (see description)
Description
This routine is used to perform advisory unlocking of database files and records. Advisory locking means that
the tasks that use the record take responsibility for setting and removing locks as needed.
For more information regarding database locking see 'Ensuring database consistency.'
Diagnostics
Upon successful completion a value of 0 is returned. Otherwise, -1 is returned and calling “c_geterrno()” on
page 112 will retrieve one of the following error codes:
See also
“hsc_lock_file()” on page 144
“hsc_unlock_file()” on page 197
“hsc_unlock_record()” on page 198
Related topics
“Ensuring database consistency” on page 45
198 www.honeywell.com
APPLICATION LIBRARY FOR C AND C++
HsctimeToDate()
Converts date/time stored in HSCTIME format to VARIANT DATE format.
C/C++ synopsis
#include <src/defs.h>
#include <src/points.h>
void HsctimeToDate(
HSCTIME*,
DATE*
);
Description
Converts a date/time value stored in HSCTIME format to VARIANT DATE format.
199
APPLICATION LIBRARY FOR C AND C++
HsctimeToFiletime()
Converts date/time stored in HSCTIME format to FILETIME format.
C/C++ synopsis
#include <src/defs.h>
#include <src/points.h>
void HsctimeToFiletime(
HSCTIME*,
FILETIME*
);
Description
Converts a date/time value stored in HSCTIME format to FILETIME format.
200 www.honeywell.com
APPLICATION LIBRARY FOR C AND C++
infdouble()
Returns the (IEEE 754) Infinity value as a Double data type.
C/C++ Synopsis
double infdouble();
Arguments
No arguments are passed with this function.
Returns
Returns the (IEEE 754) positive Infinity value as a Double (double-precision floating-point) data type.
Description
This function is useful for creating a valid (IEEE 754) Infinity value for comparison purposes with Double data
type variables.
Attention
This function is platform dependent (only valid for an INTEL X86 system).
See also
“Validating IEEE 754 special values” on page 19
“isinfdouble()” on page 209
“inffloat()” on page 202
“isinffloat()” on page 210
“Data types” on page 25
201
APPLICATION LIBRARY FOR C AND C++
inffloat()
Returns the (IEEE 754) Infinity value as a Float data type.
C/C++ Synopsis
float inffloat();
Arguments
No arguments are passed with this function.
Returns
Returns the (IEEE 754) positive Infinity value as a Float (single-precision floating-point) data type.
Description
This function is useful for creating a valid (IEEE 754) Infinity value for comparison purposes with Float data
type variables.
Attention
This function is platform dependent (only valid for an INTEL X86 system).
See also
“Validating IEEE 754 special values” on page 19
“isinffloat()” on page 210
“infdouble()” on page 201
“isinfdouble()” on page 209
“Data types” on page 25
202 www.honeywell.com
APPLICATION LIBRARY FOR C AND C++
Int2toPV()
Inserts an int2 value into a PARvalue union.
C/C++ synopsis
#include <src/defs.h>
#include <src/almmsg.h>
PARvalue* Int2toPV(
int2 int2_val,
PARvalue* pvvalue
);
Arguments
Argument Description
pvvalue (in) A pointer to a PARvalue structure.
int2_val (in) The int2 value to insert into the PARvalue structure.
Description
This function inserts an int2 value into a PARvalue, and then returns a pointer to the PARvalue passed in. This
function allows you to set attributes into a notification structure using calls to “hsc_insert_attrib()” on page 134
and “hsc_insert_attrib_byindex()” on page 139 functions in a single line of code.
Diagnostics
If this function is successful, the return value is a pointer back to the PARvalue passed in, otherwise, the return
value is NULL and calling “c_geterrno()” on page 112 will retrieve the following error code:
Example
See the examples in “hsc_insert_attrib()” on page 134 and “hsc_insert_attrib_byindex()” on page 139.
See also
“DbletoPV()” on page 104
“hsc_insert_attrib()” on page 134
“hsc_insert_attrib_byindex()” on page 139
“Int4toPV()” on page 204
“PritoPV()” on page 224
“RealtoPV()” on page 226
“StrtoPV()” on page 235
“TimetoPV()” on page 236
203
APPLICATION LIBRARY FOR C AND C++
Int4toPV()
Inserts an int4 value into a PARvalue union.
C/C++ synopsis
#include <src/defs.h>
#include <src/almmsg.h>
PARvalue* Int4toPV(
int4 int4_val,
PARvalue* pvvalue
);
Arguments
Argument Description
pvvalue (in) A pointer to a PARvalue structure.
int4_val (in) The int4 value to insert into the PARvalue structure.
Description
This function inserts an int4 value into a PARvalue, and then returns a pointer to the PARvalue passed in. This
function allows you to set attributes into a notification structure using calls to “hsc_insert_attrib()” on page 134
and “hsc_insert_attrib_byindex()” on page 139 functions in a single line of code.
Diagnostics
If this function is successful, the return value is a pointer back to the PARvalue passed in, otherwise, the return
value is NULL and calling “c_geterrno()” on page 112 will retrieve the following error code:
Example
See the examples in “hsc_insert_attrib()” on page 134 and “hsc_insert_attrib_byindex()” on page 139.
See also
“DbletoPV()” on page 104
“hsc_insert_attrib()” on page 134
“hsc_insert_attrib_byindex()” on page 139
“Int2toPV()” on page 203
“PritoPV()” on page 224
“RealtoPV()” on page 226
“StrtoPV()” on page 235
“TimetoPV()” on page 236
204 www.honeywell.com
APPLICATION LIBRARY FOR C AND C++
c_intchr()
Copies an integer array to a character string.
C/C++ synopsis
#include <src/defs.h>
Arguments
Argument Description
intbuf (in) source integer buffer containing ASCII.
intbuflen (in) size of source integer buffer in bytes.
chrbuf (out) destination character buffer.
chrbuflen (in) size of character buffer in bytes (to allow non null-terminated character buffers).
Description
Copies characters from an integer buffer into a character buffer. It will either space fill or truncate so as to
ensure that chrbuflen characters are copied into the character buffer. If the system stores words with the least
significant byte first then byte swapping will be performed with the move.
See also
“c_chrint()” on page 94
205
APPLICATION LIBRARY FOR C AND C++
IsGDAerror()
Determines whether a returned GDA status value is an error.
C/C++ synopsis
#include <src/defs.h>
#include <src/gdamacro.h>
bool IsGDAerror
(
GDAERR* pGdaError
);
Arguments
Argument Description
pGdaError (in) pointer to the DGAERR structure containing the status
Description
Determines whether a particular GDA status code is an error by returning a 0 in the return value. If the function
returns a non zero value, calling “c_geterrno()” on page 112 will retrieve the error code.
Diagnostics
Returns TRUE if pGdaError indicates an error condition, otherwise it returns FALSE.
See also
“IsGDAwarning()” on page 208
“IsGDAnoerror()” on page 207
“hsc_IsError()” on page 142
“c_geterrno()” on page 112
206 www.honeywell.com
APPLICATION LIBRARY FOR C AND C++
IsGDAnoerror()
Determines whether a returned GDA status value is neither an error nor a warning.
C/C++ synopsis
#include <src/defs.h>
#include <src/gdamacro.h>
bool IsGDAnoerror(
GDAERR* pGdaError
);
Arguments
Argument Description
pGdaError (in) pointer to the GDAERR structure containing the status
Description
This macro determines whether a particular GDA status code is an error by returning a 0 in the return value. If the
function returns a non zero value, calling “c_geterrno()” on page 112 will retrieve the error code.
Diagnostics
This routine returns TRUE if pGdaError indicates neither an error condition nor a warning condition, otherwise it
returns FALSE.
See also
“IsGDAwarning()” on page 208
“IsGDAerror()” on page 206
“c_geterrno()” on page 112
207
APPLICATION LIBRARY FOR C AND C++
IsGDAwarning()
Determines whether a returned GDA status value is a warning.
C/C++ synopsis
#include <src/defs.h>
#include <src/gdamacro.h>
bool IsGDAwarning(
GDAERR* pGdaError
);
Arguments
Argument Description
pGdaError (in) pointer to the GDAERR structure containing the status
Description
This macro determines whether a particular GDA status code is an error by returning a 0 in the return value. If the
function returns a non zero value, calling “c_geterrno()” on page 112 will retrieve the error code.
Diagnostics
This routine returns TRUE if pGdaError indicates a warning condition, otherwise it returns FALSE.
See also
“IsGDAerror()” on page 206
“IsGDAnoerror()” on page 207
“hsc_IsWarning()” on page 143
“c_geterrno()” on page 112
208 www.honeywell.com
APPLICATION LIBRARY FOR C AND C++
isinfdouble()
Validates the Double data type argument as an (IEEE 754) Infinity value.
C/C++ Synopsis
int isinfdouble(double ieee);
Arguments
Argument Description
ieee (in) An (IEEE 754) value to test
Returns
Returns TRUE (-1) if it is a valid (IEEE 754) Infinity value; otherwise FALSE (0).
Description
This function is useful for checking that the argument is, or is not, a valid (IEEE 754) Infinity value.
Attention
This function is platform dependent (only valid for an INTEL X86 system).
See also
“Validating IEEE 754 special values” on page 19
“infdouble()” on page 201
“inffloat()” on page 202
“isinffloat()” on page 210
“Data types” on page 25
209
APPLICATION LIBRARY FOR C AND C++
isinffloat()
Validates the Float data type argument as an (IEEE 754) Infinity value.
C/C++ Synopsis
int isinffloat(float ieee);
Arguments
Argument Description
ieee (in) An (IEEE 754) value to test
Returns
Returns TRUE (-1) if it is a valid (IEEE 754) Infinity value; otherwise FALSE (0).
Description
This function is useful for checking that the argument is, or is not, a valid (IEEE 754) Infinity value.
Attention
Note that this function is platform dependent (only valid for an INTEL X86 system).
See also
“Validating IEEE 754 special values” on page 19
“inffloat()” on page 202
“infdouble()” on page 201
“isinfdouble()” on page 209
“Data types” on page 25
210 www.honeywell.com
APPLICATION LIBRARY FOR C AND C++
isnandouble()
Validates the Double data type argument as an (IEEE 754) NaN (Not a Number) value.
C/C++ Synopsis
int isnandouble(double ieee);
Arguments
Argument Description
ieee (in) An (IEEE 754) value to test
Returns
Returns TRUE (-1) if it is a valid (IEEE 754) NaN value; otherwise FALSE (0).
Description
This function is useful for checking that the argument is, or is not, a valid (IEEE 754) NaN value. For example, a
controller can send an IEEE 754 NaN value in response to a data request, which should be tested for.
Attention
This function is platform dependent (only valid for an INTEL X86 system).
See also
“Validating IEEE 754 special values” on page 19
“nandouble()” on page 216
“nanfloat()” on page 217
“isnanfloat()” on page 212
“Data types” on page 25
211
APPLICATION LIBRARY FOR C AND C++
isnanfloat()
Validates the Float data type argument as an (IEEE 754) NaN (Not a Number) value.
C/C++ Synopsis
int isnanfloat(float ieee);
Arguments
Argument Description
ieee (in) An (IEEE 754) value to test
Returns
Returns TRUE (-1) if it is a valid (IEEE 754) NaN value; otherwise FALSE (0).
Description
This function is useful for checking that the argument is, or is not, a valid (IEEE 754) NaN value. For example, a
controller can send an IEEE 754 NaN value in response to a data request, which should be tested for.
Attention
This function is platform dependent (only valid for an INTEL X86 system).
See also
“Validating IEEE 754 special values” on page 19
“nanfloat()” on page 217
“nandouble()” on page 216
“isnandouble()” on page 211
“Data types” on page 25
212 www.honeywell.com
APPLICATION LIBRARY FOR C AND C++
C/C++ synopsis
#include <src/defs.h>
Arguments
Argument Description
year (in/out) number of years since 0 AD (for example, 2012).
month (in/out) month (1–12).
day (in/out) day (1–31).
julian (in) number of Julian days.
Description
Converts between Julian days (used by the History subsystem) and a Gregorian date (day, month, year format).
Diagnostics
Upon successful completion c_gtoj returns the number of Julian days. c_jtog returns the values in the addresses
pointed to by the year, month and day parameters.
See also
“c_gethstpar_..._2()” on page 113
213
APPLICATION LIBRARY FOR C AND C++
c_logmsg()
Writes a message to the log file.
C/C++ synopsis
#include <src/defs.h>
Arguments
Argument Description
progname (in) name of program module
lineno (in) line number in program module
format (in) printf type format of message
Description
c_logmsg should be used instead of printf to write messages to the log file. This is typically used for
debugging purposes.
This routine writes the message to standard error. If the application is a task (with its own LRN) then the
message will be captured and written to the log file.
If the program is a utility then the message will appear in the command prompt window.
Diagnostics
This routine has no return value. If it is called incorrectly it will write its own message to standard error
indicating the source of the problem.
Example
c_logmsg('abproc.c','134' 'Point ABSTAT001 PV out of normal range (%d)', abpv);
c_logmsg handles all carriage control. There is no need to put a line feed characters in calls to c_logmsg.
214 www.honeywell.com
APPLICATION LIBRARY FOR C AND C++
c_mzero()
Tests a real value for -0.0.
C/C++ synopsis
#include <src/defs.h>
Arguments
Argument Description
value (in) real value to be tested.
Description
Returns TRUE if the specified value is equal to minus zero. Otherwise, FALSE is returned. Minus zero is used to
represent bad data in history data.
215
APPLICATION LIBRARY FOR C AND C++
nandouble()
Returns the (IEEE 754) QNaN (Quiet Not a Number) value as a Double data type.
C/C++ Synopsis
double nandouble();
Arguments
No arguments are passed with this function.
Returns
Returns the (IEEE 754) QNaN value as a Double (double-precision floating-point) data type.
Description
This function is useful for creating a valid (IEEE 754) QNaN value for storage.
Attention
This function is platform dependent (only valid for an INTEL X86 system).
See also
“Validating IEEE 754 special values” on page 19
“isnandouble()” on page 211
“nanfloat()” on page 217
“isnanfloat()” on page 212
“Data types” on page 25
216 www.honeywell.com
APPLICATION LIBRARY FOR C AND C++
nanfloat()
Returns the (IEEE 754) QNaN (Quiet Not a Number) value as a Float data type.
C/C++ Synopsis
float nanfloat();
Arguments
No arguments are passed with this function.
Returns
Returns the (IEEE 754) QNaN value as a Float (single-precision floating-point) data type.
Description
This function is useful for creating a valid (IEEE 754) QNaN value for storage.
Attention
This function is platform dependent (only valid for an INTEL X86 system).
See also
“Validating IEEE 754 special values” on page 19
“isnanfloat()” on page 212
“nandouble()” on page 216
“isnandouble()” on page 211
“Data types” on page 25
217
APPLICATION LIBRARY FOR C AND C++
c_oprstr_...()
Sends a message to a Station.
C/C++ synopsis
#include <system>
#include <src/defs.h>
#include <src/M4_err.h>
#include <src/trbtbl_def>
Arguments
Argument Description
crt (in) Station number.
message (in) pointer to null-terminated string to be sent to the Station.
param1 (in) value of parameter 1 required to identify response task request.
prmblk (out) task request parameter block which was received from GETREQ when the task began
executing.
Description
Outputs a specified message to the Operator zone of a Station.
Diagnostics
Upon successful completion c_oprstr_response will return a pointer to a null-terminated string containing the
response from the operator. Upon successful completion c_oprstr_info, c_oprstr_message and
218 www.honeywell.com
APPLICATION LIBRARY FOR C AND C++
c_oprstr_prompt will return zero. Otherwise, a NULL pointer or -1 will be returned, and calling “c_geterrno()” on
page 112 will retrieve the following error code:
Warnings
c_oprstr_prompt requires that the calling task “c_trm04()” on page 239 until the ENTER key is pressed. This
means that the calling task must be a server task and not a utility task.
If the operator changes displays or presses the ESC key after a c_oprstr_prompt call, no operator input will be
saved, and the task will not be requested. If you do not want the operator to avoid entering data, you will need to
set a flag internal to your program that indicates whether a response has been received and start a task timer
with the “c_tmstrt_...()” on page 238 function. If a response has not been received from the operator after an
interval (specified by you in the “c_tmstrt_...()” on page 238 function), you will need to repeat the
c_oprstr_prompt call. If a response from the operator is received you will need to stop the timer using
“c_tmstop()” on page 237.
Example
#include <stdio.h> /* for NULL */
#include "src/defs.h"
#include "src/M4_err.h"
#include "src/trbtbl_def"
static progname="%M%";
main ()
{
struct prm prmblk;
int crt=1;
char *reply;
uint2 point;
...
...
...
if (c_getreq(&prmblk) == 0)
{
switch (prmblk.param1)
{
case 1:
/* request a point name from the operator */
if (c_oprstr_prompt(crt,"ENTER POINT NAME?",2))
c_logmsg (progname,"123","c_oprstr_prompt %x",c_geterrno());
break;
case 2:
reply=c_oprstr_response(crt,&prmblk);
if (reply==NULL)
c_logmsg(progname,"132",
"c_oprstr_response error %x",c_geterrno());
else
{
if (c_getpnt(reply,point) == -1)
c_oprstr_message(crt,"ILLEGAL POINT NAME");
else
{
/* we have a valid point type/number */
}
}
break;
} /* end switch */
}
}
219
APPLICATION LIBRARY FOR C AND C++
c_pps_2()
Processes a point special (without waiting for completion).
C/C++ synopsis
#include <src/defs.h>
#include <scr/M4_err.h>
Arguments
Argument Description
point (in) Point type/number to be processed.
param (in) Point parameter to be processed. -1 for all parameters.
status (out) return error code.
Description
Requests a demand scan of the specified point.
The point is always processed.
This function is not applicable to Honeywell Process Controller points, Remote points, Container points or
System Interface Points (PSA).
Diagnostics
Upon successful completion, a value of 0 is returned in status. Otherwise, one of the following error codes is
returned:
See also
“c_ppsw_2()” on page 221
220 www.honeywell.com
APPLICATION LIBRARY FOR C AND C++
c_ppsw_2()
Processes a point special and waits for completion.
C/C++ synopsis
#include <src/defs.h>
#include <scr/M4_err.h>
Arguments
Argument Description
point (in) point type/number to be processed.
param (in) point parameter to be processed. -1 for all parameters.
status (out) return error code.
Description
Requests a demand scan of the specified point and wait for the scan to complete. If, after 10 seconds, the scan
has not replied, a timeout will be indicated.
The point is always processed.
This function is not applicable to Honeywell Process Controller points, Remote points, Container points or
System Interface Points (PSA).
Diagnostics
Upon successful completion, a value of 0 is returned in status. Otherwise, one of the following error codes is
returned:
See also
“c_pps_2()” on page 220
221
APPLICATION LIBRARY FOR C AND C++
c_ppv_2()
Processes a point value (without waiting for completion).
C/C++ synopsis
#include <src/defs.h>
#include <scr/M4_err.h>
Arguments
Argument Description
point (in) Point type/number to be processed.
param (in) Point parameter to be processed. -1 for all parameters.
value (in) Value to be stored into the point parameter.
Description
Requests a Demand scan of the specified Point.
The point is always processed.
This function is not applicable to Honeywell Process Controller points, Remote points, Container points or
System Interface Points (PSA).
Diagnostics
Upon successful completion a value of 0 is returned. Otherwise, -1 is returned and calling “c_geterrno()” on
page 112 will retrieve one of the following error codes:
See also
“c_ppvw_2()” on page 223
222 www.honeywell.com
APPLICATION LIBRARY FOR C AND C++
c_ppvw_2()
Processes a point value and waits for completion.
C/C++ synopsis
#include <src/defs.h>
#include <scr/M4_err.h>
Arguments
Argument Description
point (in) Point type/number to be processed.
param (in) Point parameter to be processed. -1 for all parameters.
value (in) Value to be stored into the point parameter.
Description
Requests a Demand scan of the specified Point and waits for the scan to complete. If after 10 seconds the scan
has not replied, then a timeout will be indicated. The point is always processed.
This function is not applicable to Honeywell Process Controller points, Remote points, Container points or
System Interface Points (PSA).
Diagnostics
Upon successful completion a value of 0 is returned. Otherwise, -1 is returned and calling “c_geterrno()” on
page 112 will retrieve one of the following error codes:
See also
“c_ppv_2()” on page 222
223
APPLICATION LIBRARY FOR C AND C++
PritoPV()
Inserts a priority and sub-priority value into a PARvalue union.
C/C++ synopsis
#include <src/defs.h>
#include <src/almmsg.h>
PARvalue* PritoPV(
int2 priority,
int2 subpriority,
PARvalue* pvvalue
);
Arguments
Argument Description
pvvalue (in) A pointer to a PARvalue structure.
priority (in) The priority value to insert into the PARvalue structure.
sub-priority (in) The sub-priority value to insert into the PARvalue structure.
Description
Inserts a priority and sub-priority value into a PARvalue, and then returns a pointer to the PARvalue passed in.
This allows you to set attributes into a notification structure using calls to “hsc_insert_attrib()” on page 134 and
“hsc_insert_attrib_byindex()” on page 139 functions in a single line of code.
Diagnostics
If this function is successful, the return value is a pointer back to the PARvalue passed in, otherwise, the return
value is NULL and calling “c_geterrno()” on page 112 will retrieve the following error code:
Example
See the examples in “hsc_insert_attrib()” on page 134 and “hsc_insert_attrib_byindex()” on page 139.
See also
“DbletoPV()” on page 104
“hsc_insert_attrib()” on page 134
“hsc_insert_attrib_byindex()” on page 139
“Int2toPV()” on page 203
“Int4toPV()” on page 204
“RealtoPV()” on page 226
“StrtoPV()” on page 235
“TimetoPV()” on page 236
224 www.honeywell.com
APPLICATION LIBRARY FOR C AND C++
c_prsend_...()
Queue file to print system for printing.
C/C++ synopsis
#include <src/defs.h>
#include <src/M4_err.h>
Arguments
Argument Description
crt (in) CRT number.
printer (in) printer number.
filename (in) pointer to null-terminated string containing the pathname (maximum 60 characters) of the file
to be printed.
Description
Requests the print system to print the specified file.
c_prsend_crt will send the file to the demand report printer that is associated with the specified CRT.
c_prsend_printer will send the file to the specified printer.
Diagnostics
Upon successful completion, a value of 0 is returned. Otherwise, -1 is returned and calling “c_geterrno()” on
page 112 will retrieve the following error code:
[M4_QEMPTY] The file could not be queued to the printer because the printer queue had no
free records.
Example
#define PRINTER_NO 1
#define SAMPLE_FILENAME '...\user\sample.dat'
static char *progname='sample.c';
225
APPLICATION LIBRARY FOR C AND C++
RealtoPV()
Inserts a real value into a PARvalue union.
C/C++ synopsis
#include <src/defs.h>
#include <src/almmsg.h>
PARvalue* RealtoPV(
float real_val,
PARvalue* pvvalue
);
Arguments
Argument Description
pvvalue (in) A pointer to a PARvalue structure.
real_val (in) The real value to insert into the PARvalue structure.
Description
Inserts a real value into a PARvalue, and then returns a pointer to the PARvalue passed in. This function allows
you to set attributes into a notification structure using calls to “hsc_insert_attrib()” on page 134 and
“hsc_insert_attrib_byindex()” on page 139 functions in a single line of code.
Diagnostics
If this function is successful, the return value is a pointer back to the PARvalue passed in, otherwise, the return
value is NULL and calling “c_geterrno()” on page 112 will retrieve the following error code:
Example
See the examples in “hsc_insert_attrib()” on page 134 and “hsc_insert_attrib_byindex()” on page 139.
See also
“DbletoPV()” on page 104
“hsc_insert_attrib()” on page 134
“hsc_insert_attrib_byindex()” on page 139
“Int2toPV()” on page 203
“Int4toPV()” on page 204
“PritoPV()” on page 224
“StrtoPV()” on page 235
“TimetoPV()” on page 236
226 www.honeywell.com
APPLICATION LIBRARY FOR C AND C++
c_rqtskb...()
Requests a task if not busy.
C/C++ synopsis
#include <src/defs.h>
#include <src/M4_err.h>
#include <src/sn90_err.h>
#include <src/trbtbl_def>
int2 c_rqtskb(
int lrn
);
int2 c_rqtskb_prm(
int lrn,
int2* prmblk
);
Arguments
Argument Description
lrn (in) Logical resource number of the task to be requested.
prmblk (in) pointer to parameter block to be passed to the task.
Description
c_rqtskb requests the specified queued task without any parameters. If the task is already running, no
action is taken.
c_rqtskb_prm requests the specified queued task and passes a parameter block. If the task is not executing, or
the parameter block is zero, then the request is passed to the task. If the task is already executing
and the parameter block is not zero, then the request is queued. If a request is already queued, the
task is considered busy and an error code is returned.
Most of the system's tasks take in parameters in the form of the prm structure. Note that the prm
structure is defined in the file trbtbl_def in the src folder. It is recommended that developers make
use of this parameter block structure. To do so, first instantiate and initialize the structure with
relevant data, then cast a pointer to it to an int2* in order to call this function:
prm my_pblk;
int myLrn;
myLRN = 111; //user application LRN
...
return_val = c_rqtskb_prm(myLrn, (int2*) &my_pblk);
Note that the some LRNs listed in the def/src/lrns file (for example, the Keyboard Service
program (LRN 1) and Server Display program (LRN 21)), actually use multiple LRNs. The most
important example of this is the Server Display program. Each Station is associated with its own
Server Display and Keyboard Service programs. Each of these tasks use its own LRN. The Server
Display programs of the first 20 Stations are assigned LRNs 21 through to 40. For example, to
request the Server Display program for Station 3, you would request LRN 23.
Stations 21-40, if assigned, use other LRNs. These can be displayed using the utility usrlrn with
the options -p -a.
Notes
To call up a named display in Station you need to:
1. Memset to 0 the Parameter Request Block structure.
2. Ensure the prmblk.pathlen is set to 0. This pathlen is only used for the new HMI protocol.
227
APPLICATION LIBRARY FOR C AND C++
Diagnostics
Upon successful completion a value of 0 is returned. Otherwise, -1 is returned and calling “c_geterrno()” on
page 112 will retrieve one of the following error codes:
[M4_ILLEGAL_LRN] An illegal LRN has been specified or the task does not exist.
[M4_BUSY_TRB] The requested tasks request block is busy, could not pass parameters.
[INVALID_SEMVAL] The requested task has too many outstanding requests.
See also
“c_getreq()” on page 120
“c_tstskb()” on page 241
“c_wttskb()” on page 245
228 www.honeywell.com
APPLICATION LIBRARY FOR C AND C++
c_sps_2()
Scans a point special (without waiting for completion).
C/C++ synopsis
#include <src/defs.h>
#include <src/M4_err.h>
Arguments
Argument Description
point (in) Point type/number to be processed.
param (in) Point parameter to be processed. -1 for all parameters.
Description
SPS is used to request a Demand scan of the specified Point.
The point is only processed if the scanned value has changed.
This function is not applicable to Honeywell Process Controller points, Remote points, Container points or
System Interface Points (PSA).
Diagnostics
Upon successful completion a value of 0 is returned. Otherwise, -1 is returned and calling “c_geterrno()” on
page 112 will retrieve one of the following error codes:
See also
“c_spsw_2()” on page 230
229
APPLICATION LIBRARY FOR C AND C++
c_spsw_2()
Scans a point special and waits for completion.
C/C++ synopsis
#include <src/defs.h>
#include <src/M4_err.h>
Arguments
Argument Description
point (in) Point type/number to be processed.
param (in) Point parameter to be processed. -1 for all parameters.
Description
Requests a Demand scan of the specified Point and wait for the Scan to complete. If after 10 seconds the Scan
has not replied, then a timeout will be indicated. The point is only processed if the scanned value has changed.
This function is not applicable to Honeywell Process Controller points, Remote points, Container points or
System Interface Points (PSA).
Diagnostics
Upon successful completion a value of 0 is returned. Otherwise, -1 is returned and calling “c_geterrno()” on
page 112 will retrieve one of the following error codes:
See also
“c_sps_2()” on page 229
230 www.honeywell.com
APPLICATION LIBRARY FOR C AND C++
c_spv_2()
Scans a point value (without waiting for completion).
C/C++ synopsis
#include <src/defs.h>
#include <src/M4_err.h>
Arguments
Argument Description
point (in) point type and/or number to be processed
param (in) point parameter to be processed. PV=0 through A4=7
value (in) value to be stored into the point parameter
Description
Passes the value to the point processor for storage into the point parameter.
The point is processed only if the scanned value has changed.
This function is not applicable to Honeywell Process Controller points, Remote points, Container points or
System Interface Points (PSA).
Diagnostics
Upon successful completion, a value of 0 is returned. Otherwise, one of the following error codes is returned:
See also
“c_spvw_2()” on page 232
231
APPLICATION LIBRARY FOR C AND C++
c_spvw_2()
Scans a point value and waits for completion.
C/C++ synopsis
#include <src/defs.h>
#include <src/M4_err.h>
Arguments
Argument Description
point (in) point type and/or number to be processed.
param (in) point parameter to be processed. PV=0 through A4=7.
value (in) value to be stored into the point parameter.
Description
Passes the value to the point processor for storage into the point parameter.
The point is processed only if the scanned value has changed.
This function is not applicable to Honeywell Process Controller points, Remote points, Container points or
System Interface Points (PSA).
Diagnostics
Upon successful completion, a value of 0 is returned. Otherwise, one of the following error codes is returned:
See also
“c_spv_2()” on page 231
232 www.honeywell.com
APPLICATION LIBRARY FOR C AND C++
c_stcupd()
Updates Controller's sample time counter.
C/C++ synopsis
#include <src/defs.h>
#include <src/M4_err.h>
Arguments
Argument Description
rtu (in) the controller number to be updated
seconds (in) the number of seconds
Description
Sets the sample time counter of a Controller. The scan task counts down this counter, and if it reaches zero the
controller will be failed. A time of greater than 60 seconds must be used if automatic recovery via the diagnostic
scan is required.
Diagnostics
Upon successful completion a value of 0 is returned. Otherwise, -1 is returned and calling c_geterrno() will
retrieve one of the following error codes:
233
APPLICATION LIBRARY FOR C AND C++
stn_num()
Finds out the Station number of a display task given the task's LRN.
C/C++ synopsis
#include <src/defs.h>
int2 stn_num(
int2* pLrn // (in) A pointer to the LRN
);
Arguments
Argument Description
pLrn (in) pointer to the LRN
Description
Quickly determines the Station number of a particular Station's display task given its LRN.
Diagnostics
Returns the Station number (>0) if successful. Otherwise it returns -1.
See also
“dsply_lrn()” on page 105
234 www.honeywell.com
APPLICATION LIBRARY FOR C AND C++
StrtoPV()
Inserts a character string into a PARvalue union.
C/C++ synopsis
#include <src/defs.h>
#include <src/almmsg.h>
#include <src/M4_err.h>
PARvalue* StrtoPV(
const char* string_val,
PARvalue* pvvalue
);
Arguments
Argument Description
pvvalue (in) A pointer to a PARvalue structure
string_val (in) The character string to insert into the PARvalue structure
Description
Inserts a character string into a PARvalue, and then returns a pointer to the PARvalue passed in. This function
allows you to set attributes into a notification structure using calls to “hsc_insert_attrib()” on page 134 and
“hsc_insert_attrib_byindex()” on page 139 functions in a single line of code.
Diagnostics
If this function is successful, the return value is a pointer back to the PARvalue passed in, otherwise, the return
value is NULL and calling “c_geterrno()” on page 112 will retrieve one of the following error codes:
Example
See the examples in “hsc_insert_attrib()” on page 134 and “hsc_insert_attrib_byindex()” on page 139.
See also
“DbletoPV()” on page 104
“hsc_insert_attrib()” on page 134
“hsc_insert_attrib_byindex()” on page 139
“Int2toPV()” on page 203
“Int4toPV()” on page 204
“PritoPV()” on page 224
“RealtoPV()” on page 226
“TimetoPV()” on page 236
235
APPLICATION LIBRARY FOR C AND C++
TimetoPV()
Inserts a time value into a PARvalue union.
C/C++ synopsis
#include <src/defs.h>
#include <src/almmsg.h>
#include <src/M4_err.h>
PARvalue* TimetoPV(
HSCTIME time_val,
PARvalue* pvvalue
);
Arguments
Argument Description
pvvalue (in) A pointer to a PARvalue structure
time_val (in) The time value to insert into the PARvalue structure
Description
Inserts a time value into a PARvalue, and then returns a pointer to the PARvalue passed in. This function allows
you to set attributes into a notification structure using calls to “hsc_insert_attrib()” on page 134 and
“hsc_insert_attrib_byindex()” on page 139 functions in a single line of code.
Diagnostics
If this function is successful, the return value is a pointer back to the PARvalue passed in, otherwise, the return
value is NULL and calling “c_geterrno()” on page 112 will retrieve one of the following error codes:
Example
See the examples in “hsc_insert_attrib()” on page 134 and “hsc_insert_attrib_byindex()” on page 139.
See also
“DbletoPV()” on page 104
“hsc_insert_attrib()” on page 134
“hsc_insert_attrib_byindex()” on page 139
“Int2toPV()” on page 203
“Int4toPV()” on page 204
“PritoPV()” on page 224
“RealtoPV()” on page 226
“StrtoPV()” on page 235
236 www.honeywell.com
APPLICATION LIBRARY FOR C AND C++
c_tmstop()
Stops a timer for the calling task.
C/C++ synopsis
#include <src/defs.h>
Arguments
Argument Description
tmridx (in) index of which timer to stop.
Description
Stops the timer specified by the argument tmridx. This index must correspond to the return value of
“c_tmstrt_...()” on page 238.
See also
“c_tmstrt_...()” on page 238
“c_trmtsk()” on page 240
237
APPLICATION LIBRARY FOR C AND C++
c_tmstrt_...()
Starts a timer for the calling task.
C/C++ synopsis
#include <src/defs.h>
#include <src/M4_err.h>
Arguments
Argument Description
cycle (in) time interval between executions in seconds.
param1 (in) parameter passed to task as parameter 1.
param2 (in) parameter passed to task as parameter 2.
Description
Starts a timer to request the calling task every cycle seconds. This is equivalent to calling “c_rqtskb...()” on
page 227 every interval. A timer is stopped by calling “c_tmstop()” on page 237.
The arguments param1 and param2 are passed as words two and three of the ten word parameter block, to the
task each interval. These parameters can be accessed by calling “c_getreq()” on page 120.
Diagnostics
Upon successful completion the timer index is returned. Otherwise, -1 is returned and calling c_geterrno() will
retrieve the following error code:
See also
“c_tmstop()” on page 237
“c_getreq()” on page 120
238 www.honeywell.com
APPLICATION LIBRARY FOR C AND C++
c_trm04()
Terminate task with error status and modify restart address.
C/C++ synopsis
#include <src/defs.h>
Arguments
Argument Description
status (in) termination error status
Description
Terminates the calling task and changes the restart address to the address immediately following the call to
“c_trm04()” on page 239. The task is not terminated if it was requested while it was active. The termination
error status is posted in the task request block for any “c_wttskb()” on page 245 calls.
If the task has been marked for deletion via a “c_deltsk()” on page 103 call then the task will be removed from
the system.
See also
“c_rqtskb...()” on page 227
“c_tstskb()” on page 241
“c_wttskb()” on page 245
“c_deltsk()” on page 103
239
APPLICATION LIBRARY FOR C AND C++
c_trmtsk()
Terminates a task with error status.
C/C++ synopsis
#include <src/defs.h>
Arguments
Argument Description
status (in) termination error status
Description
Terminates the calling task and changes the restart address to the program start address. The termination error
status is posted in the task request block for any “c_wttskb()” on page 245 calls.
If the task has been marked for deletion via a “c_deltsk()” on page 103 call then the task will be removed from
the system.
See also
“c_trm04()” on page 239
“c_deltsk()” on page 103
240 www.honeywell.com
APPLICATION LIBRARY FOR C AND C++
c_tstskb()
Tests a task's status.
C/C++ synopsis
#include <src/defs.h>
#include <src/M4_err.h>
Arguments
Argument Description
lrn (in) logical resource number of the task to be tested.
Description
Tests the completion status of a specified task.
Diagnostics
Upon successful completion a value of 0 is returned indicating that the specified task is dormant. Otherwise, -1
is returned and calling “c_geterrno()” on page 112 will retrieve one of the following error codes:
Example
#include 'src/lrns' /* for user tasks LRN */
...
...
...
/* test to see if the first user task is dormant */
if (c_tstskb(USR1LRN) == 0)
c_logmsg(progname,'123','user
task 1 is dormant');
See also
“c_wttskb()” on page 245
“c_rqtskb...()” on page 227
“c_trm04()” on page 239
“c_trmtsk()” on page 240
241
APPLICATION LIBRARY FOR C AND C++
c_upper()
Converts a character string to upper case.
C/C++ synopsis
#include <src/defs.h>
Arguments
Argument Description
string (in/out) pointer to null-terminated character string.
Description
Converts a character string to upper case (7 bit ASCII). Control characters are converted to a '.' character.
See also
“c_chrint()” on page 94
“c_intchr()” on page 205
242 www.honeywell.com
APPLICATION LIBRARY FOR C AND C++
c_wdon()
Pulses the watchdog timer for a task.
C/C++ synopsis
#include <src/defs.h>
#include <src/M4_err.h>
Arguments
Argument Description
wdtidx (in) index of the watchdog timer entry to pulse.
Description
Prevents the watchdog timer from timing-out the calling task.
Should only be called with a valid watchdog timer index returned from “c_wdstrt()” on page 244.
For more information regarding watchdog timers, see 'Modifying the activity of a task.'
Diagnostics
Does not return a value and no diagnostic errors are returned if wdtidx is invalid.
See also
“c_wdstrt()” on page 244
Related topics
“Monitoring the activity of a task” on page 37
243
APPLICATION LIBRARY FOR C AND C++
c_wdstrt()
Starts a watchdog timer for the calling task.
C/C++ synopsis
#include <src/defs.h>
#include <src/M4_err.h>
#include <src/wdstrt.h>
Arguments
Argument Description
timeout (in) time interval before watchdog timer takes action indicated by mode.
mode (in) mode of action to be taken by the watchdog timer:
• WDT_MONITOR monitor timer entry only.
• WDT_ALARM_ONCE generate an alarm on first failure only.
• WDT_ALARM generate an alarm on each failure.
• WDT_RESTART_TASK restart task on first failure, reboot the server system on second failure.
• WDT_RESTART_SYS restart the server system on failure.
Description
Enables a watchdog timer for the calling task.
Calling this routine allocates an entry in the WDTTBL. Each second, WDT decrements the timer entry. If the timer
becomes zero then the action defined by the mode will be taken.
To prevent the timeout occurring, the calling task should periodically call “c_wdon()” on page 243 to pulse reset
the timer.
For more information, see 'Modifying the activity of a task.'
Diagnostics
Upon successful completion the watchdog timer index is returned. If “c_wdstrt()” on page 244 is unable to
create a timer, it returns a 0.
See also
“c_wdon()” on page 243
“c_wdstrt()” on page 244
Related topics
“Monitoring the activity of a task” on page 37
244 www.honeywell.com
APPLICATION LIBRARY FOR C AND C++
c_wttskb()
Wait for a task to become dormant.
C/C++ synopsis
#include <src/defs.h>
#include <src/M4_err.h>
Arguments
Argument Description
lrn (in) Logical resource number of the task to be waited on.
Description
Waits for the specified task to complete processing.
Diagnostics
Upon successful completion the specified tasks termination error status is returned. Otherwise, the following
error code is returned:
See also
“c_tstskb()” on page 241
“c_rqtskb...()” on page 227
“c_trm04()” on page 239
“c_trmtsk()” on page 240
245
APPLICATION LIBRARY FOR C AND C++
Backward-compatible functions
The following functions are available for backwards compatibility.
“c_badpar()” on page 247
“c_gethstpar_...()” on page 248
“c_pps()” on page 251
“c_ppsw()” on page 252
“c_ppv()” on page 253
“c_ppvw()” on page 254
“c_sps()” on page 255
“c_spsw()” on page 256
“c_spv()” on page 257
“c_spvw()” on page 258
246 www.honeywell.com
APPLICATION LIBRARY FOR C AND C++
c_badpar()
Attention
c_badpar() is deprecated and may be removed in a future release. It is provided for backward compatibility purposes
only. When used with an Experion LX server c_badpar() will only be able to access points in the range: 1<= point
number <= 65,000. Checking the return value of hsc_param_value() provides the same functionality as c_badpar().
C/C++ synopsis
#include <src/defs.h>
Arguments
Argument Description
point (in) point type/number to be tested.
param (in) parameter to be tested.
Description
Returns TRUE if the system is not running, if the specified point is not implemented, or if the parameter value is
in error; otherwise FALSE is returned.
See also
“c_mzero()” on page 215
“hsc_param_value()” on page 166
247
APPLICATION LIBRARY FOR C AND C++
c_gethstpar_...()
Attention
c_gethstpar() is deprecated and may be removed in a future release. It is provided for backward compatibility
purposes only. When used with an Experion LX server c_gethstpar() will only be able to access points in the
range: 1<= point number <= 65,000. The replacement function c_gethstpar_2() should be used instead.
C/C++ synopsis
#include <src/defs.h>
#include <src/M4_err.h>
#include <src/gethst.h>
Arguments
Argument Description
type (in) history type (see Description).
date (in) start date of history to retrieve in Julian days (number of days since 1 Jan 1981).
time (in) start time of history to retrieve in seconds since midnight.
offset (in) offset from latest history value in history intervals (where offset=1 is the most recent history
value).
numhst (in) number of history values to be returned per Point.
points (in) array of Point type/numbers to process (maximum of 100 elements).
params (in) array of point parameters to process. Each parameter is associated with the corresponding
entry in the points array. The possible parameters are defined in the file 'parameters' in the def
folder (maximum 100 elements).
numpnt (in) number of Points to be processed.
248 www.honeywell.com
APPLICATION LIBRARY FOR C AND C++
Argument Description
archive (in) pointer to a null-terminated string containing the folder name of the archive files relative to
the archive folder. A NULL pointer implies that the system will use current history and any
archive files that correspond to the value of the date and time parameters. The archive files are
found in <server folder>\archive.
For example, to access the files in <server folder>\archive\ay2012m09d26h11r008, the
archive argument is ay2012m09d26h11r008.
values (out) two dimensional array large enough to accept history values. If there is no history for the
requested time or if the data was bad, then -0.0 is stored in the array. Sized numpnt * numhst.
Description
Used to retrieve a particular type of history values for specified Points and time in history. History will be
retrieved from a specified time or Offset going backwards in time numhst intervals for each Point specified.
The history values are stored in sequence in the values array. values[x][y] represents the yth history value for
the xth point.
The history type is specified by using one of the following values:
Value Description
HST_1MIN one minute standard history
HST_6MIN six minute standard history
HST_1HOUR one hour standard history
HST_8HOUR eight hour standard history
HST_24HOUR twenty four hour standard history
HST_5SECF Fast history
HST_1HOURE one hour extended history
HST_8HOURE eight hour extended history
HST_24HOURE twenty four hour extended history
Diagnostics
Upon successful completion a value of 0 is returned. Otherwise, -1 is returned, and calling c_geterrno() will
return one of the following error codes:
Example
#include <src/defs.h>
#include <src/M4_err.h>
#include <src/gethst.h>
#include 'parameters'
#define NHST 50
#define NPNT 3
249
APPLICATION LIBRARY FOR C AND C++
See also
“hsc_param_values()” on page 169
250 www.honeywell.com
APPLICATION LIBRARY FOR C AND C++
c_pps()
Attention
c_pps() is deprecated and may be removed in a future release. It is provided for backward compatibility purposes
only. When used with an Experion LX server c_pps() will only be able to access points in the range: 1<= point
number <= 65,000. The replacement function c_pps_2() should be used instead.
C/C++ synopsis
#include <src/defs.h>
#include <scr/M4_err.h>
Arguments
Argument Description
point (in) Point type/number to be processed.
param (in) Point parameter to be processed. -1 for all parameters.
status (out) return error code.
Description
Requests a demand scan of the specified point.
The point is always processed.
This function is not applicable to Honeywell Process Controller points, Remote points, Container points or
System Interface Points (PSA).
Diagnostics
Upon successful completion, a value of 0 is returned in status. Otherwise, one of the following error codes is
returned:
See also
“c_ppsw()” on page 252
“c_pps_2()” on page 220
251
APPLICATION LIBRARY FOR C AND C++
c_ppsw()
Attention
c_ppsw() is deprecated and may be removed in a future release. It is provided for backward compatibility purposes
only. When used with an Experion LX server c_ppsw() will only be able to access points in the range: 1<= point
number <= 65,000. The replacement function c_ppsw_2() should be used instead.
C/C++ synopsis
#include <src/defs.h>
#include <scr/M4_err.h>
Arguments
Argument Description
point (in) point type/number to be processed.
param (in) point parameter to be processed. -1 for all parameters.
status (out) return error code.
Description
Requests a demand scan of the specified point and wait for the scan to complete. If, after 10 seconds, the scan
has not replied, a timeout will be indicated.
The point is always processed.
This function is not applicable to Honeywell Process Controller points, Remote points, Container points or
System Interface Points (PSA).
Diagnostics
Upon successful completion, a value of 0 is returned in status. Otherwise, one of the following error codes is
returned:
See also
“c_pps()” on page 251
“c_ppsw_2()” on page 221
252 www.honeywell.com
APPLICATION LIBRARY FOR C AND C++
c_ppv()
Attention
c_ppv() is deprecated and may be removed in a future release. It is provided for backward compatibility purposes
only. When used with an Experion LX server c_ppv() will only be able to access points in the range: 1<= point
number <= 65,000. The replacement function c_ppv_2() should be used instead.
C/C++ synopsis
#include <src/defs.h>
#include <scr/M4_err.h>
Arguments
Argument Description
point (in) Point type/number to be processed.
param (in) Point parameter to be processed. -1 for all parameters.
value (in) Value to be stored into the point parameter.
Description
Requests a Demand scan of the specified Point.
The point is always processed.
This function is not applicable to Honeywell Process Controller points, Remote points, Container points or
System Interface Points (PSA).
Diagnostics
Upon successful completion a value of 0 is returned. Otherwise, -1 is returned and calling “c_geterrno()” on
page 112 will retrieve one of the following error codes:
See also
“c_ppvw()” on page 254
“c_ppv_2()” on page 222
253
APPLICATION LIBRARY FOR C AND C++
c_ppvw()
Attention
c_ppvw() is deprecated and may be removed in a future release. It is provided for backward compatibility purposes
only. When used with an Experion LX server c_ppvw() will only be able to access points in the range: 1<= point
number <= 65,000. The replacement function c_ppvw_2() should be used instead.
C/C++ synopsis
#include <src/defs.h>
#include <scr/M4_err.h>
Arguments
Argument Description
point (in) Point type/number to be processed.
param (in) Point parameter to be processed. -1 for all parameters.
value (in) Value to be stored into the point parameter.
Description
Requests a Demand scan of the specified Point and waits for the scan to complete. If after 10 seconds the scan
has not replied, then a timeout will be indicated. The point is always processed.
This function is not applicable to Honeywell Process Controller points, Remote points, Container points or
System Interface Points (PSA).
Diagnostics
Upon successful completion a value of 0 is returned. Otherwise, -1 is returned and calling “c_geterrno()” on
page 112 will retrieve one of the following error codes:
See also
“c_ppv()” on page 253
“c_ppvw_2()” on page 223
254 www.honeywell.com
APPLICATION LIBRARY FOR C AND C++
c_sps()
Attention
c_sps() is deprecated and may be removed in a future release. It is provided for backward compatibility purposes
only. When used with an Experion LX server c_sps() will only be able to access points in the range: 1<= point
number <= 65,000. The replacement function c_sps_2() should be used instead.
C/C++ synopsis
#include <src/defs.h>
#include <src/M4_err.h>
Arguments
Argument Description
point (in) Point type/number to be processed.
param (in) Point parameter to be processed. -1 for all parameters.
Description
SPS is used to request a Demand scan of the specified Point.
The point is only processed if the scanned value has changed.
This function is not applicable to Honeywell Process Controller points, Remote points, Container points or
System Interface Points (PSA).
Diagnostics
Upon successful completion a value of 0 is returned. Otherwise, -1 is returned and calling “c_geterrno()” on
page 112 will retrieve one of the following error codes:
See also
“c_spsw()” on page 256
“c_sps_2()” on page 229
255
APPLICATION LIBRARY FOR C AND C++
c_spsw()
Attention
c_spsw() is deprecated and may be removed in a future release. It is provided for backward compatibility purposes
only. When used with an Experion LX server c_spsw() will only be able to access points in the range: 1<= point
number <= 65,000. The replacement function c_spsw_2() should be used instead.
C/C++ synopsis
#include <src/defs.h>
#include <src/M4_err.h>
Arguments
Argument Description
point (in) Point type/number to be processed.
param (in) Point parameter to be processed. -1 for all parameters.
Description
Requests a Demand scan of the specified Point and wait for the Scan to complete. If after 10 seconds the Scan
has not replied, then a timeout will be indicated. The point is only processed if the scanned value has changed.
This function is not applicable to Honeywell Process Controller points, Remote points, Container points or
System Interface Points (PSA).
Diagnostics
Upon successful completion a value of 0 is returned. Otherwise, -1 is returned and calling “c_geterrno()” on
page 112 will retrieve one of the following error codes:
See also
“c_sps()” on page 255
“c_spsw_2()” on page 230
256 www.honeywell.com
APPLICATION LIBRARY FOR C AND C++
c_spv()
Attention
c_spv() is deprecated and may be removed in a future release. It is provided for backward compatibility purposes
only. When used with an Experion LX server c_spv() will only be able to access points in the range: 1<= point
number <= 65,000. The replacement function c_spv_2() should be used instead.
C/C++ synopsis
#include <src/defs.h>
#include <src/M4_err.h>
Arguments
Argument Description
point (in) point type and/or number to be processed
param (in) point parameter to be processed. PV=0 through A4=7
value (in) value to be stored into the point parameter
Description
Passes the value to the point processor for storage into the point parameter.
The point is processed only if the scanned value has changed.
This function is not applicable to Honeywell Process Controller points, Remote points, Container points or
System Interface Points (PSA).
Diagnostics
Upon successful completion, a value of 0 is returned. Otherwise, one of the following error codes is returned:
See also
“c_spvw()” on page 258
“c_spv_2()” on page 231
257
APPLICATION LIBRARY FOR C AND C++
c_spvw()
Attention
c_spvw() is deprecated and may be removed in a future release. It is provided for backward compatibility purposes
only. When used with an Experion LX server c_spvw() will only be able to access points in the range: 1<= point
number <= 65,000. The replacement function c_spvw_2() should be used instead.
C/C++ synopsis
#include <src/defs.h>
#include <src/M4_err.h>
Arguments
Argument Description
point (in) point type and/or number to be processed.
param (in) point parameter to be processed. PV=0 through A4=7.
value (in) value to be stored into the point parameter.
Description
Passes the value to the point processor for storage into the point parameter.
The point is processed only if the scanned value has changed.
This function is not applicable to Honeywell Process Controller points, Remote points, Container points or
System Interface Points (PSA).
Diagnostics
Upon successful completion, a value of 0 is returned. Otherwise, one of the following error codes is returned:
See also
“c_spv()” on page 257
“c_spvw_2()” on page 232
258 www.honeywell.com
APPLICATION LIBRARY FOR C AND C++
Examples
There are several examples located under the server install folder in user/examples/src. These can be used as a
basis for your own programs.
The examples are:
Example Description
test1.c a very simple task which prints 'Hello World' every time it is requested.
test2.c a simple task that generates 3 alarms when requested.
test3.c a task that demonstrates dealing with points.
test4.c a simple task that demonstrates the use of user tables.
test5.c a more completed task that demonstrates the use of user tables.
test6.c a utility that demonstrates dealing with points.
test7.c a complicated task demonstrating the use of watchdog timers, scan point special,
hsc_param_values and hsc_param_value_put.
test8.c a simple task that shows the information passed on the prmblk when the task is requested.
259
APPLICATION LIBRARY FOR C AND C++
260 www.honeywell.com
Network API reference
This section describes how to write applications for Experion using the Network API.
Related topics
“Prerequisites” on page 262
261
NETWORK API REFERENCE
Prerequisites
Before writing network applications for Experion, you need to:
• Install Experion and third-party software as described in the Installation Guide.
• Review the current security settings for Network API on the Security tab of the Server Wide Settings display
and ensure that Disable writes via Network API is enabled if you do not want data written to the server via
the Network API. For more information, see the topic 'Security tab, server wide settings' in the chapter
'Customizing Stations' in the .
• Be familiar with user access and file management as described in the .
Prerequisite skills
This guide assumes that you are an experienced programmer with a good understanding of either C, C++, or
Visual Basic.
It also assumes that you are familiar with the Microsoft Windows development environment and know how to
edit, compile and link applications.
262 www.honeywell.com
Network application programming
Related topics
“About the Network API” on page 264
“Summary of Network API functions” on page 266
“Using the Network API” on page 267
“Using Microsoft Visual Studio or Visual Basic to develop Network API applications” on page 275
“Folder structures for C/C++ applications” on page 276
“Network API applications fail to run” on page 277
263
NETWORK APPLICATION PROGRAMMING
Network Request
Server System
Network Reply
Remote System
264 www.honeywell.com
NETWORK APPLICATION PROGRAMMING
On any of the redundant/dual-network configurations above do not add the basename (server) to the hosts file.
Support for redundancy with the Network API is limited to Windows.
265
NETWORK APPLICATION PROGRAMMING
Function Description
Generate Alarms and Events
rhsc_notifications Use to remotely generate alarms and events. The various text fields are formatted into a
standard event log line on the server. The nPriority field defines the behavior on the server.
Point Parameter Access
rhsc_param_value_bynames Similar to rhsc_param_values_2 but provides a simpler calling interface but is less efficient.
rhsc_param_value_put_byna Similar to rhsc_param_value_puts_2 but provides a simpler calling interface but is less
mes efficient.
266 www.honeywell.com
NETWORK APPLICATION PROGRAMMING
To: Go to:
Determine the point numbers “Determining point numbers” on page 267
Determine the parameter numbers “Determining parameter numbers” on page 268
Access point parameters “Accessing point parameters” on page 268
Access historical information “Accessing historical information” on page 269
Access user tables “Accessing user table data” on page 270
Look up error strings “Looking up error strings” on page 273
Access parameter values by name “Functions for accessing parameter values by name” on
page 273
Related topics
“Determining point numbers” on page 267
“Determining parameter numbers” on page 268
“Accessing point parameters” on page 268
“Accessing historical information” on page 269
“Accessing user table data” on page 270
“Looking up error strings” on page 273
“Functions for accessing parameter values by name” on page 273
267
NETWORK APPLICATION PROGRAMMING
268 www.honeywell.com
NETWORK APPLICATION PROGRAMMING
Although rhsc_param_value_puts_2 is a list based function, there is no implication that it should be used as a
sequential write function. If any individual put fails, the function will not prevent the remaining writes from
occurring. The function will instead continue to write values to the remaining point parameters in the list.
Both of these point access functions, rhsc_param_values_2 and rhsc_param_value_puts_2, require the user to be
aware of memory management. The user is responsible for allocating space in the data structure used by these
functions and for freeing this space before exiting the network application.
For the rhsc_param_values_2 call, the subscription period field is used to indicate the frequency at which your
code will request the data. This allows the server to optimize its scanning strategies for the data you are
interested in. If you are only using this routine occasionally, use the constant NADS_READ_CACHE so the server
does not proceed with the optimization process.
The functions “rhsc_param_value_bynames” on page 294 and “rhsc_param_value_put_bynames” on page 297
are alternative functions that perform the same tasks as rhsc_param_values_2 and rhsc_param_value_puts_2.
There are performance costs associated with using these functions and it is preferable, where possible and when
performance is a priority, to use the rhsc_param_values_2 and rhsc_param_value_puts_2 functions instead.
Examples of using rhsc_param_values_2 and rhsc_param_value_puts_2 for C are located in the \<install
folder>\Honeywell\Experion PKS\Client\Netapi\Samples\C\Napitst project.
An example of using rhsc_param_values_2 and rhsc_param_value_puts_2 for C++ is located in the
\<install folder>\Honeywell\Experion PKS\Client\Netapi\Samples\C\Mfcnetapitest\Mfcnetapitest
project.
An example of using rhsc_param_values_2 and rhsc_param_value_puts_2 for VB can be located in the
\<install folder>\Honeywell\Experion PKS\Client\Netapi\Samples\Vb\Vbnetapitst project.
Attention
The maximum number of points that can be processed with one call to rhsc_param_hist_x is 20.
269
NETWORK APPLICATION PROGRAMMING
When defining the record layout of a user table, list the fields in consecutive order with their data type,
description and calculate their word offset from the beginning of the record.
An example of using rgetdat and rputdat for C can be located in the \<install folder>\Honeywell
\Experion PKS\Client\Netapi\Samples\C\Napitst project.
An example of using rgetdat_xxxx and rputdat_xxxx for VB can be located in the \<install folder>
\Honeywell\Experion PKS\Client\Netapi\Samples\Vb\Vbnetapitst project.
270 www.honeywell.com
NETWORK APPLICATION PROGRAMMING
Therefore, one rgetdat call could retrieve multiple records which could improve efficiency and program
execution time. The function above could be easily changed to do this.
int ierr;
int i;
271
NETWORK APPLICATION PROGRAMMING
return 2;
return 0;
}
'declare data
Dim ustbl07_def(7) As rgetdat_float_data_str
'setup data
For cnt = 0 To 7
ustbl07_def(cnt).file = UTBL07_F
ustbl07_def(cnt).rec = recno
ustbl07_def(cnt).word = (cnt * 2) + 1
Next
272 www.honeywell.com
NETWORK APPLICATION PROGRAMMING
rec.ipack = ustbl07_def(0).value
rec.tmout = ustbl07_def(1).value
rec.dout = ustbl07_def(2).value
rec.bmax = ustbl07_def(3).value
rec.cmin = ustbl07_def(4).value
rec.bav = ustbl07_def(5).value
rec.cav = ustbl07_def(6).value
rec.idq = ustbl07_def(7).value
End Function
This method could quite easily be applied for writing a whole record of a user table as well by using the
rputdat function.
Attention
The hexidecimal return value '839A' (NADS_PARTIAL_FUNC_FAIL) indicates that a partial function fail has
occurred and is only a warning. This warning indicates that at least one request, and possibly all requests, made to a
list-based function has failed. If this value is received, the fstatus Field of the data structure for each request should
be checked for errors.
Example
An example of using hsc_napierrstr for C can be located in the \<install folder>\Honeywell
\Experion PKS\Client\Netapi\Samples\C\Napitst project.
You should use hsc_napierrstr2 for VB. hsc_napierrstr is provided for backward compatibility only.
An example of using hsc_napierrstr2 for VB can be located in the \<install folder>\Honeywell
\Experion PKS\Client\Netapi\Samples\Vb\Vbnetapitst project.
There is a special condition for error numbers. If the lower four digits of the hexadecimal error number is '8150',
then the top four digits gives an Experion Process Controller error. In this case, hsc_napierrstr cannot be called
to resolve the error number. Instead, you can look at the file M4_err_def in the include folder for the error string
corresponding to the top four-digit Experion Process Controller error code.
Example
Consider the return value: 0x01068150. The lower four digits (8150) indicates that this is an Experion
Process Control Software error. The entry for 0106 in M4_err_def indicates that the error is due to a 'timeout
waiting for response'.
273
NETWORK APPLICATION PROGRAMMING
By using these functions in your interface, you are able to make requests using point names and parameter
names. The resolution of these names is handled by the server. Data is manipulated via a single Network API
call.
Be aware, however, that these functions produce significantly lower system performance than manually storing
the results of the rhsc_point_numbers_2 and rhsc_param_numbers_2 functions locally. This is for two reasons:
• First, the server needs to resolve point and parameter names to numbers every time the functions are called,
rather than just once at the start of the application.
• Second, point and parameter names are generally significantly longer than point and parameter numbers so
there is greater network traffic.
The function rhsc_param_value_bynames is equivalent to:
rhsc_point_numbers_2 + rhsc_param_numbers_2 + rhsc_param_values_2
The function rhsc_param_value_put_bynames is equivalent to:
rhsc_point_numbers_2 + rhsc_param_numbers_2 + rhsc_param_value_puts_2
The function rhsc_param_hist_offset_bynames is equivalent to:
rhsc_point_numbers_2 + rhsc_param_numbers_2 + rhc_param_hist_offsets_2
The function rhsc_param_hist_date_bynames is equivalent to:
rhsc_point_numbers_2 + rhsc_param_numbers_2 + rhsc_param_hist_dates_2
Attention
Optimum performance can only be achieved by using the functions rhsc_point_numbers_2 and
rhsc_param_numbers_2 to resolve point names and parameter names. The names are resolved just once, at the start of
the program. The equivalent point numbers and parameters numbers are returned by these functions and should be
stored locally so that all subsequent requests to parameter and history values use the locally stored numbers.
Although rhsc_param_value_put_byname is a list based function, there is no implication that it should be used as
a sequential write function. If any individual put fails, the function will not prevent the remaining writes from
occurring. The function will instead continue to write values to the remaining point parameters in the list.
Be careful when using rhsc_param_value_put_bynames() with more than one point/parameter pair. Each put
causes a control to be executed on the server and each control takes a small amount of time. If more than one
pair is put, the total time for each of these controls may exceed the default TCP/IP timeout. This will cause the
Network API to report the error RCV_TIMEOUT, even though all puts may have been successful. In addition,
the Network API will be unavailable until the list of puts has been processed. This could cause subsequent calls
to the network API to fail until the list is processed.
If maximum performance from the Network API is not a major consideration for your network application, then
use the rhsc_param_value_bynames, rhsc_param_value_put_bynames, rhsc_param_hist_offset_bynames and
rhsc_param_hist_date_bynames functions.
274 www.honeywell.com
NETWORK APPLICATION PROGRAMMING
275
NETWORK APPLICATION PROGRAMMING
<server directory>
src
276 www.honeywell.com
NETWORK APPLICATION PROGRAMMING
277
NETWORK APPLICATION PROGRAMMING
278 www.honeywell.com
Network API Function Reference
Network API is part of the Open Data Access (ODA) option. It allows you to create applications—in Visual
C/C++ or Visual Basic—that exchange data with the Experion database. These applications can run on another
computer or the Experion server.
Applications that use Network API can have:
• Read/write access to point parameter values
• Read access to history data
• Read/write access to server database files (user files)
The Network API provides the ability to remotely interrogate and change values in the server database through
a set of library routines.
Functions that enable access to remote point history data and user tables are available as well as remote point
control via a TCP/IP network.
There is one significant difference between Network API remote server functions and local Server functions.
The Network API functions, where sensible, allow multiple invocations of the API function remotely using a
single request through the use of list blocks passed as arguments. This enables network bandwidth and
processing resources to be used more sparingly. In other respects, the functions closely follow the functionality
of their standard Server API equivalents.
The following sections describe:
• “Functions” on page 280
• “Backward-compatibility Functions” on page 311
• “Diagnostics for Network API functions” on page 332
279
NETWORK API FUNCTION REFERENCE
Functions
This section contains Network API functions.
See also
“Backward-compatibility Functions” on page 311
“Diagnostics for Network API functions” on page 332
Related topics
“hsc_bad_value” on page 280
“hsc_napierrstr” on page 281
“rgetdat” on page 281
“rhsc_notifications” on page 283
“rhsc_param_hist_date_bynames” on page 285
“rhsc_param_hist_offset_bynames” on page 285
“rhsc_param_hist_dates_2” on page 289
“rhsc_param_hist_offsets_2” on page 290
“rhsc_param_numbers_2” on page 292
“rhsc_param_value_bynames” on page 294
“rhsc_param_value_put_bynames” on page 297
“rhsc_param_value_put_sec_bynames” on page 299
“rhsc_param_value_puts_2” on page 301
“rhsc_param_values_2” on page 304
“rhsc_point_numbers_2” on page 307
“rputdat” on page 309
hsc_bad_value
Checks whether the parameter value is bad.
C/C++ Synopsis
int hsc_bad_value (float nValue)
VB Synopsis
hsc_bad_value (ByVal nValue as Single) As Boolean
Arguments
Argument Description
nValue (in) The parameter value
Description
This function is really only useful for the history functions, which do return bad values.
Returns TRUE (-1) if the parameter value is BAD; otherwise FALSE (0).
280 www.honeywell.com
NETWORK API FUNCTION REFERENCE
hsc_napierrstr
Lookup an error string from an error number. This function is provided for backward compatibility.
C/C++ Synopsis
void hsc_napierrstr(UINT err, LPSTR texterr);
VB Synopsis
hsc_napierrstr(ByVal err As Integer) As String
Arguments
Argument Description
err (in) The error number to lookup
texterr (out) The error string returned
Diagnostics
This function will always return a usable string value.
rgetdat
Retrieve a list of fields from a user file.
C/C++ Synopsis
int rgetdat(char *server,
int num_points,
rgetdat_data* getdat_data);
VB Synopsis
rgetdat_int(ByVal server As String,
ByVal num_points As Integer,
getdat_int_data() As rgetdat_int_data_str) As Integer
rgetdat_bits(ByVal server As String,
ByVal num_points As Integer,
getdat_bits_data() As rgetdat_bits_data_str) As Integer
rgetdat_long(ByVal server As String,
ByVal num_points As Integer,
getdat_long_data() As rgetdat_long_data_str) As Integer
rgetdat_float(ByVal server As String,
ByVal num_points As Integer,
getdat_float_data() As rgetdat_float_data_str) As Integer
rgetdat_double(ByVal server As String,
ByVal num_points As Integer,
getdat_double_data()
As rgetdat_double_data_str) As Integer
rgetdat_str(ByVal server As String,
ByVal num_points As Integer,
getdat_str_data()
As rgetdat_str_data_str) As Integer
Arguments
Argument Description
server (in) Name of server that the database resides on.
281
NETWORK API FUNCTION REFERENCE
Argument Description
num_points (in) The number of points passed to rgetdat_xxxx in the getdat_xxxx_dataargument.
getdat_xxxx_data (in/out) Pointer to a series of rgetdat_xxxx_data structures (one for each point).
Description
This function call enables fields from a user table to be accessed. The fields to be accessed are referenced by the
members of the rgetdat_data structure (see below). The function accepts an array of rgetdat_data structures
thus providing the flexibility to obtain multiple fields with one call. Note that for the C interface only (not the
VB interface), the fields can be of different types and from different user tables.
Note that a successful return status from the rgetdat call indicates that no network errors were encountered (that
is, the request was received, processed and responded to). The status field in each call structure needs to be
verified on return to determine the result of the individual remote calls.
The program using this function call must ensure that the size of the network packets generated do not exceed
the maximum packet size permitted on the network. To meet this requirement, adhere to the following
guideline:
(22 * number of fields) + sum of all string value lengths in bytes <4000
The structure of the rgetdat_data structure is defined in nif_types.h. This structure and its members are
defined as follows:
int2 type (in) Defines the type of data to be retrieved/stored, this will be one of the standard server
data types. Namely using one of the following defines:
RGETDAT_TYPE_INT2, RGETDAT_TYPE_INT4, RGETDAT_TYPE_REAL4,
RGETDAT_TYPE_REAL8, RGETDAT_TYPE_STR, RGETDAT_TYPE_BITS
int2 file (in) Absolute database file number to retrieve/store field.
int2 rec (in) Record number in above file to retrieve/store field.
int2 word (in) Word offset in above record to retrieve/store field.
int2 start_bit (in) Start bit offset into the above word for the first bit of a bit sequence to be retrieved/
stored. (That is, the bit sequence starts at: word + start_bit, where start_bit=0 is the first bit
in the field.) Ignored if type is not a bit sequence.
int2 length (in) Length of bit sequence or string to retrieve/store, in characters for a string, in bits for a
bit sequence. Ignored if type is not a string or bit sequence.
int2 flags (in) Specifies the direction to read/write for circular files. (0: newest record, 1: oldest
record)
rgetdat_value value (in/out) Value of field retrieved or value to be stored. When storing strings they must be of
the length given above. When strings are retrieved, they become NULL terminated, hence
the length allocated to receive the string must be one more than the length specified above.
Bit sequences will start at bit zero and be length bits long. See below a description of the
union types.
int2 status (out) return value of actual remote getdat/putdat call.
The union structure of the value member used in the rgetdat_data structure is defined in
nif_types.h. This structure, and its members, are defined as follows:
short int2 Two byte signed integer.
long int4 Four byte signed integer.
float real4 Four byte IEEE floating point number.
double real Eight byte (double precision) IEEE floating point number.
char* str Pointer to string. (Note allocation of space for retrieving a string is the responsibility of the
program calling rgetdat, see rgetdat_data structure description above).
282 www.honeywell.com
NETWORK API FUNCTION REFERENCE
unsigned short bits Two byte unsigned integer to be used for bit sequences (partial integer). Note the maximum
length of a bit sequence is limited to 16.
Diagnostics
See “Diagnostics for Network API functions” on page 332.
rhsc_notifications
Insert an alarm or event into the event log.
C/C++ Synopsis
int rhsc_notifications(char *szHostname,
int cjrnd,
NOTIFICATION_DATA* notd);
VB Synopsis
RHSC_notifications(ByVal hostname As String,
ByVal num_requests As Long,
notification_data_array()
As notification_data) As Long
Arguments
Argument Description
szHostname (in) Name of server that the data resides on (that is, server hostname)
cprmbd (in) Number of notifications requested
notd (in/out) Pointer to an array of NOTIFICATION_DATA structures (one array element for
each request)
Description
The structure of the NOTIFICATION_DATA structure is defined in netapi_types.h. This structure and its
members are defined as follows:
RHSC_NOTIFICATIONS can be used to remotely generate alarms and events. The various text fields are the
raw data that can be specified. Not all the fields are applicable to every type of notification. The data in these
283
NETWORK API FUNCTION REFERENCE
fields are formatted for you into a standard event log line on the server. The nPriority field is used to define the
behavior on the server. The following constants are defined in nads_def.h:
NTFN_ALARM_URGENT generates an urgent
level alarm
NTFN_ALARM_HIGH generates a high level alarm
NTFN_ALARM_LOW generates a low level alarm
NTFN_ALARM_JNL generates a journal level
alarm
NTFN_EVENT only generates an event
(nothing
will be logged to the
alarm
list)
A number of predefined strings have been provided for use in the szEvent, szAction and szLevel fields.
Although there is no requirement to use these strings, their use will promote consistency. They can be found in
nads_def.h.
static char* EventStrings[] =
{
// should be an alarm type, an event type from
// one of the following strings, blank, or user defined
'CHANGE', // local operator change
'ACHANGE', // application (non-Station) change
'LOGIN', // operator login
'ALOGIN', // application (non-Station) login
'WDT', // watch dog timer event
'FAILED' // operation failed
};
static char* ActionStrings[] =
{
// should be blank (new alarm), an event type from
// one of the following strings or user defined
'OK', // alarm returned to normal
'ACK', // alarm acknowledged
'CNF' // message confirmed
};
static char* LevelStrings[] =
{
// should be an alarm level, one of the
// following strings indicating where the event
// was generated from, blank, or user defined
'CB', // Control Builder
'MSEDE', // Microsoft Excel Data Exchange
'NAPI', // Network API application
'API' // API application
};
A successful return status from the rhsc_notifications call indicates that no network errors were encountered
(that is, the request was received, processed, and responded to). If the returned value is
NADS_PARTIAL_FUNC_FAIL, then at least one request (and possibly all requests) failed. The status field of
each array element should be checked to find which request failed.
It is the responsibility of the program using this function call to ensure that the size of the network packets
generated do not exceed the maximum packet size permitted on the network. To meet this requirement, adhere
to the following guideline:
• For ALL request packets:
(15 * number of notifications) + sum of all string lengths < 4000
Note that the sum of the string lengths does not include nulls, which is the convention for C/C++.
Example
Create an event log entry indicating that a remote control has just occurred.
#include <sys/timeb.h>
int status;
int i;
/* Set the point names, parameter names and parameter offsets to appropriate values */
PARAM_DATA rgprmbd[] = {{'pntana1','DESC', 1}};
#define cprmbd (sizeof(rgprmbd)/sizeof(PARAM_DATA))
284 www.honeywell.com
NETWORK API FUNCTION REFERENCE
/* Allocate space and set the value and type to control pntana1.SP to 42.0 */
rgprmbd[0].pupvValue = (PARvalue *)malloc(sizeof (PARvalue));
strcpy(rgprmbd[0].pupvValue->text, 'FunkyDescription');
rgprmbd[0].nType = DT_CHAR;
Diagnostics
See “Diagnostics for Network API functions” on page 332.
See also
“hsc_notif_send()” on page 146
rhsc_param_hist_date_bynames
Retrieve history values for Parameters referenced by name from a start date.
This function's synopsis and description is identical to that of 'rhsc_param_hist_offset_bynames.'
rhsc_param_hist_offset_bynames
Retrieve history values for parameters referenced by name from an offset.
C Synopsis
int rhsc_param_hist_date_bynames(char
*szHostName,
int cHstRequests,
HIST_BYNAME_DATA* rghstbd);
VB Synopsis
RHSC_param_hst_date_bynames(ByVal
Server As String,
ByVal num_requests As Long,
hist_byname_data_array()
As hist_byname_data) As Long
RHSC_param_hst_offset_bynames(ByVal
Server As String,
ByVal num_requests As Long,
hist_byname_data_array()
As hist_byname_data) As Long
285
NETWORK API FUNCTION REFERENCE
Arguments
Argument Description
szHostName (in) Name of server on which the data resides
cHstRequests (in) Number of rghstbd elements
rghstbd (in / out) Pointer to an array of HIST_BYNAME_DATA structures. One array element for
each request.
Description
The structure of the HIST_BYNAMES_DATA structure is defined in netapi_types.h. This structure and its
members are defined as follows:
n_long dtStartDate (in) The start date of history to retrieve in Julian days (number of days since 1 Jan 1981). If
the function called is rhsc_param_hist_offset_bynames then this value is ignored.
n_float tmStartTime, (in) The start time of history to retrieve in seconds since midnight. If the function called is
rhsc_param_hist_offset_bynames then this value is ignored.
n_long nHstOffset, (in) Offset from latest history value in history intervals (where offset=1 is the most recent
history value). If the function called is rhsc_param_hist_date_bynames then this value is
ignored.
n_long (out) The status returned by the gethstpar function.
fGetHstParStatus,
n_short nHstType, (in) The type of history to retrieve (See Description).
n_ushort cPntPrmNames, (in) The number of point / parameter pairs requested.
n_ushort cHstValues (in) The number of history values to be returned per point / parameter pair. This value must
not be negative: the error message 'Message being built too large' is returned if it is.
n_char* szArchivePath, This member is no longer in use and is only retained for backwards compatibility. Instead,
pass a zero length string.
n_char** (in) An array of point names to process.
rgszPointNames,
n_char** rgszParamNames (in) An array of parameter names to process. Each parameter is associated with the
corresponding entry in the rgszPointNames array.
n_long* rgfPntPrmStatus (out) The status returned by the Server when calling hsc_point_number and
hsc_param_number for each point parameter pair.
n_float* rgnHstValues (out) A pointer to a the list of returned history values. The history values are stored in
rHstValuessized blocks for each point parameter pair. If there is no history for the requested
time or if the data was bad, then the value -0.0 is stored in the array.
These functions request a number of blocks of history data from a remote server. For each block, a history type
is specified using one of the following values:
Value Description
HST_1MIN One minute Standard history
HST_6MIN Six minute Standard history
HST_1HOUR One hour Standard history
HST_8HOUR Eight hour Standard history
HST_24HOUR Twenty four hour Standard history
HST_5SECF Fast history
HST_1HOURE One hour Extended history
286 www.honeywell.com
NETWORK API FUNCTION REFERENCE
Value Description
HST_8HOURE Eight hour Extended history
HST_24HOURE Twenty four hour Extended history
Depending upon which function is called, history will be retrieved from a specified date and time or offset
going backwards in time. The number of history values to be retrieved per point is specified by cHstValues.
cHstValues must not be negative. Point parameters are specified by name only and all name to number
resolutions are performed by the server.
Before making a request you must allocate sufficient memory for each list pointed to by rgnHstValues. You
must also free this memory before exiting your network application. The number of bytes required for each
request is 4*cHstValues*cPntPrmNames.
A successful return status from the rhsc_param_hist_xxxx_bynames call indicates that no network errors were
encountered (that is, the request was received, processed, and responded to). If the returned value is
NADS_PARTIAL_FUNC_FAIL, then at least one request (and possibly all requests) failed. The status fields of
each array element should be checked to find which request failed.
The program using this function call must ensure that the size of the network packets generated do not exceed
the maximum packet size permitted on the network.
To meet the program requirement not to exceed the maximum packet size permitted, adhere to the following
guidelines:
• For request packets for rhsc_param_hist_date_bynames:
(15 * number of history requests) + (2 * number of point parameter pairs) + sum of string lengths
of point names, parameter names and archive paths in bytes < 4000
Diagnostics
See “Diagnostics for Network API functions” on page 332.
Example
For rhsc_param_hist_date_bynames
int status;
int i;
n_long ConvertToDays(n_long year, n_long month, n_long day)
{
n_long nConvertedDays = 0;
n_long leap = 0;
nConvertedDays = (year - 1981) * 365 + (year - 1981) / 4 + day - 1;
leap = ((year % 400) == 0) || (((year % 100) != 0) && ((year % 4) == 0));
switch(month)
{
case 12:
nConvertedDays += 30;
case 11:
nConvertedDays += 31;
case 10:
nConvertedDays += 30;
case 9:
nConvertedDays += 31;
case 8:
nConvertedDays += 31;
case 7:
287
NETWORK API FUNCTION REFERENCE
nConvertedDays += 30;
case 6:
nConvertedDays += 31;
case 5:
nConvertedDays += 30;
case 4:
nConvertedDays += 31;
case 3:
nConvertedDays += 28 + leap;
case 2:
nConvertedDays += 31;
case 1:
break;
default:
printf("Invalid month\n");
return 0;
}
return nConvertedDays;
}
int main()
{
HIST_BYNAME_DATA rghstbd[2];
int chstbd = 2;
/* Set up date and time for 7 November 2001 at 1:00 pm */
n_long year = 2001;
n_long month = 11;
n_long day = 7;
int hour = 13;
int minute = 0;
int second = 0;
switch (status)
{
case 0:
printf("rhsc_param_hist_date_bynames successful\n");
/* Now print the 4th history value returned for AnalogPoint's op */
printf("Value = %f\n",
rghstbd[0].rgnHstValues[3 + rghstbd[0].cHstValues * 2]);
break;
case NADS_PARTIAL_FUNC_FAIL:
printf("rhsc_param_hist_date_bynames partially failed");
/* Check fStatus flags to find out which one(s) failed. */
break;
default:
printf("rhsc_param_hist_date_bynames failed (c_geterrno() = 0x%x)", status);
break;
}
288 www.honeywell.com
NETWORK API FUNCTION REFERENCE
free(rghstbd[i].rgszParamNames);
free(rghstbd[i].rgfPntPrmStatus);
free(rghstbd[i].rgnHstValues);
}
return 0;
}
For rhsc_param_hist_offset_bynames
int status;
int i;
int main()
{
HIST_BYNAME_DATA rghstbd[2];
int chstbd = 2;
n_long nOffset = 1; /* Most recent history value */
/* Allocate memory and set up rghstbd */
for (i=0; i<chstbd; i++)
{
rghstbd[i].nHstOffset = nOffset;
rghstbd[i].nHstType = HST_5SECF;
rghstbd[i].cPntPrmNames = 3;
/* Two point parameter pairs */
rghstbd[i].cHstValues = 10;
/* Ten history values each */
rghstbd[i].szArchivePath = "ay2001m11d01h13r001";
rghstbd[i].rgszPointNames = (char **)malloc(sizeof(char *) * 3);
rghstbd[i].rgszPointNames[0]="AnalogPoint";
rghstbd[i].rgszPointNames[1]="AnalogPoint";
rghstbd[i].rgszPointNames[2]="AnalogPoint";
rghstbd[i].rgszParamNames = (char **)malloc(sizeof(char *) * 3);
rghstbd[i].rgszParamNames[0]="pv";
rghstbd[i].rgszParamNames[1]="sp";
rghstbd[i].rgszParamNames[2]="op";
rghstbd[i].rgfPntPrmStatus = (n_long *)malloc(sizeof(n_long) * 3);
rghstbd[i].rgnHstValues = (n_float *)malloc(sizeof(n_float) * 30);
}
switch (status)
{
case 0:
printf("rhsc_param_hist_offset_bynames successful\n");
/* Now print the 4th history value returned for AnalogPoint's op */
printf("Value = %f\n",
rghstbd[0].rgnHstValues[3 + rghstbd[0].cHstValues * 2]);
break;
case NADS_PARTIAL_FUNC_FAIL:
printf("rhsc_param_hist_offset_bynames partially failed");
/* Check fStatus flags to find out which one(s) failed. */
break;
default:
printf("rhsc_param_hist_offset_bynames failed (c_geterrno() = 0x%x)", status);
break;
}
rhsc_param_hist_dates_2
Retrieve history values for a point based on date.
This function's synopsis and description are identical to that of 'rhsc_param_hist_offsets_2.'
289
NETWORK API FUNCTION REFERENCE
rhsc_param_hist_offsets_2
Retrieve history values for a point based on offset.
C/C++ Synopsis
int rhsc_param_hist_dates_2
(
char* server,
int num_gethsts,
rgethstpar_date_data_2* gethstpar_date_data2
);
int rhsc_param_hist_offsets_2
(
char* server,
int num_gethsts,
rgethstpar_ofst_data_2* gethstpar_ofst_data2
);
VB Synopsis
rHsc_Param_Hist_Dates_2(ByVal Server As String,
num_requests As Long,
gethstpar_date_data_array()
As Hist_Value_Data_2) As Long
rHsc_Param_Hist_Offsets_2(ByVal Server As String,
num_requests As Long,
gethstpar_ofst_data_array()
As Hist_Value_Data_2) As Long
Arguments
Argument Description
server (in) Name of server that the database resides on
num_requests (in) The number of history requests
gethstpar_x_data (in/out) Pointer to an array of rgethstpar_x_data_2 structures (one array element for each
request)
Description
rhsc_param_hist_x_2 functions are the replacements for the now deprecated rhsc_param_hist_x functions.
Attention
rhsc_param_hist_x functions can only access points in the range: 1 <= point number <= 65,000.
Use this function to retrieve history values for points. The two types of history (based on time or offset) are
retrieved using the corresponding function variation. History will be retrieved from a specified time or offset
going backwards in time. The history values to be accessed are referenced by the rgethst_date_data_2 and
rgethst_ofst_data_2 structures (see below). The functions accept an array of these structures, thus providing
access to multiple point history values with one function call.
Note that a successful return status from the rhsc_param_hist_dates_2 or rhsc_param_hist_offsets_2 calls
indicates that no network errors were encountered (that is, the request was received, processed and responded
to). The status field in each call structure needs to be verified on return to determine the result of the individual
remote calls.
The structure of the rgethstpar_date_data_2 struct is defined in netapi_types.h. This structure and its members
are defined as follows:
290 www.honeywell.com
NETWORK API FUNCTION REFERENCE
n_ushort hist_type (in) Defines the type of history to retrieve, this will be one of the standard server history
types. Namely using one of the following:
HST_1MIN, HST_6MIN, HST_1HOUR, HST_8HOUR, HST_24HOUR, HST_5SECF,
HST_1HOURE, HST_8HOURE, HST_24HOURE
n_ulong hist_start_date (in) Start date of history to receive in Julian days (number of days since 1st January 1981).
n_ufloat (in) Start time of history to retrieve in seconds since midnight.
hist_start_time
n_ushort num_hist (in) Number of history values per point to be retrieved.
n_ushort num_points (in) Number of points to be processed. MAXIMUM value allowed is 20.
n_ulong* (in) Array (of size num_points) containing the point type/numbers of the point history
point_type_nums values to retrieve.
n_ushort* point_params (in) Array of (of size num_points) containing the parameter numbers of the history values
to retrive.
n_char* archive path (in) Pointer to the NULL terminated string containing the archive path name of the archive
file. A NULL pointer implies that the system will use current history and any archive files
which correspond to the value of the date and time parameters.
n_ufloat* hist_values (out) Array (of size num_points * num_hist) to provide storage for the returned history
values.
n_ushort gethst_status (out) Return value of the actual remote hsc_history call.
The structure of the rgethstpar_ofst_data_2 struct is defined in netapi_types.h. This structure and its members
are defined as follows:
n_ushort hist_type (in) Defines the type of history to retrieve, this will be one of the standard server history
types. Namely using one of the following defines:
HST_1MIN, HST_6MIN, HST_1HOUR, HST_8HOUR, HST_24HOUR, HST_5SECF,
HST_1HOURE, HST_8HOURE, HST_24HOURE
n_ushort hist_offset (in) Offset from latest history value in history intervals where offset=1 is the most recent
history value).
n_ushort num_hist (in) Number of history values per point to be retrieved.
n_ushort num_points (in) Number of points to be processed. MAXIMUM value allowed is 20.
n_ulong* (in) Array (of size num_points) containing the point type/numbers of the point history
point_type_nums values to retrieve.
n_ushort* point_params (in) Array (of size num_points) containing the parameter numbers of the history values to
retrieve.
n_char* archive path (in) Pointer to the NULL terminated string containing the archive path name of the archive
file. A NULL pointer implies that the system will use current history and any archive files
which correspond to the value of the date and time parameters.
n_float* hist_values (out) Array (of size num_points * num_hist) to provide storage for the returned history
values.
n_ushort gethst_status (out) Return value of the actual remote hsc_history call.
The program using this function call must ensure that the size of the network packets generated does not exceed
the maximum packet size permitted on the network. To meet this requirement, adhere to the following
guideline:
• For request packets for rhsc_param_hist_dates_2:
(16 * number of rgethstpar_date_data_2 structs) + (6 * combined point / param pair count across all
rgethstpar_date_data_2 structs) + combined string lengths of archive paths < 4000.
291
NETWORK API FUNCTION REFERENCE
Attention
Combined point / parameter pair count across all rgethstpar_x_data_2 structs may vary. For example, an
rhsc_param_hist_x_2 call is made with 3 rgethstpar_x_data_2 data structures, each referencing 2, 5 and 4 point /
parameter pairs. This results in 6*2 + 6*5 + 6*4 = 66, so: (16 * 3) + (6 * (2 + 5 + 4)) + (strings ?) < 4000
Attention
Combined point / parameter pair count across all rgethstpar_x_data_2 structs may vary. For example, an
rhsc_param_hist_x_2 call is made with 3 rgethstpar_x_data_2 data structures, each referencing 2, 5 and 4 point /
parameter pairs. This results in 6*2 + 6*5 + 6*4 = 66, so: (16 * 3) + (6 * (2 + 5 + 4)) + (strings ?) < 4000
Diagnostics
See “Diagnostics for Network API functions” on page 332.
rhsc_param_numbers_2
Resolve a list of parameter names to numbers.
C Synopsis
int rhsc_param_numbers_2
(
char* szHostname,
int cprmnd,
PARAM_NUMBER_DATA_2* rgprmnd2
);
VB Synopsis
rhsc_param_numbers_2(ByVal
hostname As String,
ByVal num_requests As Long,
param_number_data_array()
As
param_number_data_2)
As Long
Arguments
Argument Description
szHostname (in) Name of server on which the database resides
cprmnd (in) The number of parameter name resolutions requested
rgprmnd2 (in/out) Pointer to an array of PARAM_NUMBER_DATA_2 structures (one for each point
parameter)
Description
rhsc_param_numbers_2 is the replacement for the now deprecated rhsc_param_numbers.
Attention
rhsc_param_numbers can only access points in the range: 1 <= point number <= 65,000.
292 www.honeywell.com
NETWORK API FUNCTION REFERENCE
The structure of the PARAM_NUMBER_DATA_2 structure is defined in netapi_types.h. This structure and its
members are defined as follows:
RHSC_PARAM_NUMBERS_2 converts a list of point parameter names to their equivalent parameter numbers
for a specified remote server.
A successful return status from the rhsc_param_numbers_2 call indicates that no network errors were
encountered (that is, the request was received, processed, and responded to). If the returned value is
NADS_PARTIAL_FUNC_FAIL, then at least one request (and possibly all requests) failed. The status field of
each array element should be checked to find which request failed.
The program using this function call must ensure that the size of the network packets generated do not exceed
the maximum packet size permitted on the network. To meet this requirement, adhere to the following
guidelines:
• For request packets:
(6 * number of points) + sum of string lengths of point names in bytes < 4000
Example
Resolve the parameter names 'pntana1.SP' and 'pntana1.DESC'.
int status;
int i;
POINT_NUMBER_DATA_2 rgpntnd2[] = {{"pntana1"}};
PARAM_NUMBER_DATA_2 rgprmnd2[] = {{0,
"SP"},{0, "DESC"}};
status = rhsc_point_numbers_2("server1",
cpntnd, rgpntnd2);
/* Check for error status. */
status = rhsc_param_numbers_2("server1",
cprmnd, rgprmnd2);
switch (status)
{
case 0:
printf("rhsc_param_numbers_2
successful\n");
for (i=0; i<cprmnd; i++)
{
printf("%s.%s has the parameter number %d\n",
rgpntnd2[0].szPntName,
rgprmnd2[i].szPrmName,
rgprmnd2[i].nPrm);
}
case NADS_PARTIAL_FUNC_FAIL:
printf("rhsc_param_numbers_2 partially failed\n");
/* Check fStatus flags to find out which ones failed. */
break;
default:
printf("rhsc_param_numbers_2 failed (c_geterrno() = 0x%x)\n",
status);
293
NETWORK API FUNCTION REFERENCE
break;
}
Diagnostics
See “Diagnostics for Network API functions” on page 332.
See also
“rhsc_point_numbers_2” on page 307
rhsc_param_value_bynames
Reads a list of point parameter values referenced by name.
C/C++ Synopsis
int rhsc_param_value_bynames
(
char* szHostname,
int nPeriod,
int cprmbd,
PARAM_BYNAME_DATA* rgprmbd
);
VB Synopsis
RHSC_param_value_bynames(ByVal hostname As String,
ByVal period As Long,
ByVal num_requests As Long,
param_byname_data_array() As
param_byname_data) As Long
Arguments
Argument Description
szHostname (in) Name of server that the data resides on.
nPeriod (in) subscription period in milliseconds for the point parameters. Use the constant
NADS_READ_CACHE if subscription is not required. If the value is in the Experion
cache, then that value will be returned. Otherwise the controller will be polled for the latest
value. Use the constant NADS_READ_DEVICE if you want to force Experion to re-poll
the controller. The subscription period will not be applied to standard point types.
cprmbd (in) Number of parameter values requested.
rgprmbd (in/out) Pointer to an array of PARAM_BYNAME_DATA structures (one array element for
each request).
Description
The structure of the PARAM_BYNAME_DATA structure is defined in nif_types.h. This structure and its
members are defined as follows:
294 www.honeywell.com
NETWORK API FUNCTION REFERENCE
If your system uses dynamic scanning, rhsc_param_value_bynames calls from the Network API do not trigger
dynamic scanning.
RHSC_PARAM_VALUE_BYNAMES requests a list of point parameter values from the specified remote
server. Point parameters are requested by name only, and all name to number resolutions are performed by the
server.
You can read a list of parameter values with different types using a single request. Each point parameter value is
placed into a union (of type PARvalue). Before making the request, you must allocate sufficient memory for
each value union. You must free this memory before exiting your network application.
A successful return status from the rhsc_param_value_bynames call indicates that no network errors were
encountered (that is, the request was received, processed, and responded to). If the returned value is
NADS_PARTIAL_FUNC_FAIL, then at least one request (and possibly all requests) failed. The status field of
each array element should be checked to find which request failed.
The program using this function call must ensure that the size of the network packets generated do not exceed
the maximum packet size permitted on the network.
Due to the ability to acquire a list of parameters of mixed data type, it is difficult to give generic limits. To meet
the program requirement not to exceed the maximum packet size permitted, adhere to the following guidelines
given for a number of specific cases:
• For all request packets:
(6 * number of point parameters) + sum of string lengths of point names + sum of string lengths
of parameter names < 4000
• For response packets when reading DT_INT2 data only:
(8 * number of points parameters) < 4000
• For response packets when reading DT_INT4 data only:
(10 * number of points parameters) < 4000
• For response packets when reading DT_REAL data only:
(14 * number of points parameters) < 4000
• For response packets when reading DT_ DBLE data only:
(14 * number of points parameters) < 4000
• For response packets when reading DT_CHAR data only:
(7 * number of points parameters) + sum of string lengths of value character strings in bytes <
4000
• For response packets when reading DT_ENUM data only:
(11 * number of points parameters) + sum of string lengths of value enumeration strings in
bytes < 4000
Example
Read the value of pntana1.SP and pntana1.DESC.
int status;
int i;
PARAM_BYNAME_DATA rgprmbd[] = {{'pntana1','SP', 1},{'pntana1', 'DESC', 1}};
#define cprmbd (sizeof(rgprmbd)/sizeof(PARAM_BYNAME_DATA))
/* Allocate sufficient memory for each value union. See sample code for rhsc_param_values for
more details */
for (i=0; i<cprmbd; i++)
{
rgprmbd[i].pupvValue = (PARvalue *)malloc(sizeof(PARvalue);}
295
NETWORK API FUNCTION REFERENCE
switch (status)
{
case 0:
printf('rhsc_param_value_bynames successful\n');
for (i=0; i<cprmbd; i++)
{
switch (rgprmbd[i].nType)
{
case DT_CHAR:
printf('%s.%s has the value %s\n',
rgprmbd[i].szPntName,
rgprmbd[i].szPrmName,
rgprmbd[i].pupvValue->text);
break;
case DT_INT2:
printf('%s.%s has the value %d\n',
rgprmbd[i].szPntName,
rgprmbd[i].szPrmName,
rgprmbd[i].pupvValue->int2);
break;
case DT_INT4:
printf('%s.%s has the value %d\n',
rgprmbd[i].szPntName,
rgprmbd[i].szPrmName,
rgprmbd[i].pupvValue->int4);
break;
case DT_REAL:
printf('%s.%s has the value %f\n',
rgprmbd[i].szPntName,
rgprmbd[i].szPrmName,
rgprmbd[i].pupvValue->real);
break;
case DT_DBLE:
printf('%s.%s has the value %f\n',
rgprmbd[].szPntName,
rgprmbd[i].szPrmName,
rgprmbd[i].pupvValue->dble);
break;
case DT_ENUM:
printf('%s.%s has the ordinal value %d and enum string %s\n',
rgprmbd[0].szPntName,
rgprmbd[i].szPrmName,
rgprmbd[i].pupvValue->en.ord,
rgprmbd[i].pupvValue->en.text);
break;
default:
printf('Illegal type found\n');
break;
}
}
case NADS_PARTIAL_FUNC_FAIL:
printf('rhsc_param_value_bynames partially failed');
/* Check fStatus flags to find out which one(s) failed. */
break;
default:
printf('rhsc_param_value_bynames failed (c_geterrno() = 0x%x)', status);
break;
}
Diagnostics
See “Diagnostics for Network API functions” on page 332.
See also
“rhsc_param_value_puts_2” on page 301
“rhsc_param_value_put_bynames” on page 297
296 www.honeywell.com
NETWORK API FUNCTION REFERENCE
rhsc_param_value_put_bynames
Control a list of point parameter values referenced by name.
C/C++ Synopsis
int rhsc_param_put_bynames
(
char* szHostname,
int cprmbd,
PARAM_BYNAME_DATA*
rgprmbd
);
VB Synopsis
RHSC_param_value_put_bynames(ByVal hostname As String,
ByVal num_requests As Long,
param_byname_data_array()
As param_byname_data) As Long
Arguments
Argument Description
szHostname (in) Name of server that the data resides on
cprmbd (in) Number of controls to parameters values requested
rgprmbd (in/out) Pointer to an array of PARAM_BYNAME_DATA structures (one array element for
each request)
Description
The structure of the PARAM_BYNAME_DATA structure is defined in nif_types.h. This structure and its
members are defined as follows:
297
NETWORK API FUNCTION REFERENCE
TCP/IP timeout. This will cause the Network API to report the error RCV_TIMEOUT, even though all puts
may have been successful. In addition, the Network API will be unavailable until the list of puts has been
processed. This could cause subsequent calls to the network API to fail until the list is processed.
To simplify the handling of enumerations, two data types have been included for use with this function only.
The data types are DT_ENUM_ORD, and DT_ENUM_STR. When writing a value to an enumeration point
parameter, supply the ordinal part of the enumeration only and use the DT_ENUM_ORD data type.
Alternatively, if you don't know the ordinal value, supply only the text component of the enumeration and use
the DT_ENUM_STR data type. If the DT_ENUM data type is specified, only the ordinal value is used by this
function (similar to DT_ENUM_ORD).
A successful return status from the rhsc_param_value_put_bynames call indicates that no network errors were
encountered (that is, the request was received, processed, and responded to).
If the returned value is NADS_PARTIAL_FUNC_FAIL, then at least one request (and possibly all requests)
failed. The status field of each array element should be checked to find which request failed. For each array
element, a value of CTLOK (See “Diagnostics for Network API functions” on page 332) or 0 in the status field
indicates that the control was successful.
The program using this function must ensure that the size of the network packets generated do not exceed the
maximum packet size permitted on the network.
Due to the ability to acquire a list of parameters of mixed data type, it is difficult to give generic limits. To meet
the program requirement not to exceed the maximum packet size permitted, adhere to the following guidelines
given for a number of specific cases:
• For request packets when writing DT_INT2 data only:
(10 * number of points parameters) + sum of string lengths of point names + sum of string lengths
of parameter names < 4000
298 www.honeywell.com
NETWORK API FUNCTION REFERENCE
Example
Control the SP value of 'pntana1' to 42.0 and change its DESC to say 'FunkyDescription.'
int status;
int i;
/* Set the point names, parameter names and parameter offsets to appropriate values */
PARAM_BYNAME_DATA rgprmbd[] = {{'pntana1','SP', 1},{'pntana1', 'DESC', 1}};
#define cprmbd (sizeof(rgprmbd)/sizeof(PARAM_BYNAME_DATA))
/* Allocate space and set the value and type to control pntana1.SP to 42.0 */
rgprmbd[0].pupvValue = (PARvalue *)malloc(sizeof(DT_REAL));
rgprmbd[0].pupvValue->real = (float)42.0;
rgprmbd[0].nType = DT_REAL;
/* Allocate space and set the value and type to control pntana1.DESC to 'FunkyDescription' */
rgprmbd[1].pupvValue = (PARvalue *)malloc(strlen('FunkyDescription')+1);
strcpy(rgprmbd[1].pupvValue->text, 'FunkyDescription');
rgprmbd[1].nType = DT_CHAR;
switch (status)
{
case 0:
printf('rhsc_param_value_put_bynames successful\n');
break;
case NADS_PARTIAL_FUNC_FAIL:
printf('rhsc_param_value_put_bynames partially failed');
/* Check fStatus flags to find out which one(s) failed. */
break;
default:
printf('rhsc_param_value_bynames failed (c_geterrno() = 0x%x)', status);
break;
}
Diagnostics
See “Diagnostics for Network API functions” on page 332.
See also
“rhsc_param_values_2” on page 304
“rhsc_param_value_put_bynames” on page 297
rhsc_param_value_put_sec_bynames
This function acts similarly to “rhsc_param_value_put_bynames” on page 297, except that it has an extra
Station-related argument.
C/C++ Synopsis
int rhsc_param_put_sec_bynames
(
char* szHostname,
int cprmbd,
PARAM_BYNAME_DATA* rgprmbd,
unsigned short nStn
);
VB Synopsis
RHSC_param_value_put_sec_bynames(ByVal hostname As String,
ByVal num_requests As Long,
299
NETWORK API FUNCTION REFERENCE
param_byname_data_array() As param_byname_data,
Station As short) As Long
Arguments
Argument Description
szHostname (in) Name of server that the data resides on
cprmbd (in) Number of controls to parameters values requested
rgprmbd (in/out) Pointer to an array of PARAM_BYNAME_DATA structures (one array element for
each request)
nStn (in) Station number, which the Network Server uses in the associated CHANGE event for
this call.
If operator-based security is used, the operator's name/ID will also be captured.
Note that even if the Station is not connected to the server, events raised by this function
will still be logged against it.
Description
Unlike most Network API functions, events raised by this function are associated with the specified Station.
(Events raised by other functions are associated with 'Network Server'.) If you want to control what events are
logged by an application, see “Controlling what events are logged by an external application”.
Diagnostics
See “Diagnostics for Network API functions” on page 332.
Bit 14 Bit 15 Log all events from an external Log only events with security
application information
0 0 No No
1 0 No Yes
0 1 Yes Yes
1 1 Yes Yes
The events that are logged by an external application that uses Network Server or OPC Server are determined
by two check boxes on the Alarm/Event Options tab of the Server Wide Settings display:
• Log Network Server and OPC Server changes to the database as events
• Log Network Server changes with security information to the database as events
There are three possible scenarios:
• If you do not want events logged, clear both check boxes
300 www.honeywell.com
NETWORK API FUNCTION REFERENCE
• If you only want events that have been raised via rhsc_param_value_puts_sec or
rhsc_param_value_put_sec_bynames, then:
– Clear the Log Network Server and OPC Server changes to the database as events check box
– Select the Log Network Server changes with security information to the database as events check
box
• If you want all events logged, then select the Log Network Server and OPC Server changes to the
database as events check box.
rhsc_param_value_puts_2
Control a list of point parameter values.
C Synopsis
int rhsc_param_value_puts_2
(
char* szHostname,
int cprmvd,
PARAM_VALUE_DATA_2* rgprmvd2
);
VB Synopsis
rhsc_param_value_puts_2
(ByVal hostname As String,
ByVal num_requests As Long,
Param_value_data_array ()
As param_value_data_2) As Long
Arguments
Argument Description
szHostname (in) Name of server that the database resides on
cprmvd (in) The number of controls to parameters requested
rgprmvd2 (in/out) Pointer to a series of PARAM_VALUE_DATA_2 structures (one array element for
each point)
Description
rhsc_param_value_puts_2 is the replacement for the now deprecated rhsc_param_value_puts.
Attention
rhsc_param_value_puts can only access points in the range: 1 <= point number <= 65,000
The structure of the PARAM_VALUE_DATA_2 structure is defined in netapi_types.h. This structure and its
members are defined as follows:
301
NETWORK API FUNCTION REFERENCE
RHSC_PARM_VALUE_PUTS_2 writes a list of point parameter values to the specified remote server and
performs the necessary control. A function return of 0 is given if the point parameter values are successfully
controlled, otherwise, an error code is returned.
You can write a list of parameter values with different types using a single request. The value is placed into a
union (of type PARvalue). Before storing the value to be written to a point parameter in the
PARAM_VALUE_DATA_2 structure, you must allocate sufficient memory for the union. You must free this
memory before exiting your network application.
Although this is a list based function, there is no implication that it should be used as a sequential write
function. If any individual put fails, the function will not prevent the remaining writes from occurring. The
function will instead continue to write values to the remaining point parameters in the list.
Be careful when using rhsc_param_value_puts_2() and rhsc_param_value_put_bynames() with more than one
point/parameter pair. Each put causes a control to be executed on the server and each control takes a small
amount of time. If more than one pair is put, the total time for each of these controls may exceed the default
TCP/IP timeout. This will cause the Network API to report the error RCV_TIMEOUT, even though all puts
may have been successful. In addition, the Network API will be unavailable until the list of puts has been
processed. This could cause subsequent calls to the network API to fail until the list is processed.
To simplify the handling of enumerations, two data types have been included for use with this function only.
The data types are DT_ENUM_ORD, and DT_ENUM_STR. When writing a value to an enumeration point
parameter, supply the ordinal part of the enumeration only and use the DT_ENUM_ORD data type.
Alternatively, if you don't know the ordinal value, supply only the text component of the enumeration and use
the DT_ENUM_STR data type. If the DT_ENUM data type is specified, only the ordinal value is used by this
function (similar to DT_ENUM_ORD).
A successful return status from the rhsc_param_value_puts_2 call indicates that no network errors were
encountered (that is, the request was received, processed, and responded to).
If the returned value is NADS_PARTIAL_FUNC_FAIL, then at least one request (and possibly all requests)
failed. The status field of each array element should be checked to find which request failed. For each array
element, a value of CTLOK (See Diagnostics for Network API functions) or 0 in the status field indicates that
the control was successful.
The program using this function call must ensure that the size of the network packets generated do not exceed
the maximum packet size permitted on the network.
302 www.honeywell.com
NETWORK API FUNCTION REFERENCE
Due to the ability to control a list of parameters of mixed data type, it is difficult to give generic limits. To meet
the program requirement not to exceed the maximum packet size permitted, adhere to the following guidelines
given for a number of specific cases:
• For request packets when writing DT_INT2 data only:
(14 * number of points parameters) < 4000
Example
Control pntana1's SP value to 42.0 and change its DESC to say 'Funky description.'
int status;
int i;
PARAM_VALUE_DATA_2 rgprmvd2[cprmvd];
rgprmnd2[0].nPnt = rgpntnd2[0].nPnt;
rgprmnd2[1].nPnt = rgpntnd2[0].nPnt;
status = rhsc_param_numbers_2("Server1", cprmnd, rgprmnd2);
/* Set the point number, parameter number and offset for the point parameter. Allocate space,
assign a value, and set the type for pntana1.PV */
Rgprmvd2[0].nPnt = rgprmnd2[0].nPnt;
Rgprmvd2[0].nPrm = rgprmnd2[0].nPrm;
Rgprmvd2[0].nPrmoffset = 1 /* Set
parameter offset to default value*/
Rgprmvd2[0].pupvValue = (PARvalue *)malloc(sizeof(DT_REAL));
Rgprmvd2[0].pupvValue->real = (float)42.0;
Rgprmvd2[0].nType = DT_REAL;
/* Set the point number, parameter number and offset for the point parameter. Allocate space,
303
NETWORK API FUNCTION REFERENCE
Diagnostics
See “Diagnostics for Network API functions” on page 332.
See also
“rhsc_param_values_2” on page 304
“rhsc_param_value_put_bynames” on page 297
rhsc_param_values_2
Read a list of point parameter values.
C Synopsis
int rhsc_param_values_2
(
char* szHostname,
int nPeriod,
int cprmvd,
PARAM_VALUE_DATA_2* rgprmvd2
);
VB Synopsis
rhsc_param_values_2(ByVal hostname As String,
ByVal period as Long,
ByVal num_requests as Long,
param_value_data_array()
As param_value_data_2) As Long
Arguments
Argument Description
szHostname (in) Name of server that the database resides on.
304 www.honeywell.com
NETWORK API FUNCTION REFERENCE
Argument Description
nPeriod (in) subscription period in milliseconds for the point parameters. Use the constant
NADS_READ_CACHE if subscription is not required. If the value is in the Experion
cache, then that value will be returned. Otherwise the controller will be polled for the latest
value. Use the constant NADS_READ_DEVICE if you want to force Experion to re-poll
the controller. The subscription period will not be applied to standard point types.
cprmvd (in) The number of parameter values requested.
rgprmvd2 (in/out) Pointer to an array of PARAM_VALUE_DATA_2 structures (one array element for
each request).
Description
rhsc_param_values_2 is the replacement for the now deprecated rhsc_param_values.
Attention
rhsc_param_values can only access points in the range: 1 <= point number <= 65,000.
The structure of the PARAM_VALUE_DATA_2 structure is defined in netapi_types.h. This structure and its
members are defined as follows:
If your system uses dynamic scanning, rhsc_param_values_2 calls from the Network API do not trigger
dynamic scanning.
RHSC_PARM_VALUES_2 requests a list of point parameter values from the specified remote server. A
function return of 0 is given if the parameter values were successfully read else an error code is returned.
You can read a list of parameter values with different types using a single request. Each point parameter value is
placed into a union (of type PARvalue). Before making the request, you must allocate sufficient memory for
each value union. You must free this memory before exiting your Network application.
A successful return status from the rhsc_param_values_2 call indicates that no network errors were encountered
(that is, the request was received, processed, and responded to). If the returned value is
NADS_PARTIAL_FUNC_FAIL, then at least one request (and possibly all requests) failed. The status field of
each array element should be checked to find which request failed.
The program using this function call must ensure that the size of the network packets generated do not exceed
the maximum packet size permitted on the network.
Due to the ability to acquire a list of parameters of mixed data type, it is difficult to give generic limits. To meet
the program requirement not to exceed the maximum packet size permitted, adhere to the following guidelines
given for a number of specific cases:
• For ALL request packets:
(10 * number of point parameters) < 4000
• For response packets when reading DT_INT2 data only:
(10 * number of points parameters) < 4000
• For response packets when reading DT_INT4 data only:
(12 * number of points parameters) < 4000
305
NETWORK API FUNCTION REFERENCE
Example
Read the value of pntana1.SP and pntana1.DESC.
int status;
int i;
POINT_NUMBER_DATA_2 rgpntnd2[] = {{'pntana1'}};
PARAM_NUMBER_DATA_2 rgprmnd2[] = {{0, 'SP'}, {0, 'DESC'}};
PARAM_VALUE_DATA_2 rgprmvd2[cprmvd];
/*
ALLOCATING MEMORY:
Sufficient memory must be allocated for each value union. If the
value type is not known, allocate memory for the largest possible
size of a PARvalue union. See below for an example of how to allocate
this memory.
If the data type is known, then allocate the exact amount of memory
to save space.
For example for DT_REAL values:
rgprmvd2[0].pupvValue = (PARvalue *) malloc(sizeof(DT_REAL));
*/
for (i=0; i<cprmvd; i++)
{
rgprmvd2[i].pupvValue = (PARvalue *)malloc(sizeof(PARvalue);}
status = rhsc_param_values_2('server1',
NADS_READ_CACHE, cprmvd, rgprmvd2);
switch (status)
{
case 0:
printf('rhsc_param_values_2 successful\n');
for (i=0; i<cprmvd; i++)
{
switch (rgprmvd2[i].nType)
{
case DT_CHAR:
printf('%s.%s has the value %s\n',
rgpntnd2[0].szPntName,
rgprmnd2[i].szPrmName,
306 www.honeywell.com
NETWORK API FUNCTION REFERENCE
rgprmvd2[i].pupvValue->text);
break;
case DT_INT2:
printf('%s.%s has the value %d\n',
rgpntnd2[0].szPntName,
rgprmnd2[i].szPrmName,
rgprmvd2[i].pupvValue->int2);
break;
case DT_INT4:
printf('%s.%s has the value %d\n',
rgpntnd2[0].szPntName,
rgprmnd2[i].szPrmName,
rgprmvd2[i].pupvValue->int4);
break;
case DT_REAL:
printf('%s.%s has the value %f\n',
rgpntnd2[0].szPntName,
rgprmnd2[i].szPrmName,
rgprmvd2[i].pupvValue->real);
break;
case DT_DBLE:
printf('%s.%s has the value %f\n',
rgpntnd2[0].szPntName,
rgprmnd2[i].szPrmName,
rgprmvd2[i].pupvValue->dble);
break;
case DT_ENUM:
printf('%s.%s has the ordinal value %d and enum string %s\n',
rgpntnd2[0].szPntName,
rgprmnd2[i].szPrmName,
rgprmvd2[i].pupvValue->en.ord,
rgprmvd2[i].pupvValue->en.text);
break;
default:
printf('Illegal type found\n');
break;
}
}
break;
case NADS_PARTIAL_FUNC_FAIL:
printf('rhsc_param_values_2 partially failed\n');
/* Check fStatus flags to find out which ones failed. */
break;
default:
printf('rhsc_param_values_2 failed (c_geterrno() = 0x%x)\n', status);
break;
}
free(rgprmvd2[i].pupvValue);
}
Diagnostics
See “Diagnostics for Network API functions” on page 332.
See also
“rhsc_param_value_puts_2” on page 301
“rhsc_param_value_put_bynames” on page 297
rhsc_point_numbers_2
Resolve a list of point names to numbers.
C/C++ Synopsis
int rhsc_point_numbers_2
(
char* szHostname,
int cpntnd,
307
NETWORK API FUNCTION REFERENCE
POINT_NUMBER_DATA_2* rgpntnd2
);
VB Synopsis
rhsc_point_numbers_2(ByVal hostname As String,
ByVal num_requests As Long,
point_number_data_array()
As Point_Number_Data_2) As Long
Arguments
Argument Description
szHostname (in) Name of server that the database resides on
cpntnd (in) The number of point name resolutions requested
rgpntnd2 (in/out) Pointer to a series of POINT_NUMBER_DATA_2 structures (one array element for
each request)
Description
rhsc_point_numbers_2 is the replacement for the now deprecated rhsc_point_numbers.
Attention
rhsc_point_numbers can only access points in the range: 1 <= point number <= 65,000.
The structure of the POINT_NUMBER_DATA_2 structure is defined in nif_types.h. This structure and its
members are defined as follows:
RHSC_POINT_NUMBERS_2 converts a list of point names to their equivalent point numbers for a specified
remote server.
A successful return status from the rhsc_point_numbers_2 call indicates that no network errors were
encountered (that is, the request was received, processed, and responded to). If the returned value is
NADS_PARTIAL_FUNC_FAIL, then at least one request (and possibly all requests) failed. The status field of
each array element should be checked to find which request failed.
The program using this function call must ensure that the size of the network packets generated do not exceed
the maximum packet size permitted on the network. To meet this program requirement, adhere to the following
guidelines:
• For request packets:
(4 * number of points) + sum of string lengths of point names in bytes < 4000
Example
Resolve the point names 'pntana1' and 'pntana2.'
int status;
int i;
POINT_NUMBER_DATA_2 rgpntnd2[] = {{'pntana1'},{'pntana2'}};
#define cpntnd sizeof(rgpntnd2)/sizeof(POINT_NUMBER_DATA_2)
308 www.honeywell.com
NETWORK API FUNCTION REFERENCE
switch (status)
{
case 0:
printf('rhsc_point_numbers_2 successful\n');
for (i=0; i<cpntnd; i++)
{
printf('%s has the point number %d\n',
rgpntnd2[i].szPntName,
rgpntnd2[i].nPnt);
}
break;
case NADS_PARTIAL_FUNC_FAIL:
printf('rhsc_point_numbers_2 partially failed\n');
/* Check fStatus flags to find out which ones failed. */
break;
default:
printf('rhsc_point_numbers_2 failed (c_geterrno() = 0x%x)\n', status);
break;
}
Diagnostics
See “Diagnostics for Network API functions” on page 332.
rputdat
Store a list of fields to a user file.
C Synopsis
int rputdat(char *server,
int num_points,
rgetdat_data getdat_data[])
VB Synopsis
rputdat_int(ByVal server As String,
ByVal num_points As Integer,
getdat_int_data() As rgetdat_int_data_str) As Integer
rputdat_bits(ByVal server As String,
ByVal num_points As Integer,
putdat_bits_data() As rgetdat_bits_data_str) As Integer
rputdat_long(ByVal server As String,
ByVal num_points As Integer,
getdat_long_data() As rgetdat_long_data_str) As Integer
rputdat_float(ByVal server As String,
ByVal num_points As Integer,
getdat_float_data()
As rgetdat_float_data_str) As Integer
rputdat_double(ByVal server As String,
ByVal num_points As Integer,
getdat_double_data()
As rgetdat_double_data_str) As Integer
rputdat_str(ByVal server As String,
ByVal num_points As Integer,
getdat_str_data()
As rgetdat_str_data_str) As Integer
Arguments
Argument Description
server (in) Name of server that the database resides on
num_points (in) The number of points passed to rgetdat_xxxx in the getdat_xxxx_data argument
getdat_xxxx_data (in/out) Pointer to a series of rgetdat_xxxx_data structures (one for each point)
309
NETWORK API FUNCTION REFERENCE
Description
This function call enables fields from a user table to be changed. The fields to be accessed are referenced by the
members of the rgetdat_data structure (see below). The function accepts an array of rgetdat_data structures thus
providing the flexibility to set multiple fields with one call. Note that the fields can be of different types and
from different database files.
A successful return status from the rputdat call indicates that no network error were encountered (that is, the
request was received, processed and responded to). The status field in each call structure must still be checked
on return to determine the result of the individual remote calls.
The structure of the rgetdat_data structure is defined in nif_types.h. This structure and its members are defined
as follows:
int2 type (in) Defines the type of data to be retrieved/stored, this will be one of the standard server
data types. Namely using one of the following defines:
RGETDAT_TYPE_INT2, RGETDAT_TYPE_INT4, RGETDAT_TYPE_REAL4,
RGETDAT_TYPE_REAL8, RGETDAT_TYPE_STR, RGETDAT_TYPE_BITS
int2 file (in) Absolute database file number to retrieve/store field.
int2 rec (in) Record number in above file to retrieve/store field.
int2 word (in) Word offset in above record to retrieve/store field.
int2 start_bit (in) Start bit offset into the above word for the first bit of a bit sequence to be retrieved/
stored. (that is, The bit sequence starts at: word + start_bit, start_bit=0 is the first bit in the
field.). Ignored if type not a bit sequence.
int2 length (in) Length of bit sequence or string to retrieve/store, in characters for a string, in bits for a
bit sequence. Ignored if type not a string or bit sequence.
int2 flags (in) Bit zero specifies the direction to read/write for circular files. (0 = newest record, 1 =
oldest record)
union value (in/out) Value of field retrieved or value to be stored. When storing strings they must be of
the length given above. When strings are retrieved they become NULL terminated, hence
the length allocated to receive the string must be one more than the length specified above.
Bit sequences will start at bit zero and be length bits long. See below for a description of
the union types.
int2 status (out) Return value of actual remote putdat/putdat call.
The union structure of the value member used in the rgetdat_data structure is defined in nif_types.h. This
structure and its members is defined as follows:
The program using this function must ensure that the size of the network packets generated do not exceed the
maximum packet size permitted on the network. To meet this requirement, adhere to the following guideline:
(22 * number of fields) + sum of all string value lengths in bytes <4000
Diagnostics
See “Diagnostics for Network API functions” on page 332.
310 www.honeywell.com
NETWORK API FUNCTION REFERENCE
Backward-compatibility Functions
The following functions are available for backwards compatibility.
hsc_napierrstr
Lookup an error string from an error number. This function is provided for backward compatibility.
C/C++ Synopsis
void hsc_napierrstr(UINT err, LPSTR texterr);
VB Synopsis
hsc_napierrstr(ByVal err As Integer) As String
Arguments
Argument Description
err (in) The error number to lookup
texterr (out) The error string returned
Diagnostics
This function will always return a usable string value.
rgethstpar_date
Retrieve history values for a Point based on date.
This function's synopsis and description are identical to that of 'rgethstpar_ofst.'
rgethstpar_ofst
Retrieve history values for a point based on offset.
C synopsis
int rgethstpar_date
(
char* server,
int num_gethsts,
rgethstpar_date_data* gethstpar_date_data
);
int rgethstpar_ofst
(
char* server,
int num_gethsts,
rgethstpar_ofst_data* gethstpar_ofst_data
);
VB synopsis
rgethstpar_date(ByVal server As String,
gethstpar_date_data
As rgethstpar_date_data_str) As Integer
rgethstpar_ofst(ByVal server As String,
gethstpar_ofst_data
As rgethstpar_ofst_data_str) As Integer
311
NETWORK API FUNCTION REFERENCE
Arguments
Argument Description
server (in) Name of server that the database resides on
num_gethsts (in) The number of points passed to rgethstpar_xxxx in the gethstpar_xxxx_data argument
gethstpar_xxxx_data (in/out) Pointer to a series of rgethstpar_xxxx_data structures (one for each point)
Description
This function is provided for backwards compatibility. These functions can only access points in the range: 1 <=
point number <=65,000.
The functions rhsc_param_hist_dates_2 and rhsc_param_hist_offsets_2 should be used instead.
Use this function to retrieve history values for points. The two types of history (based on time or offset) are
retrieved using the corresponding function variation. History will be retrieved from a specified time or offset
going backwards in time. The history values to be accessed are referenced by the rgethst_date_data and
rgethst_ofst_data structures (see below). The functions accept an array of these structures, thus providing access
to multiple point history values with one function call.
Note that a successful return status from the rgethst call indicates that no network errors were encountered (that
is, the request was received, processed and responded to). The status field in each call structure needs to be
verified on return to determine the result of the individual remote calls.
The structure of the rgethst_date_data structure is defined in nif_types.h. This structure and its members are
defined as follows:
uint2 hist_type (in) Defines the type of history to retrieve, this will be one of the standard server history
types. Namely using one of the following:
HST_1MIN, HST_6MIN, HST_1HOUR, HST_8HOUR, HST_24HOUR, HST_5SECF,
HST_1HOURE, HST_8HOURE, HST_24HOURE
uint4 hist_start_date (in) Start date of history to receive in Julian days (number of days since 1st January 1981).
ureal4 hist_start_time (in) Start time of history to retrieve in seconds since midnight.
uint2 num_hist (in) Number of history values per point to be retrieved.
uint2 num_points (in) Number of points to be processed. MAXIMUM value allowed is 20.
uint2* point_type_nums (in) Array (of dimension num_points) containing the point type/numbers of the point
history values to retrieve.
uint2* point_params (in) Array of (dimension num_points) containing the parameter numbers of the history
values to retrive.
uchar* archive path This member is no longer in use and is only retained for backwards compatibility. Instead,
pass a zero length string.
real4* hist_values (out) Array (of dimension num_points * num_hist) to provide storage for the returned
history values.
uint2 gethst_status (out) Return value of the actual remote gethst_date call.
The structure of the rgethst_ofst_data structure is defined in nif_types.h. This structure and its members are
defined as follows:
uint2 hist_type (in) Defines the type of history to retrieve, this will be one of the standard server history
types. Namely using one of the following defines: HST_1MIN, HST_6MIN,
HST_1HOUR, HST_8HOUR, HST_24HOUR, HST_5SECF, HST_1HOURE,
HST_8HOURE, HST_24HOURE
uint4 hist_offset (in) Offset from latest history value in history intervals where offset=1 is the most recent
history value).
312 www.honeywell.com
NETWORK API FUNCTION REFERENCE
The program using this function call must ensure that the size of the network packets generated does not exceed
the maximum packet size permitted on the network. To meet this requirement, adhere to the following
guideline:
• For request packets for rgethst_date:
(15 * number of history requests) + (2 * number of points requested) + string lengths of archive
paths
< 4000.
Diagnostics
See “Diagnostics for Network API functions” on page 332.
rgetpnt
Get point type/number by point name string.
C Synopsis
int rgetpnt
(
char* server,
int num_points,
rgetpnt_data* getpnt_data
);
VB Synopsis
rgetpnt (ByVal server As String,
ByVal num_points As Integer,
getpnt_data() As rgetpnt_data_str) As Integer
313
NETWORK API FUNCTION REFERENCE
Arguments
Argument Description
server (in) Name of server that the database resides on
num_points (in) The number of points passed to rgetpnt in the getpnt_data argument
getpnt_data (in/out) Pointer to a series of rgetpnt_data structures (one for each point)
Description
This function is provided for backwards compatibility. It cannot be used to access point information for points
on Process Controllers. This function can only access points in the range: 1 <= point number <=65,000.
The rhsc_point_numbers_2 function should be used instead.
This function enables the point type/number to be resolved from the point name. Each point name to be resolved
is stored in a rgetpnt_data structure. The function accepts an array of structures, thus enabling multiple point
names to be resolved with one function call.
The structure of rgetpnt_data is defined in nif_types.h. This structure and its members are defined as follows:
char* point_name (in) Pointer to a null terminated string containing the point name to be resolved into a point
number.
uint2 point_type_num (out) Return value of the point type/number for the point named above.
uint2 getpnt_status (out) Return value of the actual remote getpnt call.
Note that a successful return status from the rgetpnt call indicates that no network errors, were encountered
(that is, the request was received, processed and responded to). The status field in each call structure needs to be
verified on return to determine the result of the individual remote calls.
The program using this function call must ensure that the size of the network packets generated does not exceed
the maximum packet size permitted on the network. To meet this requirement, adhere to the following
guideline:
(4 * number of points) + sum of string lengths of point names in bytes <4000
Diagnostics
See “Diagnostics for Network API functions” on page 332.
See also
“rhsc_point_numbers_2” on page 307
rgetval_numb
Retrieve the value of a numeric point parameter.
This function's synopsis and description are identical to that of 'rgetval_hist.'
rgetval_ascii
Retrieve the value of an ASCII point parameter.
This function's synopsis and description are identical to that of 'rgetval_hist.'
rgetval_hist
Retrieve the value of a history point parameter.
314 www.honeywell.com
NETWORK API FUNCTION REFERENCE
C Synopsis
int rgetval_numb
(
char* server,
int num_points,
rgetval_numb_data* getval_numb_data
);
int rgetval_ascii
(
char* server,
int num_points,
rgetval_ascii_data* getval_ascii_data
);
int rgetval_hist
(
char* server,
int num_points,
rgetval_hist_data* getval_hist_data
);
VB Synopsis
rgetval_numb(ByVal server As String,
ByVal num_points As Integer,
getval_numb_data() As rgetval_numb_data_str)
As Integer
rgetval_ascii(ByVal server As String,
ByVal num_points As Integer,
getval_ascii_data() As rgetval_ascii_data_str)
As Integer
rgetval_hist(ByVal server As String,
ByVal num_points As Integer,
getval_hist_data() As rgetval_hist_data_str)
As Integer
Arguments
Argument Description
server (in) Name of server that the database resides on
num_points (in) The number of points passed to rgetval_xxxx in the getval_xxxx_data argument
getval_xxxx_data (in/out) Pointer to a series of rgetval_xxxx_data structures (one for each point)
Description
This function is provided for backwards compatibility. It cannot be used to access point information for points
on Process Controllers. This function can only access points in the range: 1 <= point number <=65,000.
The rhsc_param_values_2 function should be used instead.
This function call enables access to point parameter values. The three types of parameters (numerical, ASCII
and history) are accessed using the corresponding function variations. The point parameters to be accessed are
referenced in the rgetval_numb_data, rgetval_ascii_data and rgetval_hist_data structures (see below). The
functions accept an array of structures, thus providing access to multiple point parameter values with one call.
The structure of rgetval_numb_data is defined in nif_types.h. This structure and its members are defined as
follows:
315
NETWORK API FUNCTION REFERENCE
The structure of rgetval_ascii_data is defined in nif_types.h. This structure and its members are defined as
follows:
The structure of the rgetval_hist_data structure is defined in nif_types.h. This structure and its members are
defined as follows:
Note that a successful return status from the rgetval call indicates that no network errors were encountered (that
is, the request was received, processed and responded to). The status field in each call structure must still be
checked on return to determine the result of the individual remote calls.
The program using these function calls must ensure that the size of the network packets generated does not
exceed the maximum packet size permitted on the network. This requirement can be met by adhering to the
following guideline:
(12 * number of points) + sum of all string value lengths in bytes <4000
Diagnostics
See “Diagnostics for Network API functions” on page 332.
See also
“rhsc_param_values_2” on page 304
“rhsc_param_value_puts_2” on page 301
rgetpntval
Get the numeric parameter value.
This function's synopsis and description are identical to that of 'rgetpntval_ascii.'
rgetpntval_ascii
Get the ASCII parameter value.
VB Synopsis
rgetpntval(ByVal server As String,
ByVal point As String,
316 www.honeywell.com
NETWORK API FUNCTION REFERENCE
Arguments
Argument Description
server (in) Name of server that the database resides on
point (in) Name of point
param (in) point parameter number
value (out) Value of point parameter returned by function
length (in) Maximum length of the string returned by rgetpntval_ascii
Description
This function is provided for backwards compatibility. It cannot be used to access point information for points
on Process Controllers. This function can only access points in the range: 1 <= point number <=65,000.
The rhsc_param_values_2 function should be used instead.
RGETPNTVAL and RGETPNTVAL_ASCII provide VB interfaces to request a single parameter value that has
the data types Single and String respectively. These functions can only be used to read one parameter value at a
time. A function return of 0 is given if the parameter value was successfully read; else an error code is returned.
Diagnostics
See “Diagnostics for Network API functions” on page 332.
rhsc_param_hist_dates
Attention
rhsc_param_hist_dates is deprecated and may be removed in a future release. It is provided compatibility purposes
only. When used with an Experion server rhsc_param_hist_dates will only be able to access points in the range:
1<= point number <= 65,000. The replacement function rhsc_param_hist_dates_2 should be used instead.
rhsc_param_hist_offsets
Attention
rhsc_param_hist_offsets is deprecated and may be removed in a future release. It is provided compatibility
purposes only. When used with an Experion server rhsc_param_hist_offsets will only be able to access points in
the range: 1<= point number <= 65,000. The replacement function rhsc_param_hist_offsets_2 should be used
instead.
C/C++ Synopsis
int rhsc_param_hist_dates
(
char* server,
317
NETWORK API FUNCTION REFERENCE
int num_gethsts,
rgethstpar_date_data* gethstpar_date_data
);
int rhsc_param_hist_offsets
(
char* server,
int num_gethsts,
rgethstpar_ofst_data* gethstpar_ofst_data
);
VB Synopsis
rhsc_param_hist_dates(ByVal server As String,
num_requests As Long,
gethstpar_date_data_array()
As gethstpar_date_data) As Long
rhsc_param_hist_offsets(ByVal server As String,
num_requests As Long,
gethstpar_ofst_data_array()
As gethstpar_ofst_data) As Long
Arguments
Argument Description
server (in) Name of server that the database resides on
num_requests (in) The number of history requests
gethstpar_xxxx_data (in/out) Pointer to an array of rgethstpar_xxxx_data structures (one array element for each
request)
Description
Use this function to retrieve history values for points. The two types of history (based on time or offset) are
retrieved using the corresponding function variation. History will be retrieved from a specified time or offset
going backwards in time. The history values to be accessed are referenced by the rgethst_date_data and
rgethst_ofst_data structures (see below). The functions accept an array of these structures, thus providing access
to multiple point history values with one function call.
Note that a successful return status from the rgethst call indicates that no network errors were encountered (that
is, the request was received, processed and responded to). The status field in each call structure needs to be
verified on return to determine the result of the individual remote calls.
The structure of the rgethst_date_data structure is defined in nif_types.h. This structure and its members are
defined as follows:
uint2 hist_type (in) Defines the type of history to retrieve, this will be one of the standard server history
types. Namely using one of the following:
HST_1MIN, HST_6MIN, HST_1HOUR, HST_8HOUR, HST_24HOUR, HST_5SECF,
HST_1HOURE, HST_8HOURE, HST_24HOURE
uint4 hist_start_date (in) Start date of history to receive in Julian days (number of days since 1st January 1981).
ureal4 hist_start_time (in) Start time of history to retrieve in seconds since midnight.
uint2 num_hist (in) Number of history values per point to be retrieved.
uint2 num_points (in) Number of points to be processed. MAXIMUM value allowed is 20.
uint2* point_type_nums (in) Array (of dimension num_points) containing the point type/numbers of the point
history values to retrieve.
uint2* point_params (in) Array of (dimension num_points) containing the parameter numbers of the history
values to retrive.
uchar* archive path This member is no longer in use and is only retained for backwards compatibility. Instead,
pass a zero length string.
318 www.honeywell.com
NETWORK API FUNCTION REFERENCE
real4* hist_values (out) Array (of dimension num_points * num_hist) to provide storage for the returned
history values.
uint2 gethst_status (out) Return value of the actual remote gethst_date call.
The structure of the rgethst_ofst_data structure is defined in nif_types.h. This structure and its members are
defined as follows:
uint2 hist_type (in) Defines the type of history to retrieve, this will be one of the standard server history
types. Namely using one of the following defines:
HST_1MIN, HST_6MIN, HST_1HOUR, HST_8HOUR, HST_24HOUR, HST_5SECF,
HST_1HOURE, HST_8HOURE, HST_24HOURE
uint4 hist_offset (in) Offset from latest history value in history intervals where offset=1 is the most recent
history value).
uint2 num_hist (in) Number of history values per point to be retrieved.
uint2 num_points (in) Number of points to be processed. MAXIMUM value allowed is 20.
uint2* point_type_nums (in) Array (of dimension num_points) containing the point type/numbers of the point
history values to retrieve.
uint2* point_params (in) Array of (dimension num_points) containing the parameter numbers of the history
values to retrieve.
uchar* archive path This member is no longer in use and is only retained for backwards compatibility. Instead,
pass a zero length string.
real4* hist_values (out) Array (of dimension num_points * num_hist) to provide storage for the returned
history values.
uint2 gethst_status (out) Return value of the actual remote gethst_date call.
The program using this function call must ensure that the size of the network packets generated does not exceed
the maximum packet size permitted on the network. To meet this requirement, adhere to the following
guideline:
• For request packets for rhsc_param_hist_dates:
(15 * number of history requests) + (2 * number of points requested) + string lengths of
archive paths < 4000.
• For request packets for rhsc_param_hist_offsets:
(11 * number of history requests) + (2 * number of points requested) + string lengths of
archive paths < 4000.
• For response packets:
(4 * number of history requests) + (4 * (For each history request the sum of (num_hist *
num_points)))
Diagnostics
See “Diagnostics for Network API functions” on page 332.
rhsc_param_value_puts
Attention
rhsc_param_value_puts is deprecated and may be removed in a future release. It is provided compatibility purposes
only. When used with an Experion serverrhsc_param_value_puts will only be able to access points in the range:
1<= point number <= 65,000. The replacement function rhsc_param_value_puts_2 should be used instead.
319
NETWORK API FUNCTION REFERENCE
C Synopsis
int rhsc_param_value_puts
(
char* szHostname,
int cprmvd,
PARAM_VALUE_DATA* rgprmvd
);
VB Synopsis
rhsc_param_value_puts (ByVal hostname As String,
ByVal num_requests As Long,
Param_value_data_array ()
As param_value_data) As Long
Arguments
Argument Description
szHostname (in) Name of server that the database resides on
cprmvd (in) The number of controls to parameters requested
rgprmvd (in/out) Pointer to a series of PARAM_VALUE_DATA structures (one array element for
each point)
Description
The structure of the PARAM_VALUE_DATA structure is defined in nif_types.h. This structure and its
members are defined as follows:
RHSC_PARM_VALUE_PUTS writes a list of point parameter values to the specified remote server and
performs the necessary control. A function return of 0 is given if the point parameter values are successfully
controlled, otherwise, an error code is returned.
You can write a list of parameter values with different types using a single request. The value is placed into a
union (of type PARvalue). Before storing the value to be written to a point parameter in the
PARAM_VALUE_DATA structure, you must allocate sufficient memory for the union. You must free this
memory before exiting your network application.
Although this is a list based function, there is no implication that it should be used as a sequential write
function. If any individual put fails, the function will not prevent the remaining writes from occurring. The
function will instead continue to write values to the remaining point parameters in the list.
Be careful when using rhsc_param_value_puts() and rhsc_param_value_put_bynames() with more than one
point/parameter pair. Each put causes a control to be executed on the server and each control takes a small
amount of time. If more than one pair is put, the total time for each of these controls may exceed the default
TCP/IP timeout. This will cause the Network API to report the error RCV_TIMEOUT, even though all puts
may have been successful. In addition, the Network API will be unavailable until the list of puts has been
processed. This could cause subsequent calls to the network API to fail until the list is processed.
To simplify the handling of enumerations, two data types have been included for use with this function only.
The data types are DT_ENUM_ORD, and DT_ENUM_STR. When writing a value to an enumeration point
parameter, supply the ordinal part of the enumeration only and use the DT_ENUM_ORD data type.
320 www.honeywell.com
NETWORK API FUNCTION REFERENCE
Alternatively, if you don't know the ordinal value, supply only the text component of the enumeration and use
the DT_ENUM_STR data type. If the DT_ENUM data type is specified, only the ordinal value is used by this
function (similar to DT_ENUM_ORD).
A successful return status from the rhsc_param_value_puts call indicates that no network errors were
encountered (that is, the request was received, processed, and responded to).
If the returned value is NADS_PARTIAL_FUNC_FAIL, then at least one request (and possibly all requests)
failed. The status field of each array element should be checked to find which request failed. For each array
element, a value of CTLOK (See “Diagnostics for Network API functions” on page 332) or 0 in the status field
indicates that the control was successful.
The program using this function call must ensure that the size of the network packets generated do not exceed
the maximum packet size permitted on the network.
Due to the ability to control a list of parameters of mixed data type, it is difficult to give generic limits. To meet
the program requirement not to exceed the maximum packet size permitted, adhere to the following guidelines
given for a number of specific cases:
• For request packets when writing DT_INT2 data only:
(12 * number of points parameters) < 4000
• For request packets when writing DT_INT4 data only:
(14 * number of points parameters) < 4000
• For request packets when writing DT_REAL data only:
(14 * number of points parameters) < 4000
• For request packets when writing DT_DBLE data only:
(18 * number of points parameters) < 4000
• For request packets when writing DT_CHAR data only:
(11 * number of points parameters) + sum of string lengths of value character strings in bytes
< 4000
• For request packets when writing DT_ENUM_ORD data only:
(11 * number of points parameters) < 4000
• For request packets when writing DT_ENUM_STR data only:
(11 * number of points parameters) + sum of string lengths of value enumeration strings in
bytes < 4000
• For ALL reply packets:
(4 * number of point parameters) < 4000
Example
Control pntana1's SP value to 42.0 and change its DESC to say 'Funky description.'
int status;
int i;
POINT_NUMBER_DATA rgpntnd[] = {{'pntana1'}};
PARAM_NUMBER_DATA rgprmnd[] = {{0, 'SP'},{0, 'DESC'}};
PARAM_VALUE_DATA rgprmvd[cprmvd];
rgprmnd[0].nPnt = rgpntnd[0].nPnt;
rgprmnd[1].nPnt = rgpntnd[0].nPnt;
status = rhsc_param_numbers("Server1", cprmnd, rgprmnd);
/* Set the point number, parameter number and offset for the point parameter. Allocate space,
321
NETWORK API FUNCTION REFERENCE
/* Set the point number, parameter number and offset for the point parameter. Allocate space,
assign a value, and set the type for pntana1.DESC */
rgprmvd[1].nPnt = rgprmnd[1].nPnt;
rgprmvd[1].nPrm = rgprmnd[1].nPrm;
rgprmvd[1].nPrmoffset = 1 /* Set
parameter offset to default value*/
rgprmvd[1].pupvValue =
(PARvalue *)malloc(strlen('Funky description') + 1); strcpy(rgprmvd[1].pupvValue->text, 'Funky
description');
rgprmvd[1].nType = DT_CHAR;
Diagnostics
See “Diagnostics for Network API functions” on page 332.
See also
“rhsc_param_values” on page 322
“rhsc_param_value_put_bynames” on page 297
rhsc_param_values
Attention
rhsc_param_values is deprecated and may be removed in a future release. It is provided compatibility purposes only.
When used with an Experion server rhsc_param_values will only be able to access points in the range: 1<= point
number <= 65,000. The replacement function rhsc_param_values_2 should be used instead.
C Synopsis
int rhsc_param_values
(
char* szHostname,
int nPeriod,
int cprmvd,
PARAM_VALUE_DATA* rgprmvd
);
VB Synopsis
rhsc_param_values (ByVal hostname As String,
ByVal period as Long,
322 www.honeywell.com
NETWORK API FUNCTION REFERENCE
Arguments
Argument Description
szHostname (in) Name of server that the database resides on.
nPeriod (in) subscription period in milliseconds for the point parameters. Use the constant
NADS_READ_CACHE if subscription is not required. If the value is in the Experion
cache, then that value will be returned. Otherwise the controller will be polled for the latest
value. Use the constant NADS_READ_DEVICE if you want to force Experion to re-poll
the controller. The subscription period will not be applied to standard point types.
cprmvd (in) The number of parameter values requested.
rgprmvd (in/out) Pointer to an array of PARAM_VALUE_DATA structures (one array element for
each request).
Description
The structure of the PARAM_VALUE_DATA structure is defined in nif_types.h. This structure and its
members are defined as follows:
If your system uses dynamic scanning, rhsc_param_values calls from the Network API do not trigger dynamic
scanning.
RHSC_PARM_VALUES requests a list of point parameter values from the specified remote server. A function
return of 0 is given if the parameter values were successfully read else an error code is returned.
You can read a list of parameter values with different types using a single request. Each point parameter value is
placed into a union (of type PARvalue). Before making the request, you must allocate sufficient memory for
each value union. You must free this memory before exiting your Network application.
A successful return status from the rhsc_param_values call indicates that no network errors were encountered
(that is, the request was received, processed, and responded to). If the returned value is
NADS_PARTIAL_FUNC_FAIL, then at least one request (and possibly all requests) failed. The status field of
each array element should be checked to find which request failed.
The program using this function call must ensure that the size of the network packets generated do not exceed
the maximum packet size permitted on the network.
Due to the ability to acquire a list of parameters of mixed data type, it is difficult to give generic limits. To meet
the program requirement not to exceed the maximum packet size permitted, adhere to the following guidelines
given for a number of specific cases:
• For ALL request packets:
(8 * number of point parameters) < 4000
• For response packets when reading DT_INT2 data only:
(8 * number of points parameters) < 4000
323
NETWORK API FUNCTION REFERENCE
Example
Read the value of pntana1.SP and pntana1.DESC.
int status;
int i;
POINT_NUMBER_DATA rgpntnd[] = {{'pntana1'}};
PARAM_NUMBER_DATA rgprmnd[] = {{0, 'SP'}, {0, 'DESC'}};
PARAM_VALUE_DATA rgprmvd[cprmvd];
/*
ALLOCATING MEMORY:
Sufficient memory must be allocated for each value union. If the
value type is not known, allocate memory for the largest possible
size of a PARvalue union. See below for an example of how to allocate
this memory.
If the data type is known, then allocate the exact amount of memory
to save space.
For example for DT_REAL values:
rgprmvd[0].pupvValue = (PARvalue *) malloc(sizeof(DT_REAL));
*/
for (i=0; i<cprmvd; i++)
{
rgprmvd[i].pupvValue = (PARvalue *)malloc(sizeof(PARvalue);
}
status = rhsc_param_values('server1',
NADS_READ_CACHE, cprmvd, rgprmvd);
switch (status)
{
case 0:
printf('rhsc_param_values successful\n');
for (i=0; i<cprmvd; i++)
{
switch (rgprmvd[i].nType)
324 www.honeywell.com
NETWORK API FUNCTION REFERENCE
{
case DT_CHAR:
printf('%s.%s has the value %s\n',
rgpntnd[0].szPntName,
rgprmnd[i].szPrmName,
rgprmvd[i].pupvValue->text);
break;
case DT_INT2:
printf('%s.%s has the value %d\n',
rgpntnd[0].szPntName,
rgprmnd[i].szPrmName,
rgprmvd[i].pupvValue->int2);
break;
case DT_INT4:
printf('%s.%s has the value %d\n',
rgpntnd[0].szPntName,
rgprmnd[i].szPrmName,
rgprmvd[i].pupvValue->int4);
break;
case DT_REAL:
printf('%s.%s has the value %f\n',
rgpntnd[0].szPntName,
rgprmnd[i].szPrmName,
rgprmvd[i].pupvValue->real);
break;
case DT_DBLE:
printf('%s.%s has the value %f\n',
rgpntnd[0].szPntName,
rgprmnd[i].szPrmName,
rgprmvd[i].pupvValue->dble);
break;
case DT_ENUM:
printf('%s.%s has the ordinal value %d and enum string %s\n',
rgpntnd[0].szPntName,
rgprmnd[i].szPrmName,
rgprmvd[i].pupvValue->en.ord,
rgprmvd[i].pupvValue->en.text);
break;
default:
printf('Illegal type found\n');
break;
}
}
break;
case NADS_PARTIAL_FUNC_FAIL:
printf('rhsc_param_values partially failed\n');
/* Check fStatus flags to find out which ones failed. */
break;
default:
printf('rhsc_param_values failed (c_geterrno() = 0x%x)\n', status);
break;
}
Diagnostics
See “Diagnostics for Network API functions” on page 332.
See also
“rhsc_param_value_puts” on page 319
“rhsc_param_value_put_bynames” on page 297
325
NETWORK API FUNCTION REFERENCE
rhsc_param_numbers
Attention
rhsc_param_numbers is deprecated and may be removed in a future release. It is provided compatibility purposes
only. When used with an Experion server rhsc_param_numbers will only be able to access points in the range: 1<=
point number <= 65,000. The replacement function rhsc_param_numbers_2 should be used instead.
C Synopsis
int rhsc_param_numbers(char* szHostname,
int cprmnd,
PARAM_NUMBER_DATA* rgprmnd);
VB Synopsis
rhsc_param_numbers(ByVal hostname As String,
ByVal num_requests As Long,
param_number_data_array() As
param_number_data) As Long
Arguments
Argument Description
szHostname (in) Name of server on which the database resides
cprmnd (in) The number of parameter name resolutions requested
rgprmnd (in/out) Pointer to an array of PARAM_NUMBER_DATA structures (one for each point
parameter)
Description
The structure of the PARAM_NUMBER_DATA structure is defined in nif_types.h. This structure and its
members are defined as follows:
RHSC_PARAM_NUMBERS converts a list of point parameter names to their equivalent parameter numbers for
a specified remote server.
A successful return status from the rhsc_param_numbers call indicates that no network errors were encountered
(that is, the request was received, processed, and responded to). If the returned value is
NADS_PARTIAL_FUNC_FAIL, then at least one request (and possibly all requests) failed. The status field of
each array element should be checked to find which request failed.
The program using this function call must ensure that the size of the network packets generated do not exceed
the maximum packet size permitted on the network. To meet this requirement, adhere to the following
guidelines:
• For request packets:
(4 * number of points) + sum of string lengths of point names in bytes < 4000
326 www.honeywell.com
NETWORK API FUNCTION REFERENCE
Example
Resolve the parameter names 'pntana1.SP' and 'pntana1.DESC.'
int status;
int i;
POINT_NUMBER_DATA rgpntnd[] = {{'pntana1'}};
PARAM_NUMBER_DATA rgprmnd[] = {{0, 'SP'},{0, 'DESC'}};
Diagnostics
See “Diagnostics for Network API functions” on page 332.
See also
“rhsc_point_numbers” on page 327
rhsc_point_numbers
Attention
rhsc_point_numbers is deprecated and may be removed in a future release. It is provided compatibility purposes
only. When used with an Experion server rhsc_point_numbers will only be able to access points in the range: 1<=
point number <= 65,000. The replacement function rhsc_point_numbers_2 should be used instead.
C/C++ Synopsis
int rhsc_point_numbers
(
char* szHostname,
int cpntnd,
327
NETWORK API FUNCTION REFERENCE
POINT_NUMBER_DATA* rgpntnd
);
VB Synopsis
rhsc_point_numbers(ByVal hostname As String,
ByVal num_requests As Long,
POINT_NUMBER_DATA_array()
As POINT_NUMBER_DATA) As Long
Arguments
Argument Description
szHostname (in) Name of server that the database resides on
cpntnd (in) The number of point name resolutions requested
rgpntnd (in/out) Pointer to a series of POINT_NUMBER_DATA structures (one array element for
each request)
Description
The structure of the POINT_NUMBER_DATA structure is defined in nif_types.h. This structure and its
members are defined as follows:
RHSC_POINT_NUMBERS converts a list of point names to their equivalent point numbers for a specified
remote server.
A successful return status from the rhsc_point_numbers call indicates that no network errors were encountered
(that is, the request was received, processed, and responded to). If the returned value is
NADS_PARTIAL_FUNC_FAIL, then at least one request (and possibly all requests) failed. The status field of
each array element should be checked to find which request failed.
The program using this function call must ensure that the size of the network packets generated do not exceed
the maximum packet size permitted on the network. To meet this program requirement, adhere to the following
guidelines:
• For request packets:
(2 * number of points) + sum of string lengths of point names in bytes < 4000
• For response packets:
(6 * number of points) < 4000
Example
Resolve the point names 'pntana1' and 'pntana2'.
int status;
int i;
POINT_NUMBER_DATA rgpntnd[] = {{'pntana1'},{'pntana2'}};
#define cpntnd sizeof(rgpntnd)/sizeof(POINT_NUMBER_DATA)
switch (status)
{
case 0:
printf('rhsc_point_numbers successful\n');
for (i=0; i<cpntnd; i++)
{
328 www.honeywell.com
NETWORK API FUNCTION REFERENCE
Diagnostics
See “Diagnostics for Network API functions” on page 332.
rputpntval
Set the numeric parameter value.
This function's synopsis and description are identical to that of 'rputpntval_ascii.'
rputpntval_ascii
Set the ASCII parameter value.
VB Synopsis
rputpntval(ByVal server As String,
ByVal point As String,
ByVal param As Integer,
value As Single) As Integer
rputpntval_ascii(ByVal server As String,
ByVal point As String,
ByVal param As Integer,
value As String) As Integer
Arguments
Argument Description
server (in) Name of server that the database resides on
point (in) Name of point
param (in) Point parameter number
value (out) Value of point parameter returned by function
Description
This function is provided for backwards compatibility. It cannot be used to access point information for points
on Process Controllers. This function can only access points in the range: 1 <= point number <=65,000.
Diagnostics
See “Diagnostics for Network API functions” on page 332.
rputval_hist
Store history values.
This function's synopsis and description are identical to that of 'rputval_ascii.'
329
NETWORK API FUNCTION REFERENCE
rputval_numb
Store the value of numeric point parameters.
This function's synopsis and description are identical to that of 'rputval_ascii.'
rputval_ascii
Store the value of ASCII point parameters.
C/C++ Synopsis
int rputval_numb
(
char* server,
int num_points,
rputval_numb_data* putval_numb_data
);
int rputval_ascii
(
char* server,
int num_points,
rputval_ascii_data* putval_ascii_data
);
int rputval_hist
(
char* server,
int num_points,
rputval_hist_data* putval_hist_data
);
VB Synopsis
rputval_numb(ByVal server As String,
ByVal num_points As Integer,
putval_numb_data() As rputval_numb_data_str)
As Integer
rputval_ascii(ByVal server As String,
ByVal num_points As Integer,
putval_ascii_data() As rputval_ascii_data_str)
As Integer
rputval_hist (ByVal server As String,
ByVal num_points As Integer
putval_hist_data() As rputval_hist_str)
As Integer
Arguments
Argument Description
server (in) Name of server that the database resides on
num_points (in) The number of points passed to rputval_xxxx in the putval_xxxx_data argument
putval_xxxx_data (in/out) Pointer to a series of rputval_xxxx_data structures (one for each point)
Description
This function is provided for backwards compatibility. It cannot be used to access point information for points
on Process Controllers. This function can only access points in the range: 1 <= point number <=65,000.
The rhsc_param_value_puts_2 function should be used instead.
This function call enables access to point parameter values. The three types of parameters (numerical, ASCII,
and history) are accessed using the corresponding function variations. The point parameters to be accessed are
referenced by the members of the rputval_numb_data, rputval_ascii_data, and rputval_hist_data structures (see
330 www.honeywell.com
NETWORK API FUNCTION REFERENCE
below). The functions accept an array of structures, thus providing access to multiple point parameter values
with one call.
The structure of the rputval_numb_data structure is defined in nif_types.h. This structure and its members are
defined as follows:
The structure of the rputval_ascii_data structure is defined in nif_types.h. This structure and its members is
defined as follows:
The structure of the rputval_hist_data structure is defined in nif_types.h. This structure and its members is
defined as follows:
Note that a successful return status from the rputval call indicates that no network error was encountered (that
is, the request was received, processed, and responded to). The status field in each call structure needs to be
verified on return to determine the result of the individual remote calls.
The program using these function calls must ensure that the size of the network packets generated do not exceed
the maximum packet size permitted on the network. This requirement can be met by adhering to the following
guideline:
(12 * number of points) + sum of all string value lengths in bytes <4000
Diagnostics
See “Diagnostics for Network API functions” on page 332.
331
NETWORK API FUNCTION REFERENCE
332 www.honeywell.com
NETWORK API FUNCTION REFERENCE
333
NETWORK API FUNCTION REFERENCE
334 www.honeywell.com
Using Experion's Automation Objects
This chapter provides an overview of issues applicable to developing applications that use Experion's
Automation Object Models.
Experion includes the following object models, each of which represents a particular aspect of the system.
Related topics
“Server Automation Object Model” on page 336
“HMIWeb Object Model” on page 337
“Station Scripting Objects” on page 338
“Station Object Model” on page 341
335
USING EXPERION'S AUTOMATION OBJECTS
Notes
• In Visual Basic, choose Project > References, and select HSC Server Automation Model 1.0 from the list.
• The Server object is the only object that can be directly created with the Visual Basic CreateObject function
or the 'New' keyword.
• You must only create one Server object and cache its existence, although you can make copies of it.
• The Server object can only be created on a server if the database is loaded.
• An application that uses the Server Automation model can be run as:
– An application with an allocated LRN. This is subject to the same security measures as any other
application.
– A utility on the server. This requires physical access to the server.
Applicable documentation
See the Server Scripting Reference.
Example
This example shows how to create the Server object.
Set objServer = CreateObject("HSCAutomationServer.Server")
336 www.honeywell.com
USING EXPERION'S AUTOMATION OBJECTS
Notes
• The Application object is the only object that can be directly created with the Visual Basic CreateObject
function or the 'New' keyword.
• DSP displays are represented by the “Station Object Model” on page 341.
Applicable documentation
See the HMIWeb Display Building Guide.
Example
This example shows how to create the top-level object (Application) of the HMIWeb Object Model.
Set objStationApp = CreateObject("Station.Application")
Once created, the application can then control Station through the object variable objStationApp. For example,
to instruct Station to call up a display called 'CompressorStatus', the application would use the following code.
objStationApp.CurrentPage = CompressorStatus
337
USING EXPERION'S AUTOMATION OBJECTS
Notes
• The sample Visual Basic project for an SSO.vbp provides the framework for implementing an SSO. (The
project and associated components are zipped into SSO_Sample.zip. This file is located in Station\Samples.)
• Every SSO must implement a detach method. See 'Implementing a Detach method.'
Applicable documentation
See the HMIWeb Display Building Guide.
Related topics
“Implementing a Detach method” on page 340
Creating an SSO
To create an SSO
1 Open the sample SSO project in Visual Basic.
2 Change the Project name to something appropriate, which is unique.
When you change the name, the ProgID also changes (The ProgID is of the form ProjectName.ClassName.)
For example, if you change the project name to OperStations, the ProgId will change to
OperStations.clsSSO.
3 Write your scripts.
The sample SSO contains some simple code that adds entries to the Dictionary object, and displays a
message box when Station connects to the server.
4 Compile the SSO by choosing File > Make SSO.dll. If there are any errors, you must fix them before
moving onto the next step.
5 For each Station that needs the SSO:
a Copy the SSO to the Station computer and register it. See “Registering an SSO” on page 339. (You can
skip this step if you compiled the SSO on the computer because it automatically registers itself if the
compilation is successful.)
b Choose Station > Connection Properties.
The Connection Properties dialog box opens.
c Click the Scripting tab.
d Click Add to add a new entry in the Station scripting objects list and type the SSO's ProgID after
'ProgID ='.
338 www.honeywell.com
USING EXPERION'S AUTOMATION OBJECTS
Registering an SSO
You must register an SSO on each Station computer that needs to use it. (Unless you have compiled it on the
computer.)
To register an SSO
1 Copy the SSO to the computer.
2 Open a Command Prompt window.
3 Type regsvr32 SsoName .dll , where SsoName is the name of the SSO (including its path).
339
USING EXPERION'S AUTOMATION OBJECTS
Related topics
“Station Scripting Objects” on page 338
340 www.honeywell.com
USING EXPERION'S AUTOMATION OBJECTS
Notes
• Except for DSP displays and earlier versions of Station, the Station Object Model has been superseded by
the “HMIWeb Object Model” on page 337.
• In order to control DSP displays, you must first create Station using the Application object of the “HMIWeb
Object Model” on page 337 (see “HMIWeb Object Model” on page 337). After creating the Application
object, you can then control DSP displays using the Station Object Model.
Applicable documentation
See the Display Building Guide.
Example
This example shows how to call up the Alarm Summary, a DSP display whose display number is 5. (The
variable, objStationApp, represents Station, which has already been created using the Application object of the
HMIWeb Object Model.)
objStationApp.CurrentPage = 5
341
USING EXPERION'S AUTOMATION OBJECTS
342 www.honeywell.com
Glossary
accumulator point A point type used to represent counters. Information contained in the accumulator point
can include: the raw value, a process value, a rollover value, a scale factor, and a meter
factor.
acronym An acronym is a text string that is used to represent a state or value of a point in a
display. From an operator's point of view, it much easier to understand the significance
of an acronym such as 'Stopped', compared with an abstract value such as '0'.
action algorithm One of two types of algorithm you can assign to a point in order to perform additional
processing to change point parameter values. An action algorithm performs an action
when the value of the PV changes. Contrast with PV algorithm.
ActiveX COM-based technology for creating objects and components.
ActiveX component An ActiveX component is a type of program designed to be called up from other
applications, rather than being executed independently. An example of an ActiveX
component is a custom dialog box, which works in conjunction with scripts, to
facilitate operator input into Station.
Activity A series of actions (with a start time and an end time) that occur in a plant. The term
provides a market-neutral entity that can represent products such as batches, movement
automation, and procedural operations.
Activity Entity An object from which an activity can be created (e.g., RCM or SCM for batch/
procedure activities). Also known as Recipe.
ADO Active Data Object.
alarm An indication (visual and/or audible) that alerts an operator at a Station of an abnormal
or critical condition. Each alarm has a type and a priority. Alarms can be assigned
either to individual points or for system-wide conditions, such as a controller
communications failure. Alarms can be viewed on a Station display and included in
reports. Experion classifies alarms into the following types:
• PV Limit
• Unreasonable High and Unreasonable Low
• Control Failure
• External Change
alarm/event journal A file that records all alarms and events. It is accessed to generate reports and can also
be archived to off-line media.
alarm priority One of four levels of severity specified for the alarm. The alarm priorities from least to
most severe are:
• Journal
• Low
343
GLOSSARY
• High
• Urgent
344 www.honeywell.com
GLOSSARY
controller A device that is used to control and monitor one or more processes in field equipment.
Controllers include Programmable Logic Controllers (PLCs), loop controllers, bar code
readers, and scientific analyzers.
Controllers can be defined using the Quick Builder tool. Some controllers can be
configured using Station displays.
database controller See User Scan Task controller.
database point Any point that has one or more parameters with database addresses.
DCD Data Carry Detect
DCS Digital Control System
DDE Dynamic Data Exchange
default The value that an application automatically selects if the user does not explicitly select
another value.
deleted items In Quick Builder, an item that has been flagged for deletion from the server database
and appears in the Deleted grouping. When a download is performed, the item is
deleted from both the server database and the Quick Builder project database.
demand scan A one-time-only scan of a point parameter that can be requested either by an operator, a
report, or an application.
DHCP Dynamic Host Configuration Protocol
display Station uses displays to present Experion information to operators in a manner that they
can understand. The style and complexity of displays varies according to the type of
information being presented.
Displays are created in Display Builder.
Display Builder The Honeywell tool for building customized graphical displays representing process
data.
display object A display object is a graphic element, such as an alphanumeric, a pushbutton or a
rectangle, in a display.
Display objects that represent point information (such as an alphanumeric) or issue
commands (such as a pushbutton) are called 'dynamic' display objects.
Distributed System An option that enables multiple Experion servers to share data, alarms, and history
Architecture (DSA) without the need for duplicate configuration on any server.
DNS Domain Name System
DSR Data Signal Ready
DTE Data Terminal Equipment
DTR Data Terminal Ready
dual-bit status A status point that reads two bits. Status points can read one, two or three bits.
point
EIM Ethernet Interface Module
ELPM Ethernet Loop Processor Module
EMI Electromagnetic Interference
345
GLOSSARY
event A significant change in the status of an element of the system such as a point or piece of
hardware. Some events have a low, high, or urgent priority, in which case they are
further classified as alarms. Events can be viewed in Station and included in reports.
Within the context of scripts (created in Display Builder and used in Station), an event
is a change in system status or an operator-initiated action that causes a script to run.
Event Archiving Event Archiving allows you to archive events to disk or tape, where they may be
retrieved if needed.
EXE Executable.
exception scan A scan that takes place only when a change occurs at a controller address configured
for a point parameter. Some controllers can notify the server when a change occurs
within the controller. The server uses exception polling to interrogate the controller for
these changes. This type of scan can be used to reduce the scanning load when a fast
periodic scan is not required.
export In relation to Station displays, this refers to the process of registering a display with the
server so that it can be called up in Station.
In relation to Quick Builder, this refers to the process of converting the configuration
data in a project file into text files for use with other applications.
Extended history A type of history collection that provides snapshots of a point at a designated time
interval that can be:
• 1-hour snapshots
• 8-hour snapshots
• 24-hour snapshots
Fast history An type of history that provides a 5-second snapshot history for points.
field address The address within the controller that contains stored information from a field device
being monitored by the controller.
free format report An optional report type that enables users to generate their own report.
FTP File Transfer Protocol
group A group of up to eight related points whose main parameter values appear in the same
group display. Sometimes called 'operating group'.
history Point values stored to enable tracking and observation of long-term trends. Analog,
status, and accumulator point PVs can be defined to have history collected for them.
Three types of history collection are available:
• Standard
• Extended
• Fast
history gate A status point parameter that is used to control the collection of history for an analog or
status point. The history is only collected if the gate state value of the nominated
parameter is in the nominated state.
host server In a DSA system, the server on which a remote point's definition is stored and from
which alarms form the point originate.
HTTP Hypertext Transfer Protocol
IDE Integrated Development Environment.
346 www.honeywell.com
GLOSSARY
347
GLOSSARY
OPC OPC stands for OLE (Object Linking & Embedding) for Process Control. It is a set of
standards to facilitate interoperability between applications within the Process Control
Industry. These include automation/control applications, field systems/devices or
business/office applications.
OPC specifies a standard interface to be used between two types of applications called
OPC clients and OPC servers. An OPC server is an application which collects data,
generally directly from a physical device, and makes it accessible through the OPC
interface. An OPC client requests and uses the data provided by an OPC Server. By
having a standard interface OPC clients and servers written by different vendors can
communicate.
Open Database A standard set of function calls for accessing data in a database. These calls include the
Connectivity facility to make SQL (Structured Query Language) queries on the database. To use
ODBC you must have support from the client application (for example, Microsoft
Access) which will generate the ODBC calls and from some database-specific software
called an ODBC driver.
operator ID A unique identification assigned to each operator. If Operator-Based security is
enabled, the operator must use this ID and a password to sign on to a Station.
operator password A character string (not echoed on screen) used with the operator ID to sign on to a
Station.
operator security See security level.
level
Operator-based Operator-based security comprises an operator ID and password, which must be entered
security at a Station in order to access Experion functions.
output A point parameter used to issue control values. The output (OP) is often related to the
mode (MD) parameter and can be changed by an operator only if the mode is manual.
parameter The different types of values accessed by points are known in Experion as 'point
parameters.'
Experion can store and manage multiple values in the one point. You can therefore use
a single point to monitor and control a complete loop.
The names of the parameters reflect their most common usage. They can, however, be
used to hold any controller values.
periodic scan A defined regular interval in which the server acquires information from the controller
and processes the value as a point parameter. The scan period must be defined in Quick
Builder for each point source parameter value.
PIN Plant Information Network
PLC Programmable logic controller
point A data structure in the server database, usually containing information about a field
entity. A point can contain one or more parameters.
point algorithm A prescribed set of well-defined rules used to enhance a point's functionality. The point
algorithm accomplishes this by operating on the point data either before or after normal
point processing.
There are two types of point algorithms, PV (processed every time the point parameter
is scanned) and Action (processed only when a point parameter value changes).
point detail display A display that shows the current point information. Each point has a Point Detail
display.
348 www.honeywell.com
GLOSSARY
primary server This is the PC that normally runs the database software, performs processing tasks, and
allocates resources to client PCs. If the primary server is unavailable, the secondary
server takes over until it is available again.
Process Controllers The term used to refer to all control hardware (chassis, power supply, Control
Processor, and ControlNet bridge) as a single entity in an Experion system.
Process software An umbrella term for Control Builder and other hybrid controller software.
process variable An actual value in a process: a temperature, flow, pressure, and so on. Process variables
may be sourced from another parameter and may also be calculated from two or more
measured or calculated variables using algorithms.
programmable A control and monitoring unit that connects to a field device and controls low-level
logic controller plant processes with very high-speed responses. A PLC usually has an internal program
(PLC) that scans the PLC input registers and sets the output registers to the values determined
by the program. When connected to the server, the input and output values stored in the
PLC registers can be referenced, and the server can read and write to these memory
addresses.
project In Quick Builder, a working database file that enables you to make changes to the
server database without affecting the configuration data that is currently being used to
run the system.
project view In Quick Builder, a window in which you can view, add, and modify any items in the
current project file.
property An attribute or characteristic of an object within the Station Automation object model.
For example, a display object has properties that define its height, width and color.
property tab In Quick Builder, a tab in the Project View window that displays information about the
currently selected item or items. Most of the information displayed can be modified.
PV Experion abbreviation for process variable.
PV algorithm One of two types of algorithm you can assign to a point in order to perform additional
processing to change point parameter values. A PV algorithm changes the value of the
point process value (PV) input only. Contrast with Action algorithm.
PV clamp For an analog point, a configuration that will immobilize the process value (PV) at 0%
if it falls below the entry low limit value or at 100% if it goes above the entry high limit
value.
PV period An amount of time specified for the scanning of the point process value (PV)
parameter. The PV period determines the frequency with which the scan will be
performed by the server. The server groups point addresses into scan packets by PV
period and controller.
Quick Builder Quick Builder is a graphical tool that is used to define the hardware items and some
points in a Experion system. Quick Builder can run either on an Experion server, on
another computer in your system, or on a laptop.
After defining hardware and points with Quick Builder, you download these definitions
from Quick Builder to the Experion server database.
RCM Recipe Control Module.
recipe A set of points used in a process. The Recipe Manager option enables point parameters
for sets of points to be downloaded with pre-configured working values. The individual
point parameters are the recipe 'ingredients.' Also known as Activity Entity.
recordset An ADO object which contains data organized in fields and records.
349
GLOSSARY
redundant server A second server used as a backup system. In a redundant server system the 'redundant'
server is actively linked to the 'primary' server. Active linking ensures that data in the
second server is constantly updated to mirror the primary server.
remote server A server that supplies data to a local server via either a local area network (LAN) or a
wide area network (WAN).
report Information collected by the server database that is formatted for viewing. There are
several pre-formatted reports, or the user can customize a report. Reports may be
generated on demand or at scheduled intervals. Reports can be printed or displayed on a
Station.
REX Request to exit.
RFI Radio Frequency Interference
RLSD Receive Line Signal Detect
RTS/CTS Request to send/clear to send
RTU See controller.
S88/S95 A set of standards and terminology for batch control. For more information about the
standard, go to www.isa.org.
SafeBrowse object A SafeBrowse object is a Web browser specifically designed for use with Station.
SafeBrowse includes appropriate security features that prevent users from displaying
unauthorized Web pages or other documents in Station.
scan The technique used to read data from a controller. Scans are conducted for point
parameters with source addresses (for example, PV, SP, OP, MD, An). Experion uses
demand, exception, and periodic scanning techniques.
scan packet A group of point parameter source addresses assembled by the server and used as the
basic unit of server data acquisition. The server groups points into scan packets based
on the controller address that they reference and the scan period defined.
scan period The time interval that specifies the frequency at which the Experion server reads input
values from the memory addresses of controllers. Scan periods are measured in
seconds; a scan period of 120 seconds means that the server scans the controller once
every 120 seconds.
scheduler A facility used to schedule the control of a point on either a periodic or once-only basis.
SCM Sequential Control Module.
script A script is a mini-program that performs a specific task. Scripts use the Station
Automation object model to control and interrogate Station and its displays.
security level Access to Experion functions is limited by the security level that has been assigned to
each operator. Experion has six security levels. An operator is assigned a security level
and may perform functions at or below the security level that has been assigned to that
operator.
server The computer on which the Experion database software runs.
Server software An umbrella term used to refer to the database software and server utilities installed on
the Experion server computer.
server Station A computer running both the Experion database (server) software and the Station
software.
350 www.honeywell.com
GLOSSARY
set point The desired value of a process variable. Set point is a point parameter, whose value may
be entered by the operator. The set point can be changed any number of times during a
single process. The set point is represented in engineering units.
shape A shape is a special type of display object that can be used in numerous displays.
Shapes can be used as 'clip-art' or as shape sequences.
shapelink A shapelink is, in effect, a 'window' which always displays one shape of a shape
sequence. For example, a shapelink representing a point's status displays the shape that
corresponds to the current status.
shape sequence A shape sequence is a set of related shapes that are used in conjunction with shapelinks.
A shape sequences can be used to:
• Represent the status of a point (Each shape represents a particular status).
• Create an animation (Each shape is one 'frame' in the animation.)
Station The main operator interface to Experion. Stations can run either on a remote computer
through a serial or LAN link, or on the server computer.
When Station is running on the Experion server computer, it is often referred to as a
server Station.
Station Automation The Station Automation object model provides the programming interface through
object model which scripts control Station and its displays.
status point
supervisory control The action of writing information to a controller. Experion enables both automatic and
manual supervisory control. See Mode.
task A task is any of the standard server programs or an application program that can be
invoked from a display.
TCP/IP Transmission Control Protocol/Internet Protocol. A standard network protocol.
terminal server A device on the local area network (LAN) that connects to a controller by way of a
serial connection and enables the controller to 'talk to' the Experion server on the LAN.
timer A timer is a programming mechanism for running scripts at regular intervals in Station.
351
GLOSSARY
trend A display in which changes in value over time of one or more point parameters are
presented in a graphical manner.
UCM Unit Control Module.
Unreasonable High Alarms configured for an unreasonably high value and an unreasonably low value for
and Unreasonable the PV of an analog point.
Low alarms
User Scan Task A server software option used to configure a server database table (called a 'user file') to
controller act as a controller. The server interfaces with the user file rather than the actual device.
In this way you can write software to interface with the server and to communicate with
devices that are connected to, but not supported by, the Experion server. The Experion
server can then scan data from the user files into points configured on the User Scan
Task controller and, for control, the Experion server can write point control data to the
user file or a control queue.
USKB Universal Station keyboard
USR Unit Start Request
utility Experion programs run from a command line to perform configuration and maintenance
functions; for example, the lisscn utility.
virtual controller See User Scan Task controller.
WCF Windows Communication Foundation.
WINS Windows Internet Name Service.
WWW World Wide Web.
zone A defined space either inside or outside that has at least one entry.
352 www.honeywell.com
Notices
Trademarks
Experion® and SafeBrowse® are registered trademarks of Honeywell International, Inc.
Other trademarks
Microsoft and SQL Server are either registered trademarks or trademarks of Microsoft Corporation in the
United States and/or other countries.
Trademarks that appear in this document are used only to the benefit of the trademark owner, with no intention
of trademark infringement.
Third-party licenses
This product may contain or be derived from materials, including software, of third parties. The third party
materials may be subject to licenses, notices, restrictions and obligations imposed by the licensor. The licenses,
notices, restrictions and obligations, if any, may be found in the materials accompanying the product, in the
documents or files accompanying such third party materials, in a file named third_party_licenses on the media
containing the product, or at http://www.honeywell.com/ps/thirdpartylicenses.
353
NOTICES
Documentation feedback
You can find the most up-to-date documents on the Honeywell Process Solutions support website at:
http://www.honeywellprocess.com/support
If you have comments about Honeywell Process Solutions documentation, send your feedback to:
[email protected]
Use this email address to provide feedback, or to report errors and omissions in the documentation. For
immediate help with a technical problem, contact your local Honeywell Technical Assistance Center (TAC)
listed in the “Support and other contacts” section of this document.
354 www.honeywell.com
NOTICES
355
NOTICES
Support
For support, contact your local Honeywell Process Solutions Customer Contact Center (CCC). To find your
local CCC visit the website, https://www.honeywellprocess.com/en-US/contact-us/customer-support-contacts/
Pages/default.aspx.
356 www.honeywell.com
Index
357
INDEX
358 www.honeywell.com
INDEX
359
INDEX
360 www.honeywell.com
INDEX
361
INDEX
362 www.honeywell.com
INDEX
363
INDEX
UTBBLD
system status checks 57
V
user table utility 53, 54 valid attributes for a category 138
utilities
described 22
development utilities 75 W
types of utilities you can develop 22 watchdog timers, described 37
USRLRN, list available tasks 30 WDSTRT (watchdog timer start routine) 37
WTTSKB routine 36
364 www.honeywell.com