Metadata Access (IOMI Interface)

GetMetadata

Gets specified properties for the specified metadata object.

Category: Read methods

rc=GetMetadata(inMetadata,outMetadata,ns,flags,options);

Parameters

Parameter	Type	Direction	Description
rc	N	out	Return code for the method. For more information, see Return Code.
inMetadata	C	in	Metadata property string that identifies the object and properties to be read.
outMetadata	C	out	Returned metadata property string that includes the results of the read operation.
ns	C	in	Namespace to use as the context for the request.
flags	L	in	OMI_ALL=1 Specifies to get all of the properties of the requested object. This includes all of the attributes that are documented for the requested metadata type in its Attributes table, and all of the associations in its Associations table, whether they have values stored for them or not. The results include both unique and inherited properties. If the returned XML stream includes references to any associated objects, GetMetadata returns only general, identifying information for the associated objects. OMI_ALL_SIMPLE=8 Specifies to get all of the attributes of the requested object. The results include both unique and inherited attributes. OMI_DEPENDENCY_USED_BY=16384 Specifies to include associations to objects that exist in all project repositories in the method results. OMI_INCLUDE_SUBTYPES=16 Specifies to get the specified properties for metadata objects that are subtypes of the specified metadata type, in addition to the specified metadata object. The OMI_INCLUDE_SUBTYPES flag must be set with the OMI_TEMPLATE flag and a template, or the flag is ignored. OMI_LOCK=32768 Locks the specified object and any associated objects selected by GetMetadata flags and options from update by everyone except the caller. OMI_NOFORMAT=67108864 Causes date, time, and datetime values in the output XML stream to be returned as raw SAS date, SAS time, and SAS datetime floating-point values. Without the OMI_NOFORMAT flag, the default US-English locale is used to format the values into recognizable character strings. OMI_SUCCINCT=2048 Specifies to omit all properties that do not contain a value or that contain a null value. OMI_TEMPLATE=4 Checks the OPTIONS parameter for user-defined templates that define which metadata properties to return. The user-defined templates are submitted in a <TEMPLATES> element in the OPTIONS parameter.
options	C	in	Passed indicator for options. <DOAS Credential="credHandle"/> Enables a client to make a metadata request for another user. For more information, see <DOAS> Option. <TEMPLATES> Specifies properties to retrieve for the specified metadata type beyond properties already specified in the INMETADATA parameter and by GetMetadata flags. The <TEMPLATES> element must be specified with the OMI_TEMPLATE flag.

Details

The GetMetadata method gets properties for the specified metadata object.

The method provides several ways to identify the properties that you want to retrieve. For usage information, see Using GetMetadata to Get the Properties of a Specified Metadata Object.

In previous releases of SAS, when information was requested about associated objects, the method returned information about associated objects that were stored in the same repository as the requested object by default, and the user had to set a flag to get information about associated objects in other repositories. Beginning in SAS 9.2, a GetMetadata method that requests associated objects that is issued in a public repository (the foundation or a custom repository) returns associated objects from all public repositories by default. You set the OMI_DEPENDENCY_USED_BY flag only if you want to include associated objects that are in project repositories in the results.

When GetMetadata is issued in a project repository, it always returns associated objects that are in the same repository.

The GetMetadata method uses the US-English locale to format date, time, and datetime values. Set the OMI_NOFORMAT (67108864) flag to return these values as SAS floating-point values that you can format.

The OMI_LOCK (32768) flag is one of several multi-user concurrency controls supported by the SAS Open Metadata Interface. The flag enables you to lock the specified object and any associated objects selected by GetMetadata flags and options from use by other users. Metadata objects that are locked with OMI_LOCK are unlocked by issuing an UpdateMetadata method call that sets the OMI_UNLOCK or OMI_UNLOCK_FORCE flag. For an overview of the concurrency controls supported by the SAS Open Metadata Interface, see Metadata Locking Options.

The OMI_INCLUDE_SUBTYPES flag extends template processing to include associated metadata objects that are subtypes of the specified metadata object. This functionality is useful when you want to retrieve a common set of properties for multiple objects. For more information, see Using GetMetadata to Get Common Properties for Sets of Objects.

Some GetMetadata flags have interdependencies that can affect the metadata that is returned when more than one flag is set. For more information, see Using IOMI Flags.

Example 1: Standard Interface

The following is an example of how to issue a GetMetadata method regardless of the programming environment. The request gets the Name, Description, and Column values of the PhysicalTable with an Id of A5345678.A5000001.

<!-- Create a metadata list to be passed to GetMetadata method -->

inMetadata= "<PhysicalTable Id="A5345678.A5000001" Name="" Desc="">
              <Columns/>
            </PhysicalTable>";
ns="SAS";
flags=0;
options="";

rc=GetMetadata(inMetadata, outMetadata, ns, flags, options);

<!-- outMetadata XML string returned -->
<PhysicalTable Id="A5345678.A5000001" Name="New Table" Desc="New Table added 
through API">
  <Columns>
    <Column Id="A5345678.A3000001" Name="New Column" Desc="New Column added 
through API"/>
    <Column Id="A5345678.A3000002" Name="New Column2" Desc="New Column2 added 
through API"/>
  </Columns>
</PhysicalTable>

Example 2: DoRequest Method

The following is an example of an XML string that shows how to format the request in example 1 for the INMETADATA parameter of the DoRequest method.

<!-- XML string for inMetadata= parameter of DoRequest method call -->

<GetMetadata>
  <Metadata>
    <PhysicalTable Id="A5345678.A500001" Name="" Desc="">
       <Columns/>
    </PhysicalTable>
  </Metadata>
  <NS>SAS</NS>
  <Flags>0</Flags>
  <Options/>
</GetMetadata>

Related Methods

GetMetadataObjects

Top of Page