User Interface Models

Cascade Historian: Version 4.1
Prev | Chapter 3. System Overview | Next

# 3.3. User Interface Models

An application programmer can interface to the Cascade Historian through any of three basic paradigms: the ASCII command interface, the Cogent API or the Gamma dynamic library (in QNX 4).

## 3.3.1. The Command Interface

The ASCII command interface provides access to the services offered by the Cascade Historian, such as configuring histories for data points and sending queries. A complete list is shown in the Commands reference.

The command interface model is basically client-server, whereby the client initiates all exchanges and must wait for the server (the Cascade Historian) to respond. This interface receives and returns ASCII IPC messages, which are ASCII strings with `NULL` termination. They can be transmitted by either the Cogent API (see below) or by using the C function `Send()`.

The command interface can be used at run time, and is also used to configure the Cascade Historian. Configuration commands can be stored in a configuration file which is processed before the Cascade Historian opens its interface to any user application.

See Configuration and Sending Commands in this manual for details on the command interface.

## 3.3.2. Cogent API Functions

The Cascade Historian Functions reference section of the Cogent API includes a group of C functions that facilitate access to the Cascade Historian from the user's (client) application code. These functions are essentially wrappers on the IPC interface to the Cascade Historian's commands. Although the majority of these commands are ASCII, support is also provided for transferring data (resulting from queries) in the more efficient binary format (see `HI_BufferIDRead` and `HI_Interpolate`). A set of utilities for performing some commonly needed transformations on the binary data buffers is also included.

## 3.3.3. The Dynamic Library

The Cascade Historian dynamic library is an extension to the Gamma language that facilitates access to the Cascade Historian from the user's (client) Gamma application. These functions are essentially wrappers on the IPC interface to the Cascade Historian's commands. Although the majority of these commands are ASCII, support is also provided for transferring data (resulting from queries) in the more efficient binary format (see `hist_buffer_id_read` and `hist_interpolate`). A set of utilities is also included for accessing and performing some commonly needed transformations on the binary data buffers.

The dynamic library is called `histdb.so`, loadable by a Gamma application using the `DllLoad` function as follows:

            DllLoad ("histdb.so")

| The library and corresponding command is `histdb.dlb` for QNX 4.

### 3.3.3.1. Class Definitions

The Historian DLL defines the following classes:

        class HI_stVALUE
        {
              value; 	// the real-valued Y-axis data (normally the point value)
              xaxis;	// the real-valued X-axis data (normally the time)
        }

This class is used to contain a history data point. It is used to return values from the `hist_earliest`, `hist_latest`, and `hist_access_buffer` funtions.

This class is analogous to the Cogent API structure `HI_stVALUE`.

### 3.3.3.2. Error Returns

Gamma defines a special variable `_last_error_` which always contains the last error. In the Cascade Historian DLL, most errors are generated by the command interface, and are listed in the documentation for the appropriate command. When an error is generated, the DLL functions set `_last_error_` to the error string returned by the Cascade Historian, and return `nil`.

## 3.3.4. Command/Function Correspondence

The following table shows all the Cascade Historian commands, and the Cogent API functions and dynamic libary functions that correspond to them. This table is also available in the Command/Function Correspondence section of the Cogent API manual.

Table 3-1. Cascade Historian Commands and Functions

Command | API Function | DLL Function
--- | --- | ---
add | `HI_Add` | -
apropos | - | -
aproposSyntax | - | -
bufferIdData | `HI_BufferIDRead` | `hist_buffer_id_read`
bufferIdDataAscii | - | -
bufferIdDestroy | `HI_BufferIDDestroy` | `hist_buffer_id_destroy`
bufferIdLength | `HI_BufferIDLength` | `hist_buffer_id_length`
bufsize | `HI_Bufsize` | `hist_bufsize`
count | `HI_Count` | `hist_count`
deadband | `HI_Deadband` | `hist_deadband`
delete | `HI_Delete` | `hist_delete`
describe | `HI_Describe` | `hist_describe`
disable | `HI_Disable` | `hist_disable`
earliest | `HI_Earliest` | `hist_earliest`
enable | `HI_Enable` | `hist_enable`
exit | - | -
flag | - | -
filebase | `HI_FileBase` | `hist_filebase`
flush | `HI_Flush` | `hist_flush`
histdb | - | -
history | `HI_History` | `hist_history`
include | - | -
interpolate | `HI_Interpolate` | `hist_interpolate`
- | `HI_InterpolateData` | `hist_interpolate_data`
interpolatorDescribe | - | -
interpolatorList | - | -
latest | `HI_Latest` | `hist_latest`
length | `HI_Length` | `hist_length`
list | `HI_List` | `hist_list`
register | `HI_Register` | `hist_register`
unregister | `HI_Unregister` | `hist_unregister`
version | `HI_Version` | `hist_version`

## 3.3.5. Binary Data Buffer Functions

The following table lists a set of functions for accessing and performing some commonly needed transformations on the binary data buffers. This table is also available in the Binary Data Buffer Functions section of the Cogent API manual.

Table 3-2. Cascade Historian Binary Data Buffer Functions

API Function | DLL Function
--- | ---
- | `hist_access_buffer`
- | `hist_buffer2array`
`HI_ClipBuffer` | `hist_clip_buffer`
`HI_ExchangeBuffer` | `hist_exchange_buffer`
`HI_GapCountBuffer` `HI_GapFillBuffer` | `hist_gap_buffer`
- | `hist_length_buffer`
`HI_ScaleBuffer` | `hist_scale_buffer`
`HI_StatBuffer` | `hist_stat_buffer`

Prev | Home | Next
Information Flow | Up | Commands

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