Using GetMetadata to Get the Properties of a Specified Metadata Object

Filtering the Associated Objects That Are Returned By a GetMetadata Request

The GetMetadata method supports search criteria to filter the associated objects that it returns. The search criteria can be specified in both the <METADATA> element and in the <TEMPLATES> element. The search criteria enable you to retrieve only associated objects that are of a specified metadata type, or are of a specified metadata type and meet specified attribute criteria.

The search criteria is specified in a string in the association name element of the XML property string in one of the following forms:

<AssociationName search="Object"/>

<AssociationName search="Object[AttributeCriteria]"/>

Object can be an * (asterisk) or a SAS Metadata Model metadata type that is a valid associated object for the specified association name.

Specifying an * instructs the SAS Metadata Server to get objects of all metadata types that are valid for <ASSOCIATIONNAME>.

Specifying a metadata type name instructs the SAS Metadata Server to get only associated objects of the specified metadata type.
[AttributeCriteria] is an attribute specification that conforms to the syntax documented for the <XMLSELECT> option in Attribute Criteria Component Syntax. When attribute criteria are specified, GetMetadata retrieves only associated objects indicated by Object that also meet the specified attribute criteria.

This syntax has changed from SAS 9.1, which supported search criteria in the following form:

<AssociationName search="AttributeCriteria"/>

The SAS 9.2 syntax improves performance by enabling users to limit the number of metadata types on which the attribute criteria are evaluated. The older syntax form is still supported. It is the same as specifying the following:

"*[AttributeCriteria]"

Specifying Search Criteria in the <METADATA> Element

When specified in the <METADATA> element, the search criteria string looks like one of the following:

<Metadata>
  <MetadataType>
    <AssociationName search="Object"/>
  </MetadataType>
</Metadata>

<Metadata>
  <MetadataType>
    <AssociationName search="Object[AttributeCriteria]"/>
  </MetadataType>
</Metadata>

To understand the filtering that occurs, consider the following requests. In the first request, the <METADATA> element specifies to get the Document metadata object that has Id="A52WE4LI.AT0000RZ" and all objects that are associated with it through the Objects association name (all metadata types):

<GetMetadata>
   <Metadata>
      <Document Id="A52WE4LI.AT0000RZ">
          <Objects search="*"/>
      </Document>
   </Metadata>
   <NS>SAS</NS>
   <Flags>0</Flags>
   <Options/>
</GetMetadata>

The request is the same as specifying the association name without search criteria:

<GetMetadata>
   <Metadata>
      <Document Id="A52WE4LI.AT0000RZ">
         <Objects/>
      </Document>
   </Metadata>
   <NS>SAS</NS>
   <Flags>0</Flags>
   <Options/>
</GetMetadata>

In both requests, the GetMetadata method specifies to get requested attributes for the specified Document object (Id= only in this case) and all objects that are associated with it through the Objects association name. Here is an example of the output from the requests:

<!-- Using the GETMETADATA method. -->

<Document Id="A52WE4LI.AT0000RZ">
   <Objects>
     <PhysicalTable Id="A52WE4LI.B60000RT" Name="Table1" Desc="Sales table"/>
     <PhysicalTable Id="A52WE4LI.B60000RU" Name="Table2" Desc="Human Resources table"/>
     <ExternalTable Id="A52WE4LI.BA000001" Name="Oracle Sales" Desc="Sales information 
      from  Oracle database"/>
     <ExternalTable Id="A52WE4LI.BA000002" Name="Oracle HR" Desc="Human Resources
      information from Oracle database"/>
 </Objects>
</Document>

The specified Document object has four objects associated with it through the Objects association name: two PhysicalTable objects and two ExternalTable objects. By default, the GetMetadata method returns the Id=, Name= and Desc= values of the associated objects.

In this second request, a search string is used in the Objects association name of the <METADATA> element to filter the request to get only PhysicalTable objects that are associated with the specified Document object through the Objects association:

