AddMetadata :: SAS(R) 9.3 Open Metadata Interface: Reference and Usage

Short Description

Adds metadata objects to a repository.

Syntax

rc= AddMetadata(inMetadata,reposid,outMetadata,ns,flags,options);

Parameters

Method 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 defines the object to be added.
reposid	C	in	Target repository ID.
outMetadata	C	out	Returned metadata property string that includes the object as a result of the add operation.
ns	C	in	Namespace to use as the context for the request.
flags	L	in	OMI_TRUSTED_CLIENT=268435456 Determines whether the client can call this method. This flag is required.
options	C	in	Passed indicator for options. <CREATEREPOSCONTAINER/> When AddMetadata is issued in the REPOS namespace to create a RepositoryBase object, this option creates the physical directory specified in the object's Path attribute, if the physical directory does not exist. <DOAS Credential="credHandle"/> Enables a client to make a metadata request for another user. For more information, see <DOAS> Option.

Details

The AddMetadata method creates metadata objects. It is used to create both the metadata object that defines a repository, and the metadata objects that are within the repository. To update an existing metadata object, whether it defines a repository or a metadata object within the repository, use the UpdateMetadata method.

The INMETADATA parameter specifies a metadata property string that defines the properties to be added for the object. A request that creates a repository defines an object of the RepositoryBase metadata type and is issued in the REPOS namespace. A request that adds an object to a repository is issued in the SAS namespace and defines SAS namespace metadata types. Not all metadata types or their properties can be added. See the documentation for each metadata type. AddMetadata returns an error for any metadata type that cannot be added.

An AddMetadata request that creates the metadata object that defines a repository does not automatically create the physical directory specified in the Path attribute. You must create the physical directory specified in the Path attribute in advance. Or, you can pass the <CREATEREPOSCONTAINER/> element in the AddMetadata request to create the physical directory. The Path attribute accepts an absolute or relative pathname. Use backslashes or forward slashes (\ and /) to indicate the directory levels. <CREATEREPOSCONTAINER/> creates one directory, and it will be the last directory in the specified path. If the other directories in the path do not exist, the SAS Metadata Server returns an error.

The OUTMETADATA parameter mirrors the content of the INMETADATA parameter. In addition, it returns identifiers for the requested objects. Any invalid properties in the INMETADATA metadata property string remain in the OUTMETADATA metadata property string. For information about the structure of the metadata property string, see Constructing a Metadata Property String.

The AddMetadata method can be used to create an object only, to create an object and an association to an existing object, or to create an object, an association, and the associated object. Associations to objects can be made in the same repository or in a different repository. The attributes defining the objects indicate the type of operation to be performed. For more information, see Adding Metadata Objects.

Objects and associations are created subject to security constraints. For example, a requestor must have administrative status on the SAS Metadata Server to add a repository. A requestor must have WriteMetadata permission to a repository to add an object to the repository. When creating an association between a new object and an existing object, the requestor must have WriteMetadata permission either to the existing object, or to the repository in which the existing object resides.

The SAS Metadata Server assigns object identifiers after the successful completion of an AddMetadata request.

Check the return code of an AddMetadata method call. A nonzero return code indicates that a failure occurred while trying to write the metadata. A nonzero return code means none of the changes in the method call were made.

Example 1: Standard Interface

The following is an example of how to issue the AddMetadata method regardless of the programming environment. The request adds a new PhysicalTable object and provides the Name and Desc values.

<!-- Create a metadata list to be passed to AddMetadata method  -->
inMetadata = "<PhysicalTable Name="NECust" 
               Desc="All customers in the northeast region"/>";

reposid= "A0000001.A2345678";
ns= "SAS";
<!-- OMI_TRUSTED_CLIENT flag -->
flags= 268435456;  
options= "";

rc = AddMetadata(inMetadata,reposid,outMetadata,ns,flags,options);

<!-- outMetadata XML string returned -->
<PhysicalTable Id="A2345678.A2000001" Name="NECust" 
  Desc="All customers in the northeast region"/>

Example 2: DoRequest Method

The following is an example of an XML string that shows how to format the method call in example 1 for the INMETADATA parameter of the DoRequest method. A <METADATA> element, rather than an <INMETADATA> element, specifies the passed metadata property string.

<AddMetadata>
   <Metadata>
     <PhysicalTable Name="NECust" 
                    Desc="All customers in the northeast region"/>
   </Metadata>
   <Reposid>A0000001.A2345678</Reposid>
   <NS>SAS</NS>
   <Flags>268435456</Flags>
   <Options/>
</AddMetadata>

AddMetadata