Updating Metadata Objects

Using the UpdateMetadata Method

The UpdateMetadata method enables you to 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 Creating a Logical Metadata Definition. 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.

To modify an object's attributes, specify the metadata object, 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 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.

To add, modify, or delete an association, or to modify an associated object's attributes, include an association name subelement and associated object definition in the metadata property string. In the association name subelement, include the Function= attribute. In the associated object definition, include the appropriate identifier and value. For example:

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

In this metadata property string, note the following:

The <METADATA> parameter identifies the metadata type, the object instance, the association name, and the associated object definition that you want to modify.
The association name subelement specifies a Function= attribute and a directive that specifies how the SAS Metadata Server should process the associated object definition, depending on whether the association name supports a single or a multiple association.
The associated object definition has a choice of object identifiers and values. The identifier attribute and value that you specify in the associated object definition determine whether a new associated object is created, whether an existing associated object's attributes are modified, or whether the request adds an association to an existing object.

Function= Attribute

The Function= attribute specifies how the SAS Metadata Server should process the associated object definition submitted for the association name, depending on whether the association name supports a single or a multiple association. This attribute is supported only in the association name element of a metadata property string that is passed to the UpdateMetadata method.

A single association refers to an association name that has a 0:1 or 1:1 cardinality defined for it in the metadata type documentation. Only one association of that name is supported between the specified metadata types.

A multiple association refers to an association name that has a 0 to many or 1 to many cardinality. This is denoted as 0:* and 1:* in the metadata type documentation. A multiple association supports many associations between the specified metadata types.

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.

How the Function Directives Affect Association Ordering

This example shows how the UpdateMetadata method applies the various Function= directives. 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".

Associated Object Identifier and Value

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="$SymbolicName" or no identifier	Create an association and the associated object. For more information about symbolic names, see Symbolic Names.
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.

Examples of How the Object Identifiers Work

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. A dependent object requires an association to another object to exist. Metadata types that have required associations are noted in the metadata type documentation as having a 1: 1 cardinality in their Associations table.

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 include 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.

Top of Page