Revision history:

Introduced in QPR 7.6.1

Last changed in QPR 2016.1.0

 

Returns a list of IDs of QPR Metrics model elements defined by search parameters and filter criteria. First elements are fetched based on search parameters, then the list of found elements is filtered based on filter criteria which is an optional parameter. The Find command supports all SCModel element types which have IDs.

 

Synopsis:

 

SCModel.Find(Parameters, Criteria, SortBy, out ListOfElements)

 

Parameters:

 

Parameters: A semicolon-separated list of parameters for defining the search base. Supported keywords are:

•IDS = Comma-separated list of object IDs. In the case this is omitted, the default value "" (all objects) is used. Inserting a value here causes the SCORECARDIDS parameter to be ignored.

•SCORECARDIDS = Comma-separated list of scorecard IDs. In the case this is omitted, the default value “” (all scorecards) is used. This parameter is used to restrict the search base to certain scorecards. However, this parameter is ignored if the IDS parameter is defined and other than "".

•PARENTS = Comma-separated list of element IDs. In the case this is omitted, the default value “” (ignore parents) is used. PARENTS=NULL searches for elements that have no parents.

•INCLUDECHILDREN = 0 | 1 |  2. Defines whether the search is done also for all the child elements (scorecards or measures) of the elements in the search base. 0 = no (default), 1 = yes, 2 = only first level children are included.

•INCLUDEREFERENCE = 0 | 1 | 2. Defines whether the search is done also for all the reference elements (measures) of the elements in the search base. 0 = no (default), 1 = yes, 2  = search is done only for reference elements. NOTE! This parameter can be used to find and return reference elements of selected original element(s).

•ELEMENTTYPES = Comma-separated list of element type names or IDs. In the case this is omitted, the default value "" (all element types) is used. Supported element type names: SCORECARD, ELEMENT, INFORMATIONITEM, PERIOD, PERIODLEVEL, RANGE, SERIES, VALUESETTING, INTEGRATION, UNIT, CHARTTEMPLATE, ALERT, LINKEDDATA, + all user-defined element and linked element types.

•RESOLVEREFERENCES = 0 | 1. Defines if the criteria is queried also from the reference element or only from the original measure. 0 = criteria is queried also from the reference element, 1 or any other integer = criteria is queried from the original measure (default).

Criteria: An expression that must return true for an element in order for it to be returned in the result list. Supported expressions include:

•Logical operators: AND, OR, NOT. Note that these are case sensitive, so only the uppercase versions work.

•Binary comparison operators: =, <>, <, <=, >, >=

•Mathematical operators: +, -, *, /, ^

•String constants using double quotes: “string constant”

•Parentheses to group expressions and enforce calculation order: ()

•Find function:

oExpression: Find(<what>, <attribute>)

•Parameters:

▪<what> = Text to match (usually a string constant)

▪<attribute> = Element attribute (see list of supported attributes in GetProperty)

oReturn value: True if the text is found in the given action attribute.

•Any combination of these:

oFind(“MEA”, Symbol) OR (Owner.LoginName = “qpr”)

Note: Since string constants are defined using double quotes in VBScript, they must be escaped correctly (by doubling the double quotes).

SortBy: A comma-separated list of element attributes possibly prefixed by a dash ("-“) character. SortBy defines the output list order. If SortBy is an empty string then elements are not sorted at all, meaning that the order of elements may differ between successive runs. If an element attribute is prefixed with a dash, then that element attribute is used for descending sorting. Otherwise ascending sorting is used. See the list of supported attributes in GetProperty.

out ListOfElements: Variant for storing an array which contains the elements matching the search base and sorted in the order defined by the SortBy parameter.

 

Required Rights:

 

View rights to SCModel.

 

Return Values:

Below are listed the return values that this function can return:

 

RV_SUCCESS

RV_MODEL_NOT_OPEN

RV_APPLICATION_QUIT_CALLED

RV_NOT_CONNECTED_TO_SERVER

RV_NOT_AUTHENTICATED

RV_NO_RIGHTS

RV_TYPE_NOT_FOUND

RV_UNKNOWN_ERROR

 

Example Procedures:

 

iRet = SCModel.Find("SCORECARDIDS=12345,67890;ELEMENTTYPES=SCORECARD,ELEMENT", _

        "Owner.LoginName = ""jsmith""", "CREATEDDATE", olElements)

'Finds all scorecards and measures in scorecards with IDs 12345 and 67890 owned by jsmith

'and sorts them by creation date.

iRet = SCModel.Find("SCORECARDIDS=12345;ELEMENTTYPES=ELEMENT;INCLUDEREFERENCE=2", _

        "", "SYMBOL", olElements)

'Finds all reference elements pointing at elements in scorecard with ID 12345 and sorts the

'results by symbol.