Cogent C API and Utilities

Version 6.4

May 13, 2009

The Application Program Interface and several utilities used by the Cogent tools.

Cogent software is source-code compatible among the Linux, QNX 6, and QNX 4 operating systems.
Go to the Cogent Web Site.
Copyright, trademark, and software license information.

Table of Contents

I. Programmers Manual

1. Introduction
1.1. When to use the different Cogent APIs
1.2. Function Naming Conventions
1.3. System Requirements
1.4. Download and Installation
1.4.1. QNX 4
1.4.2. QNX 6
1.4.3. Linux
1.4.4. Installed file locations
1.4.5. Installing licenses
1.5. Cogent Product Integration
1.6. Where can I get help?

2. Point Structure, Storage, and Manipulation
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

3. Interprocess Communication
3.1. Connections and Channels
3.2. Task Structure Caching
3.3. Messages
3.4. Cascade NameServer Functions
3.5. Photon Functions
3.6. Pulses and Timers
3.7. Cascade QueueServer Functions
3.8. Receiving Messages and Events
3.9. Replying to Messages
3.10. Sending Messages
3.11. Task Structures
3.12. Working with TCP/IP

4. The Cascade NameServer
4.1. Domains
4.2. Locating Other Tasks on the Network
4.3. Task Started and Stopped Messages

5. Communicating with the Cascade DataHub
5.1. Exceptions
5.2. Echoes
5.3. Non-Existent Cascade DataHub Points
5.4. Parsing Point Messages
5.5. Optimizing Throughput
5.6. Point Size Limit
5.7. Cascade DataHub API Code Examples
5.7.1. Reading from the Cascade DataHub
5.7.2. Writing data to the Cascade DataHub
5.7.3. Registering for exceptions from the Cascade DataHub
5.7.4. A sample makefile definition

6. The Cascade Historian
6.1. Command/Function Correspondence
6.2. Binary Data Buffer Functions

7. Cogent Driver Specifications
7.1. Cogent Driver Functions
7.2. Hilscher Fieldbus CIF Card
7.2.1. I/O Block Functions
7.2.2. Control Block Functions
7.2.3. Status Block Functions

A. GNU General Public License
B. GNU Lesser General Public License

II. Reference

I. Utilities
lsend, gsend - send commands to Cogent and Gamma programs.
nsnames - queries the Cascade NameServer.
nserve - starts the Cascade NameServer.
qserve - starts the Cascade QueueServer.

II. Data Types
HI_stVALUE - contains an (x,y) data tuple used by the Cascade Historian.
PT_stCPOINT - holds information about a Cascade DataHub point.
PT_TYPE, PT_uVALUE - holds the type and value a Cascade DataHub point.
ST_STATUS - contains return values for some Cogent C API functions.

III. Cascade DataHub Functions
DH_AppendString - appends a string to a point.
DH_CreatePoint - constructs a point.
DH_FindPointAddress - is for internal use only.
DH_FormatPoint - puts point data in ASCII format.
DH_ParsePointMsg - parses a point message from the Cascade DataHub.
DH_ParsePointString - parses the return of DH_ReadPoint and DH_RegisterPoint.
DH_PointAdd, DH_PointDivide, DH_PointMultiply - modify a point in place, with one message.
DH_ReadPoint, DH_ReadExistingPoint - read a point from the Cascade DataHub.
DH_RegisterAllPoints - registers with the Cascade DataHub for all points.
DH_RegisterPoint, DH_RegisterExistingPoint - register with the Cascade DataHub for a point.
DH_SendPointMessage - is for internal use only.
DH_SetLock, DH_SetSecurity - set the lock or security according to point status.
DH_SetReceiveFormat - sets DataHub-to-client transmissions to binary or ASCII.
DH_SetTransmitFormat - sets client-to-DataHub transmissions to binary or ASCII.
DH_UnregisterPoint - unregisters a point from the Cascade DataHub.
DH_WritePoint, DH_WriteExistingPoint, DH_WriteExistingPoints - write points to the Cascade DataHub.

