Cogent API and Utilities

Version 4.1

Jan 06, 2003

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

With version 4.0, Cogent software now includes source-code compatibility among the QNX 4, QNX 6 and Linux operating systems, a reorganized and expanded API, and other improvements. Version 4.0 of Cogent's tools will not interoperate with version 3 or older. This documentation has been edited and reorganized to reflect those changes. For documentation of Cogent software version 3.x, please contact Cogent Real-Time Systems, Inc.

Go to the Cogent Web Site.

Table of Contents

I. Programmers Manual

1. Introduction

1.1. Function Naming Conventions
1.2. Assumptions about the Reader
1.3. System Requirements
1.4. Download and Installation
1.5. 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

6. The Cascade Historian

6.1. Command/Function Correspondence
6.2. Binary Data Buffer Functions

7. Cascade Driver Specifications

7.1. Hilscher Fieldbus CIF Card block functions
7.2. Hilscher Fieldbus CIF Card Control API
7.3. Hilscher Fieldbus CIF Card Status API

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

A. Cascade DataHub Code Examples

A.1. Reading from the Cascade DataHub
A.2. Writing data to the Cascade DataHub
A.3. Registering for exceptions from the Cascade DataHub
A.4. A sample makefile definition

Index

Colophon

List of Tables
6-1. Cascade Historian Commands and Functions
6-2. Cascade Historian Binary Data Buffer Functions

Prev	Home	Next
Colophon		Programmers Manual