Understanding Templates

A template is a metadata property string that you specify in the <TEMPLATES> element in the OPTIONS parameter of a GetMetadata, GetMetadataObjects, or DeleteMetadata method call. The template is submitted to the SAS Metadata Server with the OMI_TEMPLATE (4) flag. In GetMetadataObjects, you must set the OMI_GET_METADATA (256) flag in addition to OMI_TEMPLATE.

In a GetMetadata or GetMetadataObjects method call, a template specifies attributes or associations to retrieve for the main metadata type of the method call, one of its subtypes, or an associated metadata type. This is beyond attributes and associations that are requested in the INMETADATA parameter and by the method's flags. While the OMI_ALL flag returns all attributes and directly associated objects for the specified object, and the OMI_SIMPLE flag returns all simple attributes for the specified object and any associated objects that are requested, neither flag affects the associations of the associated objects.

A template enables you to exactly specify the attributes and associations that you want to retrieve for a specified metadata type. The specified metadata type can be the main metadata type in the request or an associated metadata type. To request associations of associated objects, you specify additional templates.

Prior to SAS 9.3, user-defined templates were the only way to retrieve information about the associations of associated objects. In SAS 9.3, SAS provides the OMI_FULL_OBJECT (2) flag. The OMI_FULL_OBJECT flag returns the full logical metadata definition of objects that are managed by the SAS type dictionary. For more information, see Using the OMI_FULL_OBJECT Flag.

User-defined templates can be used to expand the logical metadata definitions of objects that are not managed by the SAS type dictionary. You can also use templates to get some of the information that would be returned by the OMI_FULL_OBJECT flag.

In a DeleteMetadata method call, a user-defined template enables you to specify association names that should be traversed to locate associated objects to be deleted in addition to the specified metadata object. If the specified metadata object is managed by the SAS type dictionary, the user-defined template overrides information about the object’s logical metadata definition from the SAS type dictionary, which would normally be used to delete the metadata object and its associated objects.

In SAS 9.3, you can submit templates using one of two template forms:

Using multiple named templates is useful when you need to access many different logical groupings of metadata objects in the same request. For example, when multiple metadata property strings are submitted in the GetMetadata or DeleteMetadata method’s INMETADATA parameter, the TemplateName attribute can direct the SAS Metadata Server to the appropriate template to expand each request. When associated objects are requested in a template, the TemplateName attribute can redirect the SAS Metadata Server to another template for processing, before returning to the initial template.

The new form also supports attributes that enable you to specify different handling of object instances of the same metadata type. These template attributes are described in Template Attributes.

When a request specifies multiple templates, it is easy to specify associations that refer back to each other. SAS 9.3 introduces the OMI_NOEXPAND_DUPS (524288) flag to track the objects that are expanded by templates by ID, and to prevent the server from expanding an object more than once. For more information, see Templates and the OMI_NOEXPAND_DUPS Flag.

For information about creating templates, see the following:

The following table shows attributes that are supported in a template. These attributes filter the objects and information about the objects that are returned.

* The Location field refers to these locations within a template:

<MetadataType>
   <AssociationName Search="">
    <AssociatedMetadataType Match="" TemplateExpand="" TemplateName=""/>
   </AssociationName>
</MetadataType>

The Match and Search attributes support the full syntax that is available for the GetMetadataObjects <XMLSELECT search="criteria"/> option. In previous SAS releases, the Search attribute supported a subset of the syntax. For more information about the syntax, see <XMLSELECT search="criteria"/> Syntax.

For more information about using the attributes, see Creating Templates for the Get Methods and Form of a DeleteMetadata Template.