IV. Cogent Driver Functions
DR_ApCloseIPC - closes the IPC link.
DR_ApCommand - sends ASCII commands and returns replies.
DR_ApConnectIPC - connects to Cogent products via IPC.
DR_ApDescribeBuffer - gets segment attribute information.
DR_ApDescribePnt - gives a description of a point.
DR_ApInitIPC - opens the connection to the driver.
DR_ApListBuffers - lists blocks defined to the driver.
DR_ApListPoints - lists points defined to the driver.
DR_ApPointBufAddress - deletes a point's image buffer address.
DR_ApReadBlock - reads a block.
DR_ApReadControl - gets card control parameters.
DR_ApReadPoint - reads the value of a point.
DR_ApReadStatus - gets card status information.
DR_ApUpdateBuffers - forces an I/O cycle of the image buffers.
DR_ApWriteBlock - writes data to a block.
DR_ApWriteControl - sends card control information to the driver.
DR_ApWritePoint - writes a new value to a point.

V. Cascade Historian Functions
HI_Add - adds a single value at a specified time.
HI_BufferIDDestroy - destroys an interpolation buffer.
HI_BufferIDLength - gives the length of an interpolation buffer.
HI_BufferIDRead - reads an interpolation buffer.
HI_Bufsize - sets the history buffer size.
HI_ClipBuffer - clips Y values to fit within a range.
HI_Count - counts the number of histories that match a pattern.
HI_Deadband - sets the history value deadband.
HI_Delete - removes a history from memory only.
HI_Describe - describes a history's current configuration.
HI_Disable - stops data recording.
HI_Earliest - gives the earliest value in a history.
HI_Enable - activates data recording.
HI_ExchangeBuffer - swaps X and Y values.
HI_FileBase - associates the history with a file for data storage.
HI_Flush - writes buffered data to disk.
HI_GapCountBuffer - identifies and counts large gaps in data.
HI_GapFillBuffer - fills in data gaps found by HI_GapCountBuffer.
HI_History - creates a new history.
HI_Interpolate - queries history data for interpolation.
HI_InterpolateData - interpolates a history and returns data.
HI_Latest - gives the latest value in a history.
HI_Length - finds the total number of values in a history.
HI_List - finds the name of available histories.
HI_ScaleBuffer - performs offset and scaling operations.
HI_StatBuffer - generates summary statistics on Y-values.
HI_Register - registers histories with the Cascade DataHub.
HI_Unregister - unregisters histories with the Cascade DataHub.
HI_Version - gets the version number of the Cascade Historian.

