TagBrowseOpen

The TagBrowseOpen function initiates a new browse session and returns a handle to the new session that can be used in subsequent data browse function calls. Tag records are sorted on the server and, arrive at the client in the order specified by the sorting fields parameter, or default sorting order as described below under the Sort parameter.

Tag browsing provides a snapshot of tag configuration data. It is not intended to support live data updates.

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

Note: In order to conserve memory the following recommendations should be observed, as multiple open tag browsing sessions will use a large amount of memory:
1. Close an opened session at the completion of the browsing session using TagBrowseClose.
2. List only the fields that you wish to browse, not all fields.

Syntax

LONG TagBrowseOpen(STRING Filter, STRING Fields, STRING Sort[, STRING Clusters])

Filter:

Semicolon delimited list of predefined field name filters specifying the records to return during the browsing session. If you do not specify a filter string then all tag records will be displayed.

All string fields can be filtered based on regular expressions. Using an operator other than = will cause strings to not match the filter criteria. The following regular expressions are supported *expr, expr*, and *expr*.

If any of the filter names are invalid, opening a browsing session will not succeed and will return an invalid handle.

Field:

Comma separated list of record fields to be returned during the browsing session. An empty field string will return all possible fields.

Supported fields are:

Configuration Fields

ADDR, ARR_SIZE, CLUSTER, COMMENT, CUSTOM1, CUSTOM2, CUSTOM3, CUSTOM4, CUSTOM5, CUSTOM6, CUSTOM7, CUSTOM8, DEADBAND, ENG_FULL, ENG_UNITS, ENG_ZERO, EQUIPMENT, FULLNAME, HISTORIAN, ITEM, RAW_FULL, RAW_ZERO, SCALED_TYPE, TAG, TYPE, WRITE_ROLES

For full details on these fields refer to the Browse Function Field Reference.

The fields LOG_UNIT and NET_UNIT are available when using the Cicode functions and TagInfoEx are also supported.

Runtime Fields

Sort:

Comma delimited list of record fields to be returned in order of sorting preferences (each with an indication of whether the sort is A - ascending or D - descending). For example "TYPE:D". By default tag browsing records are sorted by the tag primary key Cluster.TagName. which is implicitly appended to the list of sorting fields, since all the other fields may end up not being unique.

Clusters:

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

Return Value

Session handle (LONG) if successful, -1 if unsuccessful.

Related Functions

TagInfoEx, TagInfo, TagBrowseClose, TagBrowseFirst, TagBrowsePrev, TagBrowseNumRecords, TagBrowseNext,TagBrowseGetField

Example 1

// open

TBResult = TagBrowseOpen("ADDR=*2; TYPE<=2", "TAG,TYPE,ADDR", "ADDR:D", "");

ErrLog("Open Session ID: " + IntToStr(TBResult) +

", Error = " + IntToStr(IsError()));

TBHandle = TBResult;

END

Example 2 - Filters

The following variable tags have been defined - Tag01, Tag02 and Tag03.

// Example Filter

FUNCTION TagBrowseTest1()

STRING sFilter = "TAG=Tag01|Tag03";

STRING sField = "TAG";

STRING sTag = "";

INT iStatus = -1;

INT hTagBrowse = TagBrowseOpen(sFilter,sField,sField+":A");

IF (hTagBrowse <> -1) THEN

iStatus = TagBrowseFirst(hTagBrowse);

WHILE iStatus = 0 DO

sTag = TagBrowseGetField(hTagBrowse,sField);

Message(sTag,sTag,64); // Tag01, Tag03

iStatus = TagBrowseNext(hTagBrowse);

END

TagBrowseClose(hTagBrowse);

END

END

Example 3 - Filters

// Example Filter

FUNCTION TagBrowseTest2()

STRING sFilter = "TAG=Tag01 OR TAG=Tag03";

STRING sField = "TAG";

STRING sTag = "";

INT iStatus = -1;

INT hTagBrowse = TagBrowseOpen(sFilter,sField,sField+":A");

IF (hTagBrowse <> -1) THEN

iStatus = TagBrowseFirst(hTagBrowse);

WHILE iStatus = 0 DO

sTag = TagBrowseGetField(hTagBrowse,sField);

Message(sTag,sTag,64); // Tag01, Tag03

iStatus = TagBrowseNext(hTagBrowse);

END

TagBrowseClose(hTagBrowse);

END

END

Results

Good: STRING sFilter = "TAG=Tag01|Tag03";

Good: STRING sFilter = "TAG=Tag01 OR TAG=Tag03";

Fail: STRING sFilter = "TAG=Tag01 OR Tag03";

See Also

Tag Functions