AFEventFrame.FindEventFramesByAttribute Method (AFEventFrame, Object, Int32, Int32, AFEventFrameSearchMode, String, String, AFDurationQuery[], AFAttributeValueQuery[], Boolean)

[BrowsableAttribute(false)]
[ObsoleteAttribute("This method has been replaced by the 'AFEventFrameSearch' class using the 'Root', 'Start', 'Name', 'ElementName', 'Duration' and attribute value filters.")]
public static AFNamedCollectionList<AFEventFrame> FindEventFramesByAttribute(
	AFEventFrame searchRoot,
	Object startTime,
	int startIndex,
	int maxCount,
	AFEventFrameSearchMode searchMode,
	string nameFilter,
	string referencedElementNameFilter,
	AFDurationQuery[] durationQuery,
	AFAttributeValueQuery[] valueQuery,
	bool searchFullHierarchy
)

<BrowsableAttribute(false)>
<ObsoleteAttribute("This method has been replaced by the 'AFEventFrameSearch' class using the 'Root', 'Start', 'Name', 'ElementName', 'Duration' and attribute value filters.")>
Public Shared Function FindEventFramesByAttribute ( 
	searchRoot As AFEventFrame,
	startTime As Object,
	startIndex As Integer,
	maxCount As Integer,
	searchMode As AFEventFrameSearchMode,
	nameFilter As String,
	referencedElementNameFilter As String,
	durationQuery As AFDurationQuery(),
	valueQuery As AFAttributeValueQuery(),
	searchFullHierarchy As Boolean
) As AFNamedCollectionList(Of AFEventFrame)

Dim searchRoot As AFEventFrame
Dim startTime As Object
Dim startIndex As Integer
Dim maxCount As Integer
Dim searchMode As AFEventFrameSearchMode
Dim nameFilter As String
Dim referencedElementNameFilter As String
Dim durationQuery As AFDurationQuery()
Dim valueQuery As AFAttributeValueQuery()
Dim searchFullHierarchy As Boolean
Dim returnValue As AFNamedCollectionList(Of AFEventFrame)

returnValue = AFEventFrame.FindEventFramesByAttribute(searchRoot, 
	startTime, startIndex, maxCount, 
	searchMode, nameFilter, referencedElementNameFilter, 
	durationQuery, valueQuery, searchFullHierarchy)

public:
[BrowsableAttribute(false)]
[ObsoleteAttribute(L"This method has been replaced by the 'AFEventFrameSearch' class using the 'Root', 'Start', 'Name', 'ElementName', 'Duration' and attribute value filters.")]
static AFNamedCollectionList<AFEventFrame^>^ FindEventFramesByAttribute(
	AFEventFrame^ searchRoot, 
	Object^ startTime, 
	int startIndex, 
	int maxCount, 
	AFEventFrameSearchMode searchMode, 
	String^ nameFilter, 
	String^ referencedElementNameFilter, 
	array<AFDurationQuery>^ durationQuery, 
	array<AFAttributeValueQuery>^ valueQuery, 
	bool searchFullHierarchy
)

[<BrowsableAttribute(false)>]
[<ObsoleteAttribute("This method has been replaced by the 'AFEventFrameSearch' class using the 'Root', 'Start', 'Name', 'ElementName', 'Duration' and attribute value filters.")>]
static member FindEventFramesByAttribute : 
        searchRoot : AFEventFrame * 
        startTime : Object * 
        startIndex : int * 
        maxCount : int * 
        searchMode : AFEventFrameSearchMode * 
        nameFilter : string * 
        referencedElementNameFilter : string * 
        durationQuery : AFDurationQuery[] * 
        valueQuery : AFAttributeValueQuery[] * 
        searchFullHierarchy : bool -> AFNamedCollectionList<AFEventFrame> 

Parameters

searchRoot

Type: OSIsoft.AF.EventFrameAFEventFrame
The root object to start the search. If , then the search starts at the AFDatabase.

startTime

