TrnBrowseOpen

The TrnBrowseOpen function initiates a new browse session and returns a handle to the new session that can be used in subsequent data browse function calls.

This function is a blocking function. It blocks the calling Cicode task until the operation is complete.

Syntax

INT TrnBrowseOpen( STRING Filter, STRING Fields [, STRING Clusters] )

Filter

A filter expression specifying the records to return during the browse. An empty string indicates that all records will be returned. Where a fieldname is not specified in the filter, it is assumed to be tagname. For example, the filter "AAA" is equivalent to "name=AAA".

The following regular expressions are supported: *expr, expr*, and *expr*. To specify an exclusion filtering condition, use the NOT keyword after the = operator.

Fields

Specifies via a comma delimited string the columns to be returned during the browse. An empty string indicates that the server will return all available columns. Supported fields are:

ACQERROR, CLUSTER, COMMENT, DEADBAND, ENG_UNITS, EQUIPMENT, EXPRESSION, FILENAME, FILES, FORMAT, HISTORIAN, ITEM, LSL, NAME, PRIV, SAMPLEPER, SDEVIATION, SPCFLAG, STORMETHOD, SUBGRPSIZE, TAGGENLINK, TIME, TRIGGER, TYPE, USL, XDOUBLEBAR.

See Browse Function Field Reference for information about fields.

Clusters

An optional parameter that specifies via a comma delimited string the subset of the clusters to browse. An empty string indicates that the connected clusters will be browsed.

Return Value

Returns an integer handle to the browse session. Returns -1 if unsuccessful.

The returned entries will be ordered alphabetically by name.

Related Functions

TrnBrowseClose, TrnBrowseFirst, TrnBrowseGetField, TrnBrowseNext, TrnBrowseNumRecords, TrnBrowsePrev

Example 1

INT iSession;

...

iSession = TrnBrowseOpen("NAME=ABC*", "NAME,TYPE",

"ClusterA,ClusterB");

IF iSession <> -1 THEN

// Successful case

ELSE

// Function did not succeed

END

...

Example 2 - Filters

The following trend tags have been defined: Trend01, Trend02 and Trend03.

// Example Filter

FUNCTION TrnBrowseTest()

STRING sFilter = "TAG=Trend01 OR Trend03";

STRING sField = "TAG";

STRING sTag = "";

INT iStatus = -1;

INT hTagBrowse = TrnBrowseOpen(sFilter,sField);

IF (hTagBrowse <> -1) THEN

iStatus = TrnBrowseFirst(hTagBrowse);

WHILE iStatus = 0 DO

sTag = TrnBrowseGetField(hTagBrowse,sField);

Message(sTag,sTag,64); // Trend01, Trend03

iStatus = TrnBrowseNext(hTagBrowse);

END

TrnBrowseClose(hTagBrowse);

END

END

Results

Good: STRING sFilter = "TAG=Trend01 OR Trend03";

Good: STRING sFilter = "TAG=Trend01|Trend03";

Fail: STRING sFilter = "TAG=Trend01 OR TAG=Trend03";

See Also

Trend Functions