HI_List

Cogent API and Utilities: Version 4.1
Prev |  | Next

# `HI_List`

`HI_List` -- finds the name of available histories.

## Syntax

    #include <cogent/cogent.h>

``ST_STATUS HI_List`(IP_hTASK historian, char* retbuf, int buflen, char* histpattern, int offset, int maxcount, char** histories, int* count);`

## Arguments

`historian`

  The task pointer to the Cascade Historian program.

`retbuf`

  A required buffer containing an error message.

`buflen`

  The length in bytes of `retbuf`. This must be a valid non-zero length.

`histpattern`

  A globbing pattern specifying a group of histories.

`offset`

  An integer specifying a starting point in the list generated by `histpattern`.

`maxcount`

  The maximum number of history names to be returned.

`histories`

  An array of `char*` at least `maxcount` long, to contain up to `min(`count`,`maxcount`)` history names.

`count`

  The return value containing the number of histories (same as `HI_Count`).

## Returns

`ST_OK` on success. Otherwise `ST_ERROR`, and the `retbuf` will contain a `NULL`-terminated character string with an error message. If the return value is `ST_OK`, the `retbuf` will contain the list of history names, parsed into `NULL`-terminated string, and pointed to by the `histories` array (see the note in Description).

## Description

This function queries the Cascade Historian for the names of the histories currently being kept that match the `histpattern`. You must supply an array to contain the pointers to the name strings.

| The history names are returned as strings in `retbuf`, and the pointers returned in `histories` point to the parsed contents of `retbuf`. To preserve the history names, a reserved buffer should be used, or no further historian API calls should be made until the strings are no longer needed.

| In cases where the number of histories, or the length of their names, is such that the combination exceeds `buflen` or the length of the inter-process communication buffer, not all histories will be listed, and the `count` argument will be less than the value obtained from `HI_Count`. In these cases, the `offset` parameter can be used to receive a portion of the list. Starting `offset` at `0`, `count` can then be used to increment `offset`, enabling arbitrarily long lists of names to be obtained without concern for the length of `retbuf`, the IPC buffer, or the size of the `histories` array (see Example).

This function corresponds to the Cascade Historian list command and the `hist_list` dynamic library function.

## Example

        void ListAllHistories (IP_hTASK historian)
        {
             ST_STATUS status;
             char      *histpattern = "*";
             char      *histories[100];
             int       nHist, start, count;
             /* assume retbuf, buflen are globals */

        	status = HI_Count(historian, retbuf, buflen, histpattern, &nHist);
        	/* loop querying for names until all have been received */
        	for (start=0; start < nHist && status == ST_OK; start += count)
              {
        		status = HI_List(historian, retbuf, buflen, histpattern,
                                            100, histories, &count);
                    /* process the subset of names */
                    for (i=0; i<count; i++)
                        printf ("%s\n", histories[i]);
              }
        }

Prev | Home | Next
`HI_Length` | Up | `HI_ScaleBuffer`

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