2.3. Sending Commands

Cascade Historian™ : Version 6.4
	Chapter 2. Using the Cascade Historian

In addition to the configuration file, commands can be sent directly to the Cascade Historian at any time while it is running, by using the Cogent lsend utility or your own code. Most of these commands are also wrapped as C functions, which are fully documented in the Cogent C API manual. Commands that are commonly issued at run-time include services and data-access commands, such as:

Services

`enable`	activates data recording.
`disable`	stops data recording.
`flush`	writes buffered data to disk.
`delete`	removes a history from memory only.

Data Access

`count`	counts the number of histories that match a pattern.
`describe`	describes a history's current configuration.
`earliest`	gives the earliest value in a history.
`latest`	gives the latest value in a history.
`length`	finds the total number of values in a history.
`list`	finds the name of available histories.
`interpolate`	initiates queries on history data.
`bufferIdData`	gets data from an `interpolate` query.
`bufferIdLength`	gives the length of an interpolation buffer.
`bufferIdDestroy`	destroys an interpolation buffer.

The syntax for run-time commands is the same as that used in the configuration file. It consists of the name of the command, followed by a space-separated list of arguments, all enclosed in parentheses, like this:

(command arg₁ arg₂ arg₃ ...)

2.3.1. History Names

The name of a history can be used directly in a command, or quoted as a string. There is no need to quote the name except when it contains non-alpha-numeric characters such as "/" or "." which can be used when specifying Cascade DataHub domains.

For example, the commands

(enable temp14)
(enable "temp14")
(enable "proj5/om:abc/temp14")

would all be accepted by the command parser. However, the command (enable proj5/om:abc/temp14) would not. For the sake of simplicity, we do not quote history names in this manual unless necessary.

2.3.2. Globbing Patterns

Some commands and functions take a pattern as a history name. These patterns are globbed according to Korne Shell globbing rules:

* = any number of any characters.

? = any single character.

{x,y,z} = x or y or z, where x, y, and z are non-globbing strings.

[a-h] = any one of the characters a to h, inclusive.

[agn] = any one of the characters a, g, or n.

[^...] = the inversion of any [...] expression.

To match all histories or commands, supply just the asterix character (*) as the pattern.

2.3.3. Sending commands from Gamma

If you want to send commands from a Gamma program, say with the send function, the command syntax is slightly different than what is shown above. The command name is outside the parentheses, and the arguments are separated by commas, like this:

command (arg₁, arg₂, arg₃, ...)

2.3.4. Using `lsend` to send commands

To use lsend for sending commands to the Cascade Historian, follow these steps:

Go to a shell, and and ensure that the Cascade DataHub is running by issuing the nsnames command:
```
[sh]$ nsnames
Task            Queue           Domain          Node TaskID
/dh/default     default         default         0    8521  
Hist            histq           default         0    19544 
```
This gives you a list of named tasks currently registered with nserve. The Cascade Historian should be listed by the global name you registered for it when you originally started it up, using the histdb command. (In the example above the name is Hist.)
Enter the following:
```
[sh]$  lsend nserve-name
nserve-name
```
where nserve-name is the registered name of the Cascade Historian (such as Hist in the example above). If the command is successful, the prompt will change to that name.
Enter a command, using the standard command syntax given above. For example:
```
Hist> (disable p2)
t
Hist>
```
If for some reason you need to use Gamma syntax (as explained above), you can either give the lsend command with the -g option, or use gsend, which is essentially the same thing.
When the command executes successfully, it returns its expected return value; otherwise it returns an error message or nil.


2.2. Configuration		2.4. Error Handling