2.3. Sending Commands
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 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 arg1 arg2 arg3 ...)
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 (arg1, arg2, arg3, ...)
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 ensure that the Cascade DataHub, qserve, and nserve are running by invoking the nsnames command:
[sh]$ nsnames Task Queue Domain Node TaskID /db/default datahub_2148 default 0 8521 Hist histq default 0 19544This 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-namewhere 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. You can send as many commands as you like at once, by typing them one after another, like this:
Hist> (disable p*)(enable ptbogus)(history p6) t Hist> (error "histdb: enable: No history found for: ptbogus") Hist> t Hist>The Cascade Historian returns a value for each command independently (it also returns a prompt for each, which you can ignore), and continues processing until all the commands have been attempted.