Using the UpdateMetadata Method :: SAS(R) 9.3 Open Metadata Interface: Reference and Usage

Required Attributes and Associations

The UpdateMetadata method can be issued in the REPOS namespace to modify the properties of a metadata repository or in the SAS namespace to modify the properties of an object describing an application element.

You can add or modify any attribute or association that is not designated as required in the metadata type documentation. For information about which metadata types have required attributes and associations, see “Required Attributes and Associations” in the SAS Metadata Model: Reference. An association that is designated as required typically indicates that the object is a dependent object. To remove a required association, you must delete the dependent object with the DeleteMetadata method. However, a dependent object's other attributes and associations can be modified with UpdateMetadata.

Using UpdateMetadata to Modify Attribute Values

To modify an object's attributes, specify the metadata type, object ID, and the names of the attributes that you want to modify and their new values in a metadata property string. Submit the metadata property string to the UpdateMetadata method in the INMETADATA parameter. The following is an example of such an UpdateMetadata method call that is formatted for the DoRequest interface:

<UpdateMetadata>
  <Metadata>
    <Metadata_Type Id="reposid.objectid" Attribute1="new_value" 
                   Attribute2="new_value" Attribute3="new_value"/>
  </Metadata>
  <NS>SAS</NS>
  <--- OMI_TRUSTED_CLIENT Flag ---> 
  <Flags>268435456</Flags>
  <Options/>
</UpdateMetadata>

In this method call, note the following:

The <METADATA> element specifies the metadata type, the object instance, and the attributes that you want to modify. The first part of the two-part object identifier in the object definition identifies the repository in which to execute the request. Attribute1, Attribute2, and Attribute3 are metadata type attributes. The new values specified for these attributes replace any existing values in the repository. Unmodified attributes remain unchanged.
The OMI_TRUSTED_CLIENT (268435456) flag enables the SAS Metadata Server to write to the metadata object.

Using UpdateMetadata to Add or Modify Associations

To add or modify an association for an object, include an association name subelement and associated object definition in the metadata property string that describes the target object. In the association name subelement, specify an appropriate Function attribute value. In the associated object definition, specify an appropriate associated object identifier and value. For example:

  <Metadata>
    <MetadataType Id="reposid.objectid">
       <AssociationName Function="directive">
         <AssociatedMetadataType Id
|ObjRef="value"/>
       </AssociationName>
    </MetadataType>
  </Metadata>

The <METADATA> parameter identifies the metadata type, object instance, association name, and associated object affected. In this metadata property string, note the following:

The association name subelement specifies a Function attribute and a directive. The Function attribute specifies how the SAS Metadata Server should process the associated object definition.
The associated object subelement supports a choice of associated object identifiers. The associated object identifier that you choose to specify indicates whether a new association will be made to an existing object, whether a new association and a new associated object will be created, or whether an existing associated object will be modified.

Understanding the Function Attribute

Directives Supported by the Function Attribute

The Function attribute specifies how the SAS Metadata Server should process the associated object definition submitted with the association name. The supported values, referred to as directives, specify the order in which the specified associated object is ordered in the target object's association list, when multiple associations are supported. Support for multiple associations is denoted by a 0:* cardinality figure for the association name in the metadata type documentation. Association names that support a single association have a 0:1 or 1:1 cardinality figure defined for them in the metadata type documentation.

The Function attribute supports the directives shown in the following table. If the Function attribute is omitted from an UpdateMetadata request, MODIFY is the default directive for a single association, and MERGE is the default directive for a multiple association.

Function Directives Supported by the UpdateMetadata Method

Directive	Supported for Single Associations?	Supported for Multiple Associations?	Description
Append	No	Yes	Adds the specified associations to the specified object's association list without modifying any of the other associations.
Merge	Yes	Yes	Adds or modifies associations in the specified object's association list.
Modify	Yes	No	Modifies an existing association or adds the association if the association does not exist.
Replace	Yes	Yes	Single: Overwrites an existing association with the specified association. Multiple: Replaces the existing association list with the specified association list, listing any new associations first. Any existing associations that are not represented in the new association list are deleted.
Remove	Yes	Yes	Deletes the specified associations from the specified object's association list without modifying any of the other associations.

Examples of How the Function Directives Affect Association Ordering

Assume that a Column object exists that has an Extensions association to several objects. The Extensions association name enables an association to be created to any type of object. For the purpose of this example, the number of associations and their order in the association list is important, so they are identified numerically. For example:

extension1
extension2
extension3
extension4

If we were to execute an UpdateMetadata method call that modified extension1 and added extension5 with Function=“APPEND,” the directive causes the following changes to the association list:

extension1
extension2
extension3
extension4
extension5
extension6

APPEND never modifies existing associations. Any new associations are added to the end of the existing association list. Any associations that you attempt to modify are treated as new and listed as truly new associations. Extension1 was copied, assigned a new Id value, and added to the end of the list as extension6.

