Expanding a GetMetadataObjects Request to Return Additional Properties :: SAS(R) 9.3 Open Metadata Interface: Reference and Usage

Introduction to the OMI_GET_METADATA Flag

You can expand a GetMetadataObjects method call to get additional properties by setting the OMI_GET_METADATA (256) flag and specifying flags defined for the GetMetadata method in the GetMetadataObjects request.

The OMI_GET_METADATA flag issues a GetMetadata request for each metadata object that is returned by the GetMetadataObjects method. Specifying one or more other GetMetadata flags with OMI_GET_METADATA enables you to get all properties or specific categories of properties for each metadata object.

The GetMetadataObjects method supports the following GetMetadata flags for requesting additional properties:

OMI_ALL (1)—Gets all of the attributes and associations of the specified object, and general, identifying information about any associated objects. For more information, see Example of Retrieving All Properties for All Objects.
OMI_SUCCINCT (2048)—Omits all properties that do not contain a value or that contain a null value from the output. For more information, see Suppressing Properties That Do Not Store Values from GetMetadataObjects Output.
OMI_ALL_SIMPLE (8)—Gets all of the attributes of the specified object and any associated objects requested by other flags. For more information, see Example of Retrieving Only Attributes of Objects.
OMI_TEMPLATE (4) — Instructs the SAS Metadata Server to check the <OPTIONS> element for user-defined templates that define which metadata properties to return. The templates can request additional properties for the specified metadata objects, as well as attributes and associations for associated metadata objects. Templates are specified in a <TEMPLATES> element. For more information, see Example of Retrieving Specified Attributes of All Objects. Also see Example of Retrieving Associated Objects for All Objects.

Specifying OMI_GET_METADATA and Other GetMetadata Flags

To specify a GetMetadata flag in a GetMetadataObjects request, add the flag's value to the OMI_GET_METADATA flag and to any other GetMetadataObjects flags that you have set. For example, if OMI_XMLSELECT (128) is already set, and you want to specify OMI_GET_METADATA (256) and OMI_ALL_SIMPLE (8) to get all of the attributes of each object, add their values together (128+256+8=392) and specify the sum in the FLAGS parameter.

Combining GetMetadata and GetMetadataObjects Flags

The flags in this section can be combined with other GetMetadataObjects flags.

When GetMetadata flags are used with the OMI_INCLUDE_SUBTYPES (16) flag, the GetMetadataObjects method gets the specified properties for all subtypes of the specified metadata type, in addition to all objects of the specified metadata type.
When GetMetadata flags are used with the OMI_XMLSELECT (128) flag, the GetMetadataObjects method gets the specified properties only for metadata objects that meet <XMLSELECT> search criteria.
When GetMetadata flags are used with the OMI_DEPENDENCY_USES (8192) flag, the GetMetadataObjects method gets the specified properties for objects of the specified metadata type in all public repositories (the foundation repository and all custom repositories). When GetMetadata flags are used with the OMI_DEPENDENCY_USED_BY (16384) flag, the GetMetadataObjects method gets the specified properties for objects of the specified metadata type in the current repository and all project repositories.

Example of Retrieving All Properties for All Objects

The following is an example of a GetMetadataObjects request that sets the OMI_GET_METADATA (256) and OMI_ALL (1) flags. The OMI_ALL flag lists all attributes and associations for all PhysicalTable objects returned by the GetMetadataObjects request.

 <GetMetadataObjects>
<!-- Reposid parameter specifies Test repository 1 -->
   <Reposid>A0000001.A53TPPVI</Reposid>
   <Type>PhysicalTable</Type>
   <Objects/>
   <NS>SAS</NS>
   <!-- Specify OMI_GET_METADATA(256) + OMI_ALL (1) flags -->
   <Flags>257</Flags>  
   <Options/>
</GetMetadataObjects>

In the request, note the following:

