AlmBrowseOpen

The AlmBrowseOpen function initiates a new browse session and returns a handle to the new session that can be used in subsequent data browse function calls. Use this function to browse all configured alarms.

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

Note: After calling AlmBrowseOpen() it is necessary to call AlmBrowseFirst() in order to place the cursor at the beginning of the browse session, otherwise a hardware alarm is invoked.

Syntax

LONG AlmBrowseOpen( Filter, STRING Fields [, STRING Clusters [,INT AutoCloseMode]] )

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 "Tag=AAA". Multiple filters separated by semicolons are supported.

Note: When using Date/Time fields specify in the number of seconds since 1970. For example, LOCALTIMEDATE>=1348723732.

See the topic Implement Alarm Filters Using Cicode for more information about filter syntax.

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:

ACKDATE, ACKDATEEXT, ACKMILLI, ACKTIME, ACKUTC, ACQDESC, ACQERROR, ALARMTYPE, ALMCOMMENT, AREA, ARR_SIZE, CATEGORY, CAUSE1…8, CLASSIFICATION, CLUSTER, COMMENT, CONSEQUENCE1…8, CUSTOM1…8, DATE, DATEEXT, DEADBAND, DELAY, DELTAMILLI, DELTATIME, DESC, DEVDELAY, DEVIATION, DISABLECOMMENT, DISABLEDDATE, DISABLEDTIME, DISABLEENDDATE, DISABLEENDDATEEXT, DISABLEENDTIME, ENG_ZERO, ERRDESC, ERRPAGE, EQUIPMENT, FORMAT, FULLNAME, GROUP, HDELAY, HELP, HHDELAY, HIGH, HIGHHIGH, HISTORIAN, ITEM, LDELAY, LLDELAY, LOCALTIMEDATE, LOGSTATE, LOW, LOWLOW, MESSAGE, MILLISEC, NAME, NATIVE_COMMENT, NATIVE_DESC, NATIVE_NAME, NATIVE_SUMDESC, OFFDATE, OFFDATEEXT, OFFMILLI, OFFTIME, OFFTIMEDATE, OFFUTC, OLD_DESC, ONDATE, ONDATEEXT, ONMILLI, ONTIME, ONTIMEDATE, ONUTC, PAGING, PAGINGGROUP, PRIORITY, PRIV, PSI_TYPE, RATE, RECEIPTLOCALTIMEDATE, RECEIPTDATE, RECEIPTDATEEXT, RECEIPTMILLISEC, RECEIPTTIME, RECEIPTTIMEINT, RECEIPTTIMETICKS, RESPONSE1…8, RESPONSENUM, SETPOINT, STATE, STATE_DESC, STATE_DESC0...7, SUMDESC, SUMSTATE, SUMTYPE, TAG, TAGEX, TAGGENLINK, TIME, TIMEDATE, TIMEINT, TIMETICKS, TSQUALITY, TYPE, TYPENUM, USERDESC, USERNAME, USERLOCATION, VALUE.

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.

AutoCloseMode

An optional parameter to automatically close the browsing session at page navigation.

0 - (Default) Will not automatically close the browsing session. Use AlmBrowseClose to close the session manually.

1 - The browsing session will be closed when the page is changed or otherwise closed.

Note: All other modes are reserved.

Return Value

Returns an integer handle to the browse session. Returns -1 when an error is detected.

The returned entries will be ordered alphabetically by name.

Related Functions

AlmBrowseAck, AlmBrowseDisable, AlmBrowseEnable, AlmBrowseClose, AlmBrowseFirst, AlmBrowseGetField, AlmBrowseNext, AlmBrowseNumRecords, AlmBrowsePrev

Example

INT iSession;

...

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

"ClusterA,ClusterB");

IF iSession <> -1 THEN

// Successful case

ELSE

// Function returned an error

END

...

See Also

Alarm Functions