HI_List

Arguments

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]);
      }
}