VI. Inter-Process Communication Functions
IP_AddFDHandler - tells IP_Receive to accept file input.
IP_AttachPhoton - not fully documented.
IP_AttachPhotonMainloop - not fully documented.
IP_ConnectToPort - resolves a host name and connects to a port.
IP_ConnectToService - like IP_ConnectToPort, but uses the service name.
IP_DetachPhotonMainloop - not fully documented.
IP_GetChannelID - returns the channel ID for IP library use.
IP_GetConnectionID - returns the connection ID for IP library use.
IP_IsPulse - validates a received message against a pulse ID.
IP_ListenToPort - is a wrapper for listen.
IP_ListenToService - like IP_ListenToPort, but uses the service name.
IP_MsgCascade - writes message data to an IP_MsgBuffer.
IP_MsgCreate - creates an IP_Msg structure.
IP_MsgData - returns a pointer to the data payload of an IP_Msg structure.
IP_MsgDefaultSize - gets the default size of interprocess messages.
IP_MsgDestroy - frees memory associated with a message.
IP_MsgInfoReply - replies to an IP_SYNC message using IP_MsgInfo.
IP_MsgInfoReplyRaw - replies to an IP_RAW message using IP_MsgInfo.
IP_MsgLisp - constructs a formatted text message.
IP_MsgRaw - like IP_MsgCascade, with IP_SUB_RAW for its subtype.
IP_MsgRawData - gives a pointer to IP_RAW message data.
IP_MsgResize - resizes the IP_MsgBuffer, if possible.
IP_NserveAdd - adds an entry to nserve.
IP_NserveClose - closes the channel to nserve.
IP_NserveInit - creates a task structure and informs nserve.
IP_NserveInitMyself - declares current task structure information to nserve.
IP_NserveLookup - fills in a known task structure.
IP_NserveLookupId - finds a task by node, process and channel ID.
IP_NserveLookupName - allocates and fills in a new task structure.
IP_NservePackTaskInfo - makes a Lisp-parseable version of task information.
IP_NserveQueryNameCount - gives the number of registered names.
IP_NserveQueryNames - fills an array with nserve's names.
IP_NserveReattach - closes and renews all task connections and queues.
IP_NserveRemove - removes an entry from nserve.
IP_NserveSetDomain - changes a task's domain name.
IP_pfTaskComp - compares two tasks for equality.
IP_PhotonGUIFilter - not fully documented.
IP_PhotonGUIHandler - not fully documented.
IP_ProcessMessage - classifies messages for IP_Receive.
IP_PulseDestroy - destroys a pulse.
IP_PulseNew - creates a new pulse.
IP_PulseTimed - sets up timers to trigger pulses.
IP_PulseTrigger - immediately sends a pulse.
IP_QueueClose - closes a queue.
IP_QueueOpen - opens a queue for reading or writing.
IP_QueueRead - reads a message from the queue.
IP_QueueStrerror - gives access to error strings.
IP_QueueWait - requests notification of an event.
IP_QueueWrite - writes a message to a queue.
IP_Receive - receives any message.
IP_ReceiveNonblock - receives any message, without blocking.
IP_RemoveFDHandler - prevents IP_Receive from accepting file input.
IP_Reply - replies to an IP_SYNC message using rcvid.
IP_ReplyRaw - replies to an IP_RAW message using rcvid.
IP_SelectFD - is used internally only.
IP_SetChannelID - sets the channel ID for IP library use.
IP_SetConnectionID - sets the connection ID for IP library use.
IP_SetGUIHandler - sets callback functions for GUI events.
IP_TaskCloseAsync - closes queues and cleans up resources.
IP_TaskCloseSync - closes synchronous connections and cleans up resources.
IP_TaskConnect - opens a connection to a receiver.
IP_TaskCopy - copies a task structure.
IP_TaskCreate - creates a new task structure.
IP_TaskCreateMe - creates a task structure for the current process.
IP_TaskDefaultDomain - returns the Cascade DataHub default domain.
IP_TaskDestroy - closes connections and queues, removes the task and frees memory.
IP_TaskFindID - finds a task by its node, process, and channel IDs.
IP_TaskFindName - finds a task by its name.
IP_TaskInitAsync - creates a read-only queue.
IP_TaskInitAsyncWrites - opens a task's queue as write-only.
IP_TaskIntern - adds a task to a process's task cache.
IP_TaskNew - creates a new task structure.
IP_TaskSendAsync - transmits a message via qserve and returns immediately.
IP_TaskSendRaw - sends data in bytes, synchronously.
IP_TaskSendSync - transmits a message, and waits for a reply.
IP_TaskSetDomain - sets or changes a task's domain name.
IP_TaskSetInfo - sets the fields in a task structure.
IP_TaskSetQname - sets a task's queue name.
IP_TaskUnintern - removes a task from a process's task cache.
IP_TaskWaitAsync - registers the task for events in qserve.
IP_TaskZero - sets all task structure fields to defaults.
IP_TimerTime - adjusts timer parameters.
IP_UnselectFD - is used internally only.

VII. Cascade TextLogger Functions
LG_Cache - controls how frequently data is written.
LG_Collect - specifies when a line of data is considered complete.
LG_Disable - renders a log or group inactive.
LG_Empty - specifies a place-holder string for empty data readings.
LG_Enable - activates a log or group.
LG_Exit - exits the Cascade TextLogger.
LG_Fall - associates values logged within a tolerance.
LG_File - specifies the file to receive a log.
LG_Flush - flushes all buffered output.
LG_Group - groups a number of logs or groups together.
LG_Log - writes point data in formatted lines.
LG_Output - writes an output string to a log or group, stdout, or stderr.
LG_Time - specifies the time format for a log or group.
LG_Timestamp - sets the time resolution for each line.
LG_Tolerance - sets the maximum gap between timestamps of any two points.
LG_UseGMT - sets time/date strings to GMT or local time.

VIII. Point Manipulation Functions
PT_FindCPoint - looks up a point by name in the internal point hash table.
PT_InitClient - initializes the static hash table of referenced points.
PT_NewCPoint - allocates and initializes a new point structure.
PT_PointCopyValue - copies one point structure into another.
PT_PointFormat - formats a point according to a printf-like directive.
PT_PointInt - converts a point to an integer.
PT_PointReal - converts a point to a real.
PT_PointString - converts a point to a string.


List of Tables

6.1. Cascade Historian Commands and Functions
6.2. Cascade Historian Binary Data Buffer Functions