Type: SystemObject
An object representing the starting time to begin the search. The search may compare against either the StartTime or EndTime of the event frame based on the searchMode parameter. The value may be an AFTime, DateTime, PITime, String, or numeric. A DateTime (or a DATE will be treated as UTC time if its Kind property is set to Unspecified. Because DATE values from COM or VB6 clients are marshalled as Unspecified, these client applications must convert to UTC prior to marshalling. An integer numeric represents the number of ticks (100-nanosecond intervals) since January 1, 0001. A floating point numeric represents the number of seconds since January 1, 1970 UTC. A String is interpreted as local time, unless it contains a time zone indicator such as a trailing "Z" or "GMT". Strings will be interpreted with the AFTime.Parse Overload methods so that relative formats with intervals ("*", "T+3h", etc.) are also supported. Relative time intervals are based on the object's QueryDate.

startIndex

Type: SystemInt32
The starting index (zero based) of the items to be returned.

maxCount

Type: SystemInt32
The maximum number of event frames to be returned.

searchMode

Type: OSIsoft.AF.EventFrameAFEventFrameSearchMode
Indicates the direction in time from the StartTime or EndTime to proceed when returning event frames.

nameFilter

Type: SystemString
The name filter string used for finding objects.

The query string (or match pattern) can include regular characters and wildcard characters. Regular characters must match exactly the characters specified in the query string. Wildcard characters can be matched with arbitrary fragments of the query string. Wildcard characters can be escaped using the single backslash (\) character. Use a double backslash (\\) to match a single backslash. The syntax of the query string has the following rules:

• If or empty string, then everything will be matched.
• If no wildcards, then an exact match on the query string is performed.
• Wildcard * can be placed anywhere in the query string and matches zero or more characters.
• Wildcard ? can be placed anywhere in the query string and matches exactly one character.
• One character in a set of characters are matched by placing them within [ ]. For example, a[bc] would match 'ab' or 'ac', but it would not match 'ad' or 'abd'.
• One character in a set of characters are not matched by placing them within [! ]. For example, a[!bc] would match 'ad', but it would not match 'ab', 'ac', or 'abd'.
• A character in a range of characters from first to last are matched using the following syntax: [first - last]. For example, a[a-c] would match 'aa', 'ab', or 'ac', but it would not match 'ad' or 'abc'.

referencedElementNameFilter

Type: SystemString
The name filter string of an AFElement in the event frame's ReferencedElements collection. Uses same filtering rules as specified for the nameFilter parameter. To obtain an exact match to a specific element, specify the element's ID using a format that includes the opening and closing braces, such as ID.ToString("B").

durationQuery

Type: OSIsoft.AF.EventFrameAFDurationQuery
An array of duration queries that are ANDed together to find the desired AFEventFrame objects. To not filter by duration, set this parameter to .

valueQuery

Type: OSIsoft.AF.AssetAFAttributeValueQuery
An array of attribute value queries that are ANDed together to find the desired AFEventFrame objects. At least one value query must be specified.

searchFullHierarchy

Type: SystemBoolean
Specifies if the search should include objects nested further than the immediate children of the searchRoot.

Return Value

An object matches the search if the specified nameFilter is found in the object's Name property and the attribute's value matches the specified attribute value query conditions. This method will return all event frames from the specified time up to the specified maximum count.

This will only return objects of type AFEventFrame. Types of event frames that inherit from AFEventFrame will not be returned. Use the specific find methods to return types of event frames that inherit from AFEventFrame.

How results are returned from an AFAttributeValueQuery search depends on whether the attribute template IsIndexed property is set and which AFSearchOperator is used for the search. If the attribute template has the IsIndexed property is set to , then an indexed search value is stored in the PI AF Server which is truncated to 40 characters for string values so that performance is improved. By default, attribute values are not indexed.

Searching attributes with an AFDataReference defined will be slower because the value does not exist on the server. Each attribute's AFDataReference must be executed on the client to obtain the value to evaluate the query. If the AFAttributeTemplate does not define a DataReferencePlugIn and an AFAttribute overrides the template by setting its DataReferencePlugIn, then the attribute's value from the DataReference will not be used when evaluating the query. This could cause unexpected results to be returned from this method. Therefore, an AFDataReference should be defined on the template if it will be used in a query and an AFAttribute will be defining a DataReference.

Important

This will only search event frames that have been checked into the server. If the attribute's IsConfigurationItem property is , then only the attribute values that have been checked into the server will be searched. If the attribute's values have been captured for the event frame (the AreValuesCaptured property is ), then only the attribute values that have been captured and checked into the server will be searched.

Important
The value of any attributes used in the query with a configured DataReference will be evaluated on the client. This means that additional results could be removed from those returned from the server and therefore return less than the specified maxCount.

Important
Consider using the new AFEventFrameSearch class for finding event frames instead of using this method.

AFSDK

Reference