The <REPOSID> element specifies to issue the request in Test repository 1.
The <Type> element specifies to get all objects of the PhysicalTable metadata type.
The <FLAGS> element specifies a number representing the sum of the OMI_GET_METADATA and OMI_ALL flags.

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

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

<Objects>
<PhysicalTable Id="A53TPPVI.A4000001" Name="Sales Offices" DBMSType="" 
  Desc="Sales offices in NW region" IsCompressed="0" IsEncrypted="0" 
  LockedBy="" MemberType="" MetadataCreated="05Feb2002:09:37:00" 
  MetadataUpdated="05Feb2002:09:37:00" NumRows="-1" SASTableName=""
TableName="">
<AccessControls/>
<Aggregations/>
<AnalyticTables/>
<Changes/>
<Columns>
<Column Id="A53TPPVI.A5000001" Name="City" Desc="City of Sales Office"/>
<Column Id="A53TPPVI.A5000002" Name="Address" Desc="Street Address of Sales
Office"/>
<Column Id="A53TPPVI.A5000003" Name="Manager" Desc="Name of Operations
Manager"/>
<Column Id="A53TPPVI.A5000004" Name="Employees" Desc="Number of employees"/>
</Columns>
<Documents/>
<Extensions/>
<ExternalIdentities/>
<ForeignKeys/>
<Groups/>
<Implementors/>
<Indexes/>
<Keywords/>
<ModelResults/>
<Notes/>
<PrimaryPropertyGroup/>
<Properties/>
<PropertySets/>
<ReachThruCubes/>
<ResponsibleParties/>
<Roles/>
<SASPasswords/>
<SourceClassifierMaps/>
<SourceTransformations/>
<SpecSourceTransformations/>
<SpecTargetTransformations/>
<TablePackage/>
<TargetClassifierMaps/>
<TargetTransformations/>
<Timestamps/>
<TrainedModelResults/>
<Trees/>
<UniqueKeys/>
<UsedByPrototypes/>
<UsingPrototype/>
</PhysicalTable>
<PhysicalTable Id="A53TPPVI.A4000002" Name="Sales Associates" DBMSType="" 
  Desc="Sales associates in NW region" IsCompressed="0" IsEncrypted="0" 
  LockedBy="" MemberType="" MetadataCreated="05Feb2002:09:50:56" 
  MetadataUpdated="05Feb2002:09:50:56" NumRows="-1" SASTableName=""
TableName="">
<AccessControls/>
<Aggregations/>
<AnalyticTables/>
<Changes/>
<Columns>
<Column Id="A53TPPVI.A5000005" Name="Name" Desc="Name of employee"/>
<Column Id="A53TPPVI.A5000006" Name="Address" Desc="Home Address"/>
<Column Id="A53TPPVI.A5000007" Name="Title" Desc="Job grade"/>
</Columns>
<Documents/>
<Extensions/>
<ExternalIdentities/>
<ForeignKeys/>
<Groups/>
<Implementors/>
<Indexes/>
<Keywords/>
<ModelResults/>
<Notes/>
<PrimaryPropertyGroup/>
<Properties/>
<PropertySets/>
<ReachThruCubes/>
<ResponsibleParties/>
<Roles/>
<SASPasswords/>
<SourceClassifierMaps/>
<SourceTransformations/>
<SpecSourceTransformations/>
<SpecTargetTransformations/>
<TablePackage/>
<TargetClassifierMaps/>
<TargetTransformations/>
<Timestamps/>
<TrainedModelResults/>
<Trees/>
<UniqueKeys/>
<UsedByPrototypes/>
<UsingPrototype/>
</PhysicalTable>
</Objects>

The OMI_ALL flag gets all of the attributes and associations for each object, including attributes and associations for which no value has been defined. This is useful when you want to get both actual and potential properties for all of the objects.

Suppressing Properties That Do Not Store Values from GetMetadataObjects Output

