<XMLSELECT search="criteria"/> Syntax

General Syntax

The <XMLSELECT> element is specified in the OPTIONS parameter in the following form:

<XMLSELECT search="criteria"/>

The syntax of criteria varies depending on whether you are specifying attribute criteria, association path criteria, or both.

A statement that specifies only attribute criteria on the metadata type defined in the GetMetadataObjects TYPE parameter can be specified as one of the following:

AttributeCriteria

(AttributeCriteria)

Object[AttributeCriteria]

A statement that concatenates attribute criteria is specified as one of the following:

AttributeCriteria and|or  AttributeCriteria

(AttributeCriteria and|or 
AttributeCriteria)

Object[AttributeCriteria  and|or 
AttributeCriteria]

In a statement that specifies only attribute criteria, the brackets and parentheses around the criteria are optional. For all other syntax combinations, the brackets and parentheses must be specified as shown.

A statement that specifies both attribute criteria and an association path as criteria is specified as follows:

Object[AttributeCriteria][AssociationPath]

A statement that specifies only an association path as criteria is specified as follows:

Object[AssociationPath]

A statement that specifies an association path that has multiple association levels defined is specified as follows:

Object[AssociationPathLevel1/AssociationPathLevel2/AssociationPathLeveln]

A statement that concatenates association path criteria can be specified as follows:

Object[AssociationPath1][AssociationPath2][AssociationPath3]

Object[AssociationPath1] or [AssociationPath2] or [AssociationPath3]

Object[AssociationPath1] and [AssociationPath2] and [AssociationPath3]

Object[AssociationPath1] and [AssociationPath2] or [AssociationPath3]

The first example has an implied AND logical operator between association paths.

A statement that specifies the NOT logical operator in attribute criteria is specified as follows:

not(criteria)

Object[not(criteria)]

A statement that specifies the NOT function is specified as follows:

object[not(AssociationPath)]

object[not(AssociationPathLevel1/AssociationPathLevel2)]

Object Component

The Object component is required for all searches except simple attribute criteria searches. It specifies the object class type. Valid values are a metadata type name or an asterisk (*).

The metadata type can be the same metadata type that is specified in the GetMetadataObjects TYPE parameter or a subtype of the metadata type. To determine the subtypes of a metadata type, see the metadata type descriptions in the SAS Metadata Model: Reference.
An * (asterisk) is a shorthand method of referring to the metadata type specified in the TYPE parameter.

AttributeCriteria Component

The AttributeCriteria component is optional. It enables you to filter the objects that are selected to objects matching a specified attribute=value pair. The syntax of AttributeCriteria is as follows:

[@attrname cop 'value' lop AttributeCriteria]

@attrname specifies an attribute name (for example, @Name or @Desc).
cop is a comparison operator. The supported comparison operators include:

=:

Begins with the specified character string. Numeric and datetime values are not supported. MISSING character value is supported.

?, contains, or CONTAINS

Contains the specified character string. Numeric and datetime values are not supported. MISSING character value is supported.

=, eq, or EQ

Equal to the specified character string, numeric, datetime, or MISSING value.

ne, NE

Not equal to the specified character string, numeric, datetime, or MISSING value.

ge, GE

Greater than or equal to the character string, numeric, or datetime value. MISSING value not supported.

gt, GT

Greater than the character string, numeric, or datetime value. MISSING value not supported.

le, LE

Less than or equal to the character string, numeric, or datetime value. MISSING value not supported.

lt, LT

Less than the character string, numeric, or datetime value. MISSING value not supported.
'value' is a character or numeric string enclosed within single quotation marks.

Character Strings:

Searches of character strings compare the <XMLSELECT search="criteria"/> search pattern value with the attribute data value and determine which string appears first in a sorted list. The sort order is based on the collating sequence for the specified locale. If either the data or pattern values contain any characters that are not in the locale's collation list, the locale determines how to order the unknown characters.

Missing Values:
- To search for a MISSING numeric or datetime attribute value, specify a period enclosed within single quotation marks.
- To search for a MISSING character attribute value, specify two adjacent single quotation marks.
“V” in an Attribute’s Length Limit:

When evaluating attributes that have a “Vn” in the Length limit, for example “V64”, the search process evaluates only the n number of characters to make the selection. A “Vn” in the Length limit indicates the property is arbitrarily large. The documented length (n) is the maximum length that can be stored before an overflow algorithm is invoked. Storing a string that exceeds the documented length causes one or more TextPage objects and corresponding associations that connect them to the original object to be created to store the string. The search process does not search these “overflow” objects.

Datetime Values:

In the current release, searches by date or by time are not supported. However, the SAS Metadata Server supports datetime queries on the MetadataCreated and MetadataUpdated attributes. The supported DATETIME formats are the following:
- ddmmmyyyy:hh:mm:ss.s
- ddmmmyyyy:hh:mm:ss
- a SAS date value that represents a ddmmmyyyy:hh:mm:ss value
- a MISSING datetime '.' value
The DATE format ddmmmyyyy is not supported.