<GetMetadata>
   <Metadata>
      <Document Id="A52WE4LI.AT0000RZ">
          <Objects search="PhysicalTable"/>
      </Document>
   </Metadata>
   <NS>SAS</NS>
   <Flags>0</Flags>
   <Options/>
</GetMetadata>

Here is an example of the output from the request:

<!-- Using the GETMETADATA method. -->

<Document Id="A52WE4LI.AT0000RZ">
 <Objects>
    <PhysicalTable Id="A52WE4LI.B60000RT" Name="Table1" Desc="Sales table"/>
    <PhysicalTable Id="A52WE4LI.B60000RU" Name="Table2" Desc="Human Resources table"/>
</Objects>
</Document>

The ExternalTable objects that were returned in the first example are excluded from the output of this example.

In this third request, attribute criteria are added to the search criteria string in the <METADATA> element to further filter the request. The request specifies to get PhysicalTable objects that are associated with the specified Document object through the Objects association whose Desc= attribute value has the word Sales in it:

<GetMetadata>
   <Metadata>
      <Document Id="A52WE4LI.AT0000RZ">
          <Objects search="PhysicalTable[@Desc ? 'Sales']"/>       
      </Document>    
   </Metadata>   
   <NS>SAS</NS>
   <Flags>0</Flags>
   <Options/>
</GetMetadata>

Here is an example of the output from the request:

<!-- Using the GETMETADATA method. -->

<Document Id="A52WE4LI.AT0000RZ">
   <Objects>
     <PhysicalTable Id="A52WE4LI.B60000RT" Name="Table1" Desc="Sales table"/>
  </Objects>
</Document>

Specifying Search Criteria in the <TEMPLATES> Element

Templates are submitted to the GetMetadata method in the OPTIONS parameter in a <TEMPLATES> element. To submit a template, you must set the OMI_TEMPLATE (4) flag.

To understand how search criteria are processed in a template, consider the following request.

<GetMetadata>
   <Metadata>
      <Document Id="A52WE4LI.AT0000RZ"/>
   </Metadata>
   <NS>SAS</NS>
   <!-- OMI_TEMPLATE -->
   <Flags>4</Flags>
   <Options>
      <Templates>
         <Document MetadataCreated="" MetadataUpdated="">  
              <Objects search="ExternalTable[@Desc= ?  'Human Resources']"/> 
         </Document>
     </Templates>
 </Options>  
</GetMetadata>

In the method call, note the following:

The <METADATA> element specifies to get the Document metadata object that has Id="A52WE4LI.AT0000RZ".
The OMI_TEMPLATE flag (4) instructs the SAS Metadata Server to check for a template in the <OPTIONS> element.
The <TEMPLATES> element includes a template for the Document metadata type that specifies to get the Name=, Desc=, MetadataCreated= and MetadataUpdated= attributes of the Document object, and any ExternalTable objects that are associated to the specified Document through the Objects association and whose Desc= attribute has the words Human Resources in it.

Here is an example of the output from the request:

<!-- Using the GETMETADATA method. -->

<Document Id="A52WE4LI.AT0000RZ" MetadataCreated="22Aug2008:14:52:24"  
MetadataUpdated="22Aug2008: 16:08:45">
  <Objects>
      <ExternalTable Id="A52WE4LI.BA000002"/>
   </Objects>
</Document>

Note: When the OMI_TEMPLATE flag is set, GetMetadata gets only the Id= attribute for associated objects. If you want to get additional attributes, you need to specify them in another template, or set a flag such as OMI_ALL_SIMPLE (8), which gets all attributes for the specified object and all associated objects. [cautionend]

Specifying Search Criteria in Both Elements

When search criteria are specified in both the <METADATA> and <TEMPLATES> elements, the following rules apply:

If the search criteria strings specify different association names, both are applied.
If the search criteria strings specify the same association name, the search criteria string in the <TEMPLATES> element is ignored.

For example, consider this request:

