Cogent C API and Utilities : Version 6.4
	Chapter 2. Point Structure, Storage, and Manipulation

Chapter 2. Point Structure, Storage, and Manipulation

Table of Contents

2.1. Creating Points
2.2. Maintaining a Point Hash Table
2.3. Accessing and Copying Point Values
2.4. Memory Allocation and String Values

The Cascade DataHub represents points given the following properties:

Point type: One of integer, floating point, or character string.

Point value: Based on the point type.

Confidence factor: 0 - 100 percent, unused by most applications.

Name: The character string representing the point name.

Locked: 0 for locked, or 1 for unlocked.

Security: 0 to 32768, where higher numbers represent higher security.

Address: An internal pointer carrying the DataHub address where the point was last found.

User Data: A void pointer which can be used to store user-defined data with a point structure. In addition, the Cascade DataHub uses other point attributes internally, which are not available to the user. These deal with the clients who have registered for exceptions, and the necessary flags to ensure that all clients receive the latest values for all points, regardless of communication link speed.

The Cascade DataHub point structure is called PT_stCPOINT, and a convenience pointer to the structure type is called PT_pCPOINT. The Cogent C API provides a number of functions for manipulating the PT_stCPOINT structures.

2.1. Creating Points

There are two ways to "create" a new data point: create a new point structure, or change the name of an existing point structure.

Creating a point structure is done either by creating a local variable of type PT_stCPOINT, or by allocating it on the heap (through malloc). The function PT_NewCPoint will allocate a point on the heap, and initialize all of its internal values to sensible numbers. This function is useful when you would like to maintain all of the point definitions internally to your program, and would like to manage the storage and lookup of these points yourself. The PT_FindCPoint function will automatically call PT_NewCPoint if it attempts to look up a point that does not currently exist in your application.

Changing the name of a point (or PT_stCPOINT structure) means changing the value of the name field. When doing this, the address field must be set to 0.

Zeroing an entire point structue (ie. setting all field values to 0) for points of type PT_TYPE_STRING will create a memory leak.


1.6. Where can I get help?		2.2. Maintaining a Point Hash Table