About Named Filters | System Model

A named filter can be used to filter an alarm list or an alarm count only if that alarm list or alarm count is associated to the named filter. It is not used to directly filter alarms. Instead it is used to update the active filter of multiple alarm lists or alarm counts. Once you create the named filter you then edit it to add the filter criteria you want the named filter to query.

To associate an alarm list to a named filter, you need to call AlarmSetInfo(AN, 12, “Named Filter”), where AN is the animation number of the associated alarms list, 12 is the mode for associating the named filter to the alarms list, and “NamedFilter” is the name of the filter that was created by calling the function AlarmFilterOpen.

To disassociate the named filter from an alarm list set “NamedFilter” to empty text, for example, AlarmSetInfo(AN, 12, “”). This will remove the association from the named filter, but the disassociated alarm list will not be refreshed, hence the filter query will still be in place until a new filter is applied.

In order to associate an alarm count to a named filter, you need to call AlarmCount(Type, “NamedFilter”, KeepAliveSeconds, CacheMode), where Type, KeepAliveSeconds and CacheMode are documented in the AlarmCount function, and “NamedFilter” is the named filter that was previously opened by calling AlarmFilterOpen.

In each of these cases, editing the filter criteria belonging to the named filter will update all associated alarm lists or alarm counts.

Note: If a requested filter is too complex (for example, it contains too many conditions or too many nested brackets), the filter is cleared (no filter is used). If this occurs, the hardware alarm "Too many alarms in filters" is generated on the client components, and a tracelog error message is logged.

The following examples show how to open, edit (add filter criteria), associate, disassociate and close a named filter called “MyFilter”.

                
	// The following examples show how to open, edit, associate, disassociate and close 
	// a named filter (e.g. "MyFilter").
	// These are fictional examples for demonstration purposes only.
	// The prompt message is dispplayed in prompt-line for increasing clarity.
	// This function returns zero when all examples are successful,
	// otherwise error is returned. 
	INT
	FUNCTION 
	AlarmNamedFilterExamples()

	    INT iError, iHndl;
	    INT iAN=21; // Animation Number
	    INT iOpenModeNew = 1;
	    INT iCloseModeManual = 0;
	    INT iAlarmCounted=0, IAlarmDisplayed=0; 
	    STRING sName, sEmptyString="", sNamedFilter, sLinkedFilter;


	    ! Open the new filter named "MyFilter"
	    sNamedFilter = "MyFilter";   
	    iError = AlarmFilterOpen(sNamedFilter, iOpenModeNew, iCloseModeManual);
	    IF  iError <> 0 THEN
		Prompt ("MyFilter open error!");  
		RETURN iError;    
	    END;

	    ! Edit this filter by selecting alarms of Category 1 and Area 0 
	    iHndl = AlarmFilterEditOpen(sNamedFilter);
	    IF  iHndl <> -1 THEN;
		iError = AlarmFilterEditSet(iHndl,"Category=1;Area=0;");
		IF  iError = 0 THEN
		    iError = AlarmFilterEditCommit(iHndl);
		    IF  iError = 0 THEN
			iError = AlarmFilterEditClose(iHndl);
		    END
	    END
		    IF  iError <> 0 THEN
			Prompt ("MyFilter edit error!"); 
			RETURN iError;
		    END            
		 ELSE        
		    Prompt ("MyFilter hndl-edit error!");  
		    RETURN iHndl;    
		 END;


		 ! Associate this filter to the specified AN of Alarm page.
		 ! Other alarm pages can be linked in simmilar way. 
		 PageDisplay("Alarm");
		 iError = AlarmSetInfo(iAN, 12, sNamedFilter);
		 IF  iError <> 0 THEN
		     Prompt ("MyFilter link error!");  
		     RETURN iError;    
		 END

		 !  Retrieve associated filter name. Verify associated filter.
		 sLinkedFilter = AlarmGetFilterName(iAN);  // "MyFilter"
		 IF     sLinkedFilter <> sNamedFilter THEN
		      Prompt ("MyFilter get-name error!");  
		      RETURN iError;
		 END;

		 ! Count active alarms of this filter and verify against displayed alarms
		 iAlarmCounted = AlarmCount(0, sNamedFilter, 1,0);
		 iAlarmDisplayed = AlarmCountList(iAN);
		 IF  iAlarmCounted <> iAlarmDisplayed  THEN
		     Prompt ("Count verification error!");  
		     RETURN iError;
		 END;

		 ! disassociate "MyFilter"
		 iError = AlarmSetInfo(iAN, 12, "");
		 IF  iError <> 0 THEN
		     Prompt ("MyFilter unlink error!");  
		     RETURN iError;
		 END;

		 ! Verify disassociate action. 
		 sName = AlarmGetFilterName(iAN);  // ""
		 IF  sName <> sEmptyString THEN
		     Prompt ("MyFilter unlink error!");  
		     RETURN iError;
		 END;

		 ! Close this filter
		 iError = AlarmFilterClose(sNamedFilter);
		 IF     iError <> 0 THEN 
			Prompt ("MyFilter Close error!");
		 END;

		 RETURN iError;

	      END