<GetMetadata>
   <Metadata>
      <Document Id="A52WE4LI.AT0000RZ">
          <Objects search="ExternalTable[@Desc ? 'Sales']"/>
      </Document>
   </Metadata>
   <NS>SAS</NS>
   <!-- OMI_TEMPLATE flag -->
   <Flags>12</Flags>
   <Options>
     <Templates>
      <Document>
          <Objects search="PhysicalTable[@Desc ? 'Sales']"/>
      </Document>
   </Templates>
 </Options>
</GetMetadata>

Before any metadata is retrieved, the properties in the <METADATA> and <TEMPLATES> elements are merged into one list that is used to get the metadata objects. The properties in the <METADATA> element take priority over properties in the <TEMPLATES> element. As a result, additional properties that are specified in the template are added to the list. However, any properties that are duplicated in the template are ignored.

In this example, although the search criteria in the <METADATA> element and in the <TEMPLATES> element specify different metadata types, they specify the same association name (Objects), so the search criteria in the <TEMPLATES> element is ignored. Because the OMI_TEMPLATE flag is set, the SAS Metadata Server returns only the Id= value of the specified object and its associated objects.

Now, consider the following request:

<GetMetadata>
   <Metadata>
     <Document Id="A52WE4LI.AT0000RZ">
         <ResponsibleParties  search="ResponsibleParty[@Name  ? 'Writer']"/>
     </Document>
   </Metadata>
   <NS>SAS</NS>
   <!-- OMI_TEMPLATE + OMI_ALL_SIMPLE + OMI_SUCCINCT flags -->
   <Flags>2060</Flags>
   <Options>
     <Templates>
      <ResponsibleParty>
          <Persons search="*"/>
      </ResponsibleParty>
   </Templates>
 </Options>
</GetMetadata>

In this request, note the following:

The <METADATA> element specifies to get Document A52WE4LI.AT0000RZ and a search criteria string on the ResponsibleParties association. The search criteria string specifies to get ResponsibleParty objects that are associated to the specified Document object. The search criteria further specify to get only ResponsibleParty objects that have the word Writer in their Name= attribute.
The sum of the OMI_TEMPLATE (4) + OMI_ALL_SIMPLE (8) + OMI_SUCCINCT (2048) flags instructs the SAS Metadata Server to check for a <TEMPLATES> element in the <OPTIONS> element, get all attributes for the specified object and associated objects, and to omit attributes that do not contain a value or that contain a null value from the results.
The <OPTIONS> element includes a template in the <TEMPLATES> element that specifies to get objects associated with the returned ResponsibleParty objects through the Persons association.

Here is an example of the output returned by the SAS Metadata Server:

 <!-- Using the GETMETADATA method. -->

<Document Id="A52WE4LI.AT0000RZ" Name="AugustPerformance" Desc="Summary report of 
NW Region production activity, HR expense, and sales" MetadataCreated=
"22Aug2008:14:52:24" MetadataUpdated="22Aug2008: 16:08:45" PublicType="Document" 
URI="Text" UsageVersion="1000000">
   <ResponsibleParties search="ResponsibleParty[@Name  ? 'Writer']">
      <ResponsibleParty Id="A52WE4LI.BN000003"  Name="Technical Writer" 
MetadataCreated="22Aug2008:14:52:24" MetadataUpdated="22Aug2008: 16:08:45" 
UsageVersion="1000000" >
         <Persons SEARCH="*">
            <Person Id="A52WE4LI.AR0002BE" Desc="Primary Writer" MetadataCreated=
"22Aug2008:14:52:24"  MetadataUpdated="22Aug2008: 16:08:45" Name="Melissa Mark" 
PublicType="User" UsageVersion="1000000" />
         </Persons>
     </ResponsibleParty>
   </ResponsibleParties>
</Document>

The results show that one ResponsibleParty object is associated with Document A52WE4LI.AT0000RZ through the ResponsibleParties association that has the word Writer in its Name= attribute. In turn, this ResponsibleParty object has one object associated with it through the Persons association that describes a person named Melissa Mark.

Top of Page