Datetime queries are supported only in the standard interface. For more information about how to issue SAS Open Metadata Interface methods, see Communicating with the SAS Metadata Server.

Note: Objects are persisted to disk with a GMT datetime value. Therefore, an object created in local time might have a different datetime value on disk. For example, an object created at '30May2003:16:20:01' CST could have a persisted datetime value of '30May2003:21:20:01'. To accommodate the storage conversion, the SAS Metadata Server converts values that you specify in a search string to GMT values for you. However, the datetime values returned by the server look different from the values that you submitted in the search string.

The following are examples of queries in the supported formats:
```
<XMLSELECT search="*[@MetadataCreated GT '27May2003:09:20:17.2']"/>
<XMLSELECT search="*[@MetadataCreated LT '27May2010:09:20:17']"/>
<XMLSELECT search="*[@MetadataCreated GT '1309907400']"/>
<XMLSELECT search="*[@MetadataUpdated EQ '.']"/>
```
In the third example, '1309907400' is the SAS date value for '30May2003:19:03:11' GMT.
lop is the logical operator AND or OR. It enables you to specify an additional AttributeCriteria string that is appended to and concatenated with the first AttributeCriteria string. AND specifies that both conditions must be met for an object to be selected for retrieval. OR specifies that either condition can be met for an object to be selected. An example of an OR comparison is the following:
```
  [@Name = 'John Doe' or @Name = 'Jane Doe']
```
Compound attribute criteria are also supported. Use parentheses to control evaluation order. For example:
```
search="*[@ProductName='SAS/CONNECT' and 
(@Name contains 'test - SAS/CONNECT Server' or @Name='test')]"
```
In this example, the expression enclosed within the parenthesis is evaluated first.

Note: Whether single, concatenated, or compound attribute criteria are used, the attribute test is applied only if all of the specified attribute names are valid for the object. That is, if one of the attribute names in the attribute string is misspelled, then no objects are selected. If the OMI_INCLUDE_SUBTYPES flag is set with OMI_XMLSELECT, the metadata type and subtype objects to be tested might support a different set of attribute names. Only objects that contain all of the specified attribute names are tested for a match.

NOT Logical Operator in AttributeCriteria Component

Beginning in SAS 9.3, the XMLSELECT search syntax supports a NOT logical operator for attribute criteria. The NOT logical operator returns object instances of the requested metadata type that do not have the specified value in the specified attribute. For example, the following search string returns Person objects with values other than 'Senior' in the Title attribute:

<XMLSelect search="Person[not(@Title ? 'Senior')]"/>

The NOT logical operator must be specified before the attribute criteria that it qualifies in the search string. And, the attribute criteria must be enclosed within parentheses. For example:

not(criteria)

object[not(criteria)]

NOT is supported in concatenated attribute criteria as follows:

not (criteria) and  not (criteria)

The preceding NOT (criteria) request specifies to omit object instances that meet the first criteria, and to omit object instances that meet the second criteria.

Valid use of the NOT logical operator for attribute criteria in an association path specification is as follows:

*[AssociationName/AssociatedObject[not(criteria)]]

The string specifies to return object instances that have the specified association, and that do not meet the specified attribute criteria.

You might want to use the NOT logical operator for attribute criteria in association paths to find object instances that do not meet the specified attribute criteria, and have the specified association and an associated object that meets the specified attribute criteria:

*[not(criteria)][AssociationName/AssociatedObject [criteria]]

For an example of how the NOT logical operator can be used in a GetMetadataObjects request, see Examples of How the New Template Form Can Be Used. The example uses the NOT logical operator in the Search attribute that is specified on an association name in a template to filter the associated objects that are retrieved.

For information about how to get objects that do not have a specified association, see NOT Function in the AssociationPath Component.

AssociationPath Component

The AssociationPath component enables you to specify one or more associations as search criteria. To be selected, the objects specified in the Object component must have an association that meets the criteria in AssociationPath.

The syntax of AssociationPath is as follows:

Object[AssociationPath] AND | OR [AssociationPathn]

Each AssociationPath is the following:

[AssociationPathLevel1/AssociationPathLevel2/AssociationPathLeveln]

And, AssociationPathLevel is the following:

AssociationName/AssociatedObject[AttributeCriteria]

In the syntax, Object can be a metadata type name or an asterisk. For more information, see Object Component.

Each AssociationPath specifies one association of Object to evaluate.

An AssociationPath specification can include one or many association path levels. The first AssociationPathLevel identifies the association of Object that will be evaluated. Each subsequent level filters the objects that are returned for this first association by specifying additional associations, associated metadata types, and attribute criteria that the first set of objects must match in order to be selected. For more information, see Understanding How Association Paths Are Evaluated. Each AssociationPathLevel within the AssociationPath is separated from the other levels by a slash (/).AttributeCriteria is optional in an AssociationPathLevel.