If we were to issue the same UpdateMetadata method call, except with Function=“MERGE,” the directive would change the association list as follows:

extension2
extension3
extension4
extension5
extension1

Like APPEND, MERGE adds new associations to the end of the existing association list. Unlike APPEND, however, it modifies and moves specified existing associations instead of just copying them. Extension1 is moved to the end of the association list.

Function="MODIFY" would have no effect in this UpdateMetadata method call. MODIFY is not supported for multiple associations.

If we were to issue the same UpdateMetadata method call, except with Function=“REPLACE,” the directive would cause the following changes to the association list:

extension5
extension1

The existing association list is deleted and replaced with a new list that lists new associations first, and any existing associations in the order that is specified. The old extension1 is replaced with the modified extension1.

If we were to issue the same UpdateMetadata method call with Function=“REMOVE,” the directive would cause the following changes to the association list:

extension2
extension3
extension4

The extension1 association is removed from the association list. The UpdateMetadata method returns an error message regarding extension5, because it was not in the list.

Summary of Function Directives

To add associations to an existing association list without modifying the properties of the existing associated objects, specify Function="APPEND".
To add new associations and modify the properties of the existing associated objects, specify Function="MERGE".
To delete an existing association or association list with a new association or association list, specify Function="REPLACE".
To remove an association without modifying any of the other associations in an existing association list, specify Function="REMOVE".
To modify the properties of the associated object in a single association, specify Function="MODIFY".

Understanding the Associated Object Identifiers

Identifiers and Supported Values

The following table lists the identifiers and values that are supported in an associated object definition and their behaviors when used in the UpdateMetadata method.

Identifiers and Values Supported in an Associated Object Definition

Identifier and Value	Result
Id="" Id="Reposid.$SymbolicName" or no identifier	Create an association and the associated object. For more information about symbolic names, see Symbolic Names. When a symbolic name is used to create a new object in UpdateMetadata, the form Id="Reposid.$SymbolicName" must be used whether the object is in the same repository or in a different repository than the top-level object.
Id="real_value"	Modifies the specified object with the specified properties, if the object is found. If the object is not found, the update fails.
ObjRef="real_value"	Creates an association to, but does not modify the properties of the specified object, if the object is found. If the object is not found, the update fails.

Usage Examples

The following is an example of an association name and an associated object definition that adds an association to an existing object in the same repository:

<AssociationName Function="Directive">
  <AssociatedMetadataType ObjRef="Objectid"/>
</AssociationName>

Note the use of the ObjRef attribute and an object identifier in the associated object definition. If you specify additional attributes, the method ignores them.

The following is an example of an association name and an associated object definition that adds an association and a new object in the same repository:

<AssociationName Function="Directive">
  <AssociatedMetadataType Id="" Name="Name"/>
</AssociationName>

Note the use of the Id attribute with a null value in the associated object definition. Another way to create the associated object is to omit an object identifier from the associated object definition.

The following is an example of an association name and an associated object definition that modifies an existing associated object in the same repository:

<AssociationName Function="Directive">
  <AssociatedMetadataType Id="Objectid" Name="Name"
    Desc="This is a new description for this associated object."/>
</AssociationName>

Note the use of the Id attribute with a real object identifier in the associated object definition.

To create an association to an existing object in another repository using the UpdateMetadata method, specify the ObjRef attribute and include the object's repository identifier in the object instance identifier of the associated object definition. For example:

<AssociationName Function="Directive">
  <AssociatedMetadataType ObjRef="Reposid.Objectid"/>
</AssociationName>

To create an association and a new object in another repository, specify the Id attribute, a repository identifier, and a symbolic name in the object instance identifier of the associated object definition. For example:

<AssociationName Function="Directive">
  <AssociatedMetadataType Id="Reposid.$SymbolicName" Name="Name"/>
</AssociationName>

Deleting Associations

To delete an association, specify the REPLACE or REMOVE directives in the Function attribute of the association name element.

The REPLACE directive replaces any existing associations with the specified associated object definition or list of associated object definitions. Use this directive with caution to prevent accidentally overwriting associations that you want to keep.
The REMOVE directive removes the specified associated object definition from the list of associations maintained for that association name without affecting other associations.

Deleting an association does not delete the associated object, unless the associated object is a dependent object. If you want to delete an object's associated objects and its associations, you must delete each associated object individually using the DeleteMetadata method. For more information, see Deleting Metadata Objects.

The UpdateMetadata method does not print dependent objects that it might have deleted in its output by default. To include the dependent objects deleted by an Update operation in the output, set the OMI_RETURN_LIST (1024) flag in the UpdateMetadata method call.

For an example of deleting an association, see Example of an UpdateMetadata Request That Deletes an Association.