Using GetMetadata to Get the Properties of a Specified Metadata Object

Using Templates

A template is a property string that you specify in a <TEMPLATES> element. In a GetMetadata or GetMetadataObjects method call, the <TEMPLATES> element is passed in the <OPTIONS> element to request additional properties for the metadata type specified in the main element of the method call, its subtypes, or its associated objects. The purpose of the template is to expand or to filter the properties requested by other GetMetadata and GetMetadataObjects parameters.

This section describes how to create a template and contains examples of GetMetadata and GetMetadataObjects requests that specify templates.

Creating a Template

A template is an XML property string that specifies the information that should be returned for a metadata type. The string includes the attributes and associations that should be returned for the metadata type. The string should not request properties for associated objects. Instead, additional templates should be created to request properties for associated objects.

For example, the following is a template for a PhysicalTable object that gets the object's ID, the date when the table was created, and the Column objects associated with the table:

<PhysicalTable Id="" MetadataCreated="">
   <Columns/>
</PhysicalTable>

To get properties for the requested Column objects, you should submit an additional template that looks like the following:

<Column Name="" SASFormat=""/>

The SAS Metadata Server gets the Name= and SASFormat= values for the Column objects requested by the first template.

Templates are passed to the SAS Metadata Server in a <TEMPLATES> element in the <OPTIONS> element of a method call. When the <TEMPLATES> element is used in a GetMetadata method call, the OMI_TEMPLATE (4) flag must also be set to instruct the SAS Metadata Server to check for the <TEMPLATES> element.

When the <TEMPLATES> element is used in a GetMetadataObjects method call, both the OMI_GET_METADATA (256) flag and the OMI_TEMPLATE (4) flag must be set. The OMI_GET_METADATA flag instructs the SAS Metadata Server to issue a GetMetadata call for each object that is returned by the GetMetadataObjects method to apply the templates specified in the <TEMPLATES> element.

The following is an example of a <TEMPLATES> element that passes the two templates previously described:

<Templates>
   <PhysicalTable Id="" MetadataCreated="">
     <Columns/>
   </PhysicalTable>
   <Column Name="" SASFormat=""/>
</Templates>

The metadata type specified in a template can be the same metadata type specified in the <METADATA> element of the GetMetadata request (or the <TYPE> element of a GetMetadataObjects request), a subtype, or the metadata type of an associated object. In the preceding examples, the object requested in the main element is assumed to be a PhysicalTable metadata object.

The order of the templates in the <TEMPLATES> element is not important unless the OMI_INCLUDE_SUBTYPES (16) flag is also set. The default behavior of the SAS Metadata Server is to search for objects of every metadata type listed in the <TEMPLATES> element, and to get the specified properties if objects are found. When OMI_INCLUDE_SUBTYPES is set, the SAS Metadata Server cycles through the templates iteratively, beginning with the first template and proceeding in order to the last template, and gets the specified properties of the specified metadata type and its subtypes. If a template for a subtype is found before a template for its supertype, then the subtype's template is applied, and there is no more searching for the supertype.

Specifying Search Criteria in a Template to Filter Associated Objects

Both the GetMetadata and GetMetadataObjects methods support specifying search criteria for the association names in the <METADATA> element and in the <TEMPLATE> element to filter the associated objects that are retrieved by a request. The search criteria enable you to get only associated objects that are the specified metadata type, or are the specified metadata type and also meet specified attribute criteria.

For information about using search criteria strings in the GetMetadata method, see Filtering the Associated Objects That Are Returned By a GetMetadata Request. For information about using search criteria strings in the GetMetadataObjects method, see Filtering the Associated Objects That Are Retrieved By a GetMetadataObjects Request.

Top of Page