AlmSummaryOpen

The AlmSummaryOpen 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.

The AlarmSummaryOpen function allows direct, successful subsequent execution of AlmSummaryNext and AlmSummaryPrev functions.

The AlmSummaryNext function executed directly after AlmSummaryOpen will place the data browse cursor at the earliest summary record.

The AlmSummaryPrev function executed directly after AlmSummaryOpen will place the cursor at the most recent summary record.

Note: Performance may be affected when using the AlmSummaryOpen browse functions in a system which has accumulated large volumes of alarm summary entries.

To improve performance:

• Specify only the required fields in the Fields parameter of the AlmSummaryOpen Cicode function. By default the parameter is empty and the browse will retrieve all available fields. Refer to Example 1.
• Specify a small OnTime filter for the alarm when calling the Cicode function. Confirm that the AlmSummaryClose is called for each browse session that has been opened using AlmSummaryOpen. Refer to Example 2.
• Specify a small row limit in the RowLimit parameter of the AlmSummaryOpen function. The default value is -1 which will use the default row limit specified in the Citect.ini parameter [Alarm]QueryRowLimit. Refer to Example 3.

Syntax

LONG AlmSummaryOpen(STRING Filter, STRING Fields [, STRING Clusters [, INT RowLimit, [,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".

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, ACKTIME, ACQERROR, ALARMTYPE, ALMCOMMENT, AREA, CATEGORY, CLUSTER, COMMENT, CUSTOM1, CUSTOM2, CUSTOM3, CUSTOM4, CUSTOM5, CUSTOM6, CUSTOM7, CUSTOM8, DATE, DATEEXT, DEADBAND, DELTATIME, DESC, DEVIATION, ERRDESC, ERRPAGE, EQUIPMENT, FORMAT, GROUP, HELP, HIGH, HIGHHIGH, ITEM, LEVEL, LOCALTIMEDATE, LOGSTATE, LOW, LOWLOW, MILLISEC, NAME, NATIVE_COMMENT, NATIVE_DESC, NATIVE_NAME, NATIVE_SUMDESC, OFFDATE, OFFDATEEXT, OFFMILLI, OFFTIME, OFFTIMEDATE, OLD_DESC, ONDATE, ONDATEEXT, ONMILLI, ONTIME, ONTIMEDATE, PAGING, PAGINGGROUP, PRIORITY, PRIV, QUALITY, RATE, RECEIPTLOCALTIMEDATE, RECEIPTDATE, STATE, STATE_DESC, STATE_DESC0, STATE_DESC1, STATE_DESC2, STATE_DESC3, STATE_DESC4, STATE_DESC5, STATE_DESC6, STATE_DESC7, SUMDESC, SUMSTATE, SUMTYPE, TAG, TAGEX, TIME, TIMEDATE, TYPE, TYPENUM, USERNAME, 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.

RowLimit:

The default value of iRowLimit is -1. This will cause the browse session to use the default global maximum row limit (configured by the INI parameter [Alarm]BrowseRowLimit), or the default value of the INI parameter if not specified.

Specifying a small iRowLimit can reduce the round-trip time and the memory usage of AlmSummaryOpen Cicode function in a system with large alarm summary history.

AutoCloseMode 

Optional parameter to close session at page navigation.

                   
• 0 - Will not automatically close the browsing session. Use AlmSummaryClose to close the session manually.
• 1 - The browsing session will be closed when the page is changed or otherwise closed.

Return Value

Returns an integer handle to the browse session. Returns -1 on error.

Related Functions

AlmSummaryAck, AlmSummaryClear, AlmSummaryClose, AlmSummaryDelete, AlmSummaryDeleteAll, AlmSummaryDisable, AlmSummaryEnable, AlmSummaryFirst, AlmSummaryGetField, AlmSummaryLast, AlmSummaryNext, AlmSummaryPrev, AlmSummaryNumRecords

Example

				
Example 1 - Specifying the fields

INT iSession;
...
iSession = AlmSummaryOpen("NAME=ABC*", "NAME,TYPE",
"ClusterA,ClusterB");
IF iSession <> -1 THEN
// Successful case
ELSE
// Function returned an error
END
...
				
Example 2 - Specifying the time range for multiple incremental browse sessions
				
INT session;
STRING t0 ;
STRING t1;
           
 // Below is an example of browsing alarm summary records incrementally in small time ranges
 // of 20 minutes interval over an hour from 10:00am TO 11:00am on 9th March 2015 local time.
            
 // 10:00 ~ 10:20
 t0 = IntToStr(TimestampToTimeInt(TimestampCreate(2015,03,09,10,00,00,000)));
 t1 = IntToStr(TimestampToTimeInt(TimestampCreate(2015,03,09,10,20,00,000)));
 session = AlmSummaryOpen("OnTime >= " + t0 + " AND OnTime < " + t1, "");
 IF (session >= 0) THEN
     AlmSummaryFirst(session);
     // Do something with the browse session
     // ...
     AlmSummaryClose(session);
 END
           
 // 10:20 ~ 10:40
 t0 = IntToStr(TimestampToTimeInt(TimestampCreate(2015,03,09,10,20,00,000)));
 t1 = IntToStr(TimestampToTimeInt(TimestampCreate(2015,03,09,10,40,00,000)));
 session = AlmSummaryOpen("OnTime >= " + t0 + " AND OnTime < " + t1, "");
 IF (session >= 0) THEN
     AlmSummaryFirst(session);
     // Do something with the browse session
     // ...
     AlmSummaryClose(session);
 END
           
 // 10:40 ~ 11:00
 t0 = IntToStr(TimestampToTimeInt(TimestampCreate(2015,03,09,10,40,00,000)));
 t1 = IntToStr(TimestampToTimeInt(TimestampCreate(2015,03,09,11,00,00,000)));
 session = AlmSummaryOpen("OnTime >= " + t0 + " AND OnTime < " + t1, "");
 IF (session >= 0) THEN
     AlmSummaryFirst(session);
     // Do something with the browse session
     // ...
     AlmSummaryClose(session);
 END
 ...

Example 3 - Specify RowLimit for multiple incremental browse sessions
				
INT session;
INT rowLimit = 500;
STRING continuationFilter;
REAL ts;
STRING lastOnTime;
           
// Below is an example of browsing alarm summary records incrementally in small row limit of 50
// The OnTime and Tag of the last record is used as the continuation for the next incremental session.
            
// First session
session = AlmSummaryOpen("", "", "Cluster1", rowLimit);
IF (session < 0) THEN
    RETURN;
END
            
AlmSummaryFirst(session);
// Do something with the browse session, and call AlmSummaryNext(session) to iterate
// ...
          
// Capture the timestamp of the last record for browse continuation with a next session.
AlmSummaryLast(session);
ts = (StrToReal(AlmSummaryGetField(session, "OnMilli")) / 1000) +
      StrToDate(AlmSummaryGetField(session, "OnDate")) +
      StrToTime(AlmSummaryGetField(session, "OnTime"));
           
lastOnTime = RealToStr(ts, 0, 3);
				
AlmSummaryClose(session);
            
// Continue browsing using small row limit.
continuationFilter = "OnTime > " + lastOnTime;
session = AlmSummaryOpen(continuationFilter, "", "Cluster1", rowLimit);
IF (session < 0) THEN
     RETURN;
END
  
IF AlmSummaryFirst(session) <> 0 THEN
     AlmSummaryClose(session);
      RETURN;
END
            
// Do something with the browse session, and call AlmSummaryNext(session) to iterate
// ...
            
// Capture the timestamp of the last record for browse continuation with a next session.
AlmSummaryLast(session);
ts = (StrToReal(AlmSummaryGetField(session, "OnMilli")) / 1000) +
           StrToDate(AlmSummaryGetField(session, "OnDate")) +
           StrToTime(AlmSummaryGetField(session, "OnTime"));
           
lastOnTime = RealToStr(ts, 0, 3);
AlmSummaryClose(session);
…

See Also

Published June 2018