To limit a GetMetadataObjects request to get only properties that have values defined, set the OMI_SUCCINCT (2048) flag. Here is an example of the output of the previous GetMetadataObjects request when OMI_SUCCINCT is set:

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

<Objects>
<PhysicalTable Id="A53TPPVI.A4000001" Name="Sales Offices" 
  Desc="Sales offices in NW region" IsCompressed="0" IsEncrypted="0" 
  MetadataCreated="05Feb2002:09:37:00" 
  MetadataUpdated="05Feb2002:09:37:00" NumRows="-1">
<Columns>
<Column Id="A53TPPVI.A5000001" Name="City" Desc="City of Sales Office"/>
<Column Id="A53TPPVI.A5000002" Name="Address" Desc="Street Address of Sales
Office"/>
<Column Id="A53TPPVI.A5000003" Name="Manager" Desc="Name of Operations
Manager"/>
<Column Id="A53TPPVI.A5000004" Name="Employees" Desc="Number of employees"/>
</Columns>
</PhysicalTable>
<PhysicalTable Id="A53TPPVI.A4000002" Name="Sales Associates" 
  Desc="Sales associates in NW region" IsCompressed="0" IsEncrypted="0" 
  MetadataCreated="05Feb2002:09:50:56" MetadataUpdated="05Feb2002:09:50:56" 
  NumRows="-1">
<Columns>
<Column Id="A53TPPVI.A5000005" Name="Name" Desc="Name of employee"/>
<Column Id="A53TPPVI.A5000006" Name="Address" Desc="Home Address"/>
<Column Id="A53TPPVI.A5000007" Name="Title" Desc="Job grade"/>
</Columns>
</PhysicalTable>
</Objects>

Example of Retrieving Only Attributes of Objects

The following is an example of a GetMetadataObjects request that sets the OMI_GET_METADATA (256), OMI_ALL_SIMPLE (8), and OMI_SUCCINCT (2048) flags. When OMI_ALL_SIMPLE is set in a GetMetadataObjects request, the flag instructs the method to get only the attribute values of the returned objects.

This request specifies to get all attributes of all Column objects in Test repository 1:

<GetMetadataObjects>
<!-- Reposid parameter specifies Test repository 1 -->
   <Reposid>A0000001.A53TPPVI</Reposid>
   <Type>Column</Type>
   <Objects/>
   <NS>SAS</NS>
   <!-- Specify OMI_GET_METADATA (256) + OMI_ALL_SIMPLE (8) 
         + OMI_SUCCINCT (2048) flags -->
   <Flags>2312</Flags>  
   <Options/>
</GetMetadataObjects>

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

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

<Objects>
<Column Id="A53TPPVI.A5000001" Name="City" BeginPosition="0"
ColumnLength="32" 
  ColumnName="City" ColumnType="12" Desc="City of Sales Office" EndPosition="0" 
  IsDiscrete="0" IsNullable="0" MetadataCreated="05Feb2002:09:37:00" 
  MetadataUpdated="05Feb2002:09:37:00" SASColumnLength="32" SASColumnName="City"

  SASColumnType="C" SASExtendedLength="0" SASFormat="$Char32."
SASInformat="$32." 
  SASPrecision="0" SASScale="0"/>
<Column Id="A53TPPVI.A5000002" Name="Address" BeginPosition="0"
ColumnLength="32" 
  ColumnName="Address" ColumnType="12" Desc="Street Address of Sales Office" 
  EndPosition="0" IsDiscrete="0" IsNullable="0"
MetadataCreated="05Feb2002:09:37:00" 
  MetadataUpdated="05Feb2002:09:37:00" SASColumnLength="32" 
  SASColumnName="Street_Address" SASColumnType="C" SASExtendedLength="0" 
  SASFormat="$Char32." SASInformat="$32." SASPrecision="0" SASScale="0"/>
<Column Id="A53TPPVI.A5000003" Name="Manager" BeginPosition="0"
ColumnLength="32" 
  ColumnName="Manager" ColumnType="12" Desc="Name of Operations Manager" 
  EndPosition="0" IsDiscrete="0" IsNullable="0"
MetadataCreated="05Feb2002:09:37:00" 
  MetadataUpdated="05Feb2002:09:37:00" SASColumnLength="32"
SASColumnName="Manager" 
  SASColumnType="C" SASExtendedLength="0" SASFormat="$Char32."
SASInformat="$32." 
  SASPrecision="0" SASScale="0"/>
<Column Id="A53TPPVI.A5000004" Name="Employees" BeginPosition="0"
ColumnLength="3" 
  ColumnName="Employees" ColumnType="6" Desc="Number of employees"
EndPosition="0" 
  IsDiscrete="0" IsNullable="0" MetadataCreated="05Feb2002:09:37:00" 
  MetadataUpdated="05Feb2002:09:37:00" SASColumnLength="3"
SASColumnName="Employees" 
  SASColumnType="N" SASExtendedLength="0" SASFormat="3.2" SASInformat="3.2" 
  SASPrecision="0" SASScale="0"/>
<Column Id="A53TPPVI.A5000005" Name="Name" BeginPosition="0"
ColumnLength="32" 
  ColumnName="Employee_Name" ColumnType="12" Desc="Name of employee"
EndPosition="0" 
  IsDiscrete="0" IsNullable="0" MetadataCreated="05Feb2002:09:50:56" 
  MetadataUpdated="05Feb2002:09:50:56" SASColumnLength="32"
SASColumnName="Employee" 
  SASColumnType="C" SASExtendedLength="0" SASFormat="$Char32."
SASInformat="$32." 
  SASPrecision="0" SASScale="0"/>
<Column Id="A53TPPVI.A5000006" Name="Address" BeginPosition="0"
ColumnLength="32" 
  ColumnName="Employee_Address" ColumnType="12" Desc="Home Address"
EndPosition="0" 
  IsDiscrete="0" IsNullable="0" MetadataCreated="05Feb2002:09:50:56" 
  MetadataUpdated="05Feb2002:09:50:56" SASColumnLength="32"
SASColumnName="Home_Address" 
  SASColumnType="C" SASExtendedLength="0" SASFormat="$Char32."
SASInformat="$32." 
  SASPrecision="0" SASScale="0"/>
<Column Id="A53TPPVI.A5000007" Name="Title" BeginPosition="0"
ColumnLength="32" 
  ColumnName="Title" ColumnType="12" Desc="Job grade" EndPosition="0"
IsDiscrete="0" 
  IsNullable="0" MetadataCreated="05Feb2002:09:50:56" 
  MetadataUpdated="05Feb2002:09:50:56" SASColumnLength="32"
SASColumnName="Title" 
  SASColumnType="C" SASExtendedLength="0" SASFormat="$Char32."
SASInformat="$32." 
  SASPrecision="0" SASScale="0"/>
</Objects>

Example of Retrieving Specified Attributes of All Objects

The following is an example of a GetMetadataObjects request that gets specified attributes of all objects of the specified metadata type. The GetMetadataObjects request sets the OMI_GET_METADATA (256) and OMI_TEMPLATE (4) flags and submits a template that specifies which attributes to get in a <TEMPLATES> element within the <OPTIONS> element.

<GetMetadataObjects>
<!-- Reposid parameter specifies Test repository 1 -->
   <Reposid>A0000001.A53TPPVI</Reposid>
   <Type>PhysicalTable</Type>
   <Objects/>
   <NS>SAS</NS>
   <!-- Specify OMI_GET_METADATA(256) + OMI_TEMPLATE (4) flags -->
   <Flags>260</Flags>  
   <Options>
    <Templates>
      <PhysicalTable DBMSType="" IsCompressed="" IsEncrypted="" 
        MemberType=""/>
       </Templates>
   </Options>
</GetMetadataObjects>

In the request, the template specifies to get the DBMSType, IsCompressed, IsEncrypted, and MemberType attributes for each of the PhysicalTable objects in repository A53TPPVI. Here is an example of the output from the request:

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

<Objects>
<PhysicalTable Id="A53TPPVI.A4000001" Name="Sales Offices" DBMSType="" 
  IsCompressed="0"  IsEncrypted="0" MemberType=""/>
<PhysicalTable Id="A53TPPVI.A4000002" Name="Sales Associates" DBMSType="" 
  IsCompressed="0"  IsEncrypted="0" MemberType=""/>
</Objects>

The SAS Metadata Server gets the requested properties and the Id and Name attributes that are returned by default.

For information about how to create a template, see Understanding Templates.

Example of Retrieving Associated Objects for All Objects

The following is an example of a GetMetadataObjects request that uses a template to retrieve associated objects of the specified metadata type. The GetMetadataObjects request sets the OMI_GET_METADATA (256) and OMI_TEMPLATE (4) flags and submits a template that specifies which associations to get in a <TEMPLATES> element in the <OPTIONS> element. The template specifies the metadata type and the association name for which associated objects should be returned.

<GetMetadataObjects>
<!-- Reposid parameter specifies Test repository 1 -->
   <Reposid>A0000001.A53TPPVI</Reposid>
   <Type>PhysicalTable</Type>
   <Objects/>
   <NS>SAS</NS>
   <!-- Specify OMI_GET_METADATA(256) + OMI_TEMPLATE (4) flags -->
   <Flags>260</Flags>  
   <Options>
    <Templates>
      <PhysicalTable>
          <Columns/>
          <Extensions/>
          <Indexes/>
      </PhysicalTable>
    </Templates>
   </Options>
</GetMetadataObjects>

In the request, the template specifies to get objects that are associated with the requested PhysicalTable objects through the Columns, Extensions, and Indexes association names.

Here is an example of the output from the request:

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

<Objects>
<PhysicalTable Id="A53TPPVI.A4000001" Name="Sales Offices">
     <Columns>
         <Column Id="A53TPPVI.B7000001"/>
         <Column Id="A53TPPVI.B7000002"/>
         <Column Id="A53TPPVI.B7000003"/>
         <Column Id="A53TPPVI.B7000004"/>
      </Columns>
      <Extensions/>
      <Indexes/>
</PhysicalTable>
<PhysicalTable Id="A53TPPVI.A4000002" Name="Sales Associates">
     <Columns>
         <Column Id="A53TPPVI.B7000005"/>
         <Column Id="A53TPPVI.B7000006"/>
         <Column Id="A53TPPVI.B7000007"/>
         <Column Id="A53TPPVI.B7000008"/>
      </Columns>
      <Extensions/>
      <Indexes/>
</Objects>

In this example, the returned PhysicalTable objects have associated Column objects. But, they do not have associated objects through the Extensions and Indexes association names.

In the request, note the following:

By default, the GetMetadataObjects method returns only the Id value of associated objects. To get additional attributes, you must set a flag, such as OMI_ALL_SIMPLE (8), to get all attributes for the specified object and the associated objects. Or, you can include additional templates that request specific attributes of the associated objects.
When an association name is specified in a template (<Columns/>, <Extensions/>, and <Indexes/> in the previous example), the GetMetadataObjects method gets associated objects of all metadata types that are valid for the specified association name. This example does not show objects of these associated metadata types because no objects of the additional metadata types were found. However, the Columns association name supports associations to two metadata types: Column and ColumnRange. The Extensions association name supports associations to two metadata types: Extension and NumericExtension. The Indexes association name has one valid metadata type: Index. This GetMetadataObjects request could have retrieved associated objects of all of these metadata types.

The GetMetadataObjects method also supports search criteria that enable you to filter the associated objects that are retrieved. For more information, see Filtering the Associated Objects That Are Returned by a GetMetadataObjects Request.