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 operators other than = and <> 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, FORMAT, FULLNAME, IODEV, PSI_TYPE, RAW_FULL, RAW_ZERO, SCALED_TYPE, TAG, TAG ITEM, TYPE
For full details on these fields refer to the Browse Function Field Reference.
The fields LOG_UNIT and NET_UNIT available when using the Cicode functions TagInfo and TagInfoEx are also supported.
Runtime Fields
| Field Value | Description (predefined values) |
Possible values |
|---|---|---|
| OVR_MODE | Override Mode |
integer (as per override mode element specification) |
| CTRL_MODE | Control Mode (0-1) | integer (as per control mode element specification) |
| NUM_SUBS | Number of current subscriptions to the tag |
integer |
| VALUE | Default value | as per value type |
| FIELD | Field value | as per value type |
| OVERRIDE | Override value | as per value type |
| VALID | Last Valid value | as per value type |
| STATUS | Last Status value | integer (as per status element specification) |
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,TegBrowseGetField
Example
// open
TBResult = TagBrowseOpen("ADDR=*2; TYPE<=2", "TAG,TYPE,ADDR", "ADDR:D", "");
ErrLog("Open Session ID: " + IntToStr(TBResult) +
", Error = " + IntToStr(IsError()));
TBHandle = TBResult;
END
See Also
Published June 2018