Point Structure, Storage, and Manipulation

Cogent API and Utilities: Version 4.1
Prev |  | Next

# Chapter 2. Point Structure, Storage, and Manipulation

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

Prev | Home | Next
Where can I get help? | Up | Maintaining a Point Hash Table

Copyright 1995-2002 by Cogent Real-Time Systems, Inc.