What's New in Microsoft Repository 2.0

Microsoft Repository 2.0 offers versioning and workspace management for Windows desktops and servers, which until now have been restricted to high-end and proprietary repository environments.

What's New: Version Management

What's New: Workspace Management


What's New: Version Management

Repository's new object and relationship versioning functionality enables complex configuration management operations at the information model level. The main features are:

  • Versioning of objects with efficient evolutionary storage of properties.

  • The ability to create and merge versions, which allows the user to track the evolution of an object through a graph of parallel or sequential historical versions.

  • Versioning of relationships to maintain the history of associations between object versions.

For More Information Version Management

New COM Classes

VersionCol

VersionedRelationship (subsumes V1's Relationship class)

RepositoryObjectVersion (subsumes V1's RepositoryObject class)

New Interfaces

IRepositoryObjectVersion

IRepository2

IVersionedRelationship

IVersionAdminInfo

IVersionCol

New Automation Objects

VersionCol

VersionedRelationship (subsumes V1's Relationship object)

RepositoryObjectVersion (subsumes V1's RepositoryObject object)


What's New: Workspace Management

Workspaces, together with a powerful checkin-checkout mechanism, support the implementation of sophisticated team-development functionality. This functionality includes:

  • Document management.

  • High-end source code control.

  • Configuration management of complex interrelated structures such as Web sites, program representations, and metadata for data warehouses.

For More Information Workspace Management

New COM Classes

Workspace

New Interfaces

IWorkspaceItem

IWorkspace

IWorkspaceContainer

IRepository2

New Automation Objects

Workspace


Repository Overview

Microsoft Repository provides a common place to persist information about objects and relationships between objects. In doing so, it provides a standard way to describe object-oriented information used by software tools:

  • Software tools use information composed of various classes of objects.

  • Objects expose interfaces.

  • Interfaces are composed of properties, methods, and collections.

  • Collections contain relationships to other interfaces and thus relate objects to other objects.

A software tool is modeled in Repository through an information model. Each information model is stored in the Repository database as a Repository type library.

The Repository database is dynamic and extensible. Little of the actual structure is fixed; tables and columns of data are added as new models are defined, and as existing models are extended. This enables any software tool or set of software tools to be modeled by the Repository. It also enables a user to extend existing models.

For example, Visual Basic® provides an information model called the Microsoft Development Objects (MDO) Model. The MDO Model tracks Visual Basic projects in the Repository. The set of existing Visual Basic projects is represented in the Repository by the Contents collection.

The Repository is not limited to software tools developed using Visual Basic. Visual Basic is only one of many potential clients that can use the Repository to model a software system.


Introducing Microsoft Repository

Microsoft Repository has two major components: a set of ActiveX® interfaces that a programmer can use to define open information models, and a Repository engine that is the underlying storage mechanism for these information models. The Repository engine sits on top of either Microsoft SQL Server™ or Microsoft Jet.

Microsoft Repository targets software tool vendors who want to use open information models to support the development, deployment, and reuse of component software. Corporate customers who will benefit from component reuse and tool interoperability will be the primary users of these tools.

  • How You Can Use Microsoft Repository

  • Repository Features

  • The Architecture of Microsoft Repository

  • The People Involved in a Repository System


How You Can Use Microsoft Repository

Microsoft Repository is a product upon which to build tools. You do not use Repository by itself — it is a foundation for tools that manage the process of producing application software. This process has three steps:

  1. Choose a kind of data you want Microsoft Repository to manage.

  2. Create tools to insert, maintain, visualize, and analyze that data in the Repository.

  3. Use the tools to help you understand your software system and make decisions about it.

Microsoft Repository can provide a foundation on which to build tools for the following:

  • Visualizing the structure of your applications

    For example, the Repository can contain information about your software projects. You can write programs to visualize, summarize, or maintain this data. Such programs can help you make decisions about the design and maintenance of your projects.

  • Keeping track of the reuse of particular components

    Suppose that your software projects include several fundamental class modules. Over time, you find that these class modules are reused in many different software applications. Repository can keep track of which software projects include which class modules.

  • Analyzing the impact of a change to a reusable component

    Suppose that you want to redesign a particular class module. You can use the Repository to assess which software projects already use that class module. Such information can help you decide whether or not to redesign the module.


Repository Features

These Repository features help you manage the process of producing application software:

  • Already contains useful information — For example, the version of Repository that is included with Visual Basic can maintain information about Visual Basic applications. You can build tools that analyze, report on, or present this information in useful ways. Note that you need not build any tools to collect this data; Repository includes a tool that maintains this data in the Repository for you. Over time, Repository will include more data about more tools, making it increasingly useful to you.

    The existing information in the Repository can be extended in three ways:

    • Add an entirely new kind of information.

    • Extend an existing kind of information.

    • Combine an existing kind of information with an entirely new kind of information.
  • Is object-oriented — Microsoft Repository's methods recognize the object as a unit of persistence. If you are an object-oriented programmer, Repository makes it easy for you to manage your persistent data. In contrast, if Repository were merely a relational database, your tools would have to translate between objects (the units of run-time manipulation) and rows (the units of persistence within a database table). Microsoft Repository eliminates this programming chore.

  • Enables manipulation of object models using the same techniques used to manipulate your other data — For example, you can store the classes of your object model in the Repository, retrieve them from the Repository, and use the Repository's general data manipulation facilities on them.

  • Supports both COM and Automation programming — From your programs that manipulate the contents of the Repository, you can use COM or Automation paradigms.


The Architecture of Microsoft Repository

A Microsoft Repository system consists of the following components.

Component | Description and use
The Repository database | A relational database. Queries the database directly with SQL queries. Do not write directly to the database; the Repository engine does this for you.
The Repository engine | Manages data in the Repository. Provides basic functions to store and retrieve Repository objects and the relationships among them. The engine has its own object model.
An information model | An object model. Specifies the types of information of interest to one or more tools. For example, the Microsoft Development Objects (MDO) Model is an information model that specifies the types of data of interest to Visual Basic programmers. It lets those programmers use Repository-aware tools to analyze the structure of their Visual Basic projects.
The Type Information Model | A special information model. Specifies the types of information of interest to information model creators. Used by information model creators to describe their application-specific models to the Repository.
Application development tools | Software tools for managing the process of developing, deploying, and maintaining software applications.

The following figure shows the Repository architecture.

For More Information The Repository Engine Object Model, Information Models, The Type Information Model


The People Involved in a Repository System

A Repository system includes people filling the following roles:

Person | Role
Information model creator | Designs the information model and inserts it into the Repository. One information model developer can support many tool programmers, because there are many potential tools that can manipulate the same set of data. An organization can sometimes use information models created elsewhere and already inserted into the Repository.
Programmer who creates tools to insert, maintain, visualize, or analyze the data in the information model | Populates the information model with data. Creates tools like browsers, data visualization tools, database reports, database queries, and impact analysis tools to analyze that data.
User of the insertion, maintenance, visualization, and analysis tools | Typically, programmers, application developers, and system analysts. Because the tools are for manipulating data about software systems, they are used primarily by software professionals. Note The software professionals who use these tools need not be aware that they have the Repository at all. They must, however, have Microsoft Repository installed to run these tools.


The Repository Engine Object Model

Microsoft Repository is an Automation application that stores data for tools. The Repository engine object model includes classes that expose their properties and behavior through interfaces. Repository contains objects and relationships and their respective property values.

Because Microsoft Repository can accommodate data for any tool, its object model reflects a simple, fundamental view of data. This section describes Repository's fundamental object model and introduces both the classes and the interfaces of Repository's object model.

This section includes the following topics:

  • The Data in the Repository

  • The Root Object

  • Repository Objects

  • Relationships

  • Relationship Collections

  • Target Object Collections

  • The Repository Itself


The Data in the Repository

The Repository contains data expressed as objects and relationships, along with their respective property values. The following figure shows some typical data for employees, projects, and subprojects.

The preceding figure includes all the typical kinds of data you'll find in the Repository, so you can use it to understand the classes in the Repository's object model. In the figure, you can see instances of the following classes:

  • The Repository class

    The Repository class describes the Repository itself. The entire figure represents an instance of the Repository class.

  • The RepositoryObject class

    Each instance of the RepositoryObject class describes an object. The figure shows 12 objects, one of which is the root object; each instance is a dot.

  • The ReposRoot class

    The ReposRoot class describes the root object. Each Repository includes exactly one root object.

  • The Relationship class

    Each instance of the Relationship class describes an association between two objects. The figure shows 15 relationships; each relationship is an arrow.

The figure also includes the following classes:

  • The RelationshipCol class

    Each instance of the RelationshipCol class describes a set of similar relationships. The items in a relationship collection must be similar to each other in two ways:

    • First, every item must be a relationship that conforms to the same relationship type as every other item.

    • Second, there must be one object that is common to all relationships in the collection. That object must play the same role for all relationships in the collection.

    One relationship collection in the figure is the set of Mike's assignments to subprojects. In the figure, this relationship collection appears as a pair of arrows emerging from the dot representing Mike.

  • The TargetObjectCol class

    Each instance of the TargetObjectCol class describes a set of objects. For example, one set of objects is the set of subprojects that Mike works on; the set contains two items.


The Root Object

The root object is the top-level object in the Repository. It is the object from which all Repository navigation begins. Like any Repository object, the root object can have any number of relationships with other objects. The following figure shows seven such relationships.

Each relationship connecting the root object to other objects must conform to a relationship type. The relationship type to which these relationships conform is created by the tool information model creator.

For More Information Moving Through the Repository's Contents, The Type Information Model, Information Model Creation Issues


Repository Objects

When you create a Repository object (with the CreateObject method), you can supply an object identifier or let the Repository assign one automatically. In most cases, let the Repository assign one. You should explicitly assign an object identifier in only one case: when you are inserting into the Repository a replica of an object represented in some other Repository database. This ensures that the newly created object's object identifier matches the object identifier used for the object that already exists in the other Repository database. This case applies whenever you insert a new tool information model into the Repository.

For More Information Information Model Creation, Repository Identifiers


Accessing Repository Objects

Access to Repository objects is supported at both the COM level and the Automation level, as shown in the following table.

To | Use
Create an object | CreateObject method of the IRepository interface.
Retrieve an object | Object property of the IRepository interface.
Delete an object | Delete method of the IRepositoryItem interface.
Get the value of an early-bound object property | Automation: the syntax variable = object.property, as for any Automation object property. COM: the get_PropertyName method of the COM interface to which the property is attached, where PropertyName is the name of the property to be retrieved. You can also use the late-bound property access method.
Get the value of a late-bound object property (that is, object class is not in an available type library) | Automation: the syntax variable = object.property, as for any Automation object property. COM: the standard Automation method-invocation technique to invoke the get_PropertyName method, where PropertyName is the name of the property to be retrieved. Since all Repository interfaces that expose late-bound properties are indirectly derived from the IDispatch interface, the GetIdsOfNames and Invoke methods are available for use.
Set the value of an early-bound object property | Automation: the syntax object.property = value, as for any Automation object property. COM: the put_PropertyName method of the COM interface to which the property is attached, where PropertyName is the name of the property to be set. You can also use the late-bound property access method.
Set the value of a late-bound object property (that is, object class is not in an available type library) | Automation: the syntax object.property = value, as for any Automation object property. COM: the standard Automation method-invocation technique to invoke the put_PropertyName method, where PropertyName is the name of the property to be set. Since all Repository interfaces that expose late-bound properties are indirectly derived from the IDispatch interface, the GetIdsOfNames and Invoke methods are available for use.
Get the object identifier of an object | ObjectID property of the IRepositoryObject interface.
Get the version identifier of an object | VersionID property of the IRepositoryVersion interface.
Set the object identifier of an object | Pass object identifier as a parameter when creating the object.
Get the internal identifier of an object | InternalID property of the IRepositoryObject interface.

For More Information Version Management


Relationships

A relationship is an association between two objects. In every Repository relationship, one object participates as the origin and one object participates as the destination. The terms origin and destination refer to the relative roles of the two objects.

For a given type of relationship, the assignment of one particular role as the origin and the other role as the destination is arbitrary; the origin role, however, is usually assigned to the object that acts or operates on the other object. For example, in a relationship of the type person-manages-project, person is the origin, and project is the destination.

You can use relationships to navigate through the Repository's contents. With each relationship, you can retrieve either of the two Repository objects that the relationship associates.


Accessing Relationships

Access to relationships is supported at both the COM level and the Automation level.

To | Use
Create a relationship | Add method of the IRelationshipCol interface.
Delete a relationship | Remove method of the IRelationshipCol interface.
Retrieve a relationship | Automation: the syntax relationshipCollection(index), as for retrieving an item from any Automation collection. COM: the get_Item method of the IRelationshipCol interface, specifying the relationship to be retrieved.
Retrieve an object that participates in a given relationship | Origin or Destination property of the IRelationship interface.


Relationship Collections

A relationship collection is a set of similar relationships. The relationships must be similar in these two ways:

  • The Same Relationship Type

  • The Same Object in the Same Role


The Same Relationship Type

All the relationships in a collection must conform to the same relationship type.

For More Information The Type Information Model


The Same Object in the Same Role

One object must be common to all relationships in the collection. That object must play the same role (either origin or destination) for all relationships in the collection. In the relationship collection shown in the following figure, every relationship uses the object describing Mike as the performer of the work on a subproject. The object describing Mike is the origin object in this relationship.

In contrast, the set of relationships shown in the following figure does not constitute a collection, because there is no object that all the relationships use in the same role. In fact, the relationships have no object in common, regardless of role.


A Common Object in Different Roles

The following figure shows employees and their managers.

From this data the set of relationships shown in the following figure does not constitute a valid relationship collection.

Every relationship in the preceding figure is of the same relationship type, the "manages" type. And all the relationships have an object in common: the object describing Frank. One relationship, however, has Frank in the role of person being managed, whereas the other relationships have Frank in the role of person who is managing someone else. Because the relationships do not all use the same object in the same role, they do not constitute a valid relationship collection.

The three relationships in the following figure do constitute a valid collection because Frank is in the manager role for all three relationships.


Manipulating Relationship Collections

You cannot add or delete a relationship collection after it is created. A relationship collection might consist of zero relationships, but the collection still exists. If you retrieve such a relationship collection, the Repository returns an interface pointer to a relationship collection, just as it would return for any other relationship collection.

The following figure shows four projects; each project has a collection of relationships that associate it with its subprojects.

  • Genome project — the collection has two relationships.

  • Grant proposal 108 project — the collection has one relationship.

  • General research project — the collection has zero relationships.


Accessing Relationship Collections

Access to relationship collections is supported at both the COM level and the Automation level.

To | Use
Add a relationship to a relationship collection | Add method of the IrelationshipCol interface.
Remove a relationship from a relationship collection | Remove method of the IrelationshipCol interface.
Enumerate the relationships within a relationship collection | Automation: the syntax relationshipCollection(index), as for retrieving an item from any Automation collection. COM: the get_Count and get_Item methods of the IRelationshipCol interface, or use the _NewEnum method of the IrelationshipCol interface to obtain a standard enumerator interface for the collection.


Target Object Collections

A target object collection is the set of target objects that are associated with the relationships in a particular relationship collection. For example, the relationship collection in the following figure:

corresponds to this target object collection

because the underlying data looks like this

The object that is common to all of the relationships in the corresponding relationship collection is referred to as the source object. In the preceding figure, the object describing Frank is the source object. The objects describing Kim, Iola, and Fenton are target objects.


Accessing Target Object Collections

Access to target object collections is supported at both the COM level and the Automation level.

To | Use
Include an object in a collection | Add method of the ItargetObjectCol interface.
Exclude an object from a collection | Remove method of the ItargetObjectCol interface.
Enumerate the objects within a target object collection | Automation: the syntax targetObjectCollection(index), as for retrieving an item from any Automation collection. COM: the get_Count and get_Item methods of the ITargetObjectCol interface, or use the _NewEnum method of the ItargetObjectCol interface to obtain a standard enumerator interface for the collection.


Using TargetObjectCol with Relationship Collections

The TargetObjectCol class provides a convenient way to manipulate relationship collections. When you manipulate a target object collection, you actually manipulate the corresponding relationship collection.

For example, suppose you are manipulating the target object collection describing the employees managed by Frank as shown in the following figure.

Now suppose you want to add Louise, an existing employee, to the collection. To do so, use the Add method, extending the collection to look like the collection in the following figure.

When you call the Add method, the Repository actually adds a relationship to the corresponding relationship collection. In effect, you changed the data from this:

to this:


The Repository Itself

You perform certain operations on the Repository itself. For example, you must establish a connection to the Repository in order to access any of the objects or relationships that it contains. You also manage errors and transactions on the Repository as a whole. These operations are supported by the Repository class.

You can manipulate the Repository itself from Automation or COM programs.


Accessing Methods and Properties

Access to Repository methods and properties is supported at both the COM level and the Automation level.

To | Use
Create a new Repository database and open it | Create method of the Irepository interface.
Open an existing Repository database | Open method of the Irepository interface.
Retrieve Repository error information | Automation: use the standard Err Automation object. COM: methods of the IrepositoryErrorQueueHandler, IRepositoryErrorQueue, and IEnumRepositoryErrors interfaces.
Manage transactions in the Repository | Methods of the IRepositoryTransaction interface. To retrieve an interface pointer to the IRepositoryTransaction interface, use the Transaction property of the IRepository interface.

For More Information Repository Error Handling


Information Models

When you design a software tool, you must articulate the kinds of data that the tool will manipulate. You can store the definitions of these kinds of data, called types, in the Repository by creating an information model. Each information model is, in effect, an object model represented in the Repository as data.

This section uses the example of a bookseller's database to introduce information models and describes how Microsoft Repository can represent them as data.

  • Data: Objects, Property Values, and Relationships

  • Kinds of Data: Classes, Properties, and Relationship Types

  • An Information Model Is a Template for Data

  • Data and Metadata

  • Visualizing Data and Metadata

  • Depicting Relationships Between Objects

  • How Relationships Conform to Relationship Types


Data: Objects, Property Values, and Relationships

You can think of any data as objects, property values, and relationships. When you store data with your tool, you can create objects, indicate how those objects are related to each other, and assign values to the properties of each of those objects or relationships. In the bookseller's tool, you can do the following:

  • Create objects such as:
    • Moby Dick (a book)

    • Inside OLE (a book)

    • Microsoft Press (a publisher)

    • Kraig Brockschmidt (a person)

    • Herman Melville (a person)
  • Indicate how those objects are related:
    • Herman Melville (a person) wrote Moby Dick (a book)

    • Kraig Brockschmidt (a person) wrote Inside OLE (a book)

    • Microsoft Press (a publisher) published Inside OLE (a book)
  • Assign values for the properties of each of those objects:
    • Birthday (of Herman Melville) is November 12, 1819

    • Address (of Microsoft Press) is "One Microsoft Way"
  • Assign values for the properties of each of the relationships:
    • Year of Publication (of Microsoft Press's publication of Inside OLE) is 1995

The following figure summarizes this data. The figure shows typical data about specific books, authors, and publishers. Because the data is typical, it helps you visualize the kinds of data that your tool must store.


Kinds of Data: Classes, Properties, and Relationship Types

You can begin planning your information model by answering these questions:

  • What kinds of objects will the tool store? That is, what are the classes to which the tool's objects must conform?

  • What kinds of relationships will the tool store? That is, what are the relationship types that describe how objects can be related?

  • What properties apply to the objects of each class or the relationships of each relationship type?


An Information Model Is a Template for Data

An information model is an object model stored in the Repository. An information model accommodates the kinds of things that your software tool manipulates and thus includes classes, relationship types, and properties.

A class is a template to which stored objects must conform. For example, the book class is a template; when you store an object representing a book, it can have a title and a number of pages, but it cannot have a birthday.

A relationship type is a template to which stored relationships must conform. For example, the "publication" relationship type is a template. When you store a relationship to indicate the publication of a book, the relationship you store must conform to the "publication" relationship type.

A property is a template to which stored property values must conform. For example, when you store a birthday, you must store a date. You cannot store "Abcdefg".

The typical object model stores objects that fall into three classes:

  • The Property class — Each instance of this class describes a property. For example, one instance of this class describes the Birthday property.

  • The Relationship Type class — Each instance of this class describes a relationship type. For example, one instance of this class describes the Authorship relationship type.

  • The Class class — Each instance of this class describes a class. For example, one instance of this class describes the Publisher class.


Data and Metadata

When you design a software system, you articulate the kinds of data that the system will store and manipulate. Later, when end users employ the system, they supply the data itself.

There is a distinction between the kinds of data and the data itself. This distinction is often called the type/instance distinction: software designers articulate types (such as classes or properties) and software users articulate instances (such as objects or property values). It is also known as the distinction between data and metadata. Metadata is data about data.

The distinction between data and metadata (or between instance and type) is a useful distinction, but it is not as rigid as you might initially think, because metadata, although a special kind of data, is nevertheless data. If you can write something down or store it on disk, it is data. Metadata is data because you can write it down. For example, you can make a list of the classes your program uses.

For example, in a typical relational DBMS, the system catalog describes the tables and columns that contain your data. You can think of the data in the system catalog as metadata because it is data about data — specifically, it is data about the data that your database manages for you. But you can also think of the data in the system catalog as data because with the right software tool, you can manipulate it as you would manipulate any other data. For example, when you use a database design tool, you can list out the tables in the catalog, you can sort the tables alphabetically, or you can delete every table whose name is longer than 18 characters.


Visualizing Data and Metadata

This section presents tabular and graphic techniques for visualizing data.

As you plan your information model, you first identify data as objects, property values, and relationships. (See Kinds of Data: Classes, Properties, and Relationship Types.) Next, write down your data as objects, property values, and relationships, identifying the following:

  1. What the objects are.

  2. The relationships that exist between objects.

  3. For each object or relationship, what its property values are.

You now have enough information to use tabular and graphic techniques to visualize your data. These powerful techniques can help you understand the types of data you need. The following topics describe how to visualize data and metadata:

  • Ways to List Data

  • Ways to List Data, Applied to Types


Ways to List Data

The following table lists data about books, people, and publishers. The first column (Kind of Data) provides labels for groups of data: books, people, and publishers. The actual data appears in the table's second column (Data).

Expressed graphically, the data in the table is shown in the following figure.

The following table expands the preceding table to include relationships. Again, the table uses a convenient grouping of the data. The first column labels each group.

The labels in the left (Kind of Data) column are a partial list of the object model for storing the bookseller's data. The labels identify three classes (Book, Person, and Publisher) and two relationship types (Authorship and Publication). Because it is a list, you can think of the entries in the Kind of Data column as data. Because it is data, you can create another table in which this information appears in the Data column. (See Ways to List Data, Applied to Types.)

In the Data column, each entry describes exactly one thing — either an object or a relationship. Each entry in the Data column describes a particular book, author, publisher, authorship, or publication.

The following figure contains arrows to show the relationships in the preceding table.


Ways to List Data, Applied to Types

Repository stores metadata as data. This section uses data visualization techniques to demonstrate how to model metadata. (See Ways to List Data for a table listing and organizing the data about books and publishers.)

The table that follows lists and organizes the types of the bookseller's object model. The left column contains convenient groupings of like information, and the right column (Data) contains the information itself. The Data column describes particular classes (such as Book and Person) and particular relationship types (such as Authorship and Publication). The Kind of Data column thus reveals a portion of the object model for storing classes and relationship types.

The following table enlarges the preceding table to include properties.

In the preceding table, the information in the Data column is equivalent to the information in the following figure. The following figure shows typical data about a typical object model — the bookseller's object model.


Depicting Relationships Between Objects

To depict relationships between objects, use arrows as shown in the following figure.

Diagrams of metadata use these standard conventions:

  • Show objects as dots

  • Show relationships as arrows

  • Show kinds of objects as labeled rectangles

The tabular equivalent of this graphical presentation of data is shown in the following table.

The labels in the Kind of Data column constitute a portion of an object model for storing object models. The object model for storing object models is called the Type Information Model.

Note Each entry in the Data column describes only one thing: either an object or a relationship. The 23 entries in the Data column correspond to the 23 dots and arrows in the preceding figure.


How Relationships Conform to Relationship Types

When you store a relationship, the meaning of what you store has three aspects:

  • Which two objects are related to each other?

    For example, when you store the relationship indicating that Herman Melville wrote Moby Dick, you relate the object describing Herman Melville and the object describing Moby Dick.

  • How are the two objects related?

    For example, when you store the relationship indicating that Herman Melville wrote Moby Dick, you indicate that Melville wrote the book, not that he reads it or criticizes it. You indicate that Melville wrote the book by creating a relationship that conforms to the "Authorship" relationship type.

  • What role does each object play in the relationship?

    For example, when you store the relationship indicating that Herman Melville wrote Moby Dick, you indicate that Melville wrote Moby Dick, not that Moby Dick wrote Melville. The object representing Melville plays the role of the thing performing the writing, and the object representing Moby Dick plays the role of the thing that was written.

The following figures evaluate whether potential relationships conform to the two relationship types: Authorship (of book by person) and Publication (of book by publisher).

Potential relationship

Does the relationship conform?

Microsoft Press publishes Inside OLE: Yes, the relationship conforms to the Publication relationship type.

Potential relationship

Does the relationship conform?

Kraig Brockschmidt publishes Inside OLE: No, the relationship does not conform to either relationship type. The Publication relationship type allows you to save a relationship indicating that a publisher publishes a book. This data indicates that a person publishes a book.

Potential relationship

Does the relationship conform?

Kraig Brockschmidt wrote Inside OLE: Yes, the relationship conforms to the Authorship relationship type.

Potential relationship

Does the relationship conform?

Inside OLE publishes Microsoft Press: No, the relationship does not conform to either relationship type. Although this relationship uses two objects of the correct type, it does not conform because it uses those objects in the wrong roles.

Potential relationship

Does the relationship conform?

Microsoft Press publishes Moby Dick: Yes, the relationship conforms to the Publication relationship type. The relationship conforms, even though the data is inaccurate. (Microsoft Press does not publish Moby Dick.)


The Type Information Model

The Type Information Model is the object model the Repository uses to store information models. This section describes how to create information models.

Before reading this section you should read Information Models.

You do not need the information in this section to program against an existing information model.

The following topics describe the parts of the Type Information Model:

  • Classes and Interfaces

  • Properties

  • Methods

  • Relationship Types and Collection Types

  • Diagram of an Information Model


Classes and Interfaces

In Automation programs, each object exposes its properties, collections, and behaviors through interfaces. To have the instances of a class exhibit certain behaviors or have certain properties or collections, you implement the appropriate interface for that class.

The Type Information Model accommodates such data by letting you describe interfaces. Each interface can have a set of classes that implements it, and each class can have a set of interfaces that it implements.

The following figure shows some classes and the interfaces they implement. In the figure, the Chapter class implements two interfaces, ISpellingChecker and IPagination. Both the Paragraph class and the Chapter class implement the ISpellingChecker interface.


Properties

The Type Information Model lets you describe properties. Each property has an interface that exposes it, and each interface can expose many properties. The following figure shows that the IParagraph interface exposes two properties, Left Margin and Right Margin.


Methods

An interface can expose one or more methods. The following figure shows that the IParagraph interface exposes the Reformat and ConvertIndentation methods.

The Type Information Model accommodates such data. You can enumerate the methods for each interface of an information model. Each method can have one interface that exposes it, and each interface can expose many methods.


Relationship Types and Collection Types

Tools sometimes manipulate sets of relationships as a single unit; these sets are called relationship collections. The Type Information Model lets you describe collection types, templates to which these relationship collections must conform.

The following topics describe relationship types and collection types:

  • Object Collections vs. Relationship Collections

  • Each Relationship Is in Two Collections

  • Collections Conform to Collection Types

  • Minimum and Maximum Collection Size

  • Each Relationship Type Has Two Attendant Collection Types

  • Origin and Destination

  • Naming and Unique-naming Collections

  • Sequenced Collections


Object Collections vs. Relationship Collections

You can read each relationship in two directions. For example, you can say "Herman Melville wrote Moby Dick" or "Moby Dick was written by Herman Melville." We can paraphrase each of these two statements as follows:

  • Herman Melville is in the set of persons who wrote Moby Dick.

  • Moby Dick is in the set of books written by Herman Melville.

Although awkward, this way of articulating relationships highlights the existence of collections. In the following table, each collection is shown as a collection of objects.

Collection (inside the gray ovals)

Commentary

The collection of books written by Herman Melville

Collection (inside the gray ovals)

Commentary

The collection of books written by Kraig Brockschmidt

Collection (inside the gray ovals)

Commentary

The collection of persons who wrote Moby Dick

You can also think of collections as collections of relationships. The following table shows how every collection of objects has an equivalent collection of relationships.

Object collection

Commentary

The collection of books written by Herman Melville

Relationship collection

Commentary

The collection of authorships for which Herman Melville is the writer

Object collection

Commentary

The collection of authors of Moby Dick

Relationship collection

Commentary

The collection of authorships in which Moby Dick is the written thing

As the preceding figures shows, you can think of each collection in two ways — as containing either relationships or objects. When you manipulate a collection object from a COM program, you can manipulate it with an interface called ITargetObjectCol or with an interface called IRelationshipCol. The first interface lets you manipulate a collection as if it contained objects. The second interface lets you manipulate a collection as if it contained relationships.


Each Relationship Is in Two Collections

Each relationship belongs to two collections. For example, the relationship Herman Melville wrote Billy Budd is a member of two different collections:

  • The set of books written by Herman Melville; or, expressed in terms of a relationship collection, the set of authorships for which Herman Melville is the writer.

  • The set of authors of Billy Budd; or, expressed in terms of a relationship collection, the set of authorships for which Billy Budd is the written thing.


Collections Conform to Collection Types

A collection type is a template to which a collection conforms. The right column (Data) of the following table lists some collections by name; the kinds of collections are in the left column under Kind of Data. The Kind of Data column indicates the templates to which the items in the Data column must conform. Since the items in the Data column are collections, the items in the Kind of Data column are called collection types.


Minimum and Maximum Collection Size

The most important way that a collection can conform to a collection type is in its size. That is, a collection type describes the size limitations on any collection conforming to it. In the following table, each instance of the collection type Publisher-of-book describes the collection of publishers of a particular book. A typical instance of this collection type is "Publisher-of-Inside-OLE." In the table, each book has only one publisher.

The collection type can define this restriction. That is, the Publisher-of-book collection type can impose on each collection conforming to it a maximum size of one. Similarly, the collection type can define a minimum-size restriction.

The following list contains some other examples:

  • Publisher-of-book (zero, one)

    The minimum size is zero because not every book has a publisher. The maximum size is one because no book can have two or more publishers.

  • Books-of-publisher (zero, many)

    The minimum size is zero because a publisher can exist before it actually publishes any books. The maximum size is "many" because some publishers can publish more than one book.

  • Books-of-person (zero, many)

    The minimum size is zero because not every person is an author. The maximum size is "many" because some people can write more than one book.

  • Authors-of-book (zero, many)

    The minimum size is zero because the authors of some books are anonymous. The maximum size is many because more than one person can co-author a book.


Each Relationship Type Has Two Attendant Collection Types

There is a relationship between collection type and relationship type. The following figure shows some relationship types and their attendant collection types.

In the figure, each relationship type has exactly two collection types. The following are true for every relationship:

  • Each relationship is a member of two collections.

  • Each relationship relates two objects.

  • You can read each relationship in two directions.

  • In any relationship, the related objects participate in two separate roles. For example, the roles in the relationship Kraig Brockschmidt wrote Inside OLE, are:
    • The role of writing thing, filled by the object describing Kraig Brockschmidt.

    • The role of written thing, filled by the object describing Inside OLE.

    The two roles correspond to the two collection types.


Origin and Destination

In every Repository relationship, one object participates as the origin object and the other as the destination object. Consequently, the two collections in which the relationship itself belongs are called the origin collection and the destination collection. Every origin collection conforms to a collection type called an origin collection type, and every destination collection conforms to a collection type called a destination collection type.

When you define a relationship type and its attendant collection types, you must declare one collection type as the origin. The distinction between origin and destination is important because naming collections, unique-naming collections, and sequenced collections can only be defined as origin collections.


Naming and Unique-naming Collections

Certain relationships can provide a name by which the origin object refers to the destination object. Such a relationship is called a naming relationship. A collection of naming relationships is a naming collection.

Certain naming collections require that all destination objects in the collection have unique names. Such a collection is referred to as a unique-naming collection.

Some information models require that an object can have multiple names. For example, consider a system in which a single program can have two different file names, because there are two different file systems that allow and disallow long names, respectively. The following figure illustrates.

The figure shows four relationships. Each relationship specifies a name by which one of the objects (the origin object) refers to the other object (the destination object). In particular, notice that the object representing the error-handling program file has two different names, "ErrHndl" and "ErrorHandler".

In order to support this kind of capability, the Type Information Model attaches the name property to the relationship type, not to the object class. This enables an object to have as many names as it has relationships (that is, relationships for which it is the destination).


Sequenced Collections

Some information models require that the tool can set the sequence of items in a collection. This requirement can arise when the sequence itself is significant in some way.

A collection that supports the sequencing of its items is referred to as a sequenced collection. Relationships contained within such a collection are sequenced relationships. The Type Information Model supports the definition of collection types for sequenced collections.

For example, consider a report generator tool that displays tables of data, where the data is displayed in rows and columns. Each table is represented by an object that conforms to the Table class. The columns of the table are represented by objects that conform to the Column class. Each table has a collection of columns that are included in it (the relationship that relates a Table object to a Column object is the "includes" relationship). The following figure illustrates.

The report generator tool relies on the sequence of the column items in the collection to determine the order in which the columns will appear when the table is displayed or printed. For the Student table, the report is displayed with the Student ID column leftmost, the Last Name column next, and the First Name column on the right-hand side.


Diagram of an Information Model

The following figure shows a complete information model that illustrates the various parts of the Type Information Model.

The information model in the preceding figure maintains data about files and directories. Thus, there are two classes, File and Directory.

There are three interfaces:

  1. IFile exposes behavior unique to files. Thus, only the File class implements it.

  2. IDirectory exposes behavior unique to directories. Thus, only the Directory class implements it.

  3. IDirectoryItem exposes behavior appropriate to any object that can appear as an item within a directory. Since files can be contained in directories, the File class implements IDirectoryItem. Similarly, since directories can be contained within directories, the Directory class implements IDirectoryItem.

There is one relationship type: the Containment relationship type.

There are two collection types associated with the Containment relationship:

  1. Collections that conform to the Items-of-directory collection type are origin collections for Containment relationships. The IDirectory interface exposes this collection.

  2. Collections that conform to the Directory-of-item collection type are destination collections for Containment relationships. The IDirectoryItem interface exposes this collection.

The IFile interface exposes one property: the Size property.

The IDirectoryItem interface exposes one property: the ModificationDate property.

The IDirectory interface exposes one property: the ChildCount property.

This information model exposes no methods through any of its interfaces.


Repository Identifiers

Microsoft Repository uses identifiers to distinguish objects from each other and to distinguish object versions from each other.

The following sections describe how these identifiers work:

  • Object Identifiers and Internal Identifiers

  • Object-Version Identifiers and Internal Object-Version Identifiers

  • Using Object Identifiers

  • Using Guidgen.exe


Object Identifiers and Internal Identifiers

Each Repository object has an identifier called the object identifier that distinguishes it from all other Repository objects represented in all other Repository databases. The object identifier has the following format.

The first 16 bytes of each object identifier constitute a globally unique identifier (or GUID). The next 4 bytes constitute a local identifier.

Each Repository object also has an internal identifier that distinguishes it from every other object within the same Repository database. The internal identifier is an 8-byte quantity of the following form.

The first 4 bytes constitute a site identifier (site ID). The last 4 bytes constitute the local identifier (local ID).

For any Repository object, the local identifier is the same for the internal identifier and the object identifier. That is, each Repository object has exactly one 4-byte local identifier.

There is a one-to-one correspondence between an object's site identifier and its GUID, and each Repository database includes a table (RTblSites) that maintains this correspondence. Each row of the table associates one GUID with one site identifier.

Repository uses the one-to-one correspondence between the site identifiers and GUIDs to conserve space in the Repository database. When the Repository engine stores a Repository object, it stores the internal identifier with the object. The engine does not store the GUID or the object identifier with the Repository object. When you need the object identifier of an object, the Repository engine constructs the object identifier by reading the internal identifier stored with the object, matching the site identifier to the appropriate row of the RTblSites table, and reading the GUID from that row.


Object-Version Identifiers and Internal Object-Version Identifiers

Each Repository object version has an identifier called the object-version identifier that distinguishes it from all other Repository objects represented in all other Repository databases. The object-version identifier has the following format.

The first 16 bytes of each object-version identifier constitute a globally unique identifier (or GUID). The next 4 bytes constitute a local identifier. Note that the local identifier of a Repository object version does not equal the local identifier of the more general Repository object.

Each Repository object version also has an internal object-version identifier that distinguishes it from every other object version within the same Repository database. The internal object-version identifier is a 16-byte quantity of the following form.

The first 4 bytes constitute a site identifier (site ID). The next 4 bytes constitute the local identifier (local ID) of the Repository object. The next 4 bytes constitute a branch identifier (branch ID); a branch is a portion of a version graph. The next 4 bytes constitute a version-within-branch identifier.

The first 8 bytes make up the internal identifier of the Repository object. The next 8 bytes make up a version identifier.


Using Object Identifiers

When you create a Repository object, you can supply an object identifier or let Repository assign one automatically. In most cases, let Repository assign one.

The exception is when you are inserting a replica of an object represented in some other Repository database into the Repository. In such cases, explicitly assign an object identifier to ensure that the newly created object's object identifier matches the object identifier used for the existing object in the other Repository database.

When you create an information model, you create a number of Repository objects to represent the classes, interfaces, collection types, properties, and relationship types of that model. You can explicitly assign an object identifier for each such object you create. If you explicitly assign object identifiers for your definition objects, you must ensure that the object identifiers are unique across all Repositories. The recommended way to guarantee such uniqueness is as follows:

  1. Generate a single unique GUID and use it for the GUID portion (the first 16 bytes) of all definition object identifiers for the information model.

  2. Manually assign unique local identifiers for each definition object in the information model.


Using Guidgen.exe

When creating object identifiers for your information model, use the Guidgen.exe program to create an unused GUID, and use the DEFINE_OBJID(name, uniqifier, guid) macro to create the object identifiers. Given a GUID and a unique number for an object, the macro will equate the symbolic name to the value for the object identifier. Use the DEFINE_OBJID macro (which is provided for both Visual C++ and Visual Basic® programmers) to avoid incompatibility problems later.


Moving Through the Repository's Contents

Because the objects represented in the Repository are connected through relationships, you can move from one object to any related object. This section describes the process of retrieving objects related to a given object.

This section requires an understanding of the information presented in The Type Information Model.

The following sections describe how to move through the Repository's contents:

  • Accessing Objects Overview

  • Common Manipulation of Objects

  • Object and Relationship Collections

  • Source Objects and Target Objects

  • Selecting Items in a Collection

  • Using Enumerators with the Repository

  • Heterogeneous Collections of Objects


Accessing Objects Overview

The information in the Repository is a network of objects and relationships. For example, consider a sample tool that stores information about bugs, persons who report those bugs, and programs in which those bugs occur. Each person can report many bugs, and each bug can be reported by one person. Each program can have many bugs reported on it, and each bug can apply to one program.

The following figure illustrates some typical data stored by this sample tool. In the figure, each point represents an object and each line represents a relationship between two objects.

The data in the preceding figure shows how you can:

  • Move from one object to another by following a particular relationship.

    For example, to learn the file name of the program containing bug 15, follow a particular relationship from bug 15 to the object representing the program, and then retrieve that object's file name property.

  • Focus your attention on a collection stored in the Repository by retrieving it directly from the Repository. For example, you can retrieve a collection containing the bugs that Frank has reported.

    The following figure shows this collection.

  • Follow a path consisting of multiple relationships by following each individual relationship in turn. For example, while manipulating the object representing Frank, you can move through the Repository's contents to answer the question "On what program did Frank report his first bug?"

    The following figure shows the path from the object representing Frank through the object representing Frank's first reported bug to the object representing the program on which Frank reported that bug.


Common Manipulation of Objects

You move to an object because you want to manipulate it. You can get or set a property, delete an object, delete a relationship between two objects, or add a relationship between two objects. The software bug-reporting example illustrates some common manipulations:

  • Get a property — retrieve a bug's description for filling out a bug report.

  • Set a property — change a bug's priority from Moderate to Urgent.

  • Delete an object — delete a new bug because it replicates an already reported bug.

  • Delete an object — disassociate a program from a bug when an employee associates a bug with a program before the bug has been accurately diagnosed.

  • Add a relationship between two objects — associate an existing but previously undiagnosed bug with a program.


Object and Relationship Collections

You move through the Repository through collections. You can get a collection of objects or a collection of relationships. A typical collection of objects is the collection of software bugs discovered by Frank, as shown in the following figure.

A typical collection of relationships is the set of bug discoveries attributed to Frank. The preceding figure represents this collection as the lines; in other words, each line represents the discovery (by Frank) of a particular bug.


Retrieving Object Collections

Object collections can be retrieved at the Automation level and the COM level.

To retrieve a collection of objects using Automation interfaces

  1. Declare a variable as an object that implements the ITargetObjectCol interface.

  2. Set it equal to the object member that is the collection you want to retrieve.

Note All collections in the Repository are attached to Repository objects as members.

For example, the following Visual Basic code retrieves a collection of bugs (a target object collection) discovered by a particular person into the variable called BugCollection.

DIM BugCollection As ITargetObjectCol
DIM Person As RepositoryObject
…
REM Retrieve the source object into the Person variable
…
Set BugCollection = Person.bugs

In this example, BugCollection(1) would refer to the first object in the collection.

To retrieve a collection of objects using COM interfaces

  1. Call the Invoke method of the interface to which the collection is attached.

  2. Pass in DISPATCH_PROPERTYGET to specify that this is a property-get operation.

  3. Pass in the dispatch identifier for the collection to be retrieved.

    The Invoke method will pass an IDispatch interface pointer for the collection back to you.

  4. Invoke the QueryInterface method of the IDispatch interface to retrieve an ITargetObjectCol interface pointer for the collection of target objects.


Retrieving Relationship Collections

Relationship collections can be retrieved at the Automation level and the COM level.

To retrieve a collection of relationships using Automation interfaces

  1. Declare a variable as an object that implements the IRelationshipCol interface.

  2. Set it equal to the object member that is the collection you want to retrieve.

For example, the following Visual Basic code retrieves a collection of bug discoveries (a relationship collection) belonging to a particular person into the variable called DiscoveryCollection.

DIM DiscoveryCollection As IRelationshipCol
DIM Person As RepositoryObject

…Retrieve the source object into the Person variable…

Set DiscoveryCollection = Person.bugs

In this example, DiscoveryCollection(1) would refer to the first relationship in the collection.

To retrieve a collection of relationships using COM interfaces

  1. Call the Invoke method of the interface to which the collection is attached.

  2. Pass in DISPATCH_PROPERTYGET to specify that this is a property-get operation.

  3. Pass in the dispatch identifier for the collection to be retrieved.

    The Invoke method will pass an IDispatch interface pointer for the collection back to you.

  4. Invoke the QueryInterface method of the IDispatch interface to retrieve an IRelationshipCol interface pointer for the collection of relationships.


Source Objects and Target Objects

Each relationship collection is attached to an object through an interface. This object is the source object for each relationship in the collection. Each relationship in the collection also has a target object — the object related to the source object.

The words source and target convey the potential for browsing. The source object of a relationship is the object for which you retrieved the collection. The target object of a relationship is the object that can become the target of a step from the source object, through the relationship, to the target object.

Note Source-and-target terminology differs from origin-and-destination terminology. The origin and destination do not change based upon which collection is being used to access a relationship; the source and target do change.

For example, the relationship between Frank and bug 15 has these two articulations:

  • Frank discovers bug 15.

  • Bug 15 is discovered by Frank.

For this relationship, the origin object is always Frank, and the destination object is always bug 15. The source and target objects, however, depend upon which collection is used to access the relationship. The two relationship collections that contain this relationship are:

  • The collection of discoverers of bug 15. The object that represents bug 15 is the source object for this collection.

  • The collection of bugs discovered by Frank. The object that represents Frank is the source object for this collection.


Selecting Items in a Collection

You can select the items of a collection by index, by sequence, by enumerator, or by name. If you get a collection for an origin object — that is, if you plan to move from an origin object to a destination object, all of these selection options are available. If you get a collection for a destination object — that is, if you plan to move from a destination object to an origin object, you have fewer selection options.

You can select collection items in the following ways:

  • By index — choose the nth item in the collection, where n is a number between one and the size of the collection.

    COM: use the get_Item method of the IRelationshipCol interface or the ITargetObjectCol interface.

    Automation: use the syntax collection(index), as for any Automation collection.

  • By sequence — Use the same programming statements to select by sequence as you use to select by index. The distinction between the two depends only on how the Repository orders the items in the collection. In most cases, the Repository uses an arbitrary order. But if the collection is a sequenced collection, the Repository orders the collection items according to the defined sequence.

    You can select by sequence only from a collection belonging to an origin object. You cannot select by sequence from a collection belonging to a destination object, because the Repository does not sequence collections belonging to destination objects.

  • With an enumerator — That is, at the COM level you can get an enumerator object for a collection, and then use the standard enumerator functions (Next, Skip, Reset, and Clone). Use the _NewEnum method of the IRelationshipCol interface or the ITargetObjectCol interface to obtain an interface pointer to an enumerator object.

    For More Information Using Enumerators with the Repository

  • By name — If the collection is a naming collection, you can select the item whose name matches the name you supply.

    COM: use the get_Item method of the IRelationshipCol interface or the ITargetObjectCol interface.

    Automation: use the syntax myCollection("name").

    Note You cannot select by name from a collection belonging to a destination object, because the Repository does not support the naming of origin objects.

    If the naming collection is not a unique-naming collection, and there are multiple items with the same name, the Repository will return the first item that it finds with the specified name.


Using Enumerators with the Repository

When the Repository establishes an enumerator for you, it reads the Repository database to determine which items should appear in the list, and the order in which those items should appear. The enumerator does not, however, contain Repository items. Rather, each element of an enumerator identifies a Repository item. To retrieve a particular item identified by the next element of an enumerator, use the Next method of the enumerator interface.

The elements in an enumerator identify the items in a collection as described by the Repository database when the enumerator was instantiated. After you instantiate the enumerator, the collection in the database can change. Specifically, the collection can change in these ways:

  • Add an item.

    Your enumerator will not refer to the newly added item. To see the new item, you must instantiate the enumerator again.

  • Remove an item.

    Your enumerator will continue to refer to the deleted item. That is, your enumerator will retain an element that refers to the deleted item by its internal identifier. When you call the Next method to retrieve the item, the method returns an error.

  • Reorder the collection.

    Your enumerator will reflect the old order. To see the new order, you must reinstantiate the enumerator.


Heterogeneous Collections of Objects

Every collection of relationships is homogeneous. In any relationship collection, each item is a relationship of the same relationship type. Some collections of objects, however, are heterogeneous — the items can have different classes.

A collection of objects can be heterogeneous because:

  • The Type Information Model allows each interface to be implemented by many classes.

  • The Type Information Model expresses each relationship type as an association between two interfaces (rather than as an association between two classes).

Each relationship type describes how the objects of classes implementing particular interfaces can be related. Thus, if a particular interface has several implementing classes, some relationship types involving that interface could yield collections whose target objects span several classes. As you prepare programs that manipulate such collections, do not assume that the collections will contain homogeneous sets of objects.

Note Plan for change; do not assume that your tool information model will remain unchanged. Although a particular relationship type of your tool information model might associate two interfaces that are implemented by exactly one class each, you might someday create other classes that implement those same interfaces. Enlargement of the number of classes implementing either of those interfaces by any Repository user introduces the possibility for heterogeneous collections of objects. If your programs using those collections depend upon homogeneous collections, you must rewrite them as soon as you implement the interfaces with several classes. To protect your programs from this cause of obsolescence, write them assuming that any collection of objects can be heterogeneous.


Information Model Creation

You can create a new information model or extend an existing one. This section provides an overview of information model creation and discusses some issues to consider in designing and inserting information models into the Repository.

  • Information Model Creation Overview

  • Information Model Creation Issues


Information Model Creation Overview

When you insert an information model into the Repository, you populate the Type Information Model. That is, you create instances of the classes, interfaces, properties, methods, and relationship types of the Type Information Model.

To create a new information model

  1. Begin a transaction.

  2. Create a Repository type library.

  3. Add classes to the Repository type library.

  4. For each class, add interfaces.

  5. For each interface, add properties.

  6. For each interface, add methods.

  7. Add relationship types and pairs of collection types.

  8. Commit the transaction.

For More Information To get detailed information about the parameters for any of the methods discussed in this section, search for the method name in the Repository Automation Reference or the Repository COM Reference.


Begin a Transaction

To write data to the Repository, bracket your interactions within the scope of a transaction.

To begin a transaction

  1. Open or create the Repository into which you want to insert the information model. To open an existing Repository, use the Open method of the IRepository interface.

    -or-

    To create a new Repository, use the Create method of the IRepository interface.

    Both of these methods return the root object for the open Repository.

  2. Invoke the Begin method of the IRepositoryTransaction interface.

    The IRepositoryTransaction interface is accessible via the Transaction property of the object that represents your connection to the Repository.


Create a Repository Type Library

The Type Information Model includes a class named ReposTypeLib; each instance of this class corresponds to a Repository type library. Each Repository type library describes an information model.

To create an instance of the ReposTypeLib class

  • Use the CreateTypeLib method of the root object’s IManageReposTypeLibs interface.

Note Each instance of ReposTypeLib has a collection of types, where each type is either a class, an interface, or a relationship type. The collection is called ReposTypeInfos, and is used to ensure that unique names are used for all classes, interfaces, and relationship types in your information model.


Add Classes to the Repository Type Library

According to the Type Information Model, you define a new object class by creating an instance of the ClassDef class.

To create a new class definition

  • Use the CreateClassDef method of the IReposTypeLib interface that is exposed by your ReposTypeLib object.

    Be sure the class identifier that you supply as an input parameter to this method matches the class's GUID in the system registry.

Note Within the system registry, you can indicate which Automation server the Repository uses to create instances of your new class. You can use the Automation server that the Repository provides for all Repository objects, or you can use your own server. (See Information Model Creation Issues for information about deciding which kind of Automation server to use.)


For Each Class, Add Interfaces

Each of the classes in your information model exposes one or more interfaces. Add a new interface to a class by creating an instance of the InterfaceDef class.

To create a new interface definition

  • Use the CreateInterfaceDef method of the IClassDef interface that is exposed by your ClassDef object.

    Be sure the interface identifier that you supply as an input parameter to this method matches the GUID that has been assigned to the interface.

Note Among the interfaces you create for your information model, you must include an interface that the ReposRoot class implements. You need this interface and an attendant relationship type to enable navigation to the objects that will populate your information model. (See Information Model Creation Issues for more information about why you need this interface.)


For Each Interface, Add Properties

Each of the interfaces in your information model can expose properties. Attach a new property to an interface by creating an instance of the PropertyDef class.

To create a new property definition

  • Use the CreatePropertyDef method of the IInterfaceDef interface that is exposed by your InterfaceDef object.


For Each Interface, Add Methods

Each of the interfaces in your information model can expose methods. Attach a new method to an interface by creating an instance of the MethodDef class.

To create a new method definition:

  • Use the CreateMethodDef method of the IInterfaceDef interface that is exposed by your InterfaceDef object.

Note If your interface has methods, you must provide your own Automation server for classes that implement this interface. (See Information Model Creation Issues for more information about deciding which kind of Automation server to use.)


Add Relationship Types and Pairs of Collection Types

Relationships connect objects to each other in the Repository. When you define a new relationship type, you also define an origin collection type and a destination collection type. The origin collection type connects the relationship type to one interface; the destination collection type connects the relationship type to a second interface. The classes that implement those interfaces are now "related" in your information model.

To create a new relationship type (and its corresponding pair of collection types) and attach it to two interfaces

  • Use the CreateRelationshipDef method of the IReposTypeLib interface that is exposed by your ReposTypeLib object.

Note One of the relationship types that you create for your information model must enable moving from the Repository’s root object to some objects of your information model. (See Information Model Creation Issues for more information about why you need this interface.)


Commit the Transaction

When you have added all of the type definition objects to your information model, use the Commit method of the IRepositoryTransaction interface to commit your additions to the Repository database.


Information Model Creation Issues

When you insert an information model into the Repository, you have the following choices and decisions to make:

  • How much of the tool information will you store in the Repository database and how much will you store in other files?

  • For each class you define in your information model, what Automation server will create instances of that class?

  • Can you tune the database schema to improve performance?

  • Should you create a new information model or extend an existing one?

  • Should you assign object identifiers, or let the Repository do this for you?

  • How will your information model accommodate movement from one object to another?

The following sections discuss each of these:

  • Choosing Which Information Belongs in the Repository

  • Choosing an Automation Server for a Class

  • Tuning the Database Schema of an Information Model

  • Extending vs. Creating Information Models

  • Assigning Object Identifiers

  • Accommodating Movement Within an Information Model


Choosing Which Information Belongs in the Repository

You do not need to store all your tool's information in the Repository. For example, suppose your tool helps application developers and systems engineers keep track of the bugs on their software systems. Your tool maintains modules, bug reports, and test suites. Each module has a name, an author, source code, and one or more bugs reported on it. Each bug can have a description, a module on which it is reported, and a test suite used to reproduce the bug. Each test suite can have one or more bugs that it can reproduce. Because your tool maintains each test suite in a file format, you decide not to explicitly insert each test suite into the Repository. Instead, you will store in the Repository only the name of a file containing the test suite.

To decide which information belongs in the Repository, consider the following questions:

  • Do you want to perform impact analysis on the data?

    The more information you store in the Repository, the more impact-analysis questions you can answer. Consider the example described above. Because the information model includes a class describing test suites, you can learn which test suite generates the most bugs.

    Conversely, because the information model does not include a class accommodating individual tests or the persons responsible for them, you cannot use the Repository to learn which person discovers the most bugs.

  • Is there another file format that is more appropriate for the fine details of your tool’s information?

    There are two aspects to consider:

    1. If a tool manipulates objects whose fundamental units of storage and manipulation are large, a file format can be more efficient than the Repository. In this case, it is probably more effective to store the data objects in their native file format, and to store in the Repository a description of each data object.

    2. If an existing tool already stores its data in a file format, switching to the Repository would require rewriting the tool. To save time, you can choose to retain the existing file format and replicate some subset of the tool’s data in the Repository.


Choosing an Automation Server for a Class

After you add your information model to the Repository, you can run your tool. Periodically, your tool will invoke the CreateObject method to create an instance of one of the classes of your information model. CreateObject must create a run-time object (that is, an Automation object). To create the run-time object, the Repository calls CoCreateInstance, using as a parameter the ClassID you provided as a property of the class.

When the Repository calls CoCreateInstance with the ClassID, the system registry is checked to determine which Automation server contains the required class factory. For most classes in your information model, a generic Automation server for Repository objects, Repodbc.dll, suffices. To use the generic server as the Automation server for a class, specify Repodbc.dll in the entry for that class in the registry.

Although Repodbc.dll suffices as the Automation server for most Repository classes, you will occasionally create a class whose instances require special treatment. For example:

  • A class of your information model requires input validation.

    You can validate the property values or collections of each instance of a class by writing a special Automation server for that class.

  • A class of your information model replicates some properties retained in another file format outside the Repository.

    Suppose your information model includes a class whose instances describe Microsoft® Word documents. Each instance describes a Word document, indicating specifically its title, subject, and author. Your class-specific Automation server must include special code to ensure that the values of the Repository properties match the values of title, subject, and author stored in the Word file.

  • A class of your information model requires some class-specific behavior that you implement in a method.

    Suppose your information model includes a class whose instances describe modem pools. Each instance describes a particular modem pool, including its phone number. Your class-specific Automation server can include a method to automatically dial the number and establish a connection.

Note At this time, Microsoft Repository supports in-process Automation servers only (that is, dynamic-link libraries).


Tuning the Database Schema of an Information Model

The Repository stores data in a relational database. When you add an information model, the Repository enlarges this database by creating new tables and columns to accommodate your tool information. Generally, each interface corresponds to a table, and each property corresponds to a column. When you populate your information model, the Repository inserts rows into these tables.

You have some control over the database schema that accommodates your tool information. For example, you can:

  • Use a single table to contain the interface-specific properties of more than one interface.

    To do this, set the TableName property for each interface definition object to the same name, before you commit the transaction that is used to create your information model.

  • Create an additional index for a table.

    To do this, open the database directly and use the SQL CREATE INDEX command, after you commit the transaction that is used to create your information model.

Note You cannot completely control the database schema. In particular, each table must include the columns IntID, Z_BrID_Z, and Z_VS_Z, and must define the primary key on those columns. Furthermore, you cannot drop columns that your information model uses to store properties.


Extending vs. Creating Information Models

You can create a new information model or extend an existing one. In general, each information model should accommodate the data about a particular area of your application environment.

Follow these guidelines:

  • To extend the Repository to accommodate a kind of data unrelated or minimally related to existing tool information, create a new information model.

  • To extend the Repository to accommodate additional kinds of data that is closely related to existing tool information, extend an existing information model.

The Repository prevents you from reusing a name for a class, interface, or relationship type within the same information model. You can, however, reuse a name in a different information model. When you create a new information model, choose your names carefully. Avoid naming confusion by using a distinctive prefix on all of your names. For example, all of the names in the Microsoft Development Objects Model are prefixed with the characters "Mdo".


Assigning Object Identifiers

Usually you should allow the Repository to assign object identifiers for your information model type definition objects. You can do this by setting the input parameter for the object identifier to OBJID_NULL on any of the Create methods.

If you are populating a new Repository with an information model that has been defined in an existing Repository, you should assign specific object identifiers. For each type definition object that you copy to the new Repository, you should use the object identifier that was assigned to that object in the existing Repository. This will ensure that the type definition has the same identity in all repositories.


Accommodating Movement Within an Information Model

Because the objects in your information model are associated through relationships, you can move among them. The first step must be from the Repository's root object to an object in your information model. To enable this first step, include in your information model a relationship type whose instances will associate the root object with objects stored in your information model. Create a relationship type with these characteristics:

  • The relationship type's origin collection type is a member of an interface implemented by the ReposRoot class.

  • The relationship type's destination collection type is a member of an interface implemented by a class of the information model.

To create this relationship type

  1. Create a new interface and add it to the set of interfaces implemented by the ReposRoot class.

  2. Create a relationship type associating the newly created interface with some interface implemented by a class of your information model. Choose an interface implemented by a fundamental class — a class whose instances are good objects from which to begin moving to other objects of the information model.

For More Information For more information about moving through the Repository, see Moving Through the Repository's Contents.


Repository Error Handling

Repository error information is available to programs that use Microsoft Repository interfaces. This section gives an overview of Repository error handling and presents techniques for accessing Repository error information.

To do this | Read this
Write programs that use Microsoft Repository | Repository Error Handling — entire section
Access Repository interfaces at the Automation level (for example, from a Visual Basic® program) | Overview of Error Handling Accessing Error Information at the Automation Level
Access Repository interfaces at the COM level (for example, from a Visual C++® program) | Overview of Error Handling Accessing Error Information at the COM Level Saving Error Queue Information


Overview of Error Handling

Error Handling Overview

At the COM level, Repository interface members return an HRESULT return value that indicates whether or not the method completed successfully. If a Repository interface member fails to complete successfully, an error object that contains details about the failure is created.

Each instance of the Repository class maintains one Repository error queue. When an error is generated by a Repository interface member, it is added to the error queue. If multiple errors occur as a result of a single member invocation, all of the errors are added to the error queue.

The Repository error queue is a transient object; that is, the contents of the queue are valid only immediately after an error has occurred. Subsequent interactions with any Repository objects will automatically clear the error queue.


Accessing Error Information at the Automation Level

When a Repository interface member generates an error, Automation programs can access the Repository error object through the global Err object. The first error in a Repository error queue is the error that is placed into the Err object.

In Visual Basic, you can use the On Error statement to invoke an error handler when an error is encountered. In the error handler, access the global Err object's properties to retrieve the error information.

Only the first error in the Repository error queue is accessible through the Err object.


Accessing Error Information at the COM Level

COM programs can access all of the errors in a Repository error queue. You can use the IRepositoryErrorQueue COM interface to manage errors in a Repository error queue. With this interface, you can:

  • Get a count of the number of errors in a queue.

  • Enumerate the errors in a queue.

  • Insert errors into a queue.

  • Remove errors from a queue.

  • Retrieve an error from a queue.

To access the first error in the error queue from a COM program

  1. Use the QueryInterface method of the IRepository interface to obtain an IRepositoryErrorQueueHandler interface pointer. There is an IRepository interface pointer associated with each instance of the Repository class.

  2. Call the GetErrorQueue method of the IRepositoryErrorQueueHandler interface to obtain an IRepositoryErrorQueue interface pointer.

  3. Use the Item method of the IRepositoryErrorQueue interface to retrieve the error information for the first error in the queue.

To access multiple errors in the error queue from a COM program

  1. Use the QueryInterface method of the IRepository interface to obtain an IRepositoryErrorQueueHandler interface pointer. There is an IRepository interface associated with each instance of the Repository class.

  2. Call the GetErrorQueue method of the IRepositoryErrorQueueHandler interface to obtain an IRepositoryErrorQueue interface pointer.

  3. Call the _NewEnum method of the IRepositoryErrorQueue interface to obtain an IEnumRepositoryErrors interface pointer.

  4. Call the Next method of the IEnumRepositoryErrors interface to return error information for the first error in the queue.

  5. Call the Next method of the IEnumRepositoryErrors interface to return error information for each of the remaining errors in the queue.


Saving Error Queue Information

A process can create multiple instances of the Repository class, with each instance connected to a Repository database. A repository database can have multiple repository instances connected to it simultaneously, from the same or from different processes. Each repository instance maintains a single, separate error queue.

You can access only one Repository error queue at a time. When you switch from one error queue to another, several things occur automatically:

  • The IRepositoryErrorQueue interface reference to the first error queue is automatically released.

  • If that reference was the only remaining reference to the interface, the error queue is destroyed.

  • An IRepositoryErrorQueue interface reference to the second error queue is automatically added.

Consequently, if you switch from one error queue to a second error queue, and then back to the first error queue, the first error queue is destroyed and re-created as an empty queue.

To switch between multiple error queues and retain all error queue information

  1. Obtain an IRepositoryErrorQueue interface pointer for the error queue.

  2. Explicitly increment the interface reference count using the AddRef method that is associated with the error queue.

Note You must repeat these steps for each error queue.

The error queues will be retained as long as you hold these explicit interface references.

To switch back and forth between error queues

  • Use the SetErrorQueue method of the IRepositoryErrorQueueHandler interface. When the error queue information is no longer needed, use the Release method to remove the explicit interface references.


Transaction and Thread Management

When you make changes to a Repository, the updates are done within the scope of a transaction. You use Repository transaction management methods to ensure that changes to a Repository database always leave the database in a consistent state. This section discusses the transaction management support provided by Microsoft Repository, and the threading model that is supported by Repository objects.

Read this section if you will be creating information models or writing programs that populate or update an information model. You do not need to read this section if you will be programming to retrieve data from the Repository.

  • Transaction Management Overview

  • Other Transaction Management Issues

  • Repository Objects and Multithreading


Transaction Management Overview

Transactions can be used to bracket multiple interactions with the Repository. Changes to a Repository that are a result of such interactions are either all committed or all undone, depending upon the way that the transaction is completed. Repository methods that write data to the Repository can be executed only within a transaction. Methods that read data from the Repository can be executed without a transaction (although such reads can be done against partially updated data).

A Repository database can have multiple Repository instances connected to it simultaneously, from the same or from different processes. Each Repository instance can have at most one transaction active at a time.

As a rule, the Repository engine never implicitly cancels transactions. If a failure occurs, you must explicitly cancel the transaction. There is one exception to this rule: If you start a transaction, and then release the Repository instance to which the transaction belongs, your transaction will be canceled.


Managing Transactions

Each instance of the Repository class implements the IRepositoryTransaction interface, which supports these methods and properties:

  • The Begin method, which marks the beginning of a transaction.

  • The Commit method, which marks the end of a transaction.

  • The Abort method, which cancels a transaction and undoes all updates performed by the transaction.

  • The GetOption and SetOption methods, which get and set transaction options that control:
    • Whether or not other transactions are permitted to open the Repository database from within the same process.

    • Whether or not updates are cached until the Commit is performed.

    • How long to wait for a transaction to start.

    • How long to wait for a lock on a Repository object.
  • The Status property, which indicates whether or not a transaction is currently active.

For each open Repository instance, the pointer to the IRepositoryTransaction interface is available through the Transaction property.

For More Information Repository Automation Reference; Repository COM Reference


Nesting Transactions

Repository permits nesting of Begin and Commit method invocations, but no actual transaction nesting occurs. A nested transaction count is maintained for each open Repository instance.

Invoking the Begin method during an active transaction increments the nested transaction count by one, but has no other effect.

Invoking the Commit method during an active transaction decrements the nested transaction count by one. If (and only if) this decrement reduces the nested transaction count to zero, all updates are committed to the Repository database.

Invoking the Abort method during an active transaction undoes all changes made during that transaction. Changes made during any nested transactions are also undone, even if the Commit method has already been invoked for those transactions. The nested transaction count is set to zero.


Transactions and Caching

Repository changes are cached to improve performance. Guaranteed updates to a Repository are written to persistent storage only when the active transaction is committed.

Multiple Repository instances within the same process share a Repository cache. Within the same process, when a transaction for one Repository instance commits, its updates are immediately visible to transactions executing for other Repository instances. These updates are not visible to open Repository instances in other processes if those processes already have the pre-update data cached. Explicit refreshes are required to view updates from transactions that have completed in other processes.

To refresh a cache

  • Refresh an individual Repository item by invoking the Refresh method for the Repository item.

    This method invalidates unchanged cache data for the Repository item. Subsequent requests for that data will be fulfilled by retrieving the data from the Repository database.

    -or-

    Refresh all Repository items currently cached for an open Repository instance by invoking the Refresh method associated with that Repository instance.

    This method invalidates unchanged cache data for all Repository items. Subsequent requests for that data will be fulfilled by retrieving the data from the Repository database.

In addition to explicit refreshes, Repository items may be refreshed implicitly at any time by the Repository engine, due to execution of internal Repository caching algorithms.


Other Transaction Management Issues

When you design an application that uses Repository, you must consider these transaction management issues:

  • What are the implications of reading Repository data outside the scope of a transaction?

  • Is a locking protocol necessary for the application?

  • Are Repository cache overflows likely to occur, and what can be done to avoid cache overflows?

    The next sections discuss each of these issues:

  • Reading Repository Data Outside of a Transaction

  • Using a Lock Protocol

  • Avoiding Repository Cache Overflows


Reading Repository Data Outside of a Transaction

A Repository method that reads data can execute outside of a transaction; however, Repository data read in this way can include partial updates from an active transaction. To ensure that data read from the Repository does not include partial updates from active transactions, put read requests into a transaction.

Otherwise, if you bracket your reads within a transaction and your Repository database is a Microsoft Jet database, you risk overloading the cache. Microsoft Jet uses an in-memory cache to speed up query processing. Cached data is not released until the transaction is committed. If your Repository application is reading a large amount of data, and you are performing the reads within the scope of a transaction to isolate them from the uncommitted changes of other applications, the Microsoft Jet cache can grow so large that it causes the application to fail. To avoid this, commit your transaction periodically (even though it is a read-only transaction).


Using a Lock Protocol

Executing transactions concurrently can adversely affect the integrity of Repository data if a locking protocol is not used. For example, consider two concurrently executing transactions that both increment an integer property of a Repository object. This property represents a sequential counter.

  1. Transaction A reads the value of the property. The current value is six.

  2. Transaction B reads the same current value of the property.

  3. Transaction A increments the retrieved property value by one, and writes it back to the Repository database. The value in the database is now seven.

  4. Transaction B increments its copy of the retrieved property value by one and writes it back to the Repository database. The value in the database is still seven. It should be eight.

To avoid this problem, use the Lock method in concurrently executing transactions to serialize access to a Repository item. The Lock method sets an exclusive lock on the item, and refreshes any unchanged cache data for the item. The lock is effective across processes and across computers. If the Repository item is already locked, the lock request waits until the lock becomes available. The item is unlocked when the transaction is ended, either by the Abort method or by the final invocation of the Commit method for the transaction.

By invoking the Lock method, the caller has exclusive access to a Repository item, as long as all other concurrently executing transactions also obtain a lock on that Repository item before updating it.

Caution Calling the Lock method on a Repository item only prevents other transactions from executing the Lock method on the Repository item. It does not block other transactions that are not using the locking protocol from changing the Repository item.


Avoiding Repository Cache Overflows

To enhance performance, Repository transactions normally run in write-back mode. In write-back mode, a transaction's updates are held in the Repository cache until the transaction is committed. If a single transaction performs a large number of updates, it can cause the Repository cache for the process to overflow.

By setting transaction options through the SetOption method, a Repository instance can operate in exclusive write-back mode, where it allows no more than one active transaction at a time for a given process and Repository database. Using exclusive write-back mode will reduce, but not eliminate, the possibility of a cache overflow. For a very large number of updates within a single transaction, or if memory is limited, the Repository cache can still overflow.

To guarantee that cache overflows will not cause transactions to fail, set the exclusive write-through mode transactional option. In exclusive write-through mode, updates are immediately flushed from the Repository cache. Exclusive write-through mode does not affect your ability to cancel an active transaction using the Abort method.


Repository Objects and Multithreading

A process can create multiple instances of the Repository class, with each instance connected to the same or to different Repository databases. Instances of the Repository class (as well as instances of other Repository-supplied classes) can be instantiated as either COM or Automation objects. With regard to multiple threads executing within a single process, these objects:

  • Support multithread processing.

  • Use the free-threaded model.

  • Are thread-safe objects.


Restrictions for Microsoft Jet Repository Databases

When Microsoft Jet manages the Repository database, a special restriction applies with regard to use of multiple threads. Only the thread that created an open Repository instance to a Repository database that is managed by Microsoft Jet can use the instance. In other words, if your Repository database is managed by Microsoft Jet, construct your application as if the Repository were using the apartment thread model.


Other Multithreading Restrictions

When programming a multithreaded Repository application, synchronize Repository commit operations between application threads. Specifically, synchronize the use of the following methods:

  • The Count method of the IRelationshipCol interface.

  • The ObjectInstances method of the IClassDef interface.

  • The ObjectInstances method of the IInterfaceDef interface.

  • The ExecuteQuery method of the IRepositoryODBC interface.


Version Management

After you have created a tool information model, you populate the model with instance data relevant to your software tools. As you continue to develop and maintain these software tools, this instance data is accessed and modified. The ability to view past versions of this instance data can be useful. For example, you could use this information to:

  • Reproduce old versions of a software component.

  • Analyze differences between two versions of a software component.

  • Determine how the relationships between various software components have changed from one release of a software tool to the next.

Microsoft Repository maintains past versions of your instance data. These past versions are accessible through Microsoft Repository version management and workspace management interfaces.

The following sections describe the version management capabilities of Microsoft Repository:

  • A More Refined View of Data

  • The Resolution Strategy for Objects and Object Versions

  • The Version Graph

  • Freezing an Object Version

  • Creating Object Versions

  • Merging Object Versions

  • Manipulating Object Versions

  • Manipulating Versioned Relationships


A More Refined View of Data

Objects in the Repository conform to classes. (See The Data in the Repository.) The following figure shows two objects that conform to the CFile class.

An individual object can change whenever any of its property values or collections change. Sometimes the new property values or collections simply replace the preceding ones. Other times, you may want to retain both the old values and the new values. Microsoft Repository can retain the old property values and collections with an old version of the object. The following figure shows three versions of the Main file and two versions of the Header file.

The different versions of an object can have different property values. The following figure includes property values for the properties X, Y, and Z – properties that the File class exposes through its various interfaces. In the figure, individual versions have different values for the properties. The picture shows the property values as ordered X-Y-Z triplets. "(22,3,4)" means X=22, Y=3, and Z=4.

Note how this works: Repository does not let you store multiple values for a particular property of an object. Instead, it lets you store multiple versions of an object – and each individual version can contain its own individual property values.

The different versions of an object can also have different collections. The following figure shows one collection (of the Persons-of-File collection type) for each of the five object versions of the File class. (To save space, the X-Y-Z triplets are not shown.)

Here are the collections of the five object versions of the Files class:

  • Persons-of-Version 1-of-Main: {Alexandra,Bruce}

  • Persons-of-Version 2-of-Main: { } (The empty set)

  • Persons-of-Version 3-of-Main: {Bruce,Christoph}

  • Persons-of-Version 1-of-Header: { } (The empty set)

  • Persons-of-Version 2-of-Header: {Christoph}

Although the preceding figure shows that the three different versions of Main have three different values for the collection type Persons-of-File, at run time things are much simpler. At run time, when your program manipulates an object, it manipulates a particular version of that object. In other words, whenever you secure from the Repository a reference to an object, Repository actually gives you a reference to a specific version of an object. No matter how your program obtains the reference – through IRepository::get_Object, through navigation, or through any other technique – Repository provides you a reference to one version of that object.

For example, suppose your program has a reference to Version 3-of-Main and Version 2-of-Header. The following figure distinguishes between object versions to which your program has current references (filled-in circles) and the other object versions (blank circles).

The preceding figure indicates that your program does not currently have a reference to any person. Your program merely has references to some collections that include persons. To get a reference to a specific person (say, Bruce), your program can navigate to it.

The preceding figure is simplified — it shows only one version of each person. The following figure is more realistic.

The preceding figure shows two collections. One collection is Persons-of-Version 3-of-Main, which contains Version 2-of-Bruce and Version 2-of-Christoph. The other collection is Persons-of-Version 2-of-Header; it contains Version 2-of-Christoph. The figure also shows that your program already has references to Version 2-of-Bruce and Version 2-of-Christoph (because the corresponding dots are filled in).

The preceding figure reflects that when you navigate along a relationship to a target object, you navigate to a specific version of that object. The figure reflects this by showing each arrowhead pointing to a specific version of an object to which you have already navigated (a filled-in circle in the set of versions of persons).

In most situations, this view is adequate. For example, you can think of a target object collection as containing a particular version of each target object. A more detailed view is sometimes useful, however, as shown in the following figure.

The preceding figure shows a single collection, Persons-of-Version 3-Of-Main. It contains two items: Bruce and Christoph. The figure does not indicate which particular version of Bruce is in the collection, because your program has not yet navigated from Version 3-of-Main to Bruce. But it does indicate that when you do navigate to Bruce, Repository can return a reference to any of the three versions. Similarly, the picture does not indicate which version of Christoph is in the collection, but it does indicate that when you navigate to Christoph, Repository returns a reference to Version 1 or to Version 2, but not to Version 3.


The Resolution Strategy for Objects and Object Versions

When you retrieve an object or navigate to an object, Repository returns an interface pointer to a specific version of that object. You can explicitly ask for a particular version, or you can rely on the Repository to choose a version of the object for you. If Repository chooses for you, it can choose any of the following:

  • The most recently created object version.

  • The object version present in the workspace in which you are operating.

  • The pinned target object version of the relationship that you are navigating along.

You can predict how Repository selects an object version to return to you:

  • If you explicitly request a specific version of an object, Repository retrieves that version; if for any reason it cannot retrieve that version, it returns an error.

  • If you are operating within a workspace, Repository retrieves the version that is in the workspace; and if for any reason it cannot return the in-workspace version of the object, it returns an error.

  • If you do not request a specific version and you are not operating within a workspace, Repository returns either the most recently created version or (if applicable) the pinned version.

The following topics discuss how Repository chooses among versions of an item:

  • Requesting a Specific Version

  • Resolution While Operating Within a Workspace

  • Resolution While Operating Outside a Workspace


Requesting a Specific Version

In some situations, you can request a specific version of an object. For example, the get_Version method of the IRepository2 interface retrieves the specific object version whose object-version ID you supply. If Repository cannot return this particular object version to you, it returns an error. For example, it returns an error if the specific version you requested does not exist, or if the specific version you requested is not present in the workspace in which you are operating.


Resolution While Operating Within a Workspace

If you are operating within a workspace, Repository returns the version of the object that is present in the workspace. If Repository cannot return the in-workspace object to you, it returns an error. Repository might fail to return an in-workspace version of the object you requested in the following situations:

  • If the workspace contains no version of the requested object, Repository returns an error.

  • If the workspace contains a version other than the specific version you explicitly requested, Repository returns an error.

  • If you navigate to a target object along a relationship that is a member of a relationship collection, but the specific version of the target object in your workspace is not among the specific versions of the target object that participate in the relationship, Repository returns an error.

For example, the following figure shows one item in the collection Persons-of-V3-of-Main. The target object of the item is Christoph. Because you have not yet navigated along the relationship, the figure does not show which particular version of Christoph will be returned to you; it shows only that it will be Version 2-of-Christoph or Version 3-of-Christoph. If you are operating in a workspace that contains Version 1-of-Christoph, Repository returns an error. When you invoke the get_Target method of the IRelationship interface, Repository cannot find a suitable version of Christoph to return to you. It cannot return Version 1 because Version 1-of-Christoph is not related to the source of the navigation. It cannot return Version 2 or Version 3 because neither Version 2-of-Christoph nor Version 3-of-Christoph is in the workspace in which you are operating. (Remember, the workspace contains object versions and a workspace can contain only one version of each object.)

In your programs, you can avoid this error by manipulating target object collections rather than relationship collections. This error occurs only when a collection includes an item that Repository cannot resolve to an in-workspace object. The only situation in which this occurs is described above: The collection is a relationship collection, and none of its items refers to the specific version of the target object that is in the workspace. When you establish a target-object collection, however, each item in the collection is a Repository object (rather than a relationship to a Repository object). If you establish the collection while operating within a workspace, each item in the collection is a version of the target object that is present in the workspace.


Resolution While Operating Outside a Workspace

If you do not request a specific version and you are not operating within a workspace, Repository generally returns the most recently created version of an object. In one situation, however, Repository first tries to find another, preferable version of the requested object. If you are navigating from an origin object to a destination object, and there is a pinned version of the target object, Repository returns an interface pointer to the pinned version. If there is no pinned version, Repository simply returns an interface pointer to the most recently created version of the target object that participates in the relationship.

Some basic facts about pinning:

  • Repository can return a pinned version (see Example 1).

  • If there is not a pinned version, Repository can return the most recent version (see Example 2).

  • A destination object version can be pinned to several origin object versions (see Example 3).

  • If a target object version is pinned for one versioned relationship, it is not necessarily pinned for others (see Example 4).

  • You can pin at most one version of the destination object for each relationship.

  • You can pin a version of the destination object only; you cannot pin an item within the target versions collection of a destination relationship.

Pinning Example One

The following figure shows a two-item collection: TestSuites-of-Version 3-of-Main. The two items are SuiteB and SuiteC. If you are not operating in a workspace and you navigate to SuiteB, Repository discovers a pinned version of the target object. (The figure shows the pinned version with a dashed arrow.) Thus, Repository returns Version 2-of-SuiteB to your program, even though Version 3-of-SuiteB was created more recently and is related to the source object version.

Pinning Example Two

The following figure shows a two-item collection: TestSuites-of-Version 3-of-Main. The two items are SuiteB and SuiteC. If you are not operating in a workspace and you navigate to SuiteC, Repository finds no pinned version, so it returns Version 2-of-SuiteC.

Note Although Version 3-of-SuiteC was created more recently, Repository does not return it because there is no relationship between it and the source object version (Version 3-of-ProductX). Repository returns Version 2-of-SuiteC because, among the versions related to the source object version, Version 2-of-SuiteC is the most recently created version.

Pinning Example Three

A destination object version can be pinned to any number of origin object versions. For example, the following figure shows that Version 3-of-SuiteD is the pinned destination object version of two different items.

Pinning Example Four

If a target object version is pinned for one versioned relationship, it is not necessarily pinned for others. For example, the following figure simultaneously shows three versions of Product Z, each of which has a collection containing Suite D. All three versions of Product Z use SuiteD as the target object. The top item uses Version 3-of-SuiteD as the pinned version of the target object. The middle item, even though it includes the same version (Version 3) of the target object, does not have it pinned; it uses Version 5-of-SuiteD as the pinned version of the target object. The bottom item includes both Version 3 and Version 5 of SuiteD, but it includes no pinned version at all.


The Version Graph

Each Repository object has a version graph, which indicates how the various versions relate to each other. An object's version graph consists of vertices and arrows. Each vertex represents a version of the object and each arrow points from one object version to a successor of that object version. The following figure shows a typical version graph for an object with 11 versions.

There are two kinds of arrows. A solid arrow indicates the creation of one object version based on another. For example, the solid arrow from Version 6 to Version 7 indicates that Version 7 was created based on Version 6. That is, Version 7 was created when a program invoked the CreateVersion method on an IRepositoryObjectVersion interface pointer to Version 6.

A dashed arrow indicates the merging of property values and collections from one object into another. For example, the dashed arrow from Version 10 to Version 11 indicates that property values and collections from Version 10 were merged into Version 11. That is, the dashed arrow was created when a program invoked the MergeVersion method with an IRepositoryObjectVersion interface pointer to Version 11 (and the invoking program provided an interface pointer to Version 10 as an input parameter i).

For More Information Creating Object Versions, Merging Object Versions


Moving Through the Version Graph

Repository helps you move through the version graph in the following ways:

  • Every object version has a collection of successor versions – the other versions of the same object that immediately follow in the version graph. In the following figure, Version 5 has two successor versions, Version 9 and Version 7. An object version's set of successor versions can be null. For example, Version 11 has no successors.

  • Every object version has a collection of predecessor versions – the other versions of the same object that immediately precede it in the version graph. In the preceding figure, for example, Version 11 has three predecessor versions: Version 9, Version 7, and Version 10.

  • Every object version (except Version 1) has a predecessor creation version – the predecessor version from which the current object version was created. For example, of Version 11's three predecessor versions, only Version 9 is its predecessor creation version.

  • Every object version has a collection of object versions – the entire set of versions of the object.


Freezing an Object Version

In the version graph, each object version with an emerging (solid or dashed) arrow must be frozen. The other object versions can be frozen or unfrozen. One purpose of Repository's versioning capability is to let you maintain multiple versions of an object so that you can remember what the object was like at different times. After you decide that a particular version of an object is worth remembering, you must protect that version of the object from further modification. You do this by freezing the object version. To freeze the object version, invoke the FreezeVersion method with an IRepositoryObjectVersion interface pointer to the version you want to preserve.

When you freeze a version of an object, you prevent any program from modifying any of its origin collections, or any of its non-annotational property values. A program can, however, modify a frozen object version in the following ways:

  • Modify a frozen object version's destination collections — By allowing such modifications, Repository lets you protect an object (such as a text formatting template) from further modification, yet allow other, newly created objects (such as text files) to include the frozen object version in their origin collections.

  • Modify an object's annotational properties — If a class exposes (through one of its interfaces) an annotational property, Repository stores one value of that property for each object (not one property value for each object version). Thus, if you change an annotational property value on an unfrozen version of an object, the change affects all versions of that object, including the frozen versions.

Repository provides two methods for you to manage the frozen status of an object version:

  • FreezeVersion freezes a version of an object.

  • IsFrozen (exposed by IRepositoryObjectVersion) determines whether an object version is frozen or unfrozen.


Creating Object Versions

Whenever you want to continue modifying an object without overwriting the non-annotational property values and origin collections of the existing object versions, you create a new version of the object. When you create a new object version, you must use an existing, frozen version of the object as the creation version of the to-be-created version. To create the new version, you invoke the CreateVersion method with an IRepositoryObjectVersion interface pointer to the creation version. Repository creates a new, unfrozen version of the object. The new version has property values identical to those of the creation version. The new version's collections are based on the creation version's collections, as follows:

  • Repository copies each origin collection whose type has the COLLECTION_NEWORGVERSIONSPARTICIPATE flag set. If this flag is not set, the origin collection is not copied.

  • By default, Repository does not copy the creation version's destination collections into the newly created version. Your application might, however, include custom behavior for the CreateVersion method that does copy some or all destination collections.

When you create a new version of an object, Repository modifies the version graph accordingly.


Merging Object Versions

The version management feature of Microsoft Repository supports branching. A branch results when you create a new object version whose predecessor version already has one or more successor versions. Common branching scenarios are:

  • When two concurrent development efforts must change the same object.

  • When a maintenance change is required on an older version of an already released object.

In scenarios like these, sometimes it is necessary to merge branched lines of development back together. You can merge one object version into another with the MergeVersion method of the IRepositoryObjectVersion interface. You can merge several branches together by successively merging two branches at a time until all branches have been merged.

The following topics describe the merging process in more detail:

  • Merge Basics

  • The Details of Merge Behavior

  • Examples of Merging Versions


Merge Basics

MergeVersion modifies an object version by combining its property values and collections with those of another version of the same object.

MergeVersion does not combine two versions into a third, newly created version. Rather, it merges the property values and collections of one version into another version. After the operation is complete, the modified version becomes a successor of the other version. MergeVersion modifies the version graph accordingly.

When you invoke MergeVersion, the object version you will use as predecessor of the merge must already be frozen. The object version to be modified — the successor of the merge — cannot be frozen.

Briefly, the merge operation has these results:

  • The object's version graph is updated, to indicate that the merge operation occurred.

  • The successor object can have different property values or collections.


The Details of Merge Behavior

You can predict how the property values and collections in a successor version will change. MergeVersion modifies one object version, the successor, by combining its property values and collections with those of another version, the predecessor. MergeVersion compares the property values and collections of the predecessor version and the successor version to a third version, called the basis version.

You invoke MergeVersion on the successor version of the merge; you pass a reference to the predecessor as an input parameter. You also pass an indication of which version is to be considered the primary version. The primary version is the version whose member values are given priority when there are merge conflicts between the two versions. For each property, MergeVersion uses this rule to resolve merge conflicts:

  • If the primary version differs from the basis version, Repository uses the property value from the primary version.

  • If only the secondary version differs from the basis version, Repository uses the property value from the secondary version.

  • If neither version differs from the basis version, Repository leaves the property value in the current version unchanged.

How MergeVersion Handles Origin Collections with COLLECTION_MERGEWHOLE Flag Set

For each origin collection type whose COLLECTION_MERGEWHOLE flag is set, MergeVersion uses this rule:

  • If the primary version's collection differs (see "Comparing Collections") from the basis version's collection, Repository uses the collection from the primary version.

  • If only the secondary version's collection differs from the basis version's, Repository uses the collection from the secondary version.

  • If neither version differs from the basis version, Repository leaves the collection in the current version unchanged.

How MergeVersion Handles Origin Collections with COLLECTION_MERGEWHOLE Flag Not Set

For each origin collection type whose COLLECTION_MERGEWHOLE flag is not set, MergeVersion combines the items in the two collections as follows:

  1. MergeVersion includes in the resulting collection each item in the basis version not changed in or deleted from either the primary version or secondary version. (See Comparing Versioned Relationships.)

  2. MergeVersion includes in the resulting collection each item in the primary version's collection that differs from the basis version.

  3. MergeVersion includes in the resulting collection each item in the secondary version's collection that differs from the basis version, provided the corresponding items in the primary version and basis version do not differ from each other.

Note The resulting collection can exclude some items found in the basis object version's collection. For example, if the primary version's collection excludes the item, the resulting collection will exclude the item. Similarly, if the primary version's collection includes an item that is identical to an item in the basis version's collection, but the secondary object version excludes the item, the resulting collection will exclude the item.

For some examples of Merge behavior, see Examples of Merging Versions.

Calculating the Basis Version

When you invoke the MergeVersion method of the IRepositoryObjectVersion interface, Repository uses the version graph. The MergeVersion method compares each object version to be merged to a basis version of the same object. The basis version of the two to-be-merged object versions is the most recently created object version that is on the creation path of both the primary object version and the secondary object version of the merge. The creation path of an object version is a path through the version graph leading from the object version directly to Version 1 of the object. Each step of the path leads from an object version to its predecessor creation version.

You can easily follow an object version's creation path backward from it to Version 1 by following the solid arrows in reverse. For example, the version graph in the following figure shows that the creation path of Version 11 goes through these other versions: 9, 5, 4, 2, and 1.

Comparing Collections

As it works, the MergeVersion method must compare collections to each other. (It compares each collection in the basis version to its corresponding collection in the primary version and in the secondary version.) MergeVersion considers two collections to be different if either of the following is true:

  • One collection contains different objects from the other collection.

  • A corresponding pair of items from the two collections differ from each other. (See "Comparing Versioned Relationships.")

Comparing Versioned Relationships

The MergeVersion method compares each collection of the basis version of an object to the corresponding collections of the primary version and of the secondary version. As part of these comparisons, the method must compare corresponding items – versioned relationships – of these collections. An item from the basis object version's collection corresponds to an item in the primary or secondary object version's collection if the two items use the same target object. Even if two items correspond, however, they can still differ in important ways. Repository considers two versioned relationships to differ if any of the following is true:

  • The collection type is a sequenced collection and the two items have different sequence numbers.

  • The collection type is a naming collection and the two items have different names.

  • The two items refer to different versions of the target object.

  • The two items use a different version of the target object as pinned version.

  • One item has a pinned target object version and the other does not.

For example, the following figure shows two items that differ in one respect only — the top item refers to Versions 1 and 3. The corresponding item of the second collection refers to Versions 3 and 5.


Examples of Merging Versions

A typical version graph for an object is shown in the following figure. The object has three properties: Size, Color, and Quantity. For selected versions of the object, the figure shows the values of these properties as ordered triplets.

If you merge Version 4 into Version 8 (using Version 4 as the primary version), Repository uses Version 2 as the Basis Version.

The resulting version graph looks like this:

In the resulting version graph, notice the following:

  • Version 4 is now a non-creation predecessor of Version 8.

  • In Version 8, the value of the Size property is medium. (The change in the primary version, from small to medium, prevails over the change in the secondary version, from small to large.)

  • In Version 8, the value of the Color property is red. (The change in the secondary version's value prevails because the corresponding value in the primary version did not change.)

  • In Version 8, the value of the Quantity property is null. (The change in the secondary version's value prevails because the corresponding value in the primary version did not change.)

Later, you merge Version 6 into Version 8, using Version 8 as the primary version. Repository uses Version 1 as the basis version. Before the merge, the version graph (with important property values shown) looks like this:

The resulting version graph is shown in the following figure.

In the resulting version graph in the preceding figure, notice the following:

  • Version 6 is now a non-creation predecessor of Version 8.

  • In Version 8, the value of the Size property is medium. (Neither the primary nor secondary version's value had changed from the basis version's value.)

  • In Version 8, the value of the Color property is red. (The change in the primary version's value, from green to red, prevails over the change in the secondary version's value, from green to null.)

  • In Version 8, the value of the Quantity property is 555. (The change in the secondary version's value, from null to 555, prevails because the corresponding value in the primary version did not change.)


Manipulating Object Versions

Access to Repository object versions is supported at both the COM level and the Automation level. Given a specific version of a Repository object, you can perform the operations listed below.

To | Use
Create the first object version | The CreateObject method of the IRepository interface
Create subsequent object versions | The CreateVersion method of the IrepositoryObjectVersion interface
Determine which predecessor version was the creation version | The PredecessorCreationVersion method of the IrepositoryObjectVersion interface
Determine how this version of the current object was resolved | The ResolutionType method of the IrepositoryObjectVersion interface
Freeze an object version | The FreezeVersion method of the IrepositoryObjectVersion interface
Retrieve the object-version identifier of an object version | The VersionID property of the IrepositoryObjectVersion interface
Retrieve the state of an object version | The IsFrozen method of the IrepositoryObjectVersion interface and the IsCheckedOut method of the IWorkspaceItem interface
Merge the contents of another object version into the current object version | The MergeVersion method of the IrepositoryObjectVersion interface

For More Information See the Repository Automation Reference or the "Repository COM Reference" section of the Repository Reference.


Manipulating Versioned Relationships

Access to relationships is supported at both the COM level and the Automation level. Given a relationship that connects two Repository objects, you can perform the operations listed below. These operations are performed relative to a specific version of the source object.

To | Use
Pin the destination object version | The Pin method of the IversionedRelationship interface
Unpin the destination object version | The Unpin method of the IversionedRelationship interface
Retrieve (a version of) the target object | The Target property of the IRelationship interface
Retrieve the source object version | The Source property of the IRelationship interface
Create a new relationship – to relate a new target object to a source object | The Add method of the IrelationshipCol or ITargetObjectCol interface
Relate a subsequent target object version to a source object | The Add method for the TargetVersions collection. This collection is accessible through the IversionedRelationship interface

For More Information See the Repository Automation Reference or the "Repository COM Reference" section of the Repository Reference.


Kinds of Versions Collections

Kinds of Version Collections

There are seven kinds of version collections:

  • Versions-of-Object Collection

  • Predecessor-Versions Collection

  • Successor-Versions Collection

  • Target-Versions Collection

  • Versions-of-Workspace Collection

  • Workspaces-of-Version Collection

  • Checkouts-of-Workspace Collection


Versions-of-Object Collection

The Versions-of-Object Collection

The Versions-of-Object version collection contains all the versions of a particular Repository object. You establish this collection with the get_ObjectVersions method of the IRepositoryObjectVersion interface.


Predecessor-Versions Collection

The Predecessor-Versions Collection

The Predecessor-Versions version collection contains all the immediate predecessors of an object version. You establish this collection with the get_PredecessorVersions method of the IRepositoryObjectVersion interface.


Successor-Versions Collection

The Successor-Versions Collection

The Successor-Versions version collection contains all the immediate successors of an object version. You establish this collection with the get_SuccessorVersions method of the IRepositoryObjectVersion interface.


Target-Versions Collection

The Target-Versions Collection

The Target-Versions version collection contains specific versions of a target object that are related to a particular version of a source object. You establish this collection with the get_TargetVersions method of the IVersionedRelationship interface.


Versions-of-Workspace Collection

The Versions-of-Workspace Collection

The Versions-of-Workspace version collection contains all the object versions present in a workspace. Remember that at most one version of each object can appear in a workspace. You establish this collection with the get_Contents method of the IWorkspace interface.


Workspaces-of-Version Collection

The Workspaces-of-Version Collection

The Workspaces-of-Version version collection contains all the workspaces in which a particular object version is present. You establish this collection with the get_Workspaces method of the IWorkspaceItem interface.


Checkouts-of-Workspace Collection

The Checkouts-of-Workspace Collection

The Checkouts-of-Workspace version collection contains all the object versions checked out to a particular workspace. You establish this collection with the get_Checkouts method of the IWorkspace interface.


Workspace Management

A workspace is a restricted view of the Repository's contents. You define which objects are contained in the workspace. For each of these objects, you define which version is used.

The following sections describe the workspace management capabilities of Microsoft Repository:

  • Workspace Management Overview

  • Objects Within Workspaces

  • Workspace Context

  • Workspaces and Repository Instances

  • Accessing the Objects in a Workspace

  • Manipulating Workspaces

  • Manipulating the Objects in a Workspace


Workspace Management Overview

Each Repository can contain workspaces. A workspace is a restricted view of the Repository's contents. The view is restricted for two reasons:

  1. A workspace can contain only those Repository object versions that you explicitly include in it. Thus, if you set up a workspace to apply to a functional area, you can include in that workspace only objects that pertain to that area.

  2. A workspace can contain only one version of any Repository object. Thus, the workspace provides you with a simple view of the Repository's data in which only one version of each object exists. In effect, operating within a workspace simplifies things because you do not need to choose among several versions of the same object. When you retrieve an object from a workspace, Repository simply returns the specific version of that object that is present in the workspace.

Although a workspace's view of the Repository data is restricted, operating in the context of a workspace is liberating for two reasons:

  1. A workspace reveals only the objects that are important to you – effectively yielding a custom view of the Repository.

  2. Because a workspace contains at most one version of any object, your within-workspace operations can avoid much of the complexity of the multi-version environment.


Objects Within Workspaces

An object version can participate in a workspace in two ways:

  • An object version can be present in the workspace. That is, the workspace can contain the object version.

    Each workspace has a Versions-of-Workspace collection containing the object versions present in the workspace. Use the Add method to include an object version in a workspace; use Remove to exclude an object version.

    Note An object version can be present in more than one workspace. Each object version has a Workspaces-of-Version collection containing the workspaces in which the object is present.

  • An object version can be checked out to a workspace.

    When an object version is checked out to a workspace, you can modify that object version only while operating in the workspace. Each workspace has a Checkouts-of-Workspace collection containing the object versions checked out to the workspace. Use the Checkout and Checkin methods to control the contents of the Checkouts-of-Workspace collection.

    Note An object version can be checked out to at most one workspace, and it can be checked out only to a workspace in which it is already present. Even when you check out an object version to a workspace, that object version can remain present in many other workspaces.


Workspace Context

When you operate within a workspace, the workspace provides a specific context for your work. That context includes the workspace's Versions-of-Workspace collection and its Checkouts-of-Workspace collection. If an object version is not part of either of these collections, it is not part of a workspace's context.

When you invoke a Repository method, the method's behavior can vary depending on whether you invoked the method from within the context of a workspace or from within the more general context of a Repository instance. For example, if you materialize the ObjectInstances collection for a class, the collection can consist of two different sets of items:

  • If you are operating within the context of a workspace, the collection contains one item for each object in that workspace conforming to that class.

  • If you are operating within the more general context of a Repository instance, the collection contains one item for each object in the Repository conforming to that class.

Similarly, if you invoke get_Object, two different things can happen:

  • If you are operating within the context of a workspace, Repository's resolution strategy yields whatever version of that object is present in the workspace.

  • If you are operating within the more general context of a Repository instance, Repository's resolution strategy yields the latest version of the object.


Establishing Workspace Context

When you create or open a Repository instance, the Repository returns to you a reference to the Repository's root object. From there, you can immediately begin to manipulate other Repository objects. For example, you can invoke get_Object to materialize a reference to a specific Repository object. Or you can begin to move from the root object to other Repository objects. In either of these cases, the resulting references refer to run-time objects that exist within the general context of the open Repository instance. Thus, if you invoke methods exposed by this object, the methods perform their work within that context.

On the other hand, you can first establish a workspace context before manipulating any Repository objects. To establish a workspace context, you must materialize a workspace object in any of these ways:

  • From the root object, you can materialize the Workspaces collection, and then retrieve a particular workspace from the resulting collection.

  • You can invoke the get_Object method to explicitly retrieve a reference to the workspace object in whose context you want to operate.

  • From the Workspace Definition object you can use the ObjectInstances method to establish a collection of all workspaces in the Repository. Then you can retrieve a particular workspace from that collection.

After you have a reference to the workspace object, you can operate within the context of that workspace. To retrieve an object directly within the context of the workspace, you can invoke the get_Object method as exposed by the workspace object. (Remember that the Workspace class implements IRepository2, so each workspace exposes methods like get_Object and get_RootObject.) Similarly, to move to an object within the context of a workspace, start by invoking the get_RootObject method exposed by the workspace object. Then, move from the root object to other objects.

To reiterate: Remember that the Workspace class and the Repository class both implement the IRepository2 interface. Thus, you can invoke methods like get_Object and get_RootObject either from a Repository or from a workspace. When you invoke one of these methods, the resulting object reference uses the same context as the object on which you called the method. Thus, if you invoke get_Object from a Repository, the resulting object exists within the general context of the open Repository instance, and subsequent calls to that new object's methods will occur within the general context of the open Repository instance. But if you invoke get_Object from a workspace, the resulting object exists within the specific context of that workspace, and subsequent calls to that new object's methods will occur within the specific context of that workspace.


Retaining Workspace Context

As you move among the objects present in the workspace, Repository automatically retains the context for you. In other words, if you retrieve an item from a relationship collection or a target object collection, the retrieved target item has the same context as the context of the relationship's source item.

However, only relationship collections and target-object collections retain workspace context. If you retrieve an item from any VersionCol object, the reference that Repository returns to you has the context of the open Repository instance in which you are operating. The object reference does not have an in-workspace context.

For example, suppose that within the context of a workspace, you have a reference to the root object. Then you perform these steps:

  1. From the root object, you move to a particular Repository object.

    As you move to each object along the navigation path, Repository returns to you whichever object version is present in the workspace. At each step, the reference that Repository returns preserves the workspace context.

  2. At some point along the navigation path, you materialize an object version's PredecessorVersions collection. Then you retrieve the first item in that collection.

    Repository returns a reference to the oldest predecessor of the object version. Because the PredecessorVersions collection is a VersionCol object (not a relationship collection or a target-object collection), this reference does not preserve the workspace context. All subsequent manipulations of this object (and all subsequent navigations from this object) occur within the general context of the open Repository instance.


Workspaces and Repository Instances

In many respects, operating within a workspace is just like operating within the Repository itself: both the Workspace class and the Repository class implement the IRepository2 interface. There are, however, some important differences:

  • Some methods exposed by the IRepository2 interface apply only to Repository instances, not to workspaces. You cannot call Open or Create on a workspace object.

  • Unlike Repository connections, workspaces are named persistent Repository objects. Thus, workspaces can be created, used across multiple sessions, and deleted, if necessary.


Accessing the Objects in a Workspace

You can retrieve a Repository object in the context of a workspace by doing one of the following:

  • Retrieving the object using the Object property that the workspace object exposes.

  • Retrieving the root object using the RootObject property that the workspace object exposes, and then moving to other objects by traversing relationships.

  • Retrieving the object from the workspace's Versions-of-Workspace collection.

Remember, when you retrieve an object using any of these alternatives, you retrieve the specific object version that is included in the workspace.


Manipulating Workspaces

Operations on workspaces are supported at both the COM level and the Automation level. You can perform the following operations on a workspace.

To | Use
Enumerate the workspaces in a Repository | Workspaces collection of the IWorkspaceContainer interface that is exposed by the root Repository object.
Create a workspace | CreateObject method of the IRepository interface that is exposed by the open Repository instance. Then use the Add method for the Workspaces collection to add the workspace to the collection of workspaces.
Delete a workspace | Delete method of the IRepositoryItem interface that is exposed by the workspace object. If you attempt to delete a workspace that contains checked-out objects, the delete will fail.
Retrieve the root object in a workspace | RootObject property of the IRepository interface that is exposed by the workspace object.
Enumerate the Repository objects contained in a workspace | Contents collection of the IWorkspace interface that is exposed by the workspace object.
Enumerate the checked-out objects in a workspace | Checkouts collection of the IWorkspace interface that is exposed by the workspace object.

For More Information Repository Automation Reference, Repository COM Reference


Manipulating Objects in a Workspace

Repository objects implement the IWorkSpaceItem interface in order to support workspace-related capabilities. The IWorkSpaceItem interface is available at both the COM level and the Automation level. Given a specific version of a Repository object, you can perform the workspace-related operations listed below.

To | Do
Determine whether an object version is checked out to a workspace | CheckedOutToWorkspace property of the IWorkSpaceItem interface.
Determine which workspaces contain a particular object version | WorkSpaces collection of the IWorkSpaceItem interface that is exposed by the object version.
Add an object version to a workspace | Obtain access to the Contents collection through the IWorkspace interface. Then use the Add method of the Contents collection to add an object version to the workspace.
Remove an object version from a workspace | Obtain access to the Contents collection through the IWorkspace interface. Then use the Remove method of the Contents collection to remove the object version from the workspace.
Check an object version out to a workspace | CheckOut method of the IWorkSpaceItem interface that is exposed by the object version.
Check an object version in from a workspace | CheckIn method of the IWorkSpaceItem interface that is exposed by the object version.

For More Information Repository Automation Reference, Repository COM Reference


Storage Strategy in the Repository Database

Repository's database storage model differs from its run-time object model. While the run-time object model is designed to accommodate run-time operations conveniently, the database model is designed to accommodate storage efficiently.

To save space in the database, Repository can sometimes store a single copy of a property value, even if that property value describes many object versions. Similarly, Repository can sometimes store a relationship once, even if many different object versions have that relationship.

Repository anticipates which object versions are especially likely to share property values and relationships and which object versions are less likely to. It uses these guidelines:

  • Two versions of the same object are likely to share property values and collections, but two versions of different objects are less likely to. In other words, if two object versions are not on the same version graph, they are not especially likely to share property values or relationships. (See The Version Graph.)

  • Within a version graph, two versions that are near each other are more likely to share values; two versions that are far apart are less likely to share values. Repository arranges each version graph into branches. (See Branches in the Version Graph.) Each branch contains versions that are especially likely to share values.

  • Although property values and collections can change, they do not change back and forth frequently. More commonly, a value holds for a few consecutive versions of an object, and then that value changes to a new value, which holds for a few more versions of the object. Thus, when Repository stores a property value, it stores the property value for an entire range of object versions. (See Ranges in the Version Graph.)

    Similarly, in a single row of the RTblRelships table, Repository can indicate that every object version in a range (of origin object versions) has a relationship to every object version in a range (of destination object versions).

The following table summarizes how Repository stores versions and relationships.

To store | Repository uses
Objects and object versions | RTblVersions table Interface-Specific Tables
Relationships | RTblRelships table


Branches in the Version Graph

Within the database, Repository partitions each version graph into branches. Each branch contains object versions that are especially likely to share property values and target object versions with each other.

A branch of a version graph is a sequence S of n (n > 0) object versions such that:

S = x1, x2, x3, …, xn

and x1 is the creation predecessor of x2
and xk is the creation predecessor of xk+1 (1 < k < n-2 )
and xn-1 is the creation predecessor of xn.

According to this definition, each object version can be in the same branch with at most one of its creation successors. For example, in the following version graph, Version 3 and Version 4 cannot be in the same branch, because they are both creation successors of Version 2.

In fact, this version graph has four branches, as shown in the following figure.

Every version graph has at least one branch — the branch beginning with the first version of the object.

Each object version is a member of exactly one branch; branches do not overlap.

When you create a new version of an object, Repository tries to add the newly created version to the same branch as its predecessor. If that branch already includes a successor to the creation version, however, Repository creates a new branch. The newly created object version is the only element of the new branch.

For example, if you create a new version from Version 8, Repository creates the new version and adds it to the branch containing Version 8. But if you create a new version from Version 3, Repository creates a new branch for the new version, because Version 3's branch already includes a creation successor of Version 3.

Each branch represents a set of object versions that are especially likely to share property values and have identical relationships. If two object versions exist on separate branches, Repository does not save any space in the database even if those versions share values for all of their properties and have identical collections for all of their collection types. For Repository to save space, the similar objects must exist on the same branch. For this reason, Repository tries during CreateVersion to assign the new version to an existing branch. The fewer the branches, the higher the likelihood that Repository can save space in the database.

Repository never moves an object version from one branch to another. After Repository assigns an object version to a branch during the CreateVersion method, that object version remains on that branch until the object version is deleted.


Version Ranges in the Version Graph

Ranges in the Version Graph

To save space in the database, Repository can associate a property value or relationship with an entire range of object versions. A range of object versions is a set of consecutive elements of a branch. (See Branches in the Version Graph.)

To refer to a range, a row of a Repository table must include the following four values:

  • The Version Graph — that is, the row must refer to the Repository object. Use the internal identifier of the object.

  • The Branch — the portion of the version graph containing the range. Use the branch identifier of the branch.

  • The Range Start — the element within the branch where the range starts. Use the version-within-branch identifier of the object version.

  • The Range End — the element within the branch where the range ends. Use the version-within-branch identifier of the object version, or use the special constant VERINFINITY (hex 7fffffff) to indicate an unbounded range.

Repository uses unbounded ranges to indicate that properties apply to a set of object versions that can grow as you make new object versions with CreateVersion.

For an example of how Repository uses unbounded ranges, see the sample data in Interface-Specific Tables.


Interface-Specific Tables

When you create a tool information model, Repository enlarges the database schema to accommodate the new kinds of data. Generally, Repository creates one table for each new interface you create. Several interfaces, however, can share a table. (See Information Model Creation Issues.)

Each row of an interface-specific table indicates that a set of property values applies to a particular range of object versions. (See Ranges in the Version Graph.)

The primary key of any interface-specific table consists of three columns: IntID, Z_BranchID_Z, and Z_VS_Z, as shown in the following table.

Column name | Data type | Description
IntID | RTIntID | The internal identifier for the object.
Z_BranchID_Z | RTBrID | Indicates the branch of the version graph containing the range to whose items the property values in this row apply.
Z_VS_Z | RTVerID | A version-within-branch identifier indicating the lower bound of the range to whose items the property values in this row apply.
Z_VE_Z | RTVerID | A version-within-branch identifier indicating the upper bound of the range to whose items the property values in this row apply.
(User-supplied column name for Interface-specific property 1) | (User-supplied datatype) | A column corresponding to a property you defined in your tool information model. You provide a name and a data type for this column when you insert the tool information model into the Repository.
(User-supplied column name for Interface-specific property n…) | (User-supplied datatype) | Other columns corresponding to other properties you defined in your tool information model. You provide a name and a data type for each of these other columns when you insert the tool information model into the Repository.

Each row indicates a range and a set of property values. Every object version in the range is described by every property value.


Example: Rows of Interface-Specific Tables

Consider the version graph for a typical object. Suppose the object is part of a user-installed information model; it conforms to the CParagraph class. Suppose further that the CParagraph class implements two interfaces:

  • IFont exposes the properties Color, Style, and PointSize.

  • IParagraph exposes the properties Alignment and Spacing.

The following figure shows a portion of the version graph, along with properties for each version of the object.

Assume that the object's internal identifier is 7. Assume that Version 7 and Version 9 are leaf nodes; they have no successors. Also assume that there are two branches containing these object versions, as shown in the following figure.

The properties for these object versions are stored in two separate interface-specific tables. The table for the properties of the IFont interface includes the following rows.

IntID | Z_BranchID_Z | Z_VS_Z | Z_VE_Z | Color | Style | Point Size
7 | 2 | 0 | 1 | Blue | Italic | 10
7 | 2 | 3 | VERINFINITY | Blue | Italic | 10
7 | 2 | 0 | VERINFINITY | Blue | Italic | 10

The first row in the preceding table indicates that the properties (Blue, Italic, 10-point) apply to each object version in a range within Branch 2 that begins at Version 4 and ends at Version 5.

The second row indicates that the properties (Blue, Italic, 12-point) apply to each object version in a range within Branch 2 that begins at Version 9 and ends at the end of the branch.

Similarly, the third row indicates that the properties (Blue, Italic, 10-point) apply to each object version in a range within Branch 3 that begins at Version 6 and ends at the end of the branch.

The following table for the properties of the IParagraph interface includes the following rows.

IntID | Z_BranchID_Z | Z_VS_Z | Z_VE_Z | Alignment | Spacing
7 | 2 | 0 | 0 | Center | Single
7 | 2 | 1 | VERINFINITY | Center | Double
7 | 3 | 0 | VERINFINITY | Center | Double

The first row of the preceding table indicates that the properties (Center, Single) apply to each object version in a range within Branch 2 that begins at Version 4 and ends at Version 4 — a single-version range.

The second row indicates that the properties (Center, Double) apply to each object version in an unbounded range within Branch 2 that begins at Version 5.

Similarly, the third row indicates that the properties (Center, Double) apply to each object version in an unbounded range within Branch 3 that begins at Version 6.

Within the Z_VE_Z column, VERINFINITY indicates that the range has no upper bound. Thus, if you enlarge a branch (by invoking the CreateVersion method on the branch's newest object version) the creation predecessor's property values will automatically apply to the newly created version.

For example, suppose you invoke the CreateVersion method on Version 9, yielding a version graph as shown in the following figure.

In the preceding figure, the new object version is on the same branch as its predecessor, and has the same properties as it predecessor. To apply these existing property values to the newly created object, the CreateVersion method does not need to modify the IFont-specific property table or the IParagraph-specific property table, because those tables contained rows that applied those property values to ranges with no upper bound.


Storing Relationships

The run-time object model and the storage schema differ significantly. These differences are most apparent when you query the Repository database for information about relationships. In fact, the storage of relationships and the run-time manipulation of relationships differ profoundly.

The Repository database uses the RTblRelships table to store information about relationships. An individual row of the table can be any of the following:

  • A description of an individual version-to-version relationship

  • A description of a set of version-to-version relationships

  • A description of sequencing and pinning information for a single origin versioned relationship


Version-to-Version Relationships

A version-to-version relationship is a relationship that associates a particular version of the origin object with a particular version of the destination object. At run time, the Repository object model never presents an individual version-to-version relationship to you. That is, from within a COM or Automation program, you cannot materialize an object corresponding to a version-to-version relationship. Instead, you can materialize an object corresponding to a versioned relationship.

The following figure shows versioned relationships.

The preceding figure shows two versioned relationships; however, five version-to-version relationships are evident, as shown in the following figure.

In the preceding figure, each line is a version-to-version relationship. The top line indicates that Version 1-of-Bruce is in the TargetVersions collection of the versioned relationship owned by Version 3-of-Main. It also indicates that Version 3-of-Main is in the TargetVersions collection of the versioned relationship owned by Version 1-of-Bruce. The complete TargetVersions collection of the versioned relationship owned by Version 1-of-Bruce might include other items. That is, there might be other version-to-version relationships between Version 1-of-Bruce and individual versions of Main.

The following figure shows that Version 1-of-Bruce has version-to-version relationships to Version 1-of-Main, Version 2-of-Main, and Version 3-of-Main.

The preceding figure shows a total of seven version-to-version relationships.


Delete Propagation

When you delete an object version or relationship, Microsoft Repository sometimes automatically deletes other object versions and their attendant relationships. The automatic removal of an object version is called a propagated deletion. The process by which Repository first determines what propagated deletions are necessary and then performs those propagated deletions is called delete propagation.

Repository performs propagated deletions only when you remove a relationship whose corresponding origin collection type has the COLLECTION_PROPAGATEDELETE flag set. Such relationships are called delete-propagating relationships.

A single delete propagation can result in the removal of many object versions. There are several reasons for this:

  • A to-be-removed delete-propagating relationship can have a TargetVersions collection containing many items.

  • A to-be-removed object version can have many delete-propagating origin relationships.

  • An object version to be removed automatically (that is, by propagated deletion) can itself have delete-propagating origin relationships.

Delete propagation can happen whenever you do any of these things:

  • Delete a Delete-Propagating Origin Relationship.

  • Delete a Delete-Propagating Destination Relationship.

  • Remove an Item from the TargetVersions Collection of a Delete-Propagating Origin Relationship.

  • Remove an Item from the TargetVersions Collection of a Delete-Propagating Destination Relationship.

  • Delete an Object Version that Has Delete-Propagating Origin Relationships.


After Removing an Origin Relationship

If you delete a delete-propagating origin relationship, or if Repository automatically removes one after deleting its attendant origin object version, delete propagation can occur. Repository considers performing a propagated deletion on each of the relationship’s destination versions. (That is, Repository considers performing a propagated deletion on each object version from the TargetVersions collection of the deleted origin relationship.)

Repository considers deleting the target versions in reverse order of their creation (not in the reverse order of their inclusion in the TargetVersions collection). In effect, Repository works backward through the version graph, attempting to delete leaf nodes before attempting to delete their predecessors.

Repository performs a propagated deletion on an object version only if the object version satisfies the requirements for object-version deletion. If the object version does not satisfy the requirements, Repository does not perform the propagated deletion on that object version.

Even if Repository encounters a candidate for propagated deletion that does not satisfy the requirements for object-version deletion, it does not stop considering the other candidates. Thus, the entire delete propagation operation might result in the deletion of some of the TargetVersions, but not others.

For More Information The VersionGraph; Requirements for Object-Version Deletion


After Removing a Destination Relationship

Deleting a destination relationship is like removing an item from a destination relationship’s TargetVersions collection. Thus, the delete propagation that occurs after such a deletion is equal to the delete propagation occurring after such a removal from a TargetVersions collection. (See After Removing an Origin Target Version.)


After Removing a Destination Target Version

If you remove an object version from the TargetVersions collection of a delete-propagating origin relationship, the Repository considers performing a propagated deletion on that object version. Repository performs a propagated deletion on the destination object version if all of the following conditions hold:

  • The destination object version has no other destination relationship of the same type as the deleted relationship.

  • The source object satisfies the basic requirements for object-version deletion. (See Requirements for Object-Version Deletion.)


After Removing an Origin Target Version

If you remove an object version from the TargetVersions collection of a delete-propagating destination relationship, Repository considers performing a propagated deletion.

Delete propagation always occurs from the origin object toward a destination object. Thus, in this situation, Repository considers performing a propagated deletion on the object version that was the source of the relationship whose TargetVersions collection you modified. Repository performs a propagated deletion on the source object version if all of the following conditions hold:

  • The item you removed was the last item in its TargetVersions collection.

  • The source object version has no other destination relationship of the same type as the destination relationship whose TargetVersions collection you modified.

  • The source object satisfies the basic requirements for object-version deletion. (See Requirements for Object-Version Deletion.)


After Removing an Object Version

You can explicitly delete an object version with the Delete method. Similarly, Repository can automatically delete an object version by performing a propagated deletion operation on it. In either case, the object version is deleted only if it satisfies the basic requirements for object-version deletion.

If an object version you are trying explicitly to delete does not satisfy these requirements, the Delete method returns an error. If an object version that Repository is trying to delete through propagation does not satisfy these requirements, Repository does not return an error. Instead, Repository continues with the delete propagation operation. That is, Repository continues to consider performing propagated deletion operations on other object versions. (See Requirements for Object-Version Deletion.)

Whether an explicit deletion or a propagated deletion is attempted, Repository deletes the object version and any of its relationships if the object version satisfies the requirements for object-version deletion.

Note Some of these deleted relationships can be delete-propagating origin relationships. Repository considers performing one or more propagated deletions for each. (See After Removing an Origin Relationship.)


Requirements for Object-Version Deletion

The following restrictions apply to object-version deletion:

  • If the object version has any successor, it cannot be deleted.

  • If the object version is the member of a TargetVersions collection of an origin relationship, and that relationship’s source object version is unchangeable, it cannot be deleted. (See Requirements for Changing an Object Version.)

If a to-be-deleted object version does not satisfy these requirements, Repository does not necessarily return an error. If you are explicitly deleting the object version with the Delete method, the method fails and returns an error. But if Repository is automatically attempting to delete the object version during delete propagation, it does not return an error. Instead, Repository continues considering other object versions as candidates for propagated deletions.


Requirements for Changing an Object Version

An object version is unchangeable if it is frozen or if it is checked out to a workspace and the attempt to change it does not occur within the context of that workspace.

Note This restriction applies when Repository automatically attempts to change an object version for you. Repository can automatically change an object during delete propagation, when a propagated deletion of a destination object version can reduce the TargetVersions collection of a corresponding origin object version’s origin relationship. In effect, the origin object version has been modified automatically by Repository.

This restriction also applies when you attempt explicitly to modify an object — by setting one of its properties, for example.


Repository Glossary


A - C

annotational property

class

collection

collection type

COM object


D - F

default interface

definition

destination collection

destination collection type

destination object


G - I

global identifier

information model

instance

interface

interface definition

internal identifier

inverted property

item


J - M

MDO Model

member

metadata

metaproperty

method

Microsoft Development Objects Model


N

naming collection

naming relationship


O

object

object identifier

object-versions version collection

origin and destination

origin collection

origin collection type

origin object


P - Q

populate

predecessors version collection

property

property value


R

relationship

relationship type

repository

repository database

repository engine

repository instance

repository item

repository object

repository type library

RepVB


S

sequenced collection

sequenced relationship

source and target

source object

successors version collection


T

target object

target-objects version collection

tool information

tool information model

type

type information model

type library


U - Z

unique-naming collection

unique-naming relationship

workspace-checkouts version collection

workspace-contents version collection

workspaces-of-item version collection


Introduction to the Repository Reference

Microsoft® Repository is composed of two major components: a set of ActiveX® interfaces that a developer can use to define information models, and a Repository engine that is the underlying storage mechanism for these information models. The Repository engine sits on top of either Microsoft SQL Server™ or Microsoft JET.

This reference manual contains the definitions for all of the core engine APIs for Microsoft Repository. These APIs are documented at the Automation level for the Visual Basic® programmer and at the COM level for the C++ programmer. The schema of the underlying SQL tables is also documented to facilitate querying repository data directly through SQL.

For an overview of information models and Microsoft Repository, see the Microsoft Repository Programmer's Guide.

For a discussion of Microsoft Repository as it relates to Visual Basic, see the Microsoft Repository for Visual Basic Manual.


ObjectCol Object

See Also

An Object collection is a set of Repository objects that can be enumerated. Two kinds of Object collections are supported by the Repository:

  1. The collection of destination objects that correspond to the relationships in a relationship collection. Use the RelationshipCol object to manage this kind of collection.

  2. The collection of all objects in the Repository that conform to a particular class or expose a particular interface.

When to Use

Use the ObjectCol object to enumerate the collection of Repository objects that conform to a particular class or expose a particular interface. With this object, you can:

  • Get a count of the number of objects in the collection.

  • Retrieve one of the objects in the collection.

  • Refresh the cached image of the object collection.

Properties

Property | Description
Count | The count of the number of items in the collection.
Item | Retrieves the specified object from the collection.

Methods

Method | Description
Refresh | Refreshes the cached image of the collection.


ObjectCol Count Property

A long integer that contains the count of the number of items in the collection. This is a read-only property.

Syntax

object.Count

The Count property syntax has the following parts.

Part | Description
object | The Object collection.


ObjectCol Item Property

Use this property to retrieve an object from the collection. This is a read-only property. There are two variations of this property.

Syntax

Set variable = object.Item( index )
Set variable = object.Item( objId )

The Item property syntax has the following parts.

Part | Description
variable | A variable declared as a RepositoryObject. Receives the specified Repository object.
object | The Object collection.
index | The index of the Repository object to be retrieved from the collection.
objId | The object identifier of the Repository object to be retrieved from the collection.

Remarks

This property yields a particular version of a Repository object. To choose which version, the Repository uses its Resolution Strategy.


ObjectCol Refresh Method

This method refreshes the cached image of the Object collection. Only cache data that has not been changed by the current process is refreshed.

Syntax

Call object.Refresh( milliSecs )

The Refresh method syntax has the following parts.

Part | Description
object | The Object collection.
milliSecs | All unchanged data relating to the item that has been in the cache for longer than millisecs milliseconds is refreshed. Set to zero to refresh all unchanged data.


Relationship Object

A relationship connects two Repository objects in the Repository database. In this release of the Microsoft® Repository, relationships are versioned. That is, every relationship is a VersionedRelationship object. A versioned relationship can connect a particular version of a Repository object to one or more specific versions of the target object. Because every relationship is a VersionedRelationship object, you can declare any relationship with the following line:

Dim myRship   As VersionedRelationship

In earlier releases of the Repository, the object model included the Relationship object, but not the VersionedRelationship object. If you have Visual Basic® programs written against earlier releases of the Microsoft Repository, those programs might include declarations like the following:

Dim oldRship   As Relationship

These programs will still work, because the Repository's object model still includes the Relationship object. Visual Basic still recognizes the preceding declaration as valid. But remember, every relationship is a versioned relationship. So the object oldRship has the same members as any versioned relationship has. In effect, the following two lines of code are equivalent:

Dim myRship   As Relationship
Dim myRship   As VersionedRelationship

Even though all relationships are now versioned relationships, the Repository object model includes the Relationship object so that you do not need to rewrite your Visual Basic programs that declare objects as Relationship objects.


RelationshipCol Object

A relationship collection is the set of relationships that are attached to a particular source Repository object. All of the relationships in the collection must conform to the same relationship type.

When to Use

Use this object to manage the relationships that belong to a particular relationship collection. With this object, you can:

  • Get a count of the number of relationships in the collection.

  • Add and remove relationships to and from the collection.

  • If the collection is sequenced, place a relationship in a specific spot in the collection sequence.

  • Retrieve a specific relationship or target object from the collection.

  • Refresh the cached image of the collection.

  • Obtain the type of the collection.

Properties

Property | Description
Count | The count of the number of items in the collection.
Item | Retrieves the specified relationship or target object from the collection.
Source | The source object for the relationship collection.
Type | The object identifier for the collection's definition object.

Methods

Method | Description
Add | Adds a relationship to the collection.
Insert | Inserts a relationship into a specific spot in a sequenced collection.
Move | Moves a relationship from one spot to another in a sequenced collection.
Refresh | Refreshes the cached image of the collection.
Remove | Removes a relationship from the collection.


RelationshipCol Add Method

This method is used to add a new item to a relationship collection, when the sequencing of relationships in the collection is not important. The new relationship connects the reposObj object version to the source object version of the collection. The new relationship is passed back to the caller.

Syntax

Set variable = object.Add( reposObj, objName )

The Add method syntax has the following parts.

Part | Description
variable | A variable declared as a VersionedRelationship object. Receives the new relationship that is created for the reposObj Repository object version.
object | The relationship collection.
reposObj | The Repository object version whose relationship is to be added to the collection.
objName | The name that the new relationship is to use for the reposObj object version. This parameter is optional.

Remarks

You can add a relationship to a collection only when the collection's source object is also the collection's origin object.

When you call this method, the origin version must be unfrozen.

You can use this method to create a new versioned relationship between the source object version and a version of the target object. You cannot use it to enlarge a versioned relationship. If the source object version already has a relationship to any version of the target object, this method will fail. You can include another version of the target object in the versioned relationship by adding an item to the versioned relationship's TargetVersions collection.

The value of plReposObj is the specific version of the target object.

If you are operating within the context of a workspace, the target object version you specify with plReposObj must be present in the workspace.


RelationshipCol Count Property

A long integer that contains the count of the number of items in the collection. This is a read-only property.

Syntax

object.Count

The Count property syntax has the following parts.

Part | Description
object | The relationship collection.


RelationshipCol Insert Method

This method adds a relationship to the collection at a specified point in the collection sequence. The new relationship connects the reposObj object to the source object of the collection. The new relationship is passed back to the caller.

Syntax

Set variable = object.Insert( reposObj, index, objName )

The Insert method syntax has the following parts.

Part | Description
variable | A variable declared as a Relationship. Receives the new relationship that is created for the reposObj Repository object.
object | The relationship collection.
reposObj | The Repository object whose relationship is to be added to the collection.
index | The index of the sequence location where the relationship is to be inserted. If another relationship is already present at this sequence location, the new relationship is inserted before the existing relationship.
objName | The name that the new relationship is to use for the reposObj object. This parameter is optional.

Remarks

Relationships may only be inserted into a collection when the collection's source object is also the collection's origin object.

This method can only be used for collections that are sequenced.

When you call this method, the origin version must be unfrozen.

You can use this method to insert a new versioned relationship between the source object version and a version of the target object. You cannot use it to enlarge a versioned relationship. If the source object version already has a relationship to any version of the target object, this method will fail. You can include another version of the target object in the versioned relationship by adding an item to the versioned relationship's TargetVersionss collection.

The value of plReposObj is the specific version of the target object.

If you are operating within the context of a workspace, the target object version you specify with plReposObj must be present in the workspace.


RelationshipCol Item Property

Use this property to retrieve a target object or relationship from the collection. This is a read-only property. There are three variations of this property.

Syntax

Set variable = object.Item( index )
Set variable = object.Item( objName )
Set variable = object.Item( objId )

The Item property syntax has the following parts.

Part | Description
variable | A variable declared as a RepositoryObject. Receives the target object of the specified relationship. See the "Remarks" section for an exception.
object | The relationship collection.
index | The index of the relationship to be retrieved from the collection.
objName | The name that the relationship uses to refer to its destination object. This variation can only be used when the target object is also the destination object, and when the collection requires names for destination objects.
objId | The object identifier for the target object to be retrieved from the collection.

Remarks

This property is available on two interfaces: the default interface, ITargetObjectCol, and a second interface, IRelationshipCol. If you choose to access the property that is exposed by the IRelationshipCol interface, your variable will receive the specified VersionedRelationship object instead of the relationship's target object. In this case, you should declare your variable as a VersionedRelationship instead of a RepositoryObject. Each item in the collection is a versioned relationship — it has a collection of TargetVersions. When you obtain a reference to the target object of a particular item (with the get_Target method of the IRelationship interface), the Repository chooses a particular version of the target object from the items in the versioned relationship's TargetVersions collection.

For details on how to access a member of an interface that is not the default interface, see Accessing Automation Object Members.


RelationshipCol Move Method

This method moves a VersionedRelationship object from one point in the collection sequence to another point.

Syntax

Call object.Move( indexFrom, indexTo )

The Move method syntax has the following parts.

Part | Description
object | The relationship collection.
indexFrom | The index of the VersionedRelationship object to be moved in the collection sequence.
indexTo | The index of the sequence location to which the VersionedRelationship object is to be moved.

Remarks

This method can only be used with sequenced collections.

When you call this method, the origin object version must be unfrozen.


RelationshipCol Refresh Method

This method refreshes the cached image of the relationship collection. Only cache data that has not been changed by the current process is refreshed.

Syntax

Call object.Refresh( milliSecs )

The Refresh method syntax has the following parts.

Part | Description
object | The relationship collection.
milliSecs | All unchanged data relating to the item that has been in the cache for longer than millisecs milliseconds is refreshed. Set to zero to refresh all unchanged data.


RelationshipCol Remove Method

This method deletes a relationship from its relationship collection. The exact behavior of this method depends on whether the relationship collection is an origin collection or a destination collection.

If the relationship collection is an origin collection, this method deletes the versioned relationship.

If the relationship collection is a destination collection, this method first performs object-version resolution to yield a single target-object version, and then it removes that target-object version from the relationship's TargetVersions collection.

Syntax

Call object.Remove( index )
Call object.Remove( objName )

The Remove method syntax has the following parts.

Part | Description
object | The relationship collection.
index | The index of the relationship to be removed from the collection.
objName | The relationship that uses this name for its destination object is to be removed from the collection.

Remarks

A relationship can be removed by name only if it is a unique-naming relationship.

If the source is the origin, the origin version must be unfrozen.

If the relationship is a destination relationship and the resolution strategy yields a target object version that is frozen, this method fails.


RelationshipCol Source Property

Use this property to retrieve the source object for the relationship collection. This is a read-only property.

Syntax

Set variable = object.Source

The Source property syntax has the following parts.

Part | Description
variable | A variable declared as a RepositoryObjectVersion object. Receives the source object version of the relationship collection.
object | The relationship collection.


RelationshipCol Type Property

This property specifies the type of the collection. More specifically, it is the object identifier of the collection definition object for the collection. Type is a read-only property. To copy this property to another variable, use a variable that is declared as a Variant.

Syntax

object.Type

The Type property syntax has the following parts.

Part | Description
object | The relationship collection.


Repository Object

When you define a tool information model, the classes, relationships, properties, and collections for the model are stored in a Repository. Multiple tool information models may be stored in the same Repository.

When you access a Repository, you do so via a Repository instance.

When to Use

You can use a Repository instance to:

  • Create a new Repository database.

  • Connect to a Repository.

  • Access the root Repository object.

  • Retrieve a Repository object.

  • Retrieve a specific Repository object version.

  • Create the initial version of a Repository object.

  • Refresh cached Repository data.

  • Manage Repository transactions.

Properties

Property | Description
ConnectionString | The ODBC connection string that the Repository engine uses to obtain an ODBC connection. This property is not a default interface member.
Object | Retrieves the specified Repository object.
ReposConnection | The ODBC connection handle that the Repository engine is using to access the Repository database. This property is not a default interface member.
RootObject | The root Repository object of the currently open Repository.
Transaction | The transaction processing interface.
Version | Retrieves the specified Repository object version.

Methods

Property | Description
Create | Creates a new Repository database.
CreateObject | Creates a new Repository object in the currently open Repository.
ExecuteQuery | Executes the specified SQL query against the Repository database. This method is not a default interface member.
FreeConnection | Releases an ODBC connection handle. This method is not a default interface member.
GetNewConnection | Obtains a new ODBC connection handle using the same connection settings that the Repository engine is using to access the Repository database. This method is not a default interface member.
InternalIDToObjectID | Converts an internal identifier into an object identifier.
InternalIDToVersionID | Converts an internal object-version identifier into an object-version identifier.
ObjectIDToInternalID | Converts an object identifier into an internal identifier.
Open | Opens the specified Repository.
Refresh | Refreshes the cached image of all data for the currently open Repository.
VersionIDToInternalID | Converts an object-version identifier into an internal object-version identifier.


Accessing Automation Object Members

Microsoft Repository contains a number of Automation objects that support multiple interfaces. With each Automation object, one interface is defined to be the default interface, and the members (the properties, methods, and collections) that are attached to that interface are accessible via the standard Visual Basic mechanisms.

When accessing members that are attached to an interface that is not the default interface for an Automation object, a different access technique must be used. An additional reference to the object must be declared that explicitly calls for the non-default interface. The non-default interface members can then be accessed via the new object reference.

The following example illustrates how to access a property that is attached to an interface that is not the default interface for an Automation object. In this example, the connection string that is used to connect to the Repository database is retrieved. Repository objects implement the IRepositoryODBC interface; this interface is not the default interface. The ConnectionString property is attached to the IRepositoryODBC interface. The ConnectionString property is the ODBC connection string that the Repository uses when connecting to a database server.

Dim myRepos     As Repository
Dim nonDefIfc   As IRepositoryODBC

'  Initialize the myRepos object by opening a
'  connection to a Repository database.

Set nonDefIfc = myRepos
connect$ = nonDefIfc.ConnectionString

In this example, the nonDefIfc object does not use up additional resources; it is just an alternate view of the myRepos object.


Connecting to a Repository Database

Microsoft® Repository can access Repository databases that are managed by either Microsoft Jet or Microsoft SQL Server. The ODBC connection string that is used to specify the location of the Repository database varies, depending upon which database server is managing the Repository database.

The ODBC connection string contains keyword=keyValue pairs, separated by semicolons.

Connecting to a Jet Repository Database

To connect to a Jet Repository database, use the DBQ keyword to specify the path to the database file. The DBQ keyword must be the first keyword in the connection string, if it is present. If the DBQ keyword is not present, the connection string is assumed to contain only a database path specification. In this case, the Repository will add the DBQ keyword to the front of the ODBC connection string before passing it on to the database server. If the JET database file specified by the DBQ keyword does not exist, Microsoft Repository will create it.

Connecting to a SQL Server Repository Database

To connect to a SQL Server Repository database, use the SERVER keyword to specify the SQL Server name and (optionally) the database name. To specify the database name, use this syntax:

    SERVER=serverName;DATABASE=databaseName

If the database name is not specified, the default database for the user performing the open is used.

Note If you choose to use a SQL Server Repository database, you must either use an existing database, or create an empty database and specify which users can access the database. The Repository engine will not automatically create this database for you. If you create a new SQL Server database, be sure to create the necessary "Login" and "User" accounts for people who will be accessing the database, and assign the appropriate permissions to these accounts. If everyone will be granted full permissions, then you can use this SQL command to set database access permissions: "Grant all to public".

Connecting via a Data Source Name

You can use the DSN keyword to specify a Data Source Name (DSN) to connect to an existing Jet or SQL Server Repository database. The DSN keyword specifies a Data Source Name that has been configured via the ODBC Data Source Administrator.

The Default Repository Database

If you do not specify the Repository database via any of the mechanisms described above, a connection will be established to the default Repository database. The location of the default Repository database is stored in the system registry in this registry key:

    HKEY_LOCAL_MACHINE\
        Software\
            Microsoft\
                Repository\
                    Current Location

This registry key must contain either a DBQ keyword-value pair, SERVER keyword-value pair, DSN keyword-value pair, or just the path to a Jet Repository database. The default value for this registry key is:

    windowsDirectory\MsApps\Repostry\Repostry.mdb

where windowsDirectory is the path specification for the directory that contains either the Windows NT or Windows 95 installation. Unless you change this registry key value after installing Microsoft Repository, your default database server will be Microsoft Jet.

Note Microsoft Repository will create a default Repository database for you when it is installed. This database is managed by Microsoft Jet. It's location is determined by the default value of the Current Location registry key.


Repository ConnectionString Property

This property contains the ODBC connection string that the Repository engine uses to obtain an ODBC connection to the Repository database. This is a read-only property.

This property is not attached to the default interface for the Repository Automation object; it is attached to the IRepositoryODBC interface. For details on how to access a member of an interface that is not the default interface, see Accessing Automation Object Members.

Syntax

object.ConnectionString

The ConnectionString property syntax has the following parts.

Part | Description
object | The object that represents the open Repository instance through which this program is interacting with the Repository.

Remarks

The ODBC connection string can contain user identification and password information. Take care to protect this information from exposure to unauthorized access.


Repository Create Method

Use this method to create a new Repository database. The fundamental Repository tables are automatically created. The root Repository object of the new Repository is passed back to the caller.

Syntax

Set variable = object.Create( connect, user, password, flags )

The Create method syntax has the following parts.

Part | Description
variable | A variable declared as a RepositoryObject. Receives the root Repository object for the new Repository.
object | The instance of the Repository class that you are using to create the new Repository database.
connect | The ODBC connection string to be used for accessing the database server that will host your new Repository.
user | The user name to use for identification to the database server.
password | The password that matches the user input parameter.
flags | Flags that determine database access and caching behavior for the open Repository. For details, see the ConnectionFlags Enumeration.


Repository CreateObject Method

This method creates a new Repository object of the specified type.

Syntax

Set variable = object.CreateObject( typeId, objectId )

The CreateObject method syntax has the following parts.

Part | Description
variable | Declared as a RepositoryObject. Receives the new Repository object.
object | The object that represents the open Repository instance through which this program is interacting with the Repository.
typeId | The type of the new object; that is, the object identifier of the object definition to which the new object conforms.
objectId | The object identifier to be assigned to the new object. Either pass in ObjID_NULL or do not supply this optional parameter to have the Repository assign an object identifier for you.

Remarks

Use this method to create the first version of a new Repository object. To create subsequent versions of a Repository object versions, use the CreateVersion method of the RepositoryObjectVersion object.


Repository ExecuteQuery Method

This method executes the specified SQL query against the Repository database, and returns a collection of Repository objects. The columns that are returned by the query must be either just the internal identifier (IntID) column, or the internal identifier and the type identifier (IntID, TypeID) columns of the RTblVersions table.

Syntax

Set variable = object.ExecuteQuery( queryString )

The ExecuteQuery method syntax has the following parts.

Part | Description
variable | Declared as an ObjectCol object. Receives the collection of objects that meet the selection criteria of the SQL query.
object | The object that represents the open Repository instance through which this program is interacting with the Repository.
queryString | A string that contains the SQL Query or the name of a stored procedure to be executed.


Repository FreeConnection Method

This method frees an ODBC connection handle.

This property is not attached to the default interface for the Repository Automation object; it is attached to the IRepositoryODBC interface. For details on how to access a member of an interface that is not the default interface, see Accessing Automation Object Members.

Syntax

Call object.FreeConnection( hdbc )

The FreeConnection method syntax has the following parts.

Part | Description
object | The object that represents the open Repository instance through which this program is interacting with the Repository.
hdbc | The ODBC connection handle to be released.

Remarks

Use this method to free the handle obtained via either the ReposConnection property or the GetNewConnection method before releasing your open Repository instance.


Repository GetNewConnection Method

This method obtains a new ODBC connection handle using the same ODBC connection string that the Repository engine is using to access the Repository database. Using a new ODBC connection handle isolates you from changes made by the Repository engine.

This property is not attached to the default interface for the Repository Automation object; it is attached to the IRepositoryODBC interface. For details on how to access a member of an interface that is not the default interface, see Accessing Automation Object Members.

Syntax

variable = object.GetNewConnection

The GetNewConnection method syntax has the following parts.

Part | Description
variable | Receives the new connection handle.
object | The object that represents the open Repository instance through which this program is interacting with the Repository.

Remarks

Be sure to free the handle obtained via this method before releasing your open Repository instance. To free the connection handle, use the FreeConnection method.


Repository InternalIDToObjectID Method

This method translates an internal identifier into an object identifier. Internal identifiers are used by the Repository engine to identify Repository objects.

Syntax

variable = object.InternalIDToObjectID( internalId )

The InternalIDToObjectID method syntax has the following parts.

Part | Description
variable | Receives the object identifier.
object | The object that represents the open Repository instance through which this program is interacting with the Repository.
internalId | The internal identifier to be converted.

Remarks

Repository object identifiers are globally unique, and are the same across repositories for the same object. Internal identifiers are unique only within the scope of a single Repository.

The translation performed by this method is performed without loading the object in question. This enables database queries involving an object or relationship type identifier to be constructed without having to load the definition object.


Repository InternalIDToVersionID Method

This method translates an internal object-version identifier into an object-version identifier. Internal object-version identifiers are used by the Repository engine to identify Repository object versions.

Syntax

variable = object.InternalIDToVersionID( intVersionId )

The InternalIDToVersionID method syntax has the following parts.

Part | Description
variable | Receives the object-version identifier.
object | The object that represents the open Repository instance through which this program is interacting with the Repository.
intVersionId | The internal object-version identifier to be converted.

Remarks

Repository object-version identifiers are globally unique, and are the same across repositories for the same object. Internal object-version identifiers are unique only within the scope of a single Repository.

The translation performed by this method is performed without loading the object version in question. This enables database queries involving an object or relationship type identifier to be constructed without having to load the definition object.


Repository Object Property

Use this property to retrieve a particular Repository object. This is a read-only property.

Syntax

Set variable = object.Object( objectId )

The Object property syntax has the following parts.

Part | Description
variable | Declared as a RepositoryObject. Receives the Repository object.
object | The object that represents the open Repository instance through which this program is interacting with the Repository.
objectId | The object identifier for the Repository object to be retrieved.

Remarks

The Repository returns a specific version of the Repository object to you. To choose a version, it uses its Resolution strategy.


Repository ObjectIDToInternalID Method

This method translates an object identifier into an internal identifier. Internal identifiers are used by the Repository engine to identify Repository objects.

Syntax

variable = object.ObjectIDToInternalID( objectId )

The ObjectIDToInternalID method syntax has the following parts.

Part | Description
variable | Receives the internal identifier.
object | The object that represents the open Repository instance through which this program is interacting with the Repository.
objectId | The object identifier to be converted.

Remarks

Repository object identifiers are globally unique, and are the same across repositories for the same object. Internal identifiers are unique only within the scope of a single Repository.

The translation performed by this method is performed without loading the object in question. This enables database queries involving an object or relationship type identifier to be constructed without having to load the definition object.


Repository Open Method

Use this method to open (connect to) a Repository. The root Repository object is passed back to the caller.

Syntax

Set variable = object.Open( connect, user, password, flags )

The Open method syntax has the following parts.

Part | Description
variable | A variable declared as a RepositoryObject; receives the root Repository object for the Repository.
object | The instance of the Repository class that you are using to connect to the Repository.
connect | The ODBC connection string to be used for accessing the database server that hosts your Repository.
user | The user name to use for identification to the database server.
password | The password that matches the user input parameter.
flags | Flags that determine database access and caching behavior for the open Repository. For details, see the ConnectionFlags Enumeration.


Repository Refresh Method

This method refreshes all of the cached data for this open Repository instance. Only cached data that has not been changed by the current process is refreshed.

Syntax

Call object.Refresh( milliSeconds )

The Refresh method syntax has the following parts.

Part | Description
object | The object that represents the open Repository instance through which this program is interacting with the Repository.
milliSecs | All unchanged Repository data that has been in the cache for longer than millisecs milliseconds is refreshed. Set to zero to refresh all unchanged data for the Repository.


Repository ReposConnection Property

This property contains the ODBC connection handle that the Repository engine is using to access the Repository database. This is a read-only property.

This property is not attached to the default interface for the Repository Automation object; it is attached to the IRepositoryODBC interface. For details on how to access a member of an interface that is not the default interface, see Accessing Automation Object Members.

Syntax

object.ReposConnection

The ReposConnection property syntax has the following parts.

Part | Description
object | The object that represents the open Repository instance through which this program is interacting with the Repository.

Remarks

If you use the Repository engine's ODBC connection handle, you are not isolated from changes made by the Repository engine. For example, uncommitted changes made by the Repository engine will be visible to your application.

When using the Repository engine's ODBC connection handle, you must not change the state of the handle in a way that is incompatible with the Repository engine. Specifically, do not:

  • Change any ODBC connection options.

  • Perform any accesses concurrent with Repository method invocations.

  • Directly commit or rollback a database transaction. The IRepositoryTransaction interface must always be used to manage transactions.

Be sure to free the handle obtained through this method before releasing your open Repository instance. To free the connection handle, use the FreeConnection method.


Repository RootObject Property

This property is the root Repository object for the currently open Repository. This is a read-only property.

Syntax

Set variable = object.RootObject

The RootObject property syntax has the following parts.

Part | Description
variable | A variable declared as a RepositoryObject. Receives the root Repository object.
object | The object that represents the open Repository instance through which this program is interacting with the Repository.


Repository Transaction Property

This property is the RepositoryTransaction object for the open Repository instance. This is a read-only property.

Syntax

Set variable = object.Transaction

The Transaction property syntax has the following parts.

Part | Description
variable | A variable declared as an Object. Receives the RepositoryTransaction object for this Repository instance.
object | The object that represents the open Repository instance through which this program is interacting with the Repository.

Remarks

You can gain access to the RepositoryTransaction object by using the syntax shown above. Then you can access the properties and methods of the RepositoryTransaction object via variable.method and variable.property syntax. You can also access the properties and methods of the RepositoryTransaction object directly, using syntax like the following.

Call object.Transaction.method

-or-

variable = object.Transaction.property

See the RepositoryTransaction object for details on the methods and properties that it provides.


Repository Version Property

Use this property to retrieve a particular Repository object version from the Repository. This is a read-only property.

Syntax

Set variable = object.Version( versionId )

The Version property syntax has the following parts.

Part | Description
variable | Declared as a RepositoryObjectVersion. Receives the Repository object version.
object | The object that represents the open Repository instance through which this program is interacting with the Repository.
versionId | The object-version identifier for the Repository object to be retrieved.


Repository VersionIDToInternalID Method

This method translates an object-version identifier into an internal object-version identifier. Internal object-version identifiers are used by the Repository engine to identify Repository object versions.

Syntax

variable = object.VersionIDToInternalID( versionId )

The VersionIDToInternalID method syntax has the following parts.

Part | Description
variable | Receives the internal object-version identifier.
object | The object that represents the open Repository instance through which this program is interacting with the Repository.
objectId | The object-version identifier to be converted.

Remarks

Repository object-version identifiers are globally unique, and are the same across repositories for the same object version. Internal object-version identifiers are unique only within the scope of a single Repository.

The translation performed by this method is performed without loading the object version in question. This enables database queries involving an object or relationship type identifier to be constructed without having to load the definition object.


RepositoryObject Object

A Repository object is an object that is stored in the Repository database and is managed by the Repository engine.

In this release of the Microsoft Repository, objects can be versioned. A Repository object version is a particular rendition of a Repository object. Each version of an object can differ from other versions of that object in its property values and collections. When you manipulate a Repository object within a Visual Basic® program. you actually are manipulating a particular version of that object. That is, you manipulate a RepositoryObjectVersion object.

You can declare any Repository object version with the following line:

Dim newReposObject   As RepositoryObjectVersion

In earlier releases of the Repository, the object model included the RepositoryObject object, but not the RepositoryObjectVersion object. If you have Visual Basic programs written against earlier releases of the Microsoft Repository, those programs might include declarations like the following:

Dim oldReposObject   As RepositoryObject

These programs will still work, because the Repository's object model still includes the RepositoryObject object. Visual Basic still recognizes the preceding declaration as valid. Whenever you manipulate an object, you actually manipulate a specific version of that object. So the object oldReposObject has the same members as any Repository object version has. In effect, the following two lines of code are equivalent:

Dim myReposObject   As RepositoryObjectVersion
Dim myReposObject   As RepositoryObject

Even though Repository objects are now versioned, the Repository object model includes the RepositoryObject object so that you do not need to rewrite your Visual Basic programs that declare objects as RepositoryObject objects.

When to Use

Use the RepositoryObject object to manipulate the properties of a Repository object, to delete a Repository object, or to refresh the cached image of a Repository object.

Properties

Property | Description
Interface | The specified object interface.
InternalID | The internal identifier that the Repository uses to refer to the Repository object.
Name | The name of the Repository object.
ObjectID | The object identifier for the Repository object.
Repository | The open Repository instance through which this Repository object was instantiated.
Type | The type of the Repository object.

Methods

Collection | Description
Delete | Deletes a Repository object.
Lock | Locks the Repository object.
Refresh | Refreshes the cached image of a Repository object.

Collections

Collection | Description
Properties | The collection of all of the properties that are attached to the Repository object.


RepositoryObject Delete Method

This method deletes the Repository object from the Repository. Any relationships that connect the object to other objects are deleted. If the Repository object is an origin object of a relationship collection, and the relationship type indicates that deletes are to be propagated, all of the destination objects are also deleted.

Syntax

Call object.Delete

The Delete method syntax has the following parts.

Part | Description
object | An object expression that evaluates to a RepositoryObject object.


RepositoryObject Interface Property

Use this property to obtain a view of the Repository object that uses an alternate interface as the default interface. This is a read-only property. There are three variations of this property.

Syntax

Set variable = object.Interface( interfaceId )
Set variable = object.Interface( objectId )
Set variable = object.Interface( interfaceName )

The Interface property syntax has the following parts.

Part | Description
variable | An object variable. Receives the Repository object with the specified interface as the default interface.
object | An object expression that evaluates to a RepositoryObject object.
interfaceId | The interface identifier for the interface to be retrieved.
objectId | The object identifier for the interface definition to which the interface to be retrieved conforms.
InterfaceName | A string containing the name of the interface to be retrieved.


RepositoryObject InternalID Property

This property is the internal identifier that the Repository engine uses to refer to this object. The internal identifier is unique within the Repository, but not unique across repositories. This is a read-only property. To copy this property to another variable, use a variable declared as a Variant.

Syntax

object.InternalID

The InternalID property syntax has the following parts.

Part | Description
object | An object expression that evaluates to a RepositoryObject object.


RepositoryObject Lock Method

Use this method to lock the Repository object. Locking the object prevents other processes from updating the object while you are working with it. The lock is released when you end the current transaction.

Call object.Lock

The Lock method syntax has the following parts.

Part | Description
object | An object expression that evaluates to a RepositoryObject object.


RepositoryObject Name Property

A character string that contains the name of the Repository object.

The name property is normally a property of the relationship for which this Repository object is the destination object. When the name is retrieved, the name from the first naming relationship found is returned. If the object is not the destination of any naming relationship, a null name is returned. When the name is set, the new name is set for all naming relationships for which the object is the destination.

Syntax

object.Name

The Name property syntax has the following parts.

Part | Description
object | An object expression that evaluates to a RepositoryObject object.

Remarks

If the Repository object exposes the INamedObject interface, the name that is retrieved is always the Name property of the INamedObject interface. Likewise, when this property is set, the Name property of the INamedObject interface and the name associated with all naming relationships are set to the new value.


RepositoryObject ObjectID Property

This property is the object identifier for the Repository object. The object identifier is unique across all repositories. This is a read-only property. To copy this property to another variable, use a variable declared as a Variant.

Syntax

object.ObjectID

The ObjectID property syntax has the following parts.

Part | Description
object | An object expression that evaluates to a RepositoryObject object.


RepositoryObject Refresh Method

This method refreshes the cached image of the Repository object. Only cached data that has not been changed by the current process is refreshed.

Syntax

Call object.Refresh( milliSecs )

The Refresh method syntax has the following parts.

Part | Description
object | An object expression that evaluates to a RepositoryObject object.
milliSecs | All unchanged data relating to the item that has been in the cache for longer than millisecs milliseconds is refreshed. Set this parameter to zero to refresh all unchanged data.


RepositoryObject Repository Property

The Repository property is the open Repository instance through which this Repository object was instantiated. This is a read-only property.

Syntax

Set variable = object.Repository

The Repository property syntax has the following parts.

Part | Description
variable | A variable declared as an instance of the Repository class. Receives the object that represents the open Repository instance.
object | An object expression that evaluates to a RepositoryObject object.


RepositoryObject Properties Collection

The Properties collection contains all of the persistent properties that are attached to the Repository object through the IRepositoryObject interface.

Syntax

Set variable = object.Properties( index )

The Properties collection syntax has the following parts.

Part | Description
variable | A variable declared as a ReposProperty object. Receives the specified property.
object | An object expression that evaluates to a RepositoryObject object.
index | An integer index that identifies which property in the collection is to be addressed. The valid range is from one to the number of elements in the collection. The number of elements in the collection is specified by object.Properties.Count.


RepositoryObject Type Property

This property specifies the type of the Repository object. More specifically, it is the object identifier of the object definition object for the Repository object. Type is a read-only property. To copy this property to another variable, use a variable declared as a Variant.

Syntax

object.Type

The Type property syntax has the following parts.

Part | Description
object | An object expression that evaluates to a RepositoryObject object.

Remarks

An object in the Repository is simultaneously a Repository object, an Automation object, and an object of a model-specific type, as defined by a tool information model.

The model-specific type of a Repository object is defined by its object definition. Each object definition is itself a Repository object, and consequently has an object identifier assigned to it. In other words, the value of an object definition object's ObjectID property is used as the value of the Type property for all Repository objects that conform to that object definition.


RepositoryObjectVersion Object

A Repository object is an object that is stored in the Repository database, and is managed by the Repository engine. A Repository object version is a specific rendition of that Repository object. The Repository can retain multiple renditions of a Repository object so that you can reestablish historical states of the Repository.

A Repository object version is also an Automation object.

When to Use

Use the RepositoryObjectVersion object to manipulate the properties of a Repository object version, to delete a Repository object version, or to refresh the cached image of a Repository object version.

Properties

Property Description

CheckedOutToWorkspace | The workspace to which the object version is checked out.
Interface | The specified object interface.
InternalID | The internal object identifier that the Repository uses to refer to the Repository object.
IsCheckedOut | Indicates whether the object version is checked out to any workspace.
IsFrozen | Indicates whether the object version is frozen.
Name | The name of the Repository object version.
ObjectID | The object identifier for the Repository object.
PredecessorCreationVersion | The object version from which the current object version was originally created.
Repository | The open Repository instance through which this Repository object was instantiated.
ResolutionType | Indicates why the Repository returned this particular version of the object to your program, rather than returning some other version of the same object.
Type | The type of the Repository object.
VersionID | The object-version identifier for the Repository object version.
VersionInternalID | The internal object-version identifier that the Repository uses to refer to the Repository object version.

Methods

Method Description

Checkin | Terminates a workspaces ability to modify the object version, and allows other workspaces to check out the object version.
Checkout | Claims for the current workspace the exclusive privilege to modify the object version.
CreateVersion | Creates a new version of the current object, based on the current object version.
Delete | Deletes a Repository object.
FreezeVersion | Fixes the object version's property values and origin collections – safeguarding them from further modification.
Lock | Locks the Repository object.
MergeVersion | Modifies the current object version by combining its property values and collection with those of another version of the same Repository object.
Refresh | Refreshes the cached image of a Repository object.

Collections

Collection Description

ObjectVersions | The collection of all the versions of the current Repository object.
PredecessorVersions | The collection of all immediate predecessor versions of the current Repository object version.
Properties | The collection of all of the properties that are attached to the Repository object.
SuccessorVersions | The collection of all immediate successor versions of the current Repository object version.
Workspaces | The collection of all workspaces in which the current object version is present.


RepositoryObjectVersion CheckedOutToWorkspace Property

The CheckedOutToWorkspace property is the workspace to which this Repository object version is currently checked out. This is a read-only property.

Syntax

Set variable = object.CheckedOutToWorkspace

The CheckedOutToWorkspace property syntax has the following parts.

Part | Description
variable | A variable declared as an instance of the Workspace class. Receives the object that represents the workspace to which the object version is checked out.
object | An object expression that evaluates to a RepositoryObjectVersion object.


RepositoryObjectVersion Checkin Method

This method checks in the current object from the workspace to which it was checked out.

Syntax

Call object.Checkin

The Checkin method syntax has the following parts.

Part | Description
object | An object expression that evaluates to a RepositoryObjectVersion object.


RepositoryObjectVersion Checkout Method

This method checks out the current object version to the workspace within which you are operating.

Syntax

Call object.Checkout

The Checkout method syntax has the following parts.

Part | Description
object | An object expression that evaluates to a RepositoryObjectVersion object.


RepositoryObjectVersion CreateVersion Method

This method creates a new version of the Repository object, based on the current version.

Syntax

set variable = object.CreateVersion( versionID )

The Refresh method syntax has the following parts.

Part | Description
variable | An object expression that evaluates to a RepositoryObjectVersion object; receives a reference to the newly created object version.
object | An object expression that evaluates to a RepositoryObjectVersion object.
versionID | The value you want the Repository to use as an object-version identifier for the newly created object version. If you want the Repository to choose a value for you, set this parameter to EXT_VERSIONID_NULL.

Remarks

The current object version must be frozen.

The Repository creates the new version as unfrozen. Its property values are identical to the current object version's property values.

For each of the predecessor version's origin relationship collections, the Repository takes this action:

  • If the corresponding relationship type has the COLLECTION_NEWORGVERSIONSPARTICIPATE flag set, the Repository copies the collection to the newly created version.

  • If the corresponding relationship type does not have the COLLECTION_NEWORGVERSIONSPARTICIPATE flag set, the Repository does not copy the collection to the new version.

You cannot invoke this method while operating in a workspace.


RepositoryObjectVersion Delete Method

This method deletes the Repository object version from the Repository.

Syntax

Call object.Delete

The Delete method syntax has these parts:

Part | Description
object | An object expression that evaluates to a RepositoryObjectVersion object.

Remarks

This method fails unless the object version satisfies the basic requirements for object-version deletion. Furthermore, if the object version is checked out to any workspace, the Delete method fails unless you invoke it from within the context of that workspace. If object version satisfies both of these restrictions, the Repository deletes it and any of its relationships — including any delete-propagating origin relationships. For each of these relationships, the Repository considers performing one or more propagated deletions. See Propagation after removing an origin relationship.


RepositoryObjectVersion FreezeVersion Method

This method freezes the current RepositoryObjectVersion object.

Syntax

Call object.FreezeVersion

The FreezeVersion method syntax has the following parts.

Part | Description
object | An object expression that evaluates to a RepositoryObjectVersion object.

Remarks

The object version must be unfrozen.

After you freeze an object version, you cannot change its non-annotational property values. However, you can change the value of any of its annotational properties.

After you freeze an object version, you cannot enlarge or shrink or resequence any of its origin collections. Furthermore, you cannot change any of the individual versioned relationships in any of the origin collections. That is, you cannot enlarge or shrink an origin versioned relationship's TargetVersions collection; you cannot pin or unpin a target object version; and you change the name by which the origin object version refers to the target object.

If you call this method for an item currently checked out to any workspace (including the workspace in which you are working), it returns an error.

If the to-be-frozen object version includes any non-null origin collection whose corresponding collection type has the COLLECTION_REQUIRESFREEZE flag set, and that non-null collection includes an item whose TargetVersions collection contains a non-frozen object version, the method fails.


RepositoryObjectVersion Interface Property

Use this property to obtain a view of the Repository object version that uses an alternate interface as the default interface. This is a read-only property. There are three variations of this property.

Syntax

Set variable = object.Interface( interfaceId )
Set variable = object.Interface( objectId )
Set variable = object.Interface( interfaceName )

The Interface property syntax has the following parts.

Part | Description
variable | An object variable. Receives the Repository object with the specified interface as the default interface.
object | An object expression that evaluates to a RepositoryObjectVersion object.
interfaceId | The interface identifier for the interface to be retrieved.
objectId | The object identifier for the interface definition to which the interface to be retrieved conforms.
InterfaceName | A string containing the name of the interface to be retrieved.


RepositoryObjectVersion InternalID Property

This property is the internal identifier that the Repository engine uses to refer to this object. The internal identifier is unique within the Repository, but not unique across repositories. This is a read-only property. To copy this property to another variable, use a variable declared as a Variant.

Syntax

object.InternalID

The InternalID property syntax has the following parts.

Part | Description
object | An object expression that evaluates to a RepositoryObjectVersion object.

Remarks

This property yields the internal object identifier, not the internal object-version identifier.


RepositoryObjectVersion IsCheckedOut Property

This property indicates whether or not the object version is currently checked out to any workspace.

Syntax

Set variable = object.IsCheckedOut

The IsCheckedOut property syntax has the following parts.

Part | Description
variable | A Boolean variable.
object | An object expression that evaluates to a RepositoryObjectVersion object.


RepositoryObjectVersion IsFrozen Property

This property indicates whether or not the object version is frozen.

Syntax

Set variable = object.IsFrozen

The IsFrozen property syntax has the following parts.

Part | Description
variable | A Boolean variable.
object | An object expression that evaluates to a RepositoryObjectVersion object.


RepositoryObjectVersion Lock Method

Use this method to lock the Repository object version. Locking the object version prevents other processes from locking it while you are working with it. The lock is released when you end the current transaction.

Call object.Lock

The Lock method syntax has the following parts.

Part | Description
object | An object expression that evaluates to a RepositoryObject object.


RepositoryObjectVersion MergeVersion Method

This method changes the current object version by combining its property values and origin collections with the property values and origin collections of another version of the same object.

Syntax

Call object.MergeVersion( otherVersion , flags )

The MergeVersion method syntax has the following parts.

Part | Description
object | An object expression that evaluates to a RepositoryObjectVersion object.
otherVersion | An object expression that evaluates to a RepositoryObjectVersion object; the object version whose value you want to merge into the current object version.
flags | A flag indicating which version (the current version or the other version) the Repository should use as the primary version of the merge operation.

Remarks

The two object versions must be versions of the same object.

The current object version must be unfrozen. The other object version must be frozen.

MergeVersion compares the property values and collections of each object version to a third version, called the Basis Version.

The Repository considers one of the two to-be-merged object versions to be the primary version, and the other to be the secondary version, according to the value of flags you supply. During the merge, the Repository considers each property and origin collection type in turn. For each property, MergeVersion uses this rule:

  • If the primary version differs from the basis version, the Repository uses the property value from the primary version. If only the secondary version differs from the basis version, the Repository uses the property value from the secondary version. If neither version differs from the basis version, the Repository leaves the property value in the current version unchanged.

For each origin collection type whose Collection_MergeWhole flag is set, MergeVersion uses this rule:

  • If the primary version's collection differs from the basis version's collection, the Repository uses the collection from the primary version. If only the secondary version's collection differs from the basis version's, the Repository uses the collection from the secondary version. If neither version differs from the basis version, the Repository leaves the collection in the current version unchanged.

For each origin collection type whose Collection_MergeWhole flag is not set, MergeVersion combines the items in the two collections as follows:

  • First, MergeVersion includes in the resulting collection each item in the basis version not changed in or deleted from either the primary version or secondary version

  • Second, MergeVersion includes in the resulting collection each item in the primary version's collection that differs from the basis version.

  • Third, MergeVersion includes in the resulting collection each item in the secondary version's collection that differs from the basis version – provided the corresponding items in the primary version and basis version do not differ from each other.

Note that the resulting collection can exclude some items found in the basis object version's collection. For example, if the primary version's collection excludes the item, the resulting collection will exclude the item. Similarly, if the primary version's collection includes an item that is identical to an item in the basis version's collection, but the secondary object version excludes the item, the resulting collection will exclude the item.


RepositoryObjectVersion Name Property

A character string that contains the name of the Repository object version.

Syntax

object.Name

The Name property syntax has the following parts.

Part | Description
object | An object expression that evaluates to a RepositoryObjectVersion object.

Remarks

When you try to retrieve an object version's name, there are several places the Repository can look for a name. (See Retrieving an object version's name.)

When you try to change the value of this property, there might be several names the Repository tries to change. (See Changing an object version's name.)

Note that when you change this property, the Repository can, in some circumstances, change some names but not change others. For example, if an object version is the destination of three naming relationships and also implements the INamedObject interface, this method will try to change four names. The method returns success if any of the four attempts succeeds.


RepositoryObjectVersion ObjectID Property

This property is the object identifier for the Repository object. The object identifier is unique across all repositories. This is a read-only property. To copy this property to another variable, use a variable declared as a Variant.

Syntax

object.ObjectID

The ObjectID property syntax has the following parts.

Part | Description
object | An object expression that evaluates to a RepositoryObject object.

Remarks

This property yields the object identifier, not the object-version identifier.


RepositoryObjectVersion ObjectVersions Collection

An ObjectVersions collection contains all of the RepositoryObjectVersion objects that are versions of the same Repository object.

Syntax

Set variable = object.ObjectVersions

The ObjectVersions collection syntax has these parts:

Part | Description
variable | A variable declared as a VersionCol object. Receives a reference to the Versions-of-Object collection.
object | An object expression that evaluates to a RepositoryObjectVersion object.

Remarks

Within the returned collection, the Repository sequences the items in order of their creation, with the oldest object version first.

You cannot modify the collection. To add a new object version, use the CreateVersion method of the RepositoryObjectVersion object.


RepositoryObjectVersion PredecessorCreationVersion Property

The PredecessorCreationVersion property is the RepositoryObjectVersion object from which this Repository object version was created.

Syntax

Set variable = object.PredecessorCreationVersion

The PredecessorCreationVersion property syntax has the following parts.

Part | Description
variable | A variable declared as RepositoryObjectVersion object. Receives the object version from which the current object version was created.
object | An object expression that evaluates to a RepositoryObjectVersion object.

Remarks

If you invoke this method for the first version of an object, it returns an error.


RepositoryObjectVersion PredecessorVersions Collection

A PredecessorVersions collection contains all of the RepositoryObjectVersion objects that are immediate predecessors of the current object version.

Syntax

Set variable = object.PredecessorVersions

The PredecessorVersions collection syntax has the following parts.

Part | Description
variable | A variable declared as a VersionCol object. Receives a reference to the Predecessor-Versions collection.
object | An object expression that evaluates to a RepositoryObjectVersion object.

Remarks

This method returns only the immediate predecessors of the current object version.

If you invoke this method for the first version of an object, it returns an empty collection.

Within the returned collection, the Repository sequences the items in order of their creation, with the oldest object version first.

You cannot modify the collection. To enlarge an object's set of predecessor versions, use the MergeVersion method of the RepositoryObjectVersion object.


RepositoryObjectVersion Properties Collection

The Properties collection contains all of the persistent properties that are attached to the Repository object via the IRepositoryObject interface.

Syntax

Set variable = object.Properties( index )

The Properties collection syntax has the following parts.

Part | Description
variable | A variable declared as a ReposProperty object. Receives the specified property.
object | An object expression that evaluates to a RepositoryObjectVersion object.
index | An integer index that identifies which property in the collection is to be addressed. The valid range is from one to the number of elements in the collection. The number of elements in the collection is specified by object.Properties.Count.


RepositoryObjectVersion Refresh Method

This method refreshes the cached image of the Repository object version. Only cached data that has not been changed by the current process is refreshed.

Syntax

Call object.Refresh( milliSecs )

The Refresh method syntax has the following parts.

Part | Description
object | An object expression that evaluates to a RepositoryObjectVersion object.
milliSecs | All unchanged data relating to the item that has been in the cache for longer than millisecs milliseconds is refreshed. Set this parameter to zero to refresh all unchanged data.


RepositoryObjectVersion Repository Property

The Repository property is the open Repository instance or workspace through which this Repository object was instantiated. This is a read-only property.

Syntax

Set variable = object.Repository

The Repository property syntax has the following parts.

Part | Description
variable | A variable declared as a reference to any object implementing the IRepository interface. Receives the object that represents the open Repository instance or the workspace.
object | An object expression that evaluates to a RepositoryObject object.

Remarks

The returned reference can refer to either a Repository object or a Workspace object. If it refers to a Workspace object, you are manipulating the item within the context of that workspace. If it refers to a Repository object, you are manipulating the item not within the context of a workspace, but within the context of a shared Repository instance.


RepositoryObjectVersion ResolutionType Property

This property indicates the resolution technique by which the Repository chose to give you a reference to the current version (rather than a reference to any other version of the same object). This is a read-only property.

Syntax

object.ResolutionType

The ResolutionType property syntax has the following parts.

Part | Description
object | An object expression that evaluates to a RepositoryObjectVersion object.

Remarks

The Repository automatically sets the value of the ResolutionType property whenever you retrieve an object version. There are four possible values:

  • VersionInWorkspace

  • PinnedVersion

  • LatestVersion

  • SpecifiedVersion


RepositoryObjectVersion SuccessorVersions Collection

A SuccessorVersions collection contains all of the RepositoryObjectVersion objects that are immediate successors of the current object version.

Syntax

Set variable = object.SuccessorVersions

The SuccessorVersions collection syntax has the following parts.

Part | Description
variable | A variable declared as a VersionCol object. Receives a reference to the SuccessorVersions collection.
object | An object expression that evaluates to a RepositoryObjectVersion object.

Remarks

This method returns only the immediate successors of the current object version.

If the current object version has no successors, this method returns an empty collection.

Within the returned collection, the Repository sequences the items in order of their creation, with the oldest object version first.

You cannot modify the collection. To enlarge an object's set of successor versions, use the CreateVersion method of the RepositoryObjectVersion object.


RepositoryObjectVersion Type Property

This property specifies the type of the Repository object version. More specifically, it is the object identifier of the object definition object for the Repository object. Type is a read-only property. To copy this property to another variable, use a variable declared as a Variant.

Syntax

object.Type

The Type property syntax has the following parts.

Part | Description
object | An object expression that evaluates to a RepositoryObjectVersion object.

Remarks

An object in the Repository is simultaneously a Repository object, an Automation object, and an object of a model-specific type, as defined by a tool information model.

The model-specific type of a Repository object is defined by its object definition. Each object definition is itself a Repository object, and consequently has an object identifier assigned to it. In other words, the value of an object definition object's ObjectID property is used as the value of the Type property for all Repository objects that conform to that object definition.


RepositoryObjectVersion VersionID Property

This property is the object-version identifier for the Repository object version. The object-version identifier is unique across all repositories. This is a read-only property. To copy this property to another variable, use a variable declared as a Variant.

Syntax

object.VersionID

The VersionID property syntax has the following parts.

Part | Description
object | An object expression that evaluates to a RepositoryObjectVersion object.

Remarks

This property yields the object-version identifier, not the object identifier.


RepositoryObjectVersion VersionInternalID Property

This property is the internal object-version identifier that the Repository engine uses to refer to this object. The internal object-version identifier is unique within the Repository, but not unique across repositories. This is a read-only property. To copy this property to another variable, use a variable declared as a Variant.

Syntax

object.VersionInternalID

The VersionInternalID property syntax has the following parts.

Part | Description
object | An object expression that evaluates to a RepositoryObjectVersion object.

Remarks

This property yields the internal object-version identifier, not the internal object identifier.


RepositoryObjectVersion Workspaces Collection

The Workspaces collection contains all of the workspaces in which the object version is present.

Syntax

Set variable = object.Workspaces

The Workspaces collection syntax has the following parts.

Part | Description
variable | A variable declared as a VersionCol object. Receives a reference to the WorkspacesOfVersion collection.
object | An object expression that evaluates to a RepositoryObjectVersion object.


RepositoryTransaction Object

The Repository supports the bracketing of multiple changes within the scope of a transaction. Changes to a Repository that are bracketed within a transaction are either all committed or all undone, depending upon the way that the transaction is completed. Repository methods that are reading data from the Repository may be executed outside of a transaction, but methods that write data must be bracketed within a transaction.

You cannot directly instantiate a RepositoryTransaction object. When you connect to a Repository, a RepositoryTransaction object is created for you. It is accessible via the Repository.Transaction property.

When to Use

Use the RepositoryTransaction object to manage Repository transactions.

Properties

Property | Description
Status | The transaction status of the Repository.

Methods

Method | Description
Abort | Cancels the current transaction.
Begin | Begins a new transaction.
Commit | Commits the current transaction.
Flush | Flushes uncommitted changes to the Repository database.
GetOption | Retrieves various transaction options.
SetOption | Sets various transaction options.

Remarks

Only one transaction may be active at a time for each opened Repository instance. Nesting of Begin/Commit method invocations is permitted, but no actual nesting of transactions occurs.


RepositoryTransaction Abort Method

This method cancels the currently active transaction for an open Repository. All updates made during the transaction are undone. The nested transaction count is set to zero.

Syntax

Call object.Abort

The Abort method syntax has the following parts.

Part | Description
object | The RepositoryTransaction object for the currently open Repository instance.


RepositoryTransaction Begin Method

This method increments the nested transaction count by one. If there is no active transaction, this method begins a transaction for the open Repository instance.

Syntax

Call object.Begin

The Begin method syntax has the following parts.

Part | Description
object | The RepositoryTransaction object for the currently open Repository instance.


RepositoryTransaction Commit Method

This method decrements the nested transaction count for an open Repository instance. If the currently active transaction is not nested, all changes made to Repository data within the transaction are committed to the Repository database. A transaction is not nested if the nested transaction count equals one.

Syntax

Call object.Commit

The Commit method syntax has the following parts.

Part | Description
object | The RepositoryTransaction object for the currently open Repository instance.


RepositoryTransaction Flush Method

This method flushes cached changes to the Repository database.

Unless you have set the exclusive-write-through-mode transaction option, changes that you make within the scope of a transaction are cached, and are not written to the database until the transaction is committed. If a concurrent SQL query is run against the Repository database, the result of the query will not reflect the uncommitted changes. (This is normally the desired behavior.)

If your Repository application must be able to see uncommitted changes in SQL queries, you can use the Flush method to write uncommitted changes to the Repository database. All changes made within the scope of the current transaction are flushed. Flushing uncommitted changes does not affect your ability to cancel a transaction via the Abort method.

Syntax

Call object.Flush

The Flush method syntax has these parts:

Part | Description
object | The RepositoryTransaction object for the currently open Repository instance.


RepositoryTransaction GetOption Method

This method is used to retrieve various transaction options. The transaction options are:

  1. Whether or not subsequent transactions will execute in nonexclusive write-back mode. Nonexclusive write-back mode allows transactions for other Repository instances to execute concurrently, and caches updates for this Repository instance until a transaction is committed.

  2. Whether or not subsequent transactions will execute in exclusive write-back mode. Exclusive write-back mode does not allow transactions for other Repository instances to execute concurrently, and caches updates for this Repository instance until a transaction is committed.

  3. Whether or not subsequent transactions will execute in exclusive write-through mode. Exclusive write-through mode does not allow transactions for other Repository instances to execute concurrently, and writes updates for this Repository instance to persistent storage as soon as possible.

  4. What the maximum time is that subsequent transactions will wait to obtain a lock.

  5. What the maximum time is that subsequent transactions will wait to begin a transaction

  6. What the maximum time is to wait for an executing query.

  7. Whether changes are allowed to be made to the Repository database.

The first three of these options are mutually exclusive; only one of them can be set at a time. The last option set is the option that is in effect. The fourth through the seventh options are independent of the first three, and each other.

Syntax

variable = object.GetOption( whichOption )

The GetOption property syntax has the following parts.

Part | Description
object | The RepositoryTransaction object for the currently open Repository instance.
whichOption | This parameter specifies which option is to be retrieved or set. For a list of valid values and their meanings, see the TransactionFlags Enumeration.
variable | A variable declared as a Variant. Receives the value of the specified option.


RepositoryTransaction SetOption Method

This method is used to set various transaction options. The transaction options are:

  1. Whether or not subsequent transactions will execute in nonexclusive write-back mode. Nonexclusive write-back mode allows transactions for other Repository instances to execute concurrently, and caches updates for this Repository instance until a transaction is committed.

  2. Whether or not subsequent transactions will execute in exclusive write-back mode. Exclusive write-back mode does not allow transactions for other Repository instances to execute concurrently, and caches updates for this Repository instance until a transaction is committed.

  3. Whether or not subsequent transactions will execute in exclusive write-through mode. Exclusive write-through mode does not allow transactions for other Repository instances to execute concurrently, and writes updates for this Repository instance to persistent storage as soon as possible.

  4. What the maximum time is that subsequent transactions will wait to obtain a lock.

  5. What the maximum time is that subsequent transactions will wait to begin a transaction.

  6. What the maximum time is to wait for an executing query.

The first three of these options are mutually exclusive; only one of them can be set at a time. The last option set is the option that is in effect. The fourth through sixth options are independent of the first three, and each other.

Syntax

Call object.SetOption( whichOption, optionValue )

The SetOption method syntax has the following parts.

Part | Description
object | The RepositoryTransaction object for the currently open Repository instance.
whichOption | This parameter specifies which option is to be retrieved or set. For a list of valid values and their meanings, see the TransactionFlags Enumeration.
optionValue | The new value for the option.


RepositoryTransaction Status Property

This property indicates what the current transaction status is for the Repository instance. If the value is zero, no transaction is active. If the value is nonzero, a transaction is active. This is a read-only property. To copy this property to another variable, use a variable that is declared as a Variant.

Syntax

object.Status

The Status property syntax has the following parts.

Part | Description
object | The RepositoryTransaction object for the currently open Repository instance.

Remarks

A transaction is considered active until the Commit method has successfully executed and the nested transaction count has been decremented to zero. Depending upon the data-flushing capabilities of the underlying database server, the data associated with a committed transaction may or may not be written to the physical storage device when the Commit method returns control to its caller.


ReposProperties Object

A Repository Properties collection is the set of persistent properties and collections that are attached to a Repository object or relationship via a particular interface.

When to Use

Use the ReposProperties object to enumerate the collection of Repository properties that are attached to a particular Repository object or relationship.

Properties

Property | Description
Count | The count of the number of items in the collection.
Item | Retrieves the specified property from the collection.
Type | Retrieves the type of the interface to which these properties are attached.


ReposProperties Count Property

A long integer that contains the count of the number of items in the collection. This is a read-only property.

Syntax

object.Count

The Count property syntax has the following parts.

Part | Description
object | The Repository property collection.


ReposProperties Item Property

Use Item to retrieve a Repository property from the collection. This is a read-only property. There are three variations of this property.

Syntax

Set variable = object.Item( index )
Set variable = object.Item( objName )
Set variable = object.Item( objId )

The Item property syntax has the following parts.

Part | Description
variable | An object expression that evaluates to a ReposProperty object; receives the specified Repository property.
object | The Repository property collection.
index | The index of the Repository property to be retrieved from the collection.
objName | The name associated with the Repository property to be retrieved from the collection.
ObjId | The object identifier of the property definition object for this property.


ReposProperties Type Property

Use Type to retrieve the object identifier for the interface definition of the interface to which these properties are attached. This object identifier is referred to as the type of the interface. This is a read-only property.

Syntax

Set variable = object.Type

The Type property syntax has these parts:

Part | Description
variable | A variant. Receives the object identifier for the interface definition.
object | The Repository property collection.


ReposProperty Object

A Repository property is a persistent property or collection that is attached to an object.

When to Use

Use the ReposProperty object to retrieve the name, type, or value of a Repository property, or to set the value of a Repository property.

Properties

Property | Description
Name | The name of the property.
Type | The type of the property.
Value | The value of the property.


ReposProperty Name Property

The name of the Repository property. This is a read-only property.

Syntax

object.Name

The Name property syntax has the following parts.

Part | Description
object | An object expression that evaluates to a ReposProperty object.


ReposProperty Type Property

The type of the Repository property; that is, the object identifier of the property definition object to which this Repository property conforms. This is a read-only property. Use a Variant variable to receive the Type property.

Syntax

object.Type

The Type property syntax has the following parts.

Part | Description
object | An object expression that evaluates to a ReposProperty object.


ReposProperty Value Property

The value of the Repository property. If you do not know the type of the property, use a Variant variable to receive this property value.

Syntax

object.Value
object.Value = newValue

The Value property syntax has the following parts.

Part | Description
object | An object expression that evaluates to a ReposProperty object.
newValue | An expression that evaluates to a value of the appropriate type for the Repository property.


Workspace Object

A workspace is a Repository object that can provide a context for your work separate from other work occurring in the Repository.

When to Use

Use the Workspace object to control the contents of a workspace.

Properties

Property | Description
CheckedOutToWorkspace | Always null, because a workspace cannot be contained in or checked out to another workspace.
IsCheckedOut | Always FALSE, because a workspace cannot be present in (or checked out to) another workspace.
IsFrozen | Always FALSE, because you cannot freeze a workspace.
Interface | The specified object interface.
InternalID | The internal object identifier of the workspace.
Name | The name of the workspace.
Object | Retrieves the specified Repository object.
ObjectID | The object identifier of the workspace.
PredecessorCreationVersion | Always null, because each workspace has only one version.
Repository | The open Repository instance through which this workspace was instantiated.
ResolutionType | Always LATEST_VERSION, because each workspace has only one version.
RootObject | The root Repository object of the currently open Repository.
Transaction | The transaction processing interface.
Type | An object identifier of the type to which this workspace conforms. The property is always the object identifier of the workspace definition object of the Type Information Model.
Version | Retrieves the specified object version.
VersionID | The object-version identifier of the workspace.
VersionInternalID | The internal object-version identifier of the workspace.

Methods

Method | Description
Checkin | Returns an error, because a workspace cannot be present in (or checked out to) another workspace.
Checkout | Returns an error, because a workspace cannot be present in (or checked out to) another workspace.
Create | Returns an error, because you cannot create a new Repository database from within a workspace.
CreateObject | Creates a new Repository object in the currently open Repository.
CreateVersion | Returns an error, because each workspace has only one version.
Delete | Deletes a workspace.
FreezeVersion | Returns an error, because you cannot freeze a workspace.
InternalIDToObjectID | Converts an internal identifier into an object identifier.
InternalIDToVersionID | Converts an internal object-version identifier into an object-version identifier.
Lock | Locks the workspace.
MergeVersion | Returns an error, because each workspace has only one version.
ObjectIDToInternalID | Converts an object identifier into an internal identifier.
Open | Returns an error, because you cannot open a new Repository database from within a workspace.
Refresh | Refreshes the cached image of a Repository.
Refresh (from IRepositoryObjectVersion) | Refreshes the cached image of the RepositoryObjectVersion representing the workspace.
VersionIDToInternalID | Converts an object-version identifier into an internal object-version identifier.

Collections

Collection | Description
Checkouts | The collection of object versions checked out to the workspace.
Containers | The collection of things that contain this workspace. The collection has only one item, the Root Object.
Contents | The collection of object versions present in the workspace.
ObjectVersions | The collection of all the versions of the Repository object representing the workspace. Always contains exactly one item, because you cannot invoke CreateVersion on a workspace.
PredecessorVersions | Always null, because you cannot invoke CreateVersion on a workspace.
Properties | The collection of all the properties that are attached to the workspace.
SuccessorVersions | Always null, because you cannot invoke CreateVersion on a workspace.
Workspaces | Always null, because a workspace cannot be contained in other workspaces.


Workspace Checkin Method

This method always returns an error, because a workspace cannot be present in (or checked out to) another workspace.

Remarks

This member is exposed by the IRepositoryObjectVersion interface, a non-default interface for this object. For details on how to access a member of an interface that is not the default interface, see Accessing Automation Object Members.


Workspace Checkout Method

This method always returns an error, because a workspace cannot be present in (or checked out to) another workspace.

Remarks

This member is exposed by the IRepositoryObjectVersion interface, a non-default interface for this object. For details on how to access a member of an interface that is not the default interface, see Accessing Automation Object Members.


Workspace CheckedOutToWorkspace Property

The property is always null, because a workspace cannot be present in (or checked out to) another workspace.

Remarks

This member is exposed by the IRepositoryObjectVersion interface, a non-default interface for this object. For details on how to access a member of an interface that is not the default interface, see Accessing Automation Object Members.


Workspace Checkouts Collection

A Checkouts collection contains all of the Repository object versions checked out to the workspace.

Syntax

Set variable = object.Checkouts( index )
Set variable = object.Checkouts( objectID )

The Checkouts collection syntax has the following parts.

Part | Description
variable | A variable declared as a RepositoryObjectVersion object. Receives the specified object version.
object | An object expression that evaluates to a Workspace object.
index | An integer index that identifies which item in the collection is to be addressed. The valid range is from one to the number of elements in the collection. The number of elements in the collection is specified by object.Checkouts.Count.
objectID | An object identifier of the an object version checked out to the workspace.


Workspace Containers Collection

This collection specifies the root object that contains this workspace.

Collection descriptor | Descriptor value
Relationship Type | WsContainer_Contains_Workspace
Source Is Origin | No
Minimum Collection Size | One
Maximum Collection Size | Many
Sequenced Collection | No
Deletes Propagated | No
Destinations Named | No
Case Sensitive Names | Not Applicable
Unique Names | Not Applicable

Syntax

Set variable = object.Containers( index )

The Containers collection syntax has the following parts.

Part | Description
variable | A variable declared as a ReposRoot object or as any object that supports the IWorkspaceContainer interface. Receives the Object containing the interface.
object | The object that represents a Workspace object.
index | An integer index that identifies which element in the collection is to be addressed. This value must be one, because in this release, the Root Object is the only object that implements the IWorkspaceContainer interface.

Remarks

Although the collection's maximum size is defined as many, the collection always contains exactly one object, because only the Root Object can contain workspaces and there is only one Root Object.


Workspace Contents Collection

A Contents collection contains all of the Repository object versions present in the workspace.

Syntax

Set variable = object.Contents( index )
Set variable = object.Contents( objectID )

The Contents collection syntax has the following parts.

Part | Description
variable | A variable declared as a RepositoryObjectVersion object. Receives the specified object version.
object | An object expression that evaluates to a Workspace object.
index | An integer index that identifies which item in the collection is to be addressed. The valid range is from one to the number of elements in the collection. The number of elements in the collection is specified by object.Contents.Count.
objectID | An object identifier of the an object version present in the workspace.


Workspace Create Method

When operating on a workspace, this method always fails. To create a new Repository database, use the Create method of the Repository object.


Workspace CreateObject Method

This method creates a new Repository object of the specified type.

Syntax

Set variable = object.CreateObject( typeId, objectId )

The CreateObject method syntax has the following parts.

Part | Description
variable | Declared as a RepositoryObject. Receives the new Repository object.
object | The object that represents the workspace through which this program is interacting with the Repository.
typeId | The type of the new object; that is, the object identifier of the object definition to which the new object conforms.
objectId | The object identifier to be assigned to the new object. Either pass in ObjID_NULL or do not supply this optional parameter to have the Repository assign an object identifier for you.

Remarks

This method creates a new object in the Repository, but it does not insert the newly created object into the workspace in whose context you are operating.


Workspace CreateVersion Method

This method always returns an error, because each workspace has only one version.

Remarks

This member is exposed by the IRepositoryObjectVersion interface, a non-default interface for this object. For details on how to access a member of an interface that is not the default interface, see Accessing Automation Object Members.


Workspace Delete Method

This method deletes the workspace from the Repository. Any relationships that connect the workspace to other objects are deleted. If the workspace is an origin object of a relationship collection, and the relationship type indicates that deletes are to be propagated, all of the destination objects are also deleted.

Syntax

Call object.Delete

The Delete method syntax has the following parts.

Part | Description
object | An object expression that evaluates to a Workspace object.

Remarks

This member is exposed by the IRepositoryObjectVersion interface, a non-default interface for this object. For details on how to access a member of an interface that is not the default interface, see Accessing Automation Object Members.


Workspace FreezeVersion Method

This method always returns an error, because you cannot freeze a workspace.

Remarks

This member is exposed by the IRepositoryObjectVersion interface, a non-default interface for this object. For details on how to access a member of an interface that is not the default interface, see Accessing Automation Object Members.


Workspace InternalIDToObjectID Method

This method translates an internal identifier into an object identifier. Internal identifiers are used by the Repository engine to identify Repository objects.

Syntax

variable = object.InternalIDToObjectID( internalId )

The InternalIDToObjectID method syntax has the following parts.

Part | Description
variable | Receives the object identifier.
object | The object that represents the workspace through which this program is interacting with the Repository.
internalId | The internal identifier to be converted.

Remarks

Repository object identifiers are globally unique, and are the same across repositories for the same object. Internal identifiers are unique only within the scope of a single Repository.

The translation performed by this method is performed without loading the object in question. This enables database queries involving an object or relationship type identifier to be constructed without having to load the definition object.


Workspace IsCheckedOut Property

The property is always FALSE because a workspace cannot be present in (or checked out to) another workspace.

Remarks

This member is exposed by the IRepositoryObjectVersion interface, a non-default interface for this object. For details on how to access a member of an interface that is not the default interface, see Accessing Automation Object Members.


Workspace IsFrozen Property

The property is always FALSE, because you cannot freeze a workspace.

Remarks

This member is exposed by the IRepositoryObjectVersion interface, a non-default interface for this object. For details on how to access a member of an interface that is not the default interface, see Accessing Automation Object Members.


Workspace Interface Property

Use this property to obtain a view of the Repository workspace that uses an alternate interface as the default interface. This is a read-only property. There are three variations of this property.

Syntax

Set variable = object.Interface( interfaceId )
Set variable = object.Interface( objectId )
Set variable = object.Interface( interfaceName )

The Interface property syntax has the following parts.

Part | Description
variable | An object variable. Receives the workspace with the specified interface as the default interface.
object | An object expression that evaluates to a Workspace object.
interfaceId | The interface identifier for the interface to be retrieved.
objectId | The object identifier for the interface definition to which the interface to be retrieved conforms.
InterfaceName | A string containing the name of the interface to be retrieved.

Remarks

This member is exposed by the IRepositoryObjectVersion interface, a non-default interface for this object. For details on how to access a member of an interface that is not the default interface, see Accessing Automation Object Members.


Workspace InternalID Property

This property is the internal identifier that the Repository engine uses to refer to this workspace. Each workspace has an internal identifier that is unique within the Repository, but not unique across repositories. This is a read-only property. To copy this property to another variable, use a variable declared as a Variant.

Syntax

object.InternalID

The InternalID property syntax has the following parts.

Part | Description
object | An object expression that evaluates to a Workspace object.

Remarks

This member is exposed by the IRepositoryObjectVersion interface, a non-default interface for this object. For details on how to access a member of an interface that is not the default interface, see Accessing Automation Object Members.


Workspace InternalIDToVersionID Method

This method translates an internal object-version identifier into an object-version identifier.

Syntax

variable = object.InternalIDToVersionID( internalVersionId )

The InternalIDToVersionID method syntax has the following parts.

Part | Description
variable | Receives the object-version identifier.
object | The object that represents the current workspace through which this program is interacting with the Repository.
internalVersionId | The internal object-version identifier to be converted.

Remarks

Repository object-version identifiers are globally unique, and are the same across repositories for the same object version. Internal object-version identifiers are unique only within the scope of a single Repository.

The translation performed by this method is performed without loading the object-version in question. This enables database queries involving an object or relationship type identifier to be constructed without having to load the definition object.

This member is exposed by the IRepositoryObjectVersion interface, a non-default interface for this object. For details on how to access a member of an interface that is not the default interface, see Accessing Automation Object Members.


Workspace Lock Method

Use this method to lock the workspace. Locking the workspace prevents other processes from locking the object describing the workspace while you are working with it. The lock is released when you end the current transaction.

Call object.Lock

The Lock method syntax has the following parts.

Part | Description
object | An object expression that evaluates to a Workspace object.

Remarks

This member is exposed by the IRepositoryObjectVersion interface, a non-default interface for this object. For details on how to access a member of an interface that is not the default interface, see Accessing Automation Object Members.


Workspace MergeVersion Method

This method always returns an error, because there is only one version of each workspace.

Remarks

This member is exposed by the IRepositoryObjectVersion interface, a non-default interface for this object. For details on how to access a member of an interface that is not the default interface, see Accessing Automation Object Members.


Workspace Name Property

A character string that contains the name of the workspace.

The name property is normally a property of the relationship for which this Repository object is the destination object. However, because the Workspace object exposes the INamedObject interface, the name retrieved is the value of the Name property exposed by this interface. When you set this property, the Repository sets the name property of the INamedObject interface and it sets the name associated with every naming relationship in which this workspace participates as the destination object.

Syntax

object.Name

The Name property syntax has the following parts.

Part | Description
object | An object expression that evaluates to a Workspace object.

Remarks

This member is exposed by the INamedObject interface, a non-default interface for this object. For details on how to access a member of an interface that is not the default interface, see Accessing Automation Object Members.

Besides the name property exposed by the INamedObject interface, each workspace can have other names because each workspace has a destination naming relationship to the Root object. When you retrieve a workspace's name, the Repository retrieves the value of the name as exposed by the INamedObject interface. When you set the name, the Repository tries to change some or all of the workspace's names. (See Changing an object version's name.)


Workspace Object Property

Repository Object Property

Use this property to retrieve a particular Repository object. This is a read-only property.

Syntax

Set variable = object.Object( objectId )

The Object property syntax has the following parts.

Part | Description
variable | Declared as a RepositoryObject. Receives the Repository object.
object | The object that represents the workspace through which this program is interacting with the Repository.
objectId | The object identifier for the Repository object to be retrieved.

Remarks

The Repository returns the specific version of the Repository object that is present in the workspace. If no version of the object is present in the workspace, this property returns an error.


Workspace ObjectID Property

This property is the object identifier for the workspace. Each workspace has an object identifier that is unique across all repositories. This is a read-only property. To copy this property to another variable, use a variable declared as a Variant.

Syntax

object.ObjectID

The ObjectID property syntax has the following parts.

Part | Description
object | An object expression that evaluates to a Workspace object.

Remarks

This member is exposed by the IRepositoryObjectVersion interface, a non-default interface for this object. For details on how to access a member of an interface that is not the default interface, see Accessing Automation Object Members.


Workspace ObjectIDToInternalID Method

This method translates an object identifier into an internal identifier. Internal identifiers are used by the Repository engine to identify Repository objects.

Syntax

variable = object.ObjectIDToInternalID( objectId )

The ObjectIDToInternalID method syntax has the following parts.

Part | Description
variable | Receives the internal identifier.
object | The object that represents the workspace through which this program is interacting with the Repository.
objectId | The object identifier to be converted.

Remarks

Repository object identifiers are globally unique, and are the same across repositories for the same object. Internal identifiers are unique only within the scope of a single Repository.

The translation performed by this method is performed without loading the object in question. This enables database queries involving an object or relationship type identifier to be constructed without having to load the definition object.


Workspace ObjectVersions Collection

The ObjectVersions collection contains all of the RepositoryObjectVersion objects that are versions of the same Repository object.

Syntax

Set variable = object.ObjectVersions

The ObjectVersions collection syntax has the following parts.

Part | Description
variable | A variable declared as a VersionCol object. Receives a reference to the Versions-of-Object collection.
object | An object expression that evaluates to a Workspace object.

Remarks

Remember that each Workspace object has exactly one version (because you cannot invoke the CreateVersion method on a workspace). Thus, this collection always contains exactly one item.


Workspace Open Method

When operating on a workspace, this method always fails. To open (connect to) a Repository, use the Open method of the Repository object.


Workspace PredecessorCreationVersion Property

The property is always null, because each workspace has only one version.

Remarks

This member is exposed by the IRepositoryObjectVersion interface, a non-default interface for this object. For details on how to access a member of an interface that is not the default interface, see Accessing Automation Object Members.


Workspace PredecessorVersions Collection

A PredecessorVersions collection contains all of the RepositoryObjectVersion objects that are immediate predecessors of the current object version.

Syntax

Set variable = object.PredecessorVersions

The PredecessorVersions collection syntax has the following parts.

Part | Description
variable | A variable declared as a VersionCol object. Receives a reference to the Predecessor-Versions collection.
object | An object expression that evaluates to a Workspace object.

Remarks

Remember that each Workspace object has exactly one version (because you cannot invoke the CreateVersion method on a workspace). Thus, this collection is always null.


Workspace Properties Collection

A Properties collection contains all of the persistent properties and collections that are attached to an object through a particular interface. The Workspace object exposes three separate Properties collections. These collections are exposed by:

  1. The IWorkspace interface (the default).

  2. The IRepositoryObjectVersion interface.

  3. The INamedObject interface.

Syntax

Set variable = object.Properties( index )

The Properties collection syntax has the following parts.

Part | Description
variable | A variable declared as a ReposProperty object. Receives the specified property.
object An object expression; evaluates to an object that exposes:
  • Iworkspace

  • IrepositoryObjectVersion

    -or-

  • InamedObject

as the default interface.
index | An integer index that identifies which property in the collection is to be addressed. The valid range is from one to the number of elements in the collection. The number of elements in the collection is specified by object.Properties.Count.

Remarks

For details on how to access a member of an interface that is not the default interface, see Accessing Automation Object Members.


Workspace Refresh Method

This method refreshes all of the cached data for the open Repository instance. Only cached data that has not been changed by the current process is refreshed.

Syntax

Call object.Refresh( milliSeconds )

The Refresh method syntax has the following parts.

Part | Description
object | The object that represents the workspace through which this program is interacting with the Repository.
milliSecs | All unchanged Repository data that has been in the cache for longer than millisecs milliseconds is refreshed. Set to zero to refresh all unchanged data for the Repository.

Remarks

Even though you are operating within the context of a workspace, this method refreshes all of the cached data for the open Repository instance – including cached data not present in the workspace.


Workspace Refresh (from IRepositoryObjectVersion) Method

This method refreshes the cached image of the Repository object describing the workspace. Only cached data that has not been changed by the current process is refreshed.

Syntax

Call object.Refresh( milliSecs )

The Refresh method syntax has the following parts.

Part | Description
object | An object expression that evaluates to a Workspace object.
milliSecs | All unchanged data relating to the workspace that has been in the cache for longer than millisecs milliseconds is refreshed. Set this parameter to zero to refresh all unchanged data.

Remarks

This member is exposed by the IRepositoryObjectVersion interface, a non-default interface for this object. For details on how to access a member of an interface that is not the default interface, see Accessing Automation Object Members.


Workspace Repository Property

The Repository property is the open Repository instance through which this workspace was instantiated. This is a read-only property.

Syntax

Set variable = object.Repository

The Repository property syntax has the following parts.

Part | Description
variable | A variable declared as an instance of the Repository class. Receives the object that represents the open Repository instance.
object | An object expression that evaluates to a Workspace object.

Remarks

This member is exposed by the IRepositoryObjectVersion interface, a non-default interface for this object. For details on how to access a member of an interface that is not the default interface, see Accessing Automation Object Members.


Workspace ResolutionType Property

The property is always LATEST_VERSION, because each workspace has only one version.

Remarks

This member is exposed by the IRepositoryObjectVersion interface, a non-default interface for this object. For details on how to access a member of an interface that is not the default interface, see Accessing Automation Object Members.


Workspace RootObject Property

This property is the root Repository object for the currently open Repository. This is a read-only property. The returned reference to the root object has the context of the current workspace.

Syntax

Set variable = object.RootObject

The RootObject property syntax has the following parts.

Part | Description
variable | A variable declared as a RepositoryObject. Receives the root Repository object.
object | The object that represents the workspace through which this program is interacting with the Repository.


Workspace SuccessorVersions Collection

A SuccessorVersions collection contains all of the RepositoryObjectVersion objects that are immediate predecessors of the current object version.

Syntax

Set variable = object.SuccessorVersions

The SuccessorVersions collection syntax has the following parts.

Part | Description
variable | A variable declared as a VersionCol object. Receives a reference to the Predecessor-Versions collection.
object | An object expression that evaluates to a Workspace object.

Remarks

Remember that each Workspace object has exactly one version (because you cannot invoke the CreateVersion method on a workspace). Thus, this collection is always null.


Workspace Transaction Property

This property is the RepositoryTransaction object for the open Repository instance. This is a read-only property.

Syntax

Set variable = object.Transaction

The Transaction property syntax has the following parts.

Part | Description
variable | A variable declared as an Object. Receives the RepositoryTransaction object for this Repository instance.
object | The object that represents the workspace through which this program is interacting with the Repository.

Remarks

You can gain access to the RepositoryTransaction object by using the syntax shown above. Then you can access the properties and methods of the RepositoryTransaction object by using the variable.method and variable.property syntax. You can also access the properties and methods of the RepositoryTransaction object directly, using syntax like:

Call object.Transaction.method

-or-

variable = object.Transaction.property

See the RepositoryTransaction object for details on the methods and properties that it provides.


Workspace Type Property

This property specifies the type of the workspace. More specifically, it is the object identifier of the workspace definition object of the type information model. Type is a read-only property. To copy this property to another variable, use a variable declared as a Variant.

Syntax

object.Type

The Type property syntax has the following parts.

Part | Description
object | An object expression that evaluates to a Workspace object.

Remarks

An object in the Repository is simultaneously a Repository object, an Automation object, and an object of a model-specific type, as defined by a tool information model.

The type information model defines a model-specific type called the Workspace type. The model-specific type of a Repository object is defined by its object definition. Each object definition is itself a Repository object, and consequently has an object identifier assigned to it. In other words, the value of an object-definition object's ObjectID property is used as the value of the Type property for all Repository objects that conform to that object definition.

This member is exposed by the IRepositoryObjectVersion interface, a non-default interface for this object. For details on how to access a member of an interface that is not the default interface, see Accessing Automation Object Members.


Workspace Version Property

Use this property to retrieve a particular Repository object version from the workspace. This is a read-only property.

Syntax

Set variable = object.Version( versionId )

The Version property syntax has the following parts.

Part | Description
variable | Declared as a RepositoryObjectVersion. Receives the Repository object version.
object | The object that represents the workspace through which this program is interacting with the Repository.
versionId | The object-version identifier for the Repository object to be retrieved.

Remarks

This member is exposed by the IRepository2 interface, a non-default interface for this object. For details on how to access a member of an interface that is not the default interface, see Accessing Automation Object Members.

This method returns an error if the requested version is not present in the workspace.


Workspace VersionID Property

This property is the object-version identifier for the workspace. Each workspace has an object-version identifier that is unique across all repositories. This is a read-only property. To copy this property to another variable, use a variable declared as a Variant.

Syntax

object.VersionID

The VersionID property syntax has the following parts.

Part | Description
object | An object expression that evaluates to a Workspace object.

Remarks

This member is exposed by the IRepositoryObjectVersion interface, a non-default interface for this object. For details on how to access a member of an interface that is not the default interface, see Accessing Automation Object Members.


Workspace VersionIDToInternalID Method

This method translates an object-version identifier into an internal object-version identifier. Internal object-version identifiers are used by the Repository engine to identify Repository object versions.

Syntax

variable = object.VersionIDToInternalID( versionId )

The VersionIDToInternalID method syntax has the following parts.

Part | Description
variable | Receives the internal identifier.
object | The object that represents the workspace through which this program is interacting with the Repository.
versionId | The object-version identifier to be converted.

Remarks

Repository object-version identifiers are globally unique, and are the same across repositories for the same object version. Internal object-version identifiers are unique only within the scope of a single Repository.

The translation performed by this method is performed without loading the object version in question. This enables database queries involving an object or relationship type identifier to be constructed without having to load the definition object.

This member is exposed by the IRepository2 interface, a non-default interface for this object. For details on how to access a member of an interface that is not the default interface, see Accessing Automation Object Members.


Workspace VersionInternalID Property

This property is the internal object-version identifier that the Repository engine uses to refer to this workspace. Each workspace has an internal object-version identifier that is unique within the Repository, but not unique across repositories. This is a read-only property. To copy this property to another variable, use a variable declared as a Variant.

Syntax

object.VersionInternalID

The VersionInternalID property syntax has the following parts.

Part | Description
object | An object expression that evaluates to a Workspace object.

Remarks

This member is exposed by the IRepositoryObjectVersion interface, a non-default interface for this object. For details on how to access a member of an interface that is not the default interface, see Accessing Automation Object Members.


Workspace Workspaces Collection

The collection is always empty, because a workspace has no other workspaces that contain it.

Remarks

This member is exposed by the IRepositoryObjectVersion interface, a non-default interface for this object. For details on how to access a member of an interface that is not the default interface, see Accessing Automation Object Members.


VersionCol Object

A version collection is a collection of object versions. There are several different version collections you can establish:

  • The set of all versions of an object. (See the Versions-of-Object collection.)

  • The predecessors of an object version. (See the Predecessor-Versions collection.)

  • The successors of an object version. (See the Successor-Versions collection.)

  • The set of versions of a particular target object that are related to a particular source object version. (See the Target-Versions collection.)

  • The set of object versions present in a workspace. (See the Versions-of-Workspace collection.)

  • The set of workspaces in which a particular item is present. (See the Workspaces-of-Version collection.)

  • The set of object versions checked out to a workspace. (See the Checkouts-of-Workspace collection.)

When to Use

Use the VersionCol object to manage the contents of a workspace, to manage the target object versions of a versioned relationship, to navigate an object's version graph, or to manipulate all the versions of a particular object.

Properties

Property | Description
Count | The count of the number of object versions in the collection.
Item | Retrieves the specified object version from the collection.

Methods

Method | Description
Add | Adds an object version to the collection.
Refresh | Refreshes the cached image of the collection.
Remove | Removes an object version from the collection.


VersionCol Add Method

This method is used to add a new item to a relationship collection, when the sequencing of relationships in the collection is not important. The new relationship connects the reposObj object version to the source object version of the collection. The new relationship is passed back to the caller.

Syntax

Set variable = object.Add( reposVersion )

The Add method syntax has the following parts.

Part | Description
variable | A variable declared as a RepositoryObjectVersion object. Receives the object version that is added to the collection.
object | The version collection.
reposVersion | The Repository object version to be added to the collection.

Remarks

There are many different kinds of object-version collections. You can apply this method to some of them, but not to others. This method works for:

  • Target-versions collections. You can use this method to enlarge the set of versions of a particular target object that are related to a particular source object.

  • Versions-of-Workspace collections. You can use this method to add an object version to the set of items contained in the workspace.

This method does not work for:

  • Predecessor-versions collection. To enlarge an object version's set of predecessors, use the MergeVersion method of the RepositoryObjectVersion object.

  • Successor-versions collection. To enlarge an object version's set of successors, use the CreateVersion method of the RepositoryObjectVersion object.

  • Versions-of-Object collection. To enlarge an object's set of versions, use the CreateVersion method of the RepositoryObjectVersion object.

  • Workspaces-of-version collection. To enlarge the set of workspaces to which an item belongs, you do not add a workspace to an object version — rather you add the object version to a workspace. In other words, you use the Add method of the VersionCol object but the version collection you are manipulating is the Versions-of-Workspace collection, not the Workspaces-of-Version collection.

  • Checkouts-of-workspace collection. To checkout another item to a workspace, use the Checkout method of the RepositoryObjectVersion object.


VersionCol Count Property

A long integer that contains the count of the number of items in the collection. This is a read-only property.

Syntax

object.Count

The Count property syntax has the following parts.

Part | Description
object | The version collection.


VersionCol Item Property

Use this property to retrieve an item from the collection. This is a read-only property. There are three variations of this property.

Syntax

Set variable = object.Item( index )
Set variable = object.Item( objectId )
Set variable = object.Item( objectVersionId )

The Item property syntax has the following parts.

Part | Description
variable | A variable declared as a RepositoryObjectVersion, or as any object that implements the IrepositoryObjectVersion interface. Receives the item.
object | The version collection.
index | The index of the item to be retrieved from the collection.
objectId | The object identifier for the object version or workspace to be retrieved from the collection. You can supply an objectID only for the Versions-of-Workspace collection, the Workspaces-of-Version collection, or the Checkouts-of-workspace collection.
objectVersionId | The object-version identifier for the item to be retrieved from the collection. You can supply an objectVersionID for any version collection.


VersionCol Refresh Method

This method refreshes the cached image of the version collection. Only cache data that has not been changed by the current process is refreshed.

Syntax

Call object.Refresh( milliSecs )

The Refresh method syntax has the following parts.

Part | Description
object | The version collection.
milliSecs | All unchanged data relating to the item that has been in the cache for longer than millisecs milliseconds is refreshed. Set to zero to refresh all unchanged data.


VersionCol Remove Method

This method deletes an object version from a version collection.

Syntax

Call object.Remove( index )
Call object.Remove( objectId )
Call object.Remove( objectVersionId )

The Remove method syntax has the following parts.

Part | Description
object | The version collection.
index | The index of the item to be removed from the collection.
objectID | The object identifier for the object version or workspace to be removed from the collection. You can supply an objectID only for the Versions-of-Workspace collection, the Workspaces-of-version collection, or the Checkouts-of-workspace collection.
objectVersionID | The object-version identifier for the item to be removed from the collection. You can supply an objectVersionID for any version collection.

Remarks

There are many different kinds of object-version collections. You can apply this method to some of them, but not to others. This method works for:

  • Target-versions collections. You can use this method to reduce the set of versions of a particular target object that are related to a particular source object.

  • Versions-of-Workspace collections. You can use this method to remove an object version from the set of items contained in the workspace.

This method fails for:

  • Predecessor-versions collections. To enlarge an object version's set of predecessors, use the MergeVersion method of the RepositoryObjectVersion object.

  • Successor-versions collections. To enlarge an object version's set of successors, use the CreateVersion method of the RepositoryObjectVersion object.

  • Versions-of-Object collections. To enlarge an object's set of versions, use the CreateVersion method of the RepositoryObjectVersion object.

  • Workspaces-of-Version collections. To remove a workspace from the set of workspaces in which an object version is present, you must explicitly remove the object version from that workspace's Versions-of-Workspace collection.

  • Checkouts-of-Workspace collections. To reduce the number of items checked out to a workspace, use the Checkin method of the RepositoryObjectVersion object.


VersionedRelationship Object

A relationship connects two Repository objects in the Repository database. A relationship has an origin Repository object, a destination Repository object, and a set of properties. Each relationship conforms to a particular relationship type.

When to Use

Use the Relationship object to manipulate the properties of a relationship, to delete a relationship, or to refresh the cached image of a relationship.

Properties

Property Description

Destination | The destination object of the relationship.
Interface | The specified object interface.
Name | The name of the relationship's destination object.
Origin | The origin object of the relationship.
Repository | The open Repository instance through which this relationship was instantiated.
Source | The source object of the relationship.
Target | The target object of the relationship.
Type | The type of the relationship.

Methods

Method Description

Delete | Deletes a relationship.
Lock | Locks the relationship.
Pin | Establishes a particular item in the TargetVersions collection as the pinned target version of the relationship.
Unpin | Ensures that no item in the TargetVersions collection is pinned.

Collections

Collection Description

Properties | The collection of all of the properties that are attached to the relationship.
TargetVersions | The collection of all versions of the target object that are related to the relationship's source object version.


VersionedRelationship Delete Method

This method deletes a relationship from its relationship collection.

Syntax

Call object.Delete

The Delete method syntax has the following parts.

Part | Description
object | An object expression that evaluates to a VersionedRelationship object.

Remarks

If the item to be deleted is an origin versioned relationship, this method fails unless the source object version is changeable. If the source object version is changeable, the Repository deletes the entire relationship (rather than merely removing one item from the relationship's TargetVersions collection). In other words, after this method finishes, no version of the destination object remains related to the origin object version. Then, if the relationship is a delete-propagating relationship, the Repository considers performing one or more propagated deletions. (See Propagation after removing an origin relationship.)

If the item to be deleted is a destination versioned relationship, the Repository performs object-version Resolution to yield a single origin object version from the relationship's TargetVersions collection. If that origin object version is unchangeable, this method fails. If that origin object version is changeable, the Repository removes it from the relationship's TargetVersions collection. Then, if the relationship is a delete-propagating relationship, the Repository considers performing one or more propagated deletions. (See Propagation after removing a delete-propagating destination relationship.)


VersionedRelationship Destination Property

This property is the destination object version for the relationship. This is a read-only property.

Syntax

Set variable = object.Destination

The Destination property syntax has the following parts.

Part | Description
variable | A variable declared as a RepositoryObjectVersion. Receives the destination object for the relationship.
object | An object expression that evaluates to a VersionedRelationship object.

Remarks

If the object is a destination versioned relationship, this property is equivalent to the VersionedRelationship Source Property. If the object is an origin versioned relationship, this property is equivalent to the VersionedRelationship Target Property.


VersionedRelationship Interface Property

Use this property to obtain a view of the VersionedRelationship object that uses an alternate interface as the default interface. This is a read-only property. There are three variations of this property.

Syntax

Set variable = object.Interface( interfaceId )
Set variable = object.Interface( objectId )
Set variable = object.Interface( interfaceName )

The Interface property syntax has the following parts.

Part | Description
variable | An object variable. Receives the relationship object with the specified interface as the default interface.
object | An object expression that evaluates to a VersionedRelationship object.
interfaceId | The interface identifier for the interface to be retrieved.
objectId | The object identifier for the interface definition to which the interface to be retrieved conforms.
interfaceName | A string containing the name of the interface to be retrieved.

Remarks

Because the VersionedRelationship class implements a limited set of interfaces, the input parameter you supply must specify one of the following interfaces: IVersionedRelationship, IRelationship, IRepositoryItem, IRepositoryDispatch, or IAnnotationalProperties.


VersionedRelationship Lock Method

Use this method to lock the Versioned Relationship. Locking the relationship prevents other processes from locking the relationship while you are working with it. The lock is released when you end the current transaction.

Call object.Lock

The Lock method syntax has the following parts.

Part | Description
object | An object expression that evaluates to a VersionedRelationship object.


VersionedRelationship Name Property

A character string that contains the name that the relationship assigns to the destination object.

Syntax

object.Name

The Name property syntax has the following parts.

Part | Description
object | An object expression that evaluates to a VersionedRelationship object.

Remarks

A relationship's name is the name by which the origin object version refers to every destination object version in its TargetVersions collection. When you access or set the Name property for an origin versioned relationship, it is this name that the Repository retrieves or sets for you. (See Changing an origin relationship's name.)

When you access or set the Name property for a destination versioned relationship, the Repository takes different action. (See Changing a destination relationship's name.)


VersionedRelationship Origin Property

This property is the origin object version of the relationship. This is a read-only property.

Syntax

Set variable = object.Origin

The Origin property syntax has the following parts.

Part | Description
variable | A variable declared as a RepositoryObjectVersion object. Receives the origin object version for the relationship.
object | An object expression that evaluates to a VersionedRelationship object.

Remarks

If the object is an origin versioned relationship, this property is equivalent to the VersionedRelationship Source Property. If the object is a destination versioned relationship, this property is equivalent to the VersionedRelationship Target Property.


VersionedRelationship Pin Method

Marks a particular version of the target object as the pinned version.

Syntax

Call object.Pin( objectVersion )

The Pin method syntax has the following parts.

Part | Description
object | An object expression that evaluates to a VersionedRelationship object.
objectVersion | The Repository object version to be pinned.

Remarks

The objectVersion you supply must be a member of the versioned relationship's TargetVersions collection.

Remember that no versioned relationship can have more than one pinned target object version. If the relationship already has a pinned target object version, it becomes unpinned when you call this method, and the objectVersion you supply becomes the pinned target object version.

If the relationship is a destination relationship, the Pin method fails.

If the origin of the relationship is unchangeable, the Pin method fails.


VersionedRelationship Repository Property

The Repository property is the open Repository instance or workspace through which this relationship was instantiated. This is a read-only property.

Syntax

Set variable = object.Repository

The Repository property syntax has the following parts:

Part | Description
variable | A variable declared as a reference to any object implementing the IRepository interface. Receives the object that represents the open Repository instance or the workspace.
object | An object expression that evaluates to a VersionedRelationship object.

Remarks

This method returns a reference to either a Repository object or a Workspace object. If it returns a Workspace object, you are manipulating the item within the context of that workspace. If it returns a Repository object, you are manipulating the item not within the context of a workspace, but within the context of a shared Repository instance.


VersionedRelationship Properties Collection

A Properties collection contains all of the persistent properties and collections that are attached to an object through a particular interface. The VersionedRelationship object exposes two separate Properties collections. These collections are exposed by:

  1. The IVersionedRelationship interface (the default).

  2. The IAnnotationalProps interface.

Syntax

Set variable = object.Properties( index )

The Properties collection syntax has the following parts.

Part | Description
variable | A variable declared as a ReposProperty object. Receives the specified property.
object An object expression; evaluates to an object that exposes:
  • IversionedRelationship

    -or-

  • IAnnotationalProps

as the default interface.
index | An integer index that identifies which property in the collection is to be addressed. The valid range is from one to the number of elements in the collection. The number of elements in the collection is specified by object.Properties.Count.

Remarks

For details on how to access a member of an interface that is not the default interface, see Accessing Automation Object Members.


VersionedRelationship Source Property

This property is the source object version of the relationship. This is a read-only property.

Syntax

Set variable = object.Source

The Source property syntax has the following parts.

Part | Description
variable | A variable declared as a RepositoryObjectVersion. Receives the source object version for the relationship.
object | An object expression that evaluates to a VersionedRelationship object.


VersionedRelationship Target Property

This property is the target object version of the relationship. This is a read-only property.

Syntax

Set variable = object.Target

The Target property syntax has the following parts.

Part | Description
variable | A variable declared as a RepositoryObjectVersion. Receives the target object version for the relationship.
object | An object expression that evaluates to a VersionedRelationship object.

Remarks

A versioned relationship can have a TargetVersions collection containing the set of object versions related (through the versioned relationship) to the source object version. The Repository performs its Resolution Strategy to return one of these object versions to you.


VersionedRelationship TargetVersions Collection

A TargetVersions collection contains all of the RepositoryObjectVersion objects that are related to the source object version via the versioned relationship.

Syntax

Set variable = object.TargetVersions

The Properties collection syntax has the following parts.

Part | Description
variable | A variable declared as a VersionCol object. Receives a reference to the TargetVersions collection.
object | An object expression that evaluates to a VersionedRelationship object.


VersionedRelationship Type Property

This property specifies the type of the versioned relationship. More specifically, it is the object identifier of the relationship definition object for the versioned relationship. Type is a read-only property. To copy this property to another variable, use a variable that is declared as a Variant.

Syntax

object.Type

The Type property syntax has the following parts.

Part | Description
object | An object expression that evaluates to a VersionedRelationship object.


VersionedRelationship Unpin Method

Ensures that the versioned relationship has no pinned version.

Syntax

Call object.Unpin

The Unpin method syntax has the following parts.

Part | Description
object | An object expression that evaluates to a Versioned Relationship object.

Remarks

If the relationship is a destination relationship, the Unpin method fails.

If the origin of the relationship is unchangeable, the Pin method fails.


ClassDef Object

The ClassDef object helps you create tool information models, by adding interfaces to a class. To insert a new class definition into a tool information model, use the ReposTypeLib object.

To complete a class definition, once you have added all of the interfaces, commit the transaction that brackets your class definition modifications.

A ClassDef object is also a RepositoryObject. In addition to the members described here, ClassDef objects also provide the members that are defined for Repository objects.

When to Use

Use the ClassDef object to:

  • Add a new or existing interface to a class definition.

  • Retrieve the global identifier for the class.

  • Access the collection of interfaces that are part of a class definition.

Properties

Property | Description
ClassID | The global identifier of the class.

Methods

Method | Description
AddInterface | Adds an existing interface to the class definition.
CreateInterfaceDef | Creates a new interface and adds it to the class definition.
ObjectInstances | Materializes an object collection containing all of the objects in the Repository that conform to this class.


ClassDef ClassID Property

This property contains the global identifier that is assigned to this class. If you copy this property to a variable, declare the variable as a Variant.

Syntax

object.ClassID

The ClassID property syntax has the following parts.

Part | Description
object | An object expression that evaluates to a ClassDef object.


ClassDef AddInterface Method

The AddInterface method adds an existing interface to the collection of interfaces that are implemented by a particular class.

Syntax

Call object.AddInterface( interfaceDef, flag )

The AddInterface method syntax has the following parts.

Part | Description
object | An object expression that evaluates to a ClassDef object
interfaceDef | The InterfaceDef definition object for the interface that is to be added to the collection of interfaces that are implemented by this class.
flag | If the interface that you are adding is the default interface for the class, pass in the string "Default". Otherwise, pass in a null string.


ClassDef CreateInterfaceDef Method

The CreateInterfaceDef method creates a new interface definition, and adds the interface to the collection of interfaces that are implemented by the class.

Syntax

Set variable = object.CreateInterfaceDef( sObjId, name, interfaceId, ancestor, flag )

The CreateInterfaceDef method syntax has the following parts.

Part | Description
variable | A variable declared as an InterfaceDef object. Receives the new interface definition.
object | An object expression that evaluates to a ClassDef object
sObjId | The object identifier to be assigned to the new interface definition object. If this parameter is set to OBJID_NULL, the Repository assigns an object identifier for you.
name | The name of the interface that is to be created
interfaceId | The interface identifier for this interface. If there is none, set this parameter to zero.
ancestor | The InterfaceDef definition object for the interface that is the base interface from which the interface being created is derived.
flag | If the interface that you are creating is the default interface for the class, pass in the string "Default". Otherwise, pass in a null string.


ClassDef ObjectInstances Method

This method materializes an object collection containing all of the objects in the Repository that conform to this class.

Syntax

Set variable = object.ObjectInstances

The ObjectInstances method syntax has the following parts.

Part | Description
variable | A variable declared as an ObjectCol object. Receives the collection of objects that conform to this class.
object | An object expression that evaluates to a ClassDef object.

Remarks

The collection contains one version of each object that conforms to the class. For each such object, the Repository uses its Resolution strategy to choose which version appears in the collection.


ClassDef Interfaces Collection

The collection of all interfaces that are implemented by this class.

Collection descriptor | Descriptor value
Relationship Typeremsc | Class-Implements-Interface
Source Is Originremsc | Yes
Minimum Collection Sizeremsc | Zero
Maximum Collection Sizeremsc | Many
Sequenced Collection | No
Deletes Propagated | No
Destinations Named | No
Case Sensitive Names | Not applicable
Unique Names | Not applicable

Syntax

Set variable = object.Interfaces( index )

The Interfaces collection syntax has the following parts.

Part | Description
variable | A variable declared as an InterfaceDef object. Receives the specified interface.
object | An object expression that evaluates to a ClassDef object.
index | An integer index that identifies which element in the collection is to be addressed. The valid range is from one to the number of elements in the collection. The number of elements in the collection is specified by object.Interfaces.Count.


ClassDef Properties Collection

A Properties collection contains all of the persistent properties and collections that are attached to an object through a particular interface. The ClassDef object exposes four separate Properties collections. These collections are exposed by:

  1. The IClassDef interface (the default).

  2. The IReposTypeInfo interface.

  3. The IRepositoryObject interface.

  4. The IAnnotationalProps interface.

Syntax

Set variable = object.Properties( index )

The Properties collection syntax has the following parts.

Part | Description
variable | A variable declared as a ReposProperty object. Receives the specified property.
object An object expression; evaluates to an object that exposes:
  • IclassDef

  • IreposTypeInfo

  • IrepositoryObject

    -or-

  • IannotationalProps

as the default interface.
index | An integer index that identifies which property in the collection is to be addressed. The valid range is from one to the number of elements in the collection. The number of elements in the collection is specified by object.Properties.Count.

Remarks

For details on how to access a member of an interface that is not the default interface, see Accessing Automation Object Members.


ClassDef ReposTypeLibScopes Collection

The collection of Repository type libraries that contain this definition.

Collection descriptor | Descriptor value
Relationship Type | ReposTypeLib-ScopeFor-ReposTypeInfo
Source Is Origin | No
Minimum Collection Size | One
Maximum Collection Size | Many
Sequenced Collection | No
Deletes Propagated | Yes
Destinations Named | Yes
Case Sensitive Names | No
Unique Names | Yes

Syntax

Set variable = object.ReposTypeLibScopes( index )

The ReposTypeLibScopes collection syntax has the following parts.

Part | Description
variable | A variable declared as a ReposTypeLib object. Receives the specified repository type library object.
object | An object expression that evaluates to a ClassDef object.
index | An integer index that identifies which element in the collection is to be addressed. The valid range is from one to the number of elements in the collection. The number of elements in the collection is specified by object.TypeLibScopes.Count.


CollectionDef Object

A collection type (also referred to as a collection definition) defines how instances of a particular type of collection will behave. The properties of the collection type determine:

  • The minimum and maximum number of items in a collection.

  • Whether or not the collection type is an origin collection type.

  • Whether or not the collection type permits the naming of destination objects, and if so, whether those names are case-sensitive, and required to be unique.

  • Whether or not the collection type permits the explicit sequencing of items in the collection.

  • What happens to related objects when objects or relationships in the collection are deleted.

  • Whether or not origin collections of this type are automatically copied to new object versions by the CreateVersion method.

  • Whether the MergeVersion method combines origin collections of this type as a whole, or item-by-item.

  • Whether the FreezeVersion method requires that destination object versions of relationships of this type be frozen before the attendant origin object versions can be frozen.

The kind of relationship that a particular collection type uses to relate objects to each other is determined by its CollectionItem collection. The CollectionItem collection associates a single relationship type to the collection type.

To add a new collection type, use the InterfaceDef object.

A CollectionDef object is also a RepositoryObject. In addition to the members described here, CollectionDef objects also provide the members that are defined for Repository objects.

When to Use

Use the CollectionDef object to retrieve or modify the properties of a collection type, to determine the kind of relationship that the collection implements, or to determine the interface to which the collection is attached.

Properties

Property | Description
DispatchID | The dispatch identifier to use when accessing an instance of this type of collection.
Flags | Flags that specify details about this collection definition.
IsOrigin | Indicates whether or not collections of this type are origin collections.
MaxCount | The maximum number of target objects that can be contained in a collection of this type.
MinCount | The minimum number of target objects that must be contained in a collection of this type.

Collections

Collection | Description
CollectionItem | The collection of one relationship type that defines the relationship between target objects of this type of collection and a single source object.
Interface | The interface to which this collection definition is attached.
Properties | The collection of all persistent properties that are attached to the CollectionDef object.


CollectionDef DispatchID Property

This property contains the dispatch identifier to use when accessing a collection of this type.

This property is not attached to the default interface for the CollectionDef Automation object; it is attached to the IInterfaceMember interface. For details on how to access a member of an interface that is not the default interface, see Accessing Automation Object Members

Syntax

object.DispatchID

The DispatchID property syntax has the following parts.

Part | Description
object | An object expression; evaluates to an object that exposes IinterfaceMember as the default interface.


CollectionDef Flags Property

The CollectionDef object exposes two separate Flags properties. One of these properties is exposed by the default interface, and the other is exposed by the IInterfaceMember interface. They are both described here.

The default Flags property determines:

  • Whether or not the collection type permits the naming of destination objects, and if so, whether those names are case-sensitive, and required to be unique.

  • Whether or not the collection type permits the explicit sequencing of items in the collection.

  • What happens to related objects when objects or relationships in the collection are deleted.

  • Whether or not origin collections of this type are automatically copied to new object versions by the CreateVersion method.

  • Whether the MergeVersion method combines origin collections of this type as a whole, or item by item.

  • Whether the FreezeVersion method requires that destination object versions of relationships of this type be frozen before the attendant origin object versions can be frozen.

See the CollectionDefFlags Enumeration for a list of values and their specific purposes.

The IInterfaceDef Flags property is a flag that specifies whether or not the interface member should be visible to Automation queries. (See the InterfaceMemberFlags Enumeration for a list of values and their specific purposes.)

Syntax

object.Flags

The Flags property syntax has the following parts.

Part | Description
object | An object expression that evaluates to a CollectionDef object, for the default Flags property -or- An object expression that evaluates to an object that exposes IinterfaceMember as the default interface, for the alternate Flags property.

Remarks

For details on how to access a member of an interface that is not the default interface, see Accessing Automation Object Members


CollectionDef IsOrigin Property

This property indicates whether or not collections of this type are origin collections. If you copy this property to a variable, declare the variable as a Boolean.

Syntax

object.IsOrigin

The IsOrigin property syntax has the following parts.

Part | Description
object | An object expression that evaluates to a CollectionDef object.


CollectionDef MaxCount Property

This property specifies the maximum number of target objects that can be contained in a collection of this type. This property is maintained for informational purposes, and is not enforced by the Repository engine.

Syntax

object.MaxCount

The MaxCount property syntax has the following parts.

Part | Description
object | An object expression that evaluates to a CollectionDef object.


CollectionDef MinCount Property

This property specifies the minimum number of target objects that must be contained in a collection of this type. This property is maintained for informational purposes, and is not enforced by the Repository engine.

Syntax

object.MinCount

The MinCount property syntax has the following parts.

Part | Description
object | An object expression that evaluates to a CollectionDef object.


CollectionDef CollectionItem Collection

The collection of one relationship type that defines the relationship between target objects of this type of collection and a single source object.

Collection descriptor | Descriptor value
Relationship Type | Collection-Contains-Items
Source Is Origin | Yes
Minimum Collection Size | Zero
Maximum Collection Size | One
Sequenced Collection | No
Deletes Propagated | No
Destinations Named | No
Case Sensitive Names | Not applicable
Unique Names | Not applicable

Syntax

Set variable = object.CollectionItem( index )

The CollectionItem collection syntax has the following parts.

Part | Description
variable | A variable declared as a RelationshipDef object. Receives the specified relationship definition object.
object | An object expression that evaluates to a CollectionDef object.
index | An integer index that identifies which element in the collection is to be addressed. The valid range is from one to the number of elements in the collection. The number of elements in the collection is specified by object.CollectionItem.Count.


CollectionDef Interface Collection

For a particular collection definition, the interface collection specifies which interface exposes a member of this type.

This collection is not attached to the default interface for the CollectionDef Automation object; it is attached to the IInterfaceMember interface. For details on how to access a member of an interface that is not the default interface, see Accessing Automation Object Members.

Collection descriptor | Descriptor value
Relationship Type | Interface-Has-Members
Source Is Origin | No
Minimum Collection Size | One
Maximum Collection Size | One
Sequenced Collection | Yes
Deletes Propagated | Yes
Destinations Named | Yes
Case Sensitive Names | No
Unique Names | Yes

Syntax

Set variable = object.Interface( index )

The Interface collection syntax has the following parts.

Part | Description
variable | A variable declared as an InterfaceDef object. Receives the specified interface definition.
object | An object expression; evaluates to an object that implements IinterfaceMember as the default interface.
index | An integer index that identifies which element in the collection is to be addressed. The valid range is from one to the number of elements in the collection. The number of elements in the collection is specified by object.Interface.Count.


CollectionDef Properties Collection

A Properties collection contains all of the persistent properties and collections that are attached to an object through a particular interface. The CollectionDef object exposes four separate Properties collections. These collections are exposed by:

  1. The ICollectionDef interface (the default).

  2. The IInterfaceMember interface.

  3. The IRepositoryObject interface.

  4. The IAnnotationalProps interface.

Syntax

Set variable = object.Properties( index )

The Properties collection syntax has the following parts.

Part | Description
variable | A variable declared as a ReposProperty object. Receives the specified property.
object An object expression; evaluates to an object that exposes:
  • IcollectionDef

  • IinterfaceMember

  • IrepositoryObject

    -or-

  • IannotationalProps

as the default interface.
index | An integer index that identifies which property in the collection is to be addressed. The valid range is from one to the number of elements in the collection. The number of elements in the collection is specified by object.Properties.Count

Remarks

For details on how to access a member of an interface that is not the default interface, see Accessing Automation Object Members.


InterfaceDef Object

The properties methods, and collections that a class implements are organized into functionally related groups. Each group is implemented as a Repository interface. The properties, methods, and collections of each interface are members of the interface. An interface definition is the template to which an interface conforms.

To add a new interface to the Repository, use the ClassDef object or the ReposTypeLib object.

An InterfaceDef object is also a RepositoryObject. In addition to the members described here, InterfaceDef objects also provide the members that are defined for Repository objects.

When to Use

Use the InterfaceDef class to:

  • Retrieve or modify properties of an interface definition.

  • Determine which members are attached to an interface definition.

  • Determine which classes implement an interface.

  • Determine the base interface from which an interface derives.

  • Determine what interfaces derive from a particular interface.

  • Determine what Repository objects expose a particular interface.

  • Add a new property, method, or collection type to an interface definition.

Properties

Property | Description
Flags | Flags that specify whether the interface is extensible, and whether the interface should be visible to Automation interface queries.
InterfaceID | The global interface identifier for the interface.
TableName | The name of the SQL table that is used to store instance information for the properties of the interface.

Methods

Method | Description
CreateMethodDef | Creates a new method definition, and attaches it to the interface definition.
CreatePropertyDef | Creates a new property definition, and attaches it to the interface definition.
CreateRelationshipColDef | Creates a relationship collection type. The collection type is attached to the interface definition.
ObjectInstances | Materializes an ObjectCol collection of all objects in the Repository that expose this interface.

Collections

Collection | Description
Ancestor | The collection of one base interface from which this interface derives.
Classes | The collection of classes that implement the interface.
Descendants | The collection of other interfaces that derive from this interface.
Members | The collection of members that are exposed by the interface.
ItemInCollections | This collection is empty for interface definitions.
Properties | The collection of all persistent properties that are attached to the InterfaceDef object.
ReposTypeLibScopes | The collection of all Repository type libraries that contain this definition.


InterfaceDef Flags Property

This property contains flags that specify whether the interface is extensible, and whether the interface should be visible to Automation interface queries. (See the InterfaceDefFlags Enumeration for a list of values and their specific purposes.)

Syntax

object.Flags

The Flags property syntax has the following parts.

Part | Description
object | An object expression that evaluates to an InterfaceDef object.


InterfaceDef InterfaceID Property

This property is the global interface identifier for the interface. If you copy this property to a variable, declare the variable as a Variant.

Syntax

object.InterfaceID

The InterfaceID property syntax has the following parts.

Part | Description
object | An object expression that evaluates to an InterfaceDef object.


InterfaceDef TableName Property

This character string property contains the name of the SQL table that is used to store instance information for the properties of the interface. The length of the name must be 30 characters or less.

Syntax

object.TableName

The TableName property syntax has the following parts.

Part | Description
object | An object expression that evaluates to an InterfaceDef object.


InterfaceDef CreateMethodDef Method

This method creates a new method definition and attaches it to the interface definition.

Syntax

Set variable = object.CreateMethodDef( sObjId, name, dispId )

The CreateMethodDef method syntax has the following parts.

Part | Description
object | An object expression that evaluates to an InterfaceDef object.
variable | A variable declared as a MethodDef object. Receives the new method definition.
sObjId | The object identifier to be used for the new method definition object. The Repository engine will assign an object identifier if you set this parameter to OBJID_NULL.
name | The name of the new method.
dispId | The dispatch identifier to be used for accessing the new method.


InterfaceDef CreatePropertyDef Method

This method creates a new property definition and attaches it to the interface definition.

Syntax

Set variable = object.CreatePropertyDef( sObjId, name, dispId, CType )

The CreatePropertyDef method syntax has the following parts.

Part | Description
object | An object expression that evaluates to an InterfaceDef object.
variable | A variable declared as a PropertyDef object. Receives the new property definition.
sObjId | The object identifier to be used for the new property definition object. The Repository engine will assign an object identifier if you set this parameter to OBJID_NULL.
name | The name of the new property.
dispId | The dispatch identifier to be used for accessing the new property.
CType | The C data type of the property. For a definition of valid values, see the ODBC Programmer's Reference.


InterfaceDef CreateRelationshipColDef Method

This method creates a new collection type, attaches it to this interface, and associates it with the specified relationship type.

Syntax

Set variable = object.CreateRelationshipColDef( sObjId, name, dispId, isOrigin, flags, relshipDef )

The CreateRelationshipColDef method syntax has the following parts.

Part | Description
object | An object expression that evaluates to an InterfaceDef object.
variable | A variable declared as a CollectionDef object. Receives the new collection definition.
sObjId | The object identifier for the collection type. The Repository engine will assign an object identifier if you set this parameter to OBJID_NULL.
name | The name of the new collection type.
dispId | The dispatch identifier to be used for Automation access to collections of this type.
isOrigin | Specifies whether collections of this type are origin collections. This is a Boolean parameter.
flags | Flags that specify naming, sequencing, and delete propagation behavior for the collection type. (See the CollectionDefFlags Enumeration for a list of values and their specific purposes.)
relshipDef | The relationship definition object to which this collection type is connected.

Remarks

By default, the collection definition specifies that zero to many items are permitted in collections of this type. To specify a different minimum and maximum item count for the new collection type, change the MinCount and MaxCount properties before committing the transaction that contains this method invocation.


InterfaceDef ObjectInstances Method

This method materializes an ObjectCol collection of all objects in the Repository that expose this interface.

Syntax

Set variable = object.ObjectInstances

The ObjectInstances method syntax has the following parts.

Part | Description
object | An object expression that evaluates to an InterfaceDef object.
variable | A variable declared as an ObjectCol object. Receives the collection of objects that expose this interface.

Remarks

The retrieved collection contains one version of each object that conforms to a class exposing this interface. For each such object, the Repository uses its Resolution strategy to choose which version appears in the collection.


InterfaceDef Ancestor Collection

This collection specifies the one base interface from which this interface derives.

Collection descriptor | Descriptor value
Relationship Type | Interface-InheritsFrom-Interface
Source Is Origin | Yes
Minimum Collection Size | One
Maximum Collection Size | One
Sequenced Collection | No
Deletes Propagated | No
Destinations Named | No
Case Sensitive Names | Not applicable
Unique Names | Not applicable

Syntax

Set variable = object.Ancestor( index )

The Ancestor collection syntax has the following parts.

Part | Description
variable | A variable declared as an InterfaceDef object. Receives the specified base interface definition.
object | An object expression that evaluates to an InterfaceDef object.
index | An integer index that identifies which element in the collection is to be addressed. The valid range is from one to the number of elements in the collection. The number of elements in the collection is specified by object.Ancestor.Count.


InterfaceDef Classes Collection

This collection specifies which classes implement the interface.

Collection descriptor | Descriptor value
Relationship Type | Class-Implements-Interface
Source Is Origin | No
Minimum Collection Size | Zero
Maximum Collection Size | Many
Sequenced Collection | No
Deletes Propagated | No
Destinations Named | No
Case Sensitive Names | Not Applicable
Unique Names | Not Applicable

Syntax

Set variable = object.Classes( index )

The Classes collection syntax has the following parts.

Part | Description
variable | A variable declared as a ClassDef object. Receives the specified class definition.
object | An object expression that evaluates to an InterfaceDef object.
index | An integer index that identifies which element in the collection is to be addressed. The valid range is from one to the number of elements in the collection. The number of elements in the collection is specified by object.Classes.Count.


InterfaceDef Descendants Collection

This collection specifies other interfaces that derive from this interface.

Collection descriptor | Descriptor value
Relationship Type | Interface-InheritsFrom-Interface
Source Is Origin | No
Minimum Collection Size | Zero
Maximum Collection Size | Many
Sequenced Collection | No
Deletes Propagated | No
Destinations Named | No
Case Sensitive Names | Not applicable
Unique Names | Not applicable

Syntax

Set variable = object.Descendants( index )

The Descendants collection syntax has the following parts.

Part | Description
variable | A variable declared as an InterfaceDef object. Receives the specified interface definition.
object | An object expression that evaluates to an InterfaceDef object.
index | An integer index that identifies which element in the collection is to be addressed. The valid range is from one to the number of elements in the collection. The number of elements in the collection is specified by object.Descendants.Count.


InterfaceDef Members Collection

This collection specifies which members are attached to the interface.

Collection descriptor | Descriptor value
Relationship Type | Interface-Has-Members
Source Is Origin | Yes
Minimum Collection Size | Zero
Maximum Collection Size | Many
Sequenced Collection | Yes
Deletes Propagated | Yes
Destinations Named | Yes
Case Sensitive Names | No
Unique Names | Yes

Syntax

Set variable = object.Members( index )

The Members collection syntax has the following parts.

Part | Description
variable | A variable declared as an object. Receives the specified property definition, method definition, or collection definition.
object | An object expression that evaluates to an InterfaceDef object.
index | An integer index that identifies which element in the collection is to be addressed. The valid range is from one to the number of elements in the collection. The number of elements in the collection is specified by object.Members.Count.


InterfaceDef Properties Collection

A Properties collection contains all of the persistent properties and collections that are attached to an object through a particular interface. The InterfaceDef object exposes four separate Properties collections. These collections are exposed by:

  1. The IInterfaceDef interface (the default).

  2. The IReposTypeInfo interface.

  3. The IRepositoryObject interface.

  4. The IAnnotationalProps interface.

Syntax

Set variable = object.Properties( index )

The Properties collection syntax has the following parts.

Part | Description
variable | A variable declared as a ReposProperty object. Receives the specified property.
object An object expression; evaluates to an object that exposes:
  • IinterfaceDef

  • IreposTypeInfo

  • IrepositoryObject

    -or-

  • IannotationalProps

as the default interface.
index | An integer index that identifies which property in the collection is to be addressed. The valid range is from one to the number of elements in the collection. The number of elements in the collection is specified by object.Properties.Count.

Remarks

For details on how to access a member of an interface that is not the default interface, see Accessing Automation Object Members.


InterfaceDef ReposTypeLibScopes Collection

The collection of Repository type libraries that contain this definition.

Collection descriptor | Descriptor value
Relationship Type | ReposTypeLib-ScopeFor-ReposTypeInfo
Source Is Origin | No
Minimum Collection Size | One
Maximum Collection Size | Many
Sequenced Collection | No
Deletes Propagated | Yes
Destinations Named | Yes
Case Sensitive Names | No
Unique Names | Yes

Syntax

Set variable = object.ReposTypeLibScopes( index )

The ReposTypeLibScopes collection syntax has the following parts.

Part | Description
variable | A variable declared as a ReposTypeLib object. Receives the specified Repository type library object.
object | An object expression that evaluates to an InterfaceDef object.
index | An integer index that identifies which element in the collection is to be addressed. The valid range is from one to the number of elements in the collection. The number of elements in the collection is specified by object.TypeLibScopes.Count.


MethodDef Object

When you define a class for a tool information model, you specify the interfaces that the class implements. For each of those interfaces, you specify the members (properties, methods, and collections) that are attached to the interface.

The definition of a method as a member of an interface does not result in the method's implementation logic being stored in the Repository. However, it does add the method name to the set of defined member names for that interface. It also reserves the method's dispatch identifier in the set of defined dispatch identifier values for the interface.

A method definition (a MethodDef object) is also a RepositoryObject. In addition to the members described here, MethodDef objects also provide the members that are defined for Repository objects.

To attach a new method to an interface, use the CreateMethodDef method of the InterfaceDef object.

When to Use

Use the MethodDef object to access or modify the characteristics of a method definition, or to determine the interface definition to which a particular method is attached.

Properties

Property | Description
DispatchID | The dispatch identifier to use when invoking a method that conforms to this method definition.
Flags | Flags that specify details about this method definition.

Collections

Collection | Description
Interface | The interface to which this method definition is attached.
Properties | The collection of all persistent properties that are attached to the MethodDef object.


MethodDef DispatchID Property

This property contains the dispatch identifier that is used to invoke a method that conforms to this method definition.

Syntax

object.DispatchID

The DispatchID property syntax has the following parts.

Part | Description
object | An object expression that evaluates to a MethodDef object.


MethodDef Flags Property

See Also;

This property is a flag that specifies whether or not the interface member should be visible to Automation queries. (See the InterfaceMemberFlags Enumeration for a list of values and their specific purposes.)

Syntax

object.Flags

The Flags property syntax has the following parts.

Part | Description
object | An object expression that evaluates to a MethodDef object.


MethodDef Interface Collection

For a particular method definition, the Interface collection specifies which interface exposes a member of this type.

Collection descriptor | Descriptor value
Relationship Type | Interface-Has-Members
Source Is Origin | No
Minimum Collection Size | One
Maximum Collection Size | One
Sequenced Collection | Yes
Deletes Propagated | Yes
Destinations Named | Yes
Case Sensitive Names | No
Unique Names | Yes

Syntax

Set variable = object.Interface( index )

The Interface collection syntax has the following parts.

Part | Description
variable | A variable declared as an InterfaceDef object. Receives the specified interface definition.
object | An object expression that evaluates to a MethodDef object.
index | An integer index that identifies which element in the collection is to be addressed. The valid range is from one to the number of elements in the collection. The number of elements in the collection is specified by object.Interface.Count.


MethodDef Properties Collection

See Also;

A Properties collection contains all of the persistent properties and collections that are attached to an object via a particular interface. The MethodDef object exposes three separate Properties collections. These collections are exposed by:

  1. The IInterfaceMember interface (the default).

  2. The IRepositoryObject interface.

  3. The IAnnotationalProps interface.

Syntax

Set variable = object.Properties( index )

The Properties collection syntax has the following parts.

Part | Description
variable | A variable declared as a ReposProperty object. Receives the specified property.
object An object expression; evaluates to an object that exposes:
  • IinterfaceMember

  • IrepositoryObject

    -or-

  • IannotationalProps

as the default interface.
index | An integer index that identifies which property in the collection is to be addressed. The valid range is from one to the number of elements in the collection. The number of elements in the collection is specified by object.Properties.Count.

Remarks

For details on how to access a member of an interface that is not the default interface, see Accessing Automation Object Members.


PropertyDef Object

When you define a class for a tool information model, you specify the interfaces that the class implements. For each of those interfaces, you specify the members (properties, methods, and collections) that are attached to the interface.

In order to attach a property to an interface, a property definition must exist for the property. The characteristics of the property (its name, dispatch identifier, data type, and various storage details) are stored in the property definition object. These characteristics are defined by the properties of the property definition object.

To create a new property definition:

  1. Use the CreatePropertyDef method of the InterfaceDef object.

  2. Define any non-default characteristics of your new property definition by manipulating the properties of the property definition object.

  3. Commit your changes to the Repository database.

A PropertyDef object is also a RepositoryObject. In addition to the members described here, PropertyDef objects also provide the members that are defined for Repository objects.

When to Use

Use the PropertyDef object to retrieve or modify the characteristics of a property definition, or to determine which interface exposes a particular property.

Properties

Property | Description
APIType | The C data type of the property.
ColumnName | The name of the column in the SQL table for this property.
DispatchID | The dispatch identifier to use when accessing an instance of this type of property.
Flags | Flags that specify details about this property definition.
SQLScale | The number of digits to the right of the decimal point for a numeric property.
SQLSize | The size in bytes of the property.
SQLType | The SQL data type of the property.

Collections

Collection | Description
Interface | The interface to which this property definition is attached.
Properties | The collection of all persistent properties that are attached to the PropertyDef object.


PropertyDef APIType Property

The C data type of the property. For a definition of valid values, see the ODBC Programmer's Reference.

Syntax

object.APIType

The APIType property syntax has the following parts.

Part | Description
object | An object expression that evaluates to a PropertyDef object.


PropertyDef ColumnName Property

An SQL table is used to store instance information for the properties of an interface. By default, there is a column in this table for each property that is defined as a member of the interface. The ColumnName string property specifies the name of the column in the SQL table for the property definition. The length of the column name must be 30 bytes or less.

Syntax

object.ColumnName

The ColumnName property syntax has the following parts.

Part | Description
object | An object expression that evaluates to a PropertyDef object.


PropertyDef DispatchID Property

See Also;

This property contains the dispatch identifier to use when accessing an instance of this type of member.

This property is not attached to the default interface for the PropertyDef Automation object; it is attached to the IInterfaceMember interface. For details on how to access a member of an interface that is not the default interface, see Accessing Automation Object Members.

Syntax

object.DispatchID

The DispatchID property syntax has the following parts.

Part | Description
object | An object expression; evaluates to an object that exposes IInterfaceMember as the default interface.


PropertyDef Flags Property

The PropertyDef object exposes two separate Flags properties. One of these properties is exposed by the default interface, and the other is exposed by the IInterfaceMember interface. They are both described here.

  1. The default Flags property. A flag that specifies whether or not a column is created in the SQL table for the interface to which this property is attached. If no column is created, instances of this property are only attached to individual objects, when the property value is set for that particular object. By default, a column is created for each property. (See the PropertyDefFlags Enumeration for the symbolic and numeric values of this flag.)

  2. The IInterfaceDef Flags property. A flag that specifies whether or not the interface member should be visible to Automation queries. (See the InterfaceMemberFlags Enumeration for a list of values and their specific purposes.)

Syntax

object.Flags

The Flags property syntax has the following parts.

Part | Description
object | An object expression that evaluates to a PropertyDef object, for the default Flags property, -or- An object expression that evaluates to an object that exposes IinterfaceMember as the default interface, for the alternate Flags property.

Remarks

For details on how to access a member of an interface that is not the default interface, see Accessing Automation Object Members.


PropertyDef SQLScale Property

The number of digits to the right of the decimal point for a numeric property. This parameter is ignored unless the SQLType property specifies an SQL_NUMERIC, SQL_DECIMAL, or SQL_TIME data type.

Syntax

object.SQLScale

The SQLScale property syntax has the following parts.

Part | Description
object | An object expression that evaluates to a PropertyDef object.


PropertyDef SQLSize Property

The size in bytes of the property. This parameter is ignored when the data type of the property inherently specifies the size of the property.

Syntax

object.SQLSize

The SQLSize property syntax has the following parts.

Part | Description
object | An object expression that evaluates to a PropertyDef object.


PropertyDef SQLType Property

The SQL data type of the property. For a definition of valid values, see the ODBC Programmer's Reference.

Syntax

object.SQLType

The SQLType property syntax has the following parts.

Part | Description
object | An object expression that evaluates to a PropertyDef object.


PropertyDef Interface Collection

For a particular property definition, the Interface collection specifies which interface exposes a member of this type.

This collection is not attached to the default interface for the PropertyDef Automation object; it is attached to the IInterfaceMember interface. For details on how to access a member of an interface that is not the default interface, see Accessing Automation Object Members.

Collection descriptor | Descriptor value
Relationship Type | Interface-Has-Members
Source Is Origin | No
Minimum Collection Size | One
Maximum Collection Size | One
Sequenced Collection | Yes
Deletes Propagated | Yes
Destinations Named | Yes
Case Sensitive Names | No
Unique Names | Yes

Syntax

Set variable = object.Interface( index )

The Interface collection syntax has the following parts.

Part | Description
variable | A variable declared as an InterfaceDef object. Receives the specified interface definition.
object | An object expression; evaluates to an object that implements IInterfaceMember as the default interface.
index | An integer index that identifies which element in the collection is to be addressed. The valid range is from one to the number of elements in the collection. The number of elements in the collection is specified by object.Interface.Count.


PropertyDef Properties Collection

A Properties collection contains all of the persistent properties and collections that are attached to an object via a particular interface. The PropertyDef object exposes four separate Properties collections. These collections are exposed by:

  1. The IPropertyDef interface (the default).

  2. The IRepositoryObject interface.

  3. The IInterfaceMember interface.

  4. The IAnnotationalProps interface.

Syntax

Set variable = object.Properties( index )

The Properties collection syntax has the following parts.

Part | Description
variable | A variable declared as a ReposProperty object. Receives the specified property.
object An object expression; evaluates to an object that exposes:
  • IpropertyDef

  • IrepositoryObject

  • IinterfaceMember

    -or-

  • IannotationalProps

as the default interface.
index | An integer index that identifies which property in the collection is to be addressed. The valid range is from one to the number of elements in the collection. The number of elements in the collection is specified by object.Properties.Count.

Remarks

For details on how to access a member of an interface that is not the default interface, see Accessing Automation Object Members.


RelationshipDef Object

When you define a tool information model in the Repository, you define classes of objects, types of relationships that can exist between objects, and various properties that are attached to these object classes and relationship types. The relationship types that you define in your tool information model are represented by instances of the RelationshipDef class.

To add a new relationship type (also referred to as a relationship definition) to a tool information model, use the CreateRelationshipDef method of the ReposTypeLib object.

A RelationshipDef object is also a RepositoryObject. In addition to the members described here, RelationshipDef objects also provide the members that are defined for Repository objects.

When to Use

Use the RelationshipDef object to:

  • Access any persistent properties that are attached to a relationship definition.

  • Determine which collection types are associated with a relationship definition.

  • Determine which Repository type libraries contain a relationship definition.

Properties

Property | Description
ClassID | This property is reserved for future use.

Collections

Collection | Description
Interfaces | This collection is empty for relationship definitions. It is reserved for future use.
ItemInCollections | The collection of two collection types that are associated with this relationship definition.
Properties | The collection of all persistent properties that are attached to the RelationshipDef object.
ReposTypeLibScopes | The collection of all Repository type libraries that contain this definition.


RelationshipDef ItemInCollections Collection

A relationship type is associated with two collection types. Origin collections conform to one collection type (the origin collection type), and destination collections conform to the other collection type (the destination collection type). The ItemInCollections collection contains the two collection definition objects that represent the origin and destination collection types.

Collection descriptor | Descriptor value
Relationship Type | Collection-Contains-Items
Source Is Origin | No
Minimum Collection Size | Zero
Maximum Collection Size | Two
Sequenced Collection | No
Deletes Propagated | No
Destinations Named | No
Case Sensitive Names | Not applicable
Unique Names | Not applicable

Syntax

Set variable = object.ItemInCollections( index )

The ItemInCollections collection syntax has the following parts.

Part | Description
variable | A variable declared as a CollectionDef object. Receives the specified collection definition.
object | An object expression that evaluates to a RelationshipDef object.
index | An integer index that identifies which element in the collection is to be addressed. The valid range is from one to the number of elements in the collection. The number of elements in the collection is specified by object.ItemInCollections.Count.

Remarks

If the relationship type has not yet been connected to its origin and destination collection types, this collection can contain less than two collection types.


RelationshipDef Properties Collection

A Properties collection contains all of the persistent properties and collections that are attached to an object through a particular interface. The RelationshipDef object exposes three separate Properties collections. These collections are exposed by:

  1. The IReposTypeInfo interface (the default).

  2. The IRepositoryObject interface.

  3. The IAnnotationalProps interface.

Syntax

Set variable = object.Properties( index )

The Properties collection syntax has the following parts.

Part | Description
variable | A variable declared as a ReposProperty object. Receives the specified property.
object An object expression; evaluates to an object that exposes:
  • IreposTypeInfo

  • IrepositoryObject

    -or-

  • IannotationalProps

as the default interface.
index | An integer index that identifies which property in the collection is to be addressed. The valid range is from one to the number of elements in the collection. The number of elements in the collection is specified by object.Properties.Count.

Remarks

For details on how to access a member of an interface that is not the default interface, see Accessing Automation Object Members.


RelationshipDef ReposTypeLibScopes Collection

The collection of Repository type libraries that contain this definition.

Collection descriptor | Descriptor value
Relationship Type | ReposTypeLib-ScopeFor-ReposTypeInfo
Source Is Origin | No
Minimum Collection Size | One
Maximum Collection Size | Many
Sequenced Collection | No
Deletes Propagated | Yes
Destinations Named | Yes
Case Sensitive Names | No
Unique Names | Yes

Syntax

Set variable = object.ReposTypeLibScopes( index )

The ReposTypeLibScopes collection syntax has the following parts.

Part | Description
variable | A variable declared as a ReposTypeLib object. Receives the specified Repository type library object.
object | An object expression that evaluates to a RelationshipDef object.
index | An integer index that identifies which element in the collection is to be addressed. The valid range is from one to the number of elements in the collection. The number of elements in the collection is specified by object.TypeLibScopes.Count.


ReposRoot Object

There is one root object in each Repository. The root object is the starting point for navigating to other objects in the Repository. The root object serves as the starting point for both type and instance data navigations.

  • Type data navigation

    When you create a tool information model, the corresponding Repository type library is attached to the root object through the ReposTypeLibs collection. This collection can be used to enumerate all of the tool information models (type data) that are contained in the Repository.

  • Instance data navigation

    Once a tool information model is defined, the Repository can be populated with instance data. This instance data consists of objects and relationships that conform to the classes and relationship types of the tool information model.

    Because the objects are connected through relationships, you can navigate through this data. However, to enable general purpose Repository browsers to navigate this data, the first navigational step must be from the root object of the Repository through a root relationship collection to the primary objects of your tool information model. Primary objects are objects that make a good starting point for navigating to other objects of your tool information model.

    Because this root relationship collection is different for each tool information model, it must be defined by the tool information model. There are two options for attaching this relationship collection to the root object:

    1. The ReposRoot class implements the IReposRoot interface. This interface is provided to tool information model creators as a connection point. You can add your connecting relationship collection to this interface.

    2. You can extend the ReposRoot class to implement a new interface that is defined in your tool information model. This interface implements a relationship collection that attaches the root object to the primary objects in your tool information model.

To facilitate navigation, the root object in all repositories always has the same object identifier. The symbolic name for this object identifier is OBJID_ReposRootObj.

A ReposRoot object is also a RepositoryObject. In addition to the members described here, ReposRoot objects also provide the members that are defined for Repository objects.

When to Use

Use the ReposRoot object to:

  • Obtain a starting point for navigating to objects in the Repository.

  • Create a new tool information model.

  • Attach a relationship collection to the root object of the Repository that connects to the primary objects of your tool information model.

  • Determine what tool information models are currently stored in the Repository.

Methods

Method | Description
CreateTypeLib | Creates a Repository type library for a new tool information model.

Collections

Collection | Description
ReposTypeLibs | The collection of Repository type libraries that are currently stored in the Repository.
Properties | The collection of all persistent properties that are attached to the ReposRoot object.
Workspaces | The collection of all workspaces present in the Repository.


ReposRoot CreateTypeLib Method

This method creates a new Repository type library and attaches it to the root of the Repository. Each Repository type library represents a tool information model.

Syntax

Set variable = object.CreateTypeLib( sObjId, Name, TypeLibId )

The CreateTypeLib method syntax has the following parts.

Part | Description
variable | A variable declared as a ReposTypeLib object. Receives the new Repository type library.
object | An object expression that evaluates to a ReposRoot object.
sObjId | The object identifier to be used for the new Repository type library object. The Repository engine will assign an object identifier if you set this parameter to OBJID_NULL.
Name | The name of the new Repository type library.
TypeLibId | The global identifier by which this Repository type library is referenced.

Remarks

This method does not create an external type library; it creates a ReposTypeLib object in the Repository database.


ReposRoot ReposTypeLibs Collection

The collection of Repository type libraries that are currently stored in the Repository. Each Repository type library represents a tool information model.

Collection descriptor | Descriptor value
Relationship Type | TlbManager-ContextFor-ReposTypeLibs
Source Is Origin | Yes
Minimum Collection Size | Zero
Maximum Collection Size | Many
Sequenced Collection | No
Deletes Propagated | Yes
Destinations Named | Yes
Case Sensitive Names | No
Unique Names | Yes

Syntax

Set variable = object.ReposTypeLibs( index )

The ReposTypeLibs collection syntax has the following parts.

Part | Description
variable | A variable declared as a ReposTypeLib object. Receives the specified Repository type library.
object | An object expression that evaluates to a ReposRoot object.
index | An integer index that identifies which element in the collection is to be addressed. The valid range is from one to the number of elements in the collection. The number of elements in the collection is specified by object.ReposTypeLibs.Count.


ReposRoot Properties Collection

A Properties collection contains all of the persistent properties and collections that are attached to an object through a particular interface. The ReposRoot object exposes four separate Properties collections. These collections are exposed by:

  1. The IManageReposTypeLib interface (the default).

  2. The IReposRoot interface.

  3. The IRepositoryObject interface.

  4. The IAnnotationalProps interface.

Syntax

Set variable = object.Properties( index )

The Properties collection syntax has the following parts.

Part | Description
variable | A variable declared as a ReposProperty object. Receives the specified property.
object An object expression; evaluates to an object that exposes:
  • ImanageReposTypeLib

  • IreposRoot

  • IrepositoryObject

    -or-

  • IannotationalProps

as the default interface.
index | An integer index that identifies which property in the collection is to be addressed. The valid range is from one to the number of elements in the collection. The number of elements in the collection is specified by object.Properties.Count.

Remarks

For details on how to access a member of an interface that is not the default interface, see Accessing Automation Object Members.


ReposRoot Workspaces Collection

The collection of Repository type libraries that are currently stored in the Repository. Each Repository type library represents a tool information model.

Collection descriptor | Descriptor value
Relationship Type | WsContainer_Contains_Workspaces
Source Is Origin | Yes
Minimum Collection Size | Zero
Maximum Collection Size | Many
Sequenced Collection ???
Deletes Propagated ???
Destinations Named ???
Case Sensitive Names ???
Unique Names ???

Syntax

Set variable = object.Workspaces( index )

The Workspaces collection syntax has the following parts.

Part | Description
variable | A variable declared as a Workspace object. Receives the specified item in the collection.
object | An object expression that evaluates to a ReposRoot object.
index | An integer index that identifies which element in the collection is to be addressed. The valid range is from one to the number of elements in the collection. The number of elements in the collection is specified by object.Workspaces.Count.


ReposTypeLib Object

There is one Repository type library for every tool information model contained in the Repository database. Each tool information model provides a logical grouping of all of the type definitions related to a particular tool (or tool set). Repository type libraries are represented by ReposTypeLib objects.

A ReposTypeLib object is also a RepositoryObject. In addition to the members described here, ReposTypeLib objects also provide the members that are defined for Repository objects.

To insert a new tool information model into the Repository database, use the ReposRoot object.

When to Use

Use a ReposTypeLib object to:

  • Define new classes, relationship types, and interfaces for a tool information model.

  • Retrieve or modify the global identifier associated with a Repository type library.

  • Determine which type definitions are associated with a particular Repository type library.

Properties

Property | Description
TypeLibID | The global identifier for the Repository type library.

Methods

Method | Description
CreateClassDef | Creates a new class definition object.
CreateInterfaceDef | Creates a new interface definition object.
CreateRelationshipDef | Creates a new relationship definition object.

Collections

Collection | Description
ReposTypeInfos | The collection of all classes, interfaces, and relationship types that are defined in the Repository type library.
ReposTypeLibContexts | The collection of one Repository root object that is the context for the Repository type library.
Properties | The collection of all persistent properties that are attached to the ReposTypeLib object.


ReposTypeLib TypeLibID Property

This property is the global identifier for the Repository type library. If you copy this property to a variable, declare the variable as a Variant.

Syntax

object.TypeLibID

The TypeLibID property syntax has the following parts.

Part | Description
object | An object expression that evaluates to a ReposTypeLib object.


ReposTypeLib CreateClassDef Method

This method creates a new class definition object. No interfaces are attached to the class.

Syntax

Set variable = object.CreateClassDef( sObjId, Name, sClsId )

The CreateClassDef method syntax has the following parts.

Part | Description
variable | A variable declared as a ClassDef object. Receives the new class definition.
object | An object expression that evaluates to a ReposTypeLib object.
sObjId | The object identifier to be used for the new class definition object. The Repository engine will assign an object identifier if you set this parameter to OBJID_NULL.
Name | The name of the new class.
sClsId | The global identifier by which this class is referenced.


ReposTypeLib CreateInterfaceDef Method

The CreateInterfaceDef method creates a new interface definition object. Use the AddInterface method of the ClassDef object to attach the interface to a class definition object.

Syntax

Set variable = object.CreateInterfaceDef( sObjId, Name, sIId, Ancestor )

The CreateInterfaceDef method syntax has the following parts.

Part | Description
variable | A variable declared as an InterfaceDef object. Receives the new interface definition.
object | An object expression that evaluates to a ReposTypeLib object.
sObjId | The object identifier to be assigned to the new interface definition object. If this parameter is set to OBJID_NULL, the Repository assigns an object identifier for you.
Name | The name of the interface that is to be created.
sIId | The interface identifier associated with the signature for this interface. If there is none, set this parameter to zero.
Ancestor | The base interface from which the new interface is derived.


ReposTypeLib CreateRelationshipDef Method

This method creates a relationship definition object for a new relationship type. Once the relationship definition is created, use the CreateRelationshipColDef method of the InterfaceDef object to create origin and destination collection definitions for the new relationship type.

Syntax

Set variable = object.CreateRelationshipDef( sObjId, Name )

The CreateRelationshipDef method syntax has the following parts.

Part | Description
variable | A variable declared as a RelationshipDef object. Receives the new relationship definition.
object | An object expression that evaluates to a ReposTypeLib object.
sObjId | The object identifier for the new relationship type. The Repository engine will assign an object identifier if you set this parameter to OBJID_NULL.
Name | The name of the new relationship type.


ReposTypeLib ReposTypeInfos Collection

The collection of all classes, interfaces, and relationship types that are associated with a Repository type library. The Repository engine uses this collection to enforce the unique naming of all classes, interfaces, and relationship types for a Repository type library.

Collection descriptor | Descriptor value
Relationship Type | ReposTypeLib-ScopeFor-ReposTypeInfo
Source Is Origin | Yes
Minimum Collection Size | Zero
Maximum Collection Size | Many
Sequenced Collection | No
Deletes Propagated | Yes
Destinations Named | Yes
Case Sensitive Names | No
Unique Names | Yes

Syntax

Set variable = object.ReposTypeInfos( index )

The ReposTypeInfos collection syntax has the following parts.

Part | Description
variable | A variable declared as an Object. Receives the specified class definition, interface definition, or relationship definition.
object | An object expression that evaluates to a ReposTypeLib object.
index | An integer index that identifies which element in the collection is to be addressed. The valid range is from one to the number of elements in the collection. The number of elements in the collection is specified by object.ReposTypeInfos.Count.


ReposTypeLib ReposTypeLibContexts Collection

The collection of one Repository root that is the context for a Repository type library.

Collection descriptor | Descriptor value
Relationship Type | TlbManager-ContextFor-ReposTypeLibs
Source Is Origin | No
Minimum Collection Size | One
Maximum Collection Size | Many
Sequenced Collection | No
Deletes Propagated | Yes
Destinations Named | Yes
Case Sensitive Names | No
Unique Names | Yes

Syntax

Set variable = object.ReposTypeLibContexts( index )

The ReposTypeLibContexts collection syntax has the following parts.

Part | Description
variable | A variable declared as a ReposRoot object. Receives the Repository root object.
object | An object expression that evaluates to a ReposTypeLib object.
index | An integer index that identifies which element in the collection is to be addressed. The valid range is from one to the number of elements in the collection. The number of elements in the collection is specified by object.ReposTypeLibContexts.Count.


ReposTypeLib Properties Collection

A Properties collection contains all of the persistent properties and collections that are attached to an object through a particular interface. The ReposTypeLib object exposes three separate Properties collections. These collections are exposed by:

  1. The IReposTypeLib interface (the default).

  2. The IRepositoryObject interface.

  3. The IAnnotationalProps interface.

Syntax

Set variable = object.Properties( index )

The Properties collection syntax has the following parts.

Part | Description
variable | A variable declared as a ReposProperty object. Receives the specified property.
object An object expression; evaluates to an object that exposes:
  • IreposTypeLib

  • IrepositoryObject

    -or-

  • IannotationalProps

as the default interface.
index | An integer index that identifies which property in the collection is to be addressed. The valid range is from one to the number of elements in the collection. The number of elements in the collection is specified by object.Properties.Count.

Remarks

For details on how to access a member of an interface that is not the default interface, see Accessing Automation Object Members.


Repository Engine Classes

Repository engine classes are used to add, retrieve, and change tool information model data in the Repository. To create a new tool information model, or extend an existing one, use the Type Information Model classes.

All Repository classes expose the standard IUnknown and IDispatch interfaces that provide fundamental COM and Automation support.

Classes

  • ObjectCol

  • Relationship

  • RelationshipCol

  • Repository

  • RepositoryObject

  • RepositoryObjectVersion

  • ReposProperties

  • ReposProperty

  • VersionCol

  • VersionedRelationship


ObjectCol Class

An object collection is a set of Repository objects that can be enumerated. Two kinds of object collections are supported by the Repository:

  1. The collection of destination objects that correspond to the relationships in a relationship collection. Use the RelationshipCol class to manage this kind of collection.

  2. The collection of all objects in the Repository that implement a particular interface. Use the ObjectCol class to enumerate objects in this kind of object collection.

Use the IInterfaceDef::ObjectInstances method to materialize an instance of this class.

When to Use

Use the ObjectCol class to access the collection of Repository objects that expose a particular interface.

Interfaces

Interface | Description
IobjectCol | Manages objects in a collection.


Relationship Class

A relationship connects two Repository objects in the Repository database. In this release of the Microsoft Repository, relationships are versioned. That is, every relationship is a VersionedRelationship object. A versioned relationship can connect a particular version of a Repository object to one or more specific versions of the target object. Because every relationship is a VersionedRelationship object, you can declare any relationship with the following line of Visual Basic®:

Dim myRship   As VersionedRelationship

In earlier releases of the Repository, the object model included the Relationship class, but not the VersionedRelationship class. If you have Visual Basic programs written against earlier releases of the Microsoft Repository, those programs might include declarations like the following:

Dim oldRship   As Relationship

These programs will still work, because the Repository’s object model still includes the Relationship class. Visual Basic still recognizes preceding the declaration as valid. But remember that in this release of Microsoft Repository, every relationship is a versioned relationship. So the object oldRship, even though it is declared as a Relationship, must conform to the VersionedRelationship class.

To ensure that objects declared as Relationships conform to the VersionedRelationship class, the Repository uses the same Class Factory for both classes. In this way, any object that you declare as a Relationship implements the exact same methods as any object you declare as a VersionedRelationship. In effect, the following two lines of Visual Basic code are identical:

Dim myRship   As Relationship
Dim myRship   As VersionedRelationship


RelationshipCol Class

A relationship collection is the set of Repository relationships that connect a particular source Repository object to a set of one or more target objects. All of the relationships in the collection must conform to the same relationship type.

When to Use

Use the RelationshipCol class to manage a collection of relationships in the Repository database.

Interfaces

Interface | Description
IObjectCol | Manages objects in a collection.
IRelationshipCol | Manages a collection of relationships.
ITargetObjectCol | Manages objects in a target object collection.


RepositoryObjectVersion Class

An object version is an individual rendition of a Repository object. Each object version consists of a state that can be permanently fixed (protected from further modification) plus another, always modifiable aspect. The state of an object version consists of its non-annotational property values and its origin collections. The other, always modifiable aspect of an object version consists of its annotational properties and its destination collections.

When to Use

Use the RepositoryObjectVersion class to manipulate a particular version of a Repository object.

Interfaces

Interface | Description
IrepositoryDispatch | Provides enhanced dispatch support.
IrepositoryItem | Manages Repository objects and relationships.
IrepositoryObject | Retrieves Repository object identifiers.
IrepositoryObjectStorage | Creates and loads Repository objects.
IrepositoryObjectVersion | Manages Repository object versions.
IworkspaceItem | Manages the participate of object versions in workspaces.


VersionCol Class

A version collection is a collection of object versions.

When to Use

Use the VersionCol class to manage a collection of object versions.

Interfaces

Interface | Description
IVersionCol | Manages object versions in a collection.


Repository Class

When you populate a tool information model, the objects and relationships that conform to the model are stored in a Repository. Multiple tool information models may be stored in the same Repository. The Repository class represents your connection to a particular Repository.

When to Use

You can use the Repository class to connect to a Repository, retrieve the root object of the Repository, create new Repository objects, and manage Repository transactions and error handling.

Interfaces

Interface | Description
Irepository | Creates and populates a Repository.
IRepository2 | Manages individual versions of Repository objects.
IrepositoryErrorQueueHandler | Creates and assigns error queues.
IRepositoryODBC | Provides access to Repository database connection information.
IrepositoryTransaction | Controls Repository transactions.


RepositoryObject Class

A Repository object is an object that is stored in the Repository database and is managed by the Repository engine.

In this release of the Microsoft Repository, objects can be versioned. A Repository object version is a particular rendition of a Repository object. Each version of an object can differ from other versions of that object in its property values and collections. When you obtain a reference to a Repository object you actually are manipulating a particular version of that object. That is, you manipulate a RepositoryObjectVersion object. Because you manipulate particular versions of objects, you can declare any object with the following line of Visual Basic code:

Dim newReposObject   As RepositoryObjectVersion

In earlier releases of the Repository, the object model included the RepositoryObject class, but not the RepositoryObjectVersion class. If you have Visual Basic programs written against earlier releases of the Microsoft Repository, those programs might include declarations like the following:

Dim oldReposObject   As RepositoryObject

These programs will still work, because the Repository’s object model still includes the RepositoryObject object. Visual Basic still recognizes preceding declaration as valid. But remember, whenever you manipulate an object, you actually manipulate a specific version of that object. So the object oldReposObject, even though it is declared as a RepositoryObject, must conform to the RepositoryObjectVersion class.

To ensure that objects declared as RepositoryObject conform to the RepositoryobjectVersion class, the Repository uses the same Class Factory for both classes. In this way, any object that you declare as a Relationship implements the exact same methods as any object you declare as a VersionedRelationship. In effect, the following two lines of Visual Basic code are identical:

Dim myReposObject   As RepositoryObjectVersion
Dim myReposObject   As RepositoryObject


ReposProperties Class

The ReposProperties class provides access to the Properties collection. The Properties collection gives you a convenient mechanism to enumerate through all of the persistent properties and collections of an interface. The ReposProperty class can be used to access the individual members in the Properties collection.

When to Use

Use the ReposProperties class to access the properties and collections of a Repository object, when no custom implementation is available, and you do not already know what members are exposed by the object's interface.

Interfaces

Interface | Description
IreposProperties | Provides access to the members that are attached to an interface.


ReposProperty Class

The ReposProperty class provides access to a persistent member (a property or collection) of a tool information model interface.

When to Use

Use the ReposProperty class to access a persistent interface member, when no custom implementation is available, and you do not already know the type or name of the member.

Interfaces

Interface | Description
IReposProperty | Provides access to the members that are attached to an interface.


VersionedRelationship Class

A relationship connects two Repository objects in the Repository database. In this release of the Microsoft Repository, relationships are versioned. That is, every relationship is a VersionedRelationship object. A versioned relationship can connect a particular version of a Repository object to one or more specific versions of the target object.

When to Use

Use the VersionedRelationship class to manipulate a relationship, or to retrieve the source, target, origin, or destination object for a relationship.

Interfaces

Interface | Description
IAnnotationalProps | Gets and sets annotational properties.
IRelationship | Retrieves information about a relationship.
IRepositoryDispatch | Provides enhanced dispatch support.
IRepositoryItem | Manages Repository objects and relationships.
IVersionedRelationship | Manages the TargetVersions collection of a versioned relationship.


Type Information Model Classes

The Type Information Model is the object model the Repository uses to store tool information models. Use the Type Information Model classes to create or extend a tool information model. These classes build upon the fundamental Repository Engine Classes.

All Repository classes expose the standard IUnknown and IDispatch interfaces that provide fundamental COM and Automation support.

Classes

  • ClassDef

  • CollectionDef

  • InterfaceDef

  • MethodDef

  • PropertyDef

  • RelationshipDef

  • ReposRoot

  • ReposTypeLib

  • Workspace


ClassDef Class

When you define a tool information model in the Repository, you define classes of objects, types of relationships that can exist between objects, and various properties that are attached to these object classes and relationship types. The object classes that you define in your tool information model are represented by instances of the ClassDef class.

To insert a new class definition into a tool information model, use the ReposTypeLib class.

When to Use

Use the ClassDef class to complete the definition of a new Repository class. You can define new interfaces and attach them to the class definition. You can also attach existing interfaces to the class definition.

Interfaces

Interface | Description
IAnnotationalProps | Gets and sets annotational properties.
IClassDef | Manages class definitions.
IRepositoryDispatch | Provides enhanced dispatch support.
IRepositoryItem | Manages Repository objects and relationships.
IRepositoryObject | Retrieves Repository object identifiers.
IRepositoryObjectStorage | Creates and loads Repository objects.
IReposTypeInfo | Contains the collection of definition objects that are associated with a tool information model's Repository type library.


CollectionDef Class

Repository objects are related to each other via relationships. The set of relationships, all of the same type, that relate one object to zero or more other objects, is a relationship collection.

A collection type (also referred to as a collection definition) defines how instances of a particular collection type will behave. The characteristics of the collection type determine:

  • The minimum and maximum number of items in a collection.

  • Whether or not the collection type is an origin collection type.

  • Whether or not the collection type permits the naming of destination objects, and if so, whether those names are case sensitive, and required to be unique.

  • Whether or not the collection type permits the explicit sequencing of items in the collection.

  • What happens to related objects when objects or relationships in the collection are deleted.

  • The kind of relationship that a particular collection type uses to relate objects to each other.

A collection is attached to an interface as a member of the interface. To add a new collection type to an interface definition, use the InterfaceDef class.

When to Use

Use the CollectionDef class to retrieve or modify the properties of a collection type, or to determine the kind of relationship that the collection implements.

Interfaces

Interface | Description
IAnnotationalProps | Gets and sets annotational properties.
ICollectionDef | Manages collection definitions.
IInterfaceMember | Relates a member to an interface.
IRepositoryDispatch | Provides enhanced dispatch support.
IRepositoryItem | Manages Repository objects and relationships.
IRepositoryObject | Retrieves Repository object identifiers.
IRepositoryObjectStorage | Creates and loads Repository objects.


InterfaceDef Class

The properties, methods, and collections that a class implements are organized into functionally related groups. Each group is implemented as a COM interface. The properties, methods, and collections of each interface are members of the interface. An interface definition is the template to which an interface conforms. Interface definitions are instances of the InterfaceDef class.

To create a new interface definition, use the ClassDef class or the ReposTypeLib class.

When to Use

Use the InterfaceDef class to:

  • Retrieve or modify properties of an interface definition.

  • Determine which members are attached to an interface definition.

  • Determine which classes implement an interface.

  • Determine the base interface from which an interface derives.

  • Determine what interfaces derive from a particular interface.

  • Determine what Repository objects expose a particular interface.

  • Add a new property, method, or collection type to an interface definition.

Interfaces

Interface | Description
IannotationalProps | Gets and sets annotational properties.
IinterfaceDef | Manages interface definitions.
IRepositoryDispatch | Provides enhanced dispatch support.
IRepositoryItem | Manages Repository objects and relationships.
IRepositoryObject | Retrieves Repository object identifiers.
IRepositoryObjectStorage | Creates and loads Repository objects.
IReposTypeInfo | Contains the collection of definition objects that are associated with a tool information model's Repository type library.


MethodDef Class

When you define a class for a tool information model, you specify the interfaces that the class implements. For each of those interfaces, you specify the members (properties, methods, and collections) that are attached to the interface.

The definition of a method as a member of an interface does not result in the method's implementation logic being stored in the Repository. However, it does add the method name to the set of defined member names for that interface. It also reserves the method's dispatch identifier in the set of defined dispatch identifier values for the interface.

Instances of the MethodDef class represent method definitions.

To attach a new method to an interface, use the InterfaceDef class.

When to Use

Use the MethodDef class to access or modify the characteristics of a method definition, or to determine the interface definition to which a particular method is attached.

Interfaces

Interface | Description
IAnnotationalProps | Gets and sets annotational properties.
IInterfaceMember | Relates a member to an interface.
IRepositoryDispatch | Provides enhanced dispatch support.
IRepositoryItem | Manages Repository objects and relationships.
IRepositoryObject | Retrieves Repository object identifiers.
IRepositoryObjectStorage | Creates and loads Repository objects.


PropertyDef Class

When you define a class for a tool information model, you specify the interfaces that the class implements. For each of those interfaces, you specify the members (properties, methods, and collections) that are attached to the interface.

In order to attach a property to an interface, a property definition must exist for the property. The characteristics of the property (it's name, dispatch identifier, data type, and various storage details) are stored in the property definition. Property definitions are instances of the PropertyDef class.

To attach a new property to an interface, use the InterfaceDef class.

When to Use

Use the PropertyDef class to access or modify the characteristics of a property definition, or to determine the interface definition to which a particular property is attached.

Interfaces

Interface | Description
IannotationalProps | Gets and sets annotational properties.
IinterfaceMember | Relates a member to an interface.
IpropertyDef | Retains property characteristics.
IrepositoryDispatch | Provides enhanced dispatch support.
IrepositoryItem | Manages Repository objects and relationships.
IrepositoryObject | Retrieves Repository object identifiers.
IrepositoryObjectStorage | Creates and loads Repository objects.


RelationshipDef Class

When you define a tool information model in the Repository, you define classes of objects, types of relationships that can exist between objects, and various properties that are attached to these object classes and relationship types. The relationship types that you define in your tool information model are represented by instances of the RelationshipDef class.

When to Use

Use the RelationshipDef Class to access the properties of a relationship definition (also referred to as a relationship type).

To insert a new relationship type into a tool information model, use the ReposTypeLib class.

Interfaces

Interface | Description
IannotationalProps | Gets and sets annotational properties.
IclassDef | Manages class definitions.
IrepositoryDispatch | Provides enhanced dispatch support.
IrepositoryItem | Manages Repository objects and relationships.
IrepositoryObject | Retrieves Repository object identifiers.
IrepositoryObjectStorage | Creates and loads Repository objects.
IreposTypeInfo | Contains the collection of definition objects that are associated with a tool information model's Repository type library.


ReposRoot Class

There is one Root object in each Repository. The Root object is the starting point for navigating to other objects in the Repository. The Root object serves as the starting point for both type and instance data navigations.

  • Type data navigation

    When you create a tool information model, the corresponding Repository type library is attached to the Root object through the ReposTypeLibs collection. This collection can be used to enumerate all of the tool information models (type data) that are contained in the Repository.

  • Instance data navigation

    Once a tool information model is defined, the Repository can be populated with instance data. This instance data consists of objects and relationships that conform to the classes and relationship types of the tool information model.

    Because the objects are connected via relationships, you can navigate through this data. However, to enable general purpose Repository browsers to navigate this data, the first navigational step must be from the Root object of the Repository through a root relationship collection to the primary objects of your tool information model. Primary objects are objects that make a good starting point for navigating to other objects of your tool information model.

    Because this root relationship collection is different for each tool information model, it must be defined by the tool information model. There are two options for attaching this relationship collection to the Root object:

    1. The ReposRoot class implements the IReposRoot interface. This interface is provided to tool information model creators as a connection point. You can add your connecting relationship collection to this interface.

    2. You can extend the ReposRoot class to implement a new interface that is defined in your tool information model. This interface implements a relationship collection that attaches the Root object to the primary objects in your tool information model.

To facilitate navigation, the Root object in all repositories always has the same object identifier. The symbolic name for this object identifier is OBJID_ReposRootObj.

When to Use

Use the ReposRoot class to:

  • Obtain a starting point for navigating to objects in the Repository.

  • Create a new tool information model.

  • Attach a relationship collection to the Root object of the Repository that connects to the primary objects of your tool information model.

Interfaces

Interface | Description
IAnnotationalProps | Gets and sets annotational properties.
IManageReposTypeLib | Adds tool information models (Repository type libraries) to a Repository.
IRepositoryDispatch | Provides enhanced dispatch support.
IRepositoryItem | Manages Repository objects and relationships.
IRepositoryObject | Retrieves Repository object identifiers.
IRepositoryObjectStorage | Creates and loads Repository objects.
IReposRoot | Provides an attachment point for tool information model instance data.
IWorkspaceContainer | Manages the set of workspaces in a Repository.


ReposTypeLib Class

There is one Repository type library for every tool information model contained in the Repository database. Each tool information model provides a logical grouping of all of the type definitions related to a particular tool (or tool set). Repository type libraries are instances of the ReposTypeLib class.

To insert a new tool information model into the Repository database, use the ReposRoot class.

When to Use

Use the ReposTypeLib class to:

  • Define new classes, relationship types, and interfaces for a tool information model.

  • Retrieve or modify the global identifier associated with a Repository type library.

  • Determine which type definitions are associated with a particular Repository type library.

Interfaces

Interface | Description
IAnnotationalProps | Gets and sets annotational properties.
IRepositoryDispatch | Provides enhanced dispatch support.
IRepositoryItem | Manages Repository objects and relationships.
IRepositoryObject | Retrieves Repository object identifiers.
IRepositoryObjectStorage | Creates and loads Repository objects.
IReposTypeLib | Creates class, interface, and relationship definitions for a Repository type library.


Workspace Class

A workspace is a secluded area of the Repository within which you can operate on tool data in isolation from other Repository activity.

To insert a new workspace into the Repository database, use any class that implements the IWorkspaceContainer interface. The ReposRoot class is one such class.

When to Use

Use the Workspace class to perform any operation you would perform within the Repository, when you want to perform the operation in isolation from other Repository activity.

Interfaces

Interface | Description
INamedObject | Manages object names.
IRepository | Creates and populates a Repository.
IRepository2 | Creates and manages subsequent versions of Repository objects.
IRepositoryDispatch | Provides enhanced dispatch support.
IRepositoryItem | Manages Repository objects and relationships.
IRepositoryObject | Retrieves Repository object identifiers.
IRepositoryObjectVersion | Manages individual versions of objects, and the relationships among individual versions of the same object.
IWorkspace | Manages workspaces.
IWorkspaceItem | Manages the participation of object versions in workspaces.


IAnnotationalProps Interface

Annotational properties are Repository properties that can be associated with individual Repository objects or relationships. When a normal property is defined as a member of a Repository interface, it is defined for all objects that implement that interface. Normal properties cannot be associated with Repository relationships.

In order to be able to attach an annotational property value to a particular Repository object, two requirements must be met:

  1. The object must conform to an object class that exposes the IAnnotationalProps interface.

  2. A property definition object must exist for an IAnnotationalProps interface property with a name that matches the name of your annotational property.

If these two requirements are met, you can attach an annotational property value to an object by using the IReposProperty::put_Value method to set the value of the annotational property for that particular object.

When to Use

Use the IAnnotationalProps interface to access the annotational properties of a Repository object or relationship.

Methods

IUnknown Method | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.

IDispatch Method | Description
GetIDsOfNames | Maps a single member and a set of argument names to a corresponding set of dispatch identifiers.
GetTypeInfo | Retrieves a type information object, which can be used to get the type information for an interface.
GetTypeInfoCount | Retrieves the number of type information interfaces that an object provides (either 0 or 1).
Invoke | Provides access to properties and methods exposed by an Automation object.

IRepositoryDispatch Method | Description
get_Properties | Retrieves the IReposProperties interface pointer. The IreposProperties interface provides access to the Properties collection.

Remarks

Annotational properties are maintained by the Repository as string data. The creator and users of the annotational property must get and set the property value using the appropriate data type through the VARIANT structure. If a data type other than string is used, the Repository will perform the appropriate data conversion.

Since all annotational properties in the Repository must be defined as interface members of the IAnnotationalProps interface, all annotational property names share the same name space. When you choose a name for an annotational property, make the name as specific and unique as possible.


IEnumRepositoryErrors Interface

This interface provides enumeration capabilities for the set of errors that have been placed on the Repository error queue.

When to Use

Use the IEnumRepositoryErrors interface to access the queue of Repository errors.

Methods

IUnknown Method | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.

IEnumRepositoryErrors Method | Description
Clone | Clones the current enumerator.
Next | Returns the next one or more elements.
Reset | Resets the enumerator to the beginning.
Skip | Skips over the next one or more elements.


IEnumRepositoryErrors::Clone

Use this method to create a clone of the COM enumerator object. After cloning, the two enumerators operate independently of each other.

HRESULT Clone( IEnumRepositoryErrors **ppIEnum );

Parameters

*ppIEnum

[out]
The interface pointer for the new enumerator object.

Return Value

S_OK

The method completed successfully.

Error

Values

This method failed to complete successfully.


IEnumRepositoryErrors::Next

Use this method to retrieve the next one or more elements from the enumeration. There are two variations of this method.

HRESULT Next(
ULONG iCount,
REPOSERR *psErrors,
ULONG *piFetched
);

HRESULT Next( IErrorInfo **ppIErrorInfo );

Parameters

iCount

[in]
The number of elements the caller is requesting.

*psErrors

[out]
The array of Repository error information structures for the retrieved items.

*ppIErrorInfo

[out]
The interface pointer to the error information object for the first element in the error queue.

*piFetched

[out]
The number of elements actually fetched for the caller.

Return Value

S_OK

The method completed successfully.

Error

Values

This method failed to complete successfully.


IEnumRepositoryErrors::Reset

Use this method to reset the enumerator to the beginning of the enumeration sequence.

HRESULT Reset( void );

Return Value

S_OK

The method completed successfully.

Error

Values

This method failed to complete successfully.


IEnumRepositoryErrors::Skip

Use this method to skip over the next one or more elements in the enumeration.

HRESULT Skip( ULONG iCount );

Parameters

iCount

[in]
The number of elements to be skipped.

Return Value

S_OK

The method completed successfully.

Error

Values

This method failed to complete successfully.


INamedObject Interface

Normally, a name is associated with a Repository object through a naming relationship. The collection for such a relationship provides the scope for the name, and can require that all names in the collection be unique. This is the preferred method for naming objects, when a given object will be the destination of only one naming relationship.

If your information model contains a class that is not the destination of a naming relationship type, or is the destination of multiple relationship types, but no single relationship type is the obvious choice to be the naming relationship type, you can attach the name property to the class. This is accomplished by defining your class to implement the INamedObject interface. If your class implements the INamedObject interface, the Repository engine will use that interface when asked to retrieve or set an object name.

When to Use

Use the INamedObject interface to access the Name property of a Repository object that exposes this interface.

Properties

Property | Description
Name | The name of the object.

Methods

IUnknown Method | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.

IDispatch Method | Description
GetIDsOfNames | Maps a single member and a set of argument names to a corresponding set of dispatch identifiers.
GetTypeInfo | Retrieves a type information object, which can be used to get the type information for an interface.
GetTypeInfoCount | Retrieves the number of type information interfaces that an object provides (either 0 or 1).
Invoke | Provides access to properties and methods exposed by an Automation object.

IrepositoryDispatch Method | Description
get_Properties | Retrieves the IReposProperties interface pointer. The IreposProperties interface provides access to the persistent members exposed by the InamedObject interface.

Remarks

None of the standard Repository engine or Type Information Model classes implement the INamedObject interface. However, the Repository engine does use the INamedObject interface, if it is exposed by a Repository object.

When the IRepositoryItem::get_Name method is invoked for a Repository object, the Repository engine will perform these steps to retrieve the name:

  1. If the object exposes the INamedObject interface, the Repository engine returns the value of the Name property on the INamedObject interface.

  2. Otherwise, the Repository engine searches for a naming relationship for which the current object is the destination object, taking the workspace context into consideration.

  3. If such a relationship is found, the Repository engine returns the name associated with that relationship.

  4. If the object is not the destination of a naming relationship, the Repository engine returns a null name.

When the IRepositoryItem::put_Name method is invoked for a Repository object, the Repository engine will perform these steps to set the name:

  1. The Repository engine sets the value of the Name property of all naming relationships for which the object is the destination.

  2. If the object exposes the INamedObject interface, the Repository engine also sets the value of the Name property attached to that interface.


INamedObject Name Property

This property contains the name of an object that exposes the INamedObject interface. The name can be up to 200 bytes in length.

Dispatch Identifier: DISPID_ObjName (68)

Property Data Type: String


IObjectCol Interface

An object collection is a set of Repository objects that can be enumerated. Two kinds of object collections are supported by the Repository:

  1. The collection of destination objects that correspond to the relationships in a relationship collection. Use the ITargetObjectCol interface to manage this kind of collection.

  2. The collection of all objects in the Repository that conform to a particular class or expose a particular interface.

When to Use

Use the IObjectCol interface to enumerate the collection of Repository objects that conform to a particular class or expose a particular interface. With this interface, you can:

  • Get a count of the number of objects in the collection.

  • Enumerate the objects in the collection.

  • Retrieve an IRepositoryObject pointer to one of the objects in the collection.

  • Refresh the cached image of the object collection.

Methods

Iunknown Method | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.

Idispatch Method | Description
GetIDsOfNames | Maps a single member and a set of argument names to a corresponding set of dispatch identifiers.
GetTypeInfo | Retrieves a type information object, which can be used to get the type information for an interface.
GetTypeInfoCount | Retrieves the number of type information interfaces that an object provides (either 0 or 1).
Invoke | Provides access to properties and methods exposed by an Automation object.

IobjectCol Method | Description
get_Count | Retrieves a count of the number of objects in the collection.
get_Item | Retrieves an IRepositoryObject interface pointer for the specified collection object.
_NewEnum | Retrieves an enumeration interface pointer for the collection.
Refresh | Refreshes the cached image of the object collection.


IObjectCol::get_Count

This method is used to retrieve a count of the number of Repository objects that are in the object collection.

HRESULT get_Count( long *piCount );

Parameters

*piCount

[out]
The number of objects in the collection.

Return Value

S_OK

The method completed successfully.

Error

Values

This method failed to complete successfully.


IObjectCol::_NewEnum

This method retrieves an enumeration interface pointer for the object collection. This interface is a standard Automation enumeration interface. It supports the Clone, Next, Reset, and Skip methods. You can use the enumeration interface to step through the objects in the collection.

HRESULT _NewEnum(
IUnknown **ppIEnumObjects
);

Parameters

*ppIEnumObjects

[out]
The enumeration interface pointer.

Return Value

S_OK

The method completed successfully.

Error

Values

This method failed to complete successfully.


IObjectCol::get_Item

This method retrieves the specified object from the collection.

HRESULT get_Item(
VARIANT sItem,
IRepositoryObject **ppIReposObj
);

Parameters

sItem

[in]
Identifies the item to be retrieved from the collection. This parameter can be either the index or the object identifier of the item.

*ppIReposObj

[out]
The IRepositoryObject interface pointer for the version of the specified object from the collection.

Return Value

S_OK

The method completed successfully.

Error

Values

This method failed to complete successfully.

Remarks

When this method is invoked through the ITargetObjectCol interface (which inherits this method from the IObjectCol interface), an object can also be retrieved by name, but only if it is the destination object of a naming relationship.

This method returns a specific version of the item. To choose which version, it uses the Repository's Resolution Strategy.


IObjectCol::Refresh

This method refreshes the cached image of the collection. All unchanged data for objects in the collection is flushed from the cache.

HRESULT Refresh( long iMilliseconds );

Parameters

iMilliseconds

[in]
All unchanged data relating to the collection that has been in the cache for longer than iMilliseconds milliseconds is refreshed. Set to zero to refresh all unchanged data.

Return Value

S_OK

The method completed successfully.

Error

Values

This method failed to complete successfully.


IRelationship Interface

A relationship connects two Repository objects in the Repository database. A relationship has an origin Repository object, a destination Repository object, and a set of properties. Each relationship conforms to a particular relationship type.

When to Use

Use the IRelationship interface to manipulate a relationship, or to retrieve the source, target, origin, or destination object for a relationship.

Methods

IUnknown Method | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.

IDispatch Method | Description
GetIDsOfNames | Maps a single member and a set of argument names to a corresponding set of dispatch identifiers.
GetTypeInfo | Retrieves a type information object, which can be used to get the type information for an interface.
GetTypeInfoCount | Retrieves the number of type information interfaces that an object provides (either 0 or 1).
Invoke | Provides access to properties and methods exposed by an Automation object.

IRepositoryDispatch Method | Description
get_Properties | Retrieves the IReposProperties interface pointer. The IReposProperties interface provides access to the Properties collection.

IRepositoryItem Method | Description
Delete | Deletes a Repository item.
get_Interface | Retrieves an interface pointer to the specified item interface.
get_Name | Retrieves the name associated with an item.
get_Repository | Retrieves the IRepository interface pointer for an item's open Repository instance.
get_Type | Retrieves the type of an item.
Lock | Locks the item.
put_Name | Sets the name associated with an item.

IRelationship Method | Description
get_Destination | Retrieves an interface pointer to the destination object.
get_Origin | Retrieves an interface pointer to the origin object.
get_Source | Retrieves an interface pointer to the source object.
get_Target | Retrieves an interface pointer to the target object.


IRelationship::get_Destination

Retrieves an IRepositoryObject interface pointer to the destination object version of a relationship.

HRESULT get_Destination(
IRepositoryObject **ppIReposObj
);

Parameters

*ppIRepObj

[out]
The IRepositoryObject interface pointer for the destination Repository object version.

Return Value

S_OK

The method completed successfully.

Error

Values

This method failed to complete successfully.

Remarks

If the relationship is a destination versioned relationship, this property is equivalent to the get_Source method. If it is an origin versioned relationship, this property is equivalent to the get_Target method.

This method uses the Repository's Resolution Strategy to choose


IRelationship::get_Origin

Retrieves an IRepositoryObject interface pointer to the origin object version of a relationship.

HRESULT get_Origin(
IRepositoryObject **ppIRepObj
);

Parameters

*ppIRepObj

[out]
The IRepositoryObject interface pointer for the origin Repository object version.

Return Value

S_OK

The method completed successfully.

Error

Values

This method failed to complete successfully.

Remarks

If the relationship is an origin versioned relationship, this property is equivalent to the get_Source method. If it is a destination versioned relationship, this property is equivalent to the get_Target method.


IRelationship::get_Source

Retrieves an IRepositoryObject interface pointer to the source object version of a relationship.

HRESULT get_Source(
IRepositoryObject **ppIRepObj
);

Parameters

*ppIRepObj

[out]
The IRepositoryObject interface pointer for the source Repository object version.

Return Value

S_OK

The method completed successfully.

Error

Values

This method failed to complete successfully.


IRelationship::get_Target

Retrieves an IRepositoryObject interface pointer to a target object version of a relationship.

HRESULT get_Target(
IRepositoryObject **ppIRepObj
);

Parameters

*ppIRepObj

[out]
The IRepositoryObject interface pointer for the target Repository object version.

Return Value

S_OK

The method completed successfully.

Error

Values

This method failed to complete successfully.

Remarks

The Repository uses its Resolution Strategy to choose a target object version to return to you.

In one situation, the Repository can fail to return a version of the target object. If you are operating within a workspace, and the versioned relationship's collection of TargetVersions does not include the object version that is present in the workspace, this method fails.


IRelationshipCol Interface

A relationship collection is the set of versioned relationships that connect a particular source object version to a set of one or more target objects. All of the relationships in the collection must conform to the same relationship type.

When to Use

Use the IRelationshipCol interface to manage the Repository relationships that belong to a particular relationship collection. With this interface, you can:

  • Get a count of the number of relationships in the collection.

  • Enumerate the relationships in the collection.

  • Add and remove relationships to and from the collection.

  • If the collection is sequenced, place a relationship in a specific spot in the collection sequence.

  • Retrieve an IRelationship pointer to one of the relationships in the collection.

  • Obtain the identifier of the collection's definition object.

  • Retrieve an interface pointer for the collection's source object.

Methods

IUnknown Method | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.

IDispatch Method | Description
GetIDsOfNames | Maps a single member and a set of argument names to a corresponding set of dispatch identifiers.
GetTypeInfo | Retrieves a type information object, which can be used to get the type information for an interface.
GetTypeInfoCount | Retrieves the number of type information interfaces that an object provides (either 0 or 1).
Invoke | Provides access to properties and methods exposed by an Automation object.

IRelationshipCol Method | Description
Add | Adds a relationship to the collection.
get_Count | Retrieves a count of the number of relationships in the collection.
_NewEnum | Retrieves an enumeration interface pointer for the collection.
get_Source | Retrieves an interface pointer for the collection's source object.
get_Type | Retrieves the object identifier for the collection's definition object.
Insert | Inserts a relationship into a specific spot in a sequenced collection.
get_Item | Retrieves an IRelationship interface pointer for the specified relationship.
Move | Moves a relationship from one spot to another in a sequenced collection.
Refresh | Refreshes the cached image of the relationship collection.
Remove | Removes a relationship from the collection.

Remarks

The IRelationshipCol interface is very similar to the ITargetObjectCol interface. Use the IRelationshipCol interface when you are primarily interested in working with relationships. Use the ITargetObjectCol interface when you are primarily interested in working with objects.


IRelationshipCol::Add

This method is used to add a new item to a Repository relationship collection, when the sequencing of relationships in the collection is not important. An interface pointer for the new relationship is passed back to the caller.

HRESULT Add(
IDispatch *plReposObj,
BSTR Name,
IRelationship **pplRelship
);

Parameters

*plReposObj

[in]
The object for which a relationship is to be added to the relationship collection.

Name

[in]
The name of the new relationship.

*pplRelship

[out]
The newly added relationship's IRelationship interface pointer.

Return Value

S_OK

The method completed successfully.

Error

Values

This method failed to complete successfully.

Remarks

You can add a relationship to a collection only when the collection's source object is also the collection's origin object.

When you call this method, the origin version must be unfrozen.

You can use this method to create a new versioned relationship between the source object version and a version of the target object. You cannot use it to enlarge a versioned relationship. If the source object version already has a relationship to any version of the target object, this method will fail. You can include another version of the target object in the versioned relationship by adding an item to the versioned relationship's TargetVersions collection.

The value of plReposObj is the specific version of the target object.

If you are operating within the context of a workspace, the target object version you specify with plReposObj must be present in the workspace.


IRelationshipCol::get_Count

This method is used to retrieve a count of the number of relationships that are in the relationship collection.

HRESULT get_Count(
long *piCount
);

Parameters

*piCount

[out]
The number of relationships in the collection.

Return Value

S_OK

The method completed successfully.

Error

Values

This method failed to complete successfully.

Remarks

Remember, each item in the collection is a versioned relationship. Thus, the returned count indicates how many objects are in the collection, not how many object versions.


IRelationshipCol::_NewEnum

This method retrieves an enumeration interface pointer for the relationship collection. This interface is a standard Automation enumeration interface. It supports the Clone, Next, Reset, and Skip methods. You can use the enumeration interface to step through the relationships in the collection.

HRESULT _NewEnum(
IUnknown **ppIEnumRelships
);

Parameters

*ppIEnumRelships

[out]
The enumeration interface pointer.

Return Value

S_OK

The method completed successfully.

Error

Values

This method failed to complete successfully.


IRelationshipCol::get_Source

This method retrieves an interface pointer for the collection's source object version.

HRESULT get_Source(
IRepositoryObject **ppIInterface
);

Parameters

*ppIInterface

[out]
The interface pointer of the desired interface for the source object.

Return Value

S_OK

The method completed successfully.

Error

Values

This method failed to complete successfully.


IRelationshipCol::get_Type

This method retrieves the type of the collection; that is, it returns the object identifier for the collection's definition object.

HRESULT get_Type(
VARIANT *pColDefObjId
);

Parameters

*pColDefObjId

[out]
The object identifier of the collection's definition object.

Return Value

S_OK

The method completed successfully.

Error

Values

This method failed to complete successfully.


IRelationshipCol::Insert

This method adds a relationship to the collection at a specified point in the collection sequence. An interface pointer for the new relationship is passed back to the caller.

HRESULT Insert(
IDispatch *pIReposObj,
long iIndex,
BSTR Name,
IRelationship **ppIRelship
);

Parameters

*pIReposObj

[in]
The Repository object to be inserted into the collection sequence through the new relationship.

iIndex

[in]
The index of the sequence location where the relationship is to be inserted. If another relationship is already present at this sequence location, the new relationship is inserted before the existing relationship.

Name

[in]
The name to be associated with the object that is connected by the new relationship.

*ppIRelship

[out]
The IRelationship interface pointer for the new relationship.

Return Value

S_OK

The method completed successfully.

Error

Values

This method failed to complete successfully.

Remarks

Relationships may only be inserted into a collection when the collection's source object is also the collection's origin object.

This method can only be used for collections that are sequenced.

When you call this method, the origin version must be unfrozen.

You can use this method to insert a new versioned relationship between the source object version and a version of the target object. You cannot use it to enlarge a versioned relationship. If the source object version already has a relationship to any version of the target object, this method will fail. You can include another version of the target object in the versioned relationship by adding an item to the versioned relationship's TargetVersions collection.

The value of plReposObj is the specific version of the target object.

If you are operating within the context of a workspace, the target object version you specify with plReposObj must be present in the workspace.


IRelationshipCol::get_Item

This method retrieves the specified relationship from the collection.

HRESULT get_Item(
VARIANT sItem,
IRelationship **ppIRelship
);

Parameters

sItem

[in]
Identifies the item to be retrieved from the collection. This parameter can be either the index, the name, or the object identifier of the item.

*ppIRelship

[out]
The IRelationship interface pointer for the specified relationship from the collection.

Return Value

S_OK

The method completed successfully.

Error

Values

This method failed to complete successfully.

Remarks

Each item in the collection is a versioned relationship — it has a collection of TargetVersions. When you obtain a reference to the target object of a particular item (with the get_Target method of the IRelationship interface), the Repository chooses a particular version of the target object from the items in the versioned relationship's TargetVersions collection.

The variation of this method that specifies the relationship by destination object name can only be used for naming collections.


IRelationshipCol::Move

This method moves a relationship from one point in the collection sequence to another point.

HRESULT Move(
long iIndexFrom,
long iIndexTo
);

Parameters

iIndexFrom

[in]
The index of the relationship to be moved in the collection sequence.

iIndexTo

[in]
The index of the sequence location to which the relationship is to be moved.

Return Value

S_OK

The method completed successfully.

Error

Values

This method failed to complete successfully.

Remarks

This method can only be used for collections that are sequenced.

The origin object version must be unfrozen.


IRelationshipCol::Refresh

This method refreshes the cached image of the collection. All unchanged data for relationships in the collection is flushed from the cache.

HRESULT Refresh( long iMilliseconds );

Parameters

iMilliseconds

[in]
All unchanged data relating to the collection that has been in the cache for longer than iMilliseconds milliseconds is refreshed. Set to zero to refresh all unchanged data.

Return Value

S_OK

The method completed successfully.

Error

Values

This method failed to complete successfully.


IRelationshipCol::Remove

This method deletes a relationship from its relationship collection. The exact behavior of this method depends on whether the relationship collection is an origin collection or a destination collection.

If the relationship collection is an origin collection, this method deletes the versioned relationship.

If the relationship collection is a destination collection, this method first performs object-version resolution to yield a single target-object version, and then it removes that target-object version from the relationship's TargetVersions collection.

HRESULT Remove( VARIANT sItem );

Parameters

sItem

[in]
Identifies the item to be removed from the collection. This parameter can be either the index or the name associated with the item.

Return Value

S_OK

The method completed successfully.

Error

Values

This method failed to complete successfully.

Remarks

A relationship can be removed by name only if it is a unique-naming relationship.

If the source is the origin, the origin version must be unfrozen.

If the relationship is a destination relationship and the resolution strategy yields a target object version that is frozen, this method fails.


IRepository Interface

When you define a tool information model, the classes, relationships, properties, and collections for the model are stored in a Repository. Multiple tool information models may be stored in the same Repository.

When to Use

Use the Repository interface to create and access Repository databases. You can also use the Repository interface to create and access Repository objects in a Repository database.

Methods

IUnknown Method | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.

Idispatch Method | Description
GetIDsOfNames | Maps a single member and a set of argument names to a corresponding set of dispatch identifiers.
GetTypeInfo | Retrieves a type information object, which can be used to get the type information for an interface.
GetTypeInfoCount | Retrieves the number of type information interfaces that an object provides (either 0 or 1).
Invoke | Provides access to properties and methods exposed by an Automation object.

Irepository Method | Description
Create | Creates a Repository database.
CreateObject | Creates a new Repository object.
get_Object | Retrieves the IRepositoryObject interface pointer for a Repository object.
get_RootObject | Retrieves the IRepositoryObject interface pointer for the root Repository object.
get_Transaction | Retrieves the IRepositoryTransaction interface pointer for this Repository instance.
InternalIDToObjectID | Translate an internal identifier to an object identifier.
ObjectIDToInternalID | Translate an object identifier to an internal identifier.
Open | Opens a Repository database.
Refresh | Refreshes unchanged cached Repository data.


IRepository::Create

Use this method to create a new Repository. The fundamental Repository tables are automatically created in the new Repository. An IRepositoryObject interface pointer to the root Repository object is passed back to the caller.

HRESULT Create(
BSTR Connect,
BSTR User,
BSTR Password,
long fFlags,
IRepositoryObject **ppIRootObj
);

Parameters

Connect

[in]
The ODBC connection string to be used for accessing the database server that will host your new Repository.

User

[in]
The user name to use for identification to the database server.

Password

[in]
The password that matches the User input parameter.

fFlags

[in]
Flags that determine database access and caching behavior for the open Repository. For details, see the ConnectionFlags Enumeration.

*ppIRootObj

[out]
The IRepositoryObject interface pointer for the new Repository's root Repository object.

Return Value

S_OK

The method completed successfully.

Error

Values

This method failed to complete successfully.


IRepository::CreateObject

Creates the first version of a new Repository object. The specified COM interface pointer to the new object is passed back to the caller.

HRESULT CreateObject(
VARIANT sTypeId,
VARIANT sObjId,
IRepositoryObject *ppIReposObj
);

Parameters

sTypeId

[in]
The type of the new object; that is, the object identifier of the class definition to which the new object conforms.

sObjId

[in]
The object identifier to be assigned to the new object. Pass in OBJID_NULL to have the Repository assign an object identifier for you.

*ppIReposObj

[out]
The IRepositoryObject interface pointer for the new Repository object.

Return Value

S_OK

The method completed successfully.

Error

Values

This method failed to complete successfully.

Remarks

The new object will automatically create persistent storage for itself.

You can use this method only to create the first version of a Repository object. To create subsequent versions of the object, use IRepositoryObjectVersion::CreateVersion.


IRepository::get_Object

Retrieves an IRepositoryObject interface pointer to the specified Repository object.

HRESULT get_Object(
VARIANT sObjectId,
IRepositoryObject **ppIReposObj
);

Parameters

sObjectId

[in]
The object identifier of the Repository object to be retrieved.

*ppIReposObj

[out]
The IRepository interface pointer for the Repository object.

Return Value

S_OK

The method completed successfully.

Error

Values

This method failed to complete successfully.

Remarks

The returned IRepository interface pointer refers to a specific version of the Repository object. The Repository uses its Resolution strategy to choose which version.


IRepository::get_RootObject

Use this method to obtain a pointer to the currently open Repository's root object. The root object is the Repository object to which all other Repository objects are (either directly or indirectly) connected.

HRESULT get_RootObject(
IRepositoryObject **ppIRootObj
);

Parameters

*ppIRootObj

[out]
The IRepositoryObject interface pointer for the root Repository object.

Return Value

S_OK

The method completed successfully.

Error

Values

This method failed to complete successfully.


IRepository::get_Transaction

Retrieves the IRepositoryTransaction interface pointer for this Repository instance. Use the IRepositoryTransaction interface to manage Repository transactions for this Repository instance.

HRESULT get_Transaction(
IRepositoryTransaction **ppIRepTrans
);

Parameters

*ppIRepTrans

[out]
The IRepositoryTransaction interface pointer.

Return Value

S_OK

The method completed successfully.

Error

Values

This method failed to complete successfully.


IRepository::InternalIDToObjectID

This method translates an internal identifier into an object identifier. Internal identifiers are used by the Repository engine to identify Repository objects.

HRESULT InternalIDToObjectID(
VARIANT sInternalID,
VARIANT *sObjectId
);

Parameters

sInternalID

[in]
The internal identifier for the Repository object.

*sObjectId

[out]
The object identifier for the Repository object.

Return Value

S_OK

The method completed successfully.

Error

Values

This method failed to complete successfully.

Remarks

Repository object identifiers are globally unique, and are the same across repositories for the same object. Repository internal identifiers are unique only within the scope of a single Repository.

The translation performed by this method is performed without loading the object in question. This enables database queries involving an object or relationship type identifier to be constructed without having to load the definition object.


IRepository::ObjectIDToInternalID

This method translates an object identifier into an internal identifier. Internal identifiers are used by the Repository engine to identify Repository objects.

HRESULT ObjectIDToInternalID(
VARIANT sObjectID,
VARIANT *sInternalId
);

Parameters

sObjectID

[in]
The object identifier for the Repository object.

*sInternalId

[out]
The internal identifier for the Repository object.

Return Value

S_OK

The method completed successfully.

Error

Values

This method failed to complete successfully.

Remarks

Repository object identifiers are globally unique, and are the same across repositories for the same object. Repository internal identifiers are unique only within the scope of a single Repository.

The translation performed by this method is performed without loading the object in question. This enables database queries involving an object or relationship type identifier to be constructed without having to load the definition object.


IRepository::Open

Use this method to open a Repository. An IRepositoryObject interface pointer to the root object is passed back to the caller.

HRESULT Open(
BSTR Connect,
BSTR User,
BSTR Password,
long fFlags,
IRepositoryObject **ppIRootObj
);

Parameters

Connect

[in]
The ODBC connection string to be used for accessing the database server that hosts your Repository.

User

[in]
The user name to use for identification to the database server.

Password

[in]
The password that matches the User input parameter.

fFlags

[in]
Flags that determine database access and caching behavior for the open Repository. For details, see the ConnectionFlags Enumeration.

*ppIRootObj

[out]
The IRepositoryObject interface pointer for the open Repository's root Repository object.

Return Value

S_OK

The method completed successfully.

Error

Values

This method failed to complete successfully.


IRepository::Refresh

This method refreshes all of the cached data for this Repository instance. Only cached data that has not been changed by the current process is refreshed.

HRESULT Refresh( long iMilliseconds );

Parameters

iMilliseconds

[in]
All unchanged data that has been in the cache for longer than iMilliseconds milliseconds is refreshed. Set this parameter to zero to refresh all unchanged data.

Return Value

S_OK

The method completed successfully.

Error

Values

This method failed to complete successfully.


IRepository2 Interface

This interface exposes methods for manipulating object-version identifiers, plus other methods inherited from the IRepository interface.

When to Use

Use the IRepository2 interface to create and access Repository databases. You can also use the Repository interface to create and access Repository objects in a Repository database, and to manipulate Repository object versions.

Methods

IUnknown Method | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.

IDispatch Method | Description
GetIDsOfNames | Maps a single member and a set of argument names to a corresponding set of dispatch identifiers.
GetTypeInfo | Retrieves a type information object, which can be used to get the type information for an interface.
GetTypeInfoCount | Retrieves the number of type information interfaces that an object provides (either 0 or 1).
Invoke | Provides access to properties and methods exposed by an Automation object.

IRepository Method | Description
Create | Creates a Repository database.
CreateObject | Creates a new Repository object.
get_Object | Retrieves the IRepositoryObject interface pointer for a Repository object.
get_RootObject | Retrieves the IRepositoryObject interface pointer for the root Repository object.
get_Transaction | Retrieves the IRepositoryTransaction interface pointer for this Repository instance.
InternalIDToObjectID | Translate an internal identifier to an object identifier.
ObjectIDToInternalID | Translate an object identifier to an internal identifier.
Open | Opens a Repository database.
Refresh | Refreshes unchanged cached Repository data.

IRepository2 Method | Description
InternalIDToVersionID | Translate an internal object-version identifier to an object-version identifier.
get_Version | Retrieves the IRepositoryObjectVersion interface pointer for a Repository object version.
VersionIDToInternalID | Translate an object-version identifier to an internal object-version identifier.


IRepository2::get_Version

Retrieves an IRepositoryObjectVersion interface pointer to the specified Repository object version.

HRESULT get_Version(
VARIANT sVersionId,
IRepositoryObjectVersion **ppIReposVersion
);

Parameters

sVersionId

[in]
The object-version identifier of the Repository object version to be retrieved.

*ppIReposVersion

[out]
The IRepositoryObjectVersion interface pointer for the Repository object.

Return Value

S_OK

The method completed successfully.

Error

Values

This method failed to complete successfully.


IRepository2::InternalIDToVersionID

This method translates an internal object-version identifier into an object-version identifier. Internal object-version identifiers are used by the Repository engine to identify Repository objects versions.

HRESULT InternalIDToObjectID(
VARIANT sIntVersionID,
VARIANT *psExtVersionID
);

Parameters

sIntVersionID

[in]
The internal object-version identifier for the Repository object.

*psExtVersionID

[out]
The object-version identifier for the Repository object.

Return Value

S_OK

The method completed successfully.

Error

Values

This method failed to complete successfully.

Remarks

Repository object-version identifiers are globally unique, and are the same across repositories for the same object. Repository internal object-version identifiers are unique only within the scope of a single Repository.

The translation performed by this method is performed without loading the object version in question. This enables database queries involving an object or relationship type identifier to be constructed without having to load the definition object.


IRepository2::VersionIDToInternalID

This method translates an object-version identifier into an internal object-version identifier. Internal object-version identifiers are used by the Repository engine to identify Repository object versions.

HRESULT ObjectIDToInternalID(
VARIANT sExtVersionID,
VARIANT *psIntVersionID
);

Parameters

sExtVersionID

[in]
The object-version identifier for the Repository object.

*psIntVersionID

[out]
The internal object-version identifier for the Repository object.

Return Value

S_OK

The method completed successfully.

Error

Values

This method failed to complete successfully.

Remarks

Repository object identifiers are globally unique, and are the same across repositories for the same object. Repository internal identifiers are unique only within the scope of a single Repository.

The translation performed by this method is performed without loading the object version in question. This enables database queries involving an object or relationship type identifier to be constructed without having to load the definition object.


IRepositoryDispatch Interface

The IRepositoryDispatch interface is an enhanced IDispatch interface; in addition to all of the standard IDispatch methods, IRepositoryDispatch also provides access to the Properties collection. The Properties collection gives you a convenient mechanism to enumerate through all of the persistent properties and collections of an interface.

When you instantiate an Automation object that represents an object from your tool information model, and that object conforms to a class for which there is no custom implementation (in other words, you have provided no software implementation of the class), the Repository will provide an interface implementation for you. This interface implementation uses IRepositoryDispatch as its dispatch interface.

When to Use

Use the IRepositoryDispatch interface to access the properties and collections of a Repository object, when no custom implementation is available.

Methods

IUnknown Method | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.

IDispatch Method | Description
GetIDsOfNames | Maps a single member and a set of argument names to a corresponding set of dispatch identifiers.
GetTypeInfo | Retrieves a type information object, which can be used to get the type information for an interface.
GetTypeInfoCount | Retrieves the number of type information interfaces that an object provides (either 0 or 1).
Invoke | Provides access to properties and methods exposed by an Automation object.

IRepositoryDispatch Method | Description
get_Properties | Retrieves the IReposProperties interface pointer. The IReposProperties interface provides access to the Properties collection.

Remarks

The Repository engine will only supply an interface implementation for you if your interface is defined to inherit from IDispatch or IRepositoryDispatch.


IRepositoryDispatch::get_Properties

This method retrieves the IReposProperties interface pointer. The IReposProperties interface provides methods to access the Properties collection. The Properties collection gives you a convenient mechanism to enumerate through all of the persistent properties and collections of an interface.

HRESULT get_Properties( IReposProperties **ppIReposProps );

Parameters

*ppIReposProps

[out]
The IReposProperties interface pointer.

Return Value

S_OK

The method completed successfully.

Error Values

This method failed to complete successfully.


IRepositoryErrorQueue Interface

Errors that occur while accessing a Repository are saved on a Repository error queue. A Repository error queue is a collection of REPOSERROR structures. Individual elements on a Repository error queue can be managed in much the same way that elements can be managed in other Repository collections. This interface provides those management capabilities.

When to Use

Use the IRepositoryErrorQueue interface to manage the errors that belong to a particular Repository error queue. With this interface, you can:

  • Get a count of the number of error elements in the collection.

  • Enumerate the elements in the collection.

  • Insert and remove error elements to and from the collection.

  • Retrieve one of the error elements in the collection.

Methods

IUnknown Method | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.

IRepositoryErrorQueue Method | Description
Count | Returns a count of the number of errors on the queue.
Insert | Inserts a new error onto the error queue, in the specified location.
Item | Retrieves the specified error from the error queue.
Remove | Removes the specified error from the error queue.
_NewEnum | Creates an enumerator object for the error queue.


IRepositoryErrorQueue::Count

This method returns the number of errors that are currently on the error queue.

ULONG Count(void);

Return Value

The number of error elements on the queue.


IRepositoryErrorQueue::Insert

This method inserts a new element into the error queue. The element can either be inserted at a specific location in the queue, or it can be appended to the end of the queue.

HRESULT Insert(
ULONG iIndex,
REPOSERROR *psError
);

Parameters

iIndex

[in]
The index of the location in the error queue where this element is to be inserted. To insert an element at the beginning of the error queue, set this parameter to one. Set this parameter to zero to append the element to the end of the error queue.

*psError

[in]
The error information for the element to be inserted. The information from this structure is copied and the copy is placed on the error queue.

Return Value

S_OK

The method completed successfully.

Error

Values

This method failed to complete successfully.


IRepositoryErrorQueue::Item

This method retrieves the specified element from the error queue. There are two variations of this method.

HRESULT Item(
ULONG iIndex,
REPOSERROR *psError
);

HRESULT Item(
ULONG iIndex,
IErrorInfo **ppIErrorInfo
);

Parameters

iIndex

[in]
The index of the location in the error queue of the element to be retrieved.

*ppError

[out]
The Repository error information structure with information from the retrieved element.

*ppIErrInfoObj

[out]
The interface pointer to an error information object for the retrieved element.

Return Value

S_OK

The method completed successfully.

Error

Values

This method failed to complete successfully.


IRepositoryErrorQueue::Remove

This method removes the specified element from the error queue.

HRESULT Remove(
ULONG iIndex
);

Parameters

iIndex

[in]
The index of the location in the error queue of the element to be removed.

Return Value

S_OK

The method completed successfully.

Error

Values

This method failed to complete successfully.


IRepositoryErrorQueue::_NewEnum

This method creates an enumeration object for the error queue. An interface pointer for the enumeration object is passed back to the caller.

HRESULT _NewEnum(
IEnumRepositoryErrors **ppIEnum
);

Parameters

*ppIEnum

[out]
The interface pointer to the enumeration object.

Return Value

S_OK

The method completed successfully.

Error

Values

This method failed to complete successfully.


IRepositoryErrorQueueHandler Interface

Errors that occur while accessing a Repository are saved on a Repository error queue. A Repository error queue is a collection of REPOSERROR structures. Each thread of execution with an open Repository instance can access one active error queue at a time.

When to Use

Use the IRepositoryErrorQueueHandler interface to create a Repository error queue, assign an error queue to a thread of execution, or retrieve an interface pointer to a thread's currently assigned error queue.

Methods

IUnknown Method | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.

IRepositoryErrorQueueHandler Method | Description
CreateErrorQueue | Creates a new Repository error queue.
SetErrorQueue | Sets the active error queue for a thread.
GetErrorQueue | Retrieves an interface pointer to the currently active error queue for a thread.


IRepositoryErrorQueueHandler::CreateErrorQueue

This method creates a Repository error queue. Once created, the error queue is available to be assigned to a thread context.

HRESULT CreateErrorQueue(
IRepositoryErrorQueue **ppIErrorQueue
);

Parameters

*ppIErrorQueue

[out]
The interface pointer for the newly created Repository error queue.

Return Value

S_OK

The method completed successfully.

Error

Values

This method failed to complete successfully.


IRepositoryErrorQueueHandler::GetErrorQueue

This method retrieves the Repository error queue that is assigned to the current thread.

HRESULT GetErrorQueue(
IRepositoryErrorQueue **ppIErrorQueue
);

Parameters

*ppIErrorQueue

[out]
The interface pointer for the error queue that is currently assigned to this thread.

Return Value

S_OK

The method completed successfully.

Error

Values

This method failed to complete successfully.


IRepositoryErrorQueueHandler::SetErrorQueue

This method assigns the specified Repository error queue to the current thread context.

HRESULT SetErrorQueue(
IRepositoryErrorQueue *pIErrorQueue
);

Parameters

pIErrorQueue

[in]
The interface pointer for the error queue to be assigned to this thread.

Return Value

S_OK

The method completed successfully.

Error

Values

This method failed to complete successfully.


IRepositoryItem Interface

The IRepositoryItem interface contains methods that are common to both Repository objects and Repository relationships. It contains all of the general purpose methods that are used to manage Repository items.

When to Use

Use the IRepositoryItem interface to:

  • Retrieve an item's type or name.

  • Obtain a lock on an item.

  • Change the name of an item.

  • Delete an item.

  • Get a pointer to an alternate interface that the item exposes.

  • Get the open Repository instance through which the item is accessed.

Methods

IUnknown Method | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.

IDispatch Method | Description
GetIDsOfNames | Maps a single member and a set of argument names to a corresponding set of dispatch identifiers.
GetTypeInfo | Retrieves a type information object, which can be used to get the type information for an interface.
GetTypeInfoCount | Retrieves the number of type information interfaces that an object provides (either 0 or 1).
Invoke | Provides access to properties and methods exposed by an Automation object.

IrepositoryDispatch Method | Description
get_Properties | Retrieves the IReposProperties interface pointer. The IReposProperties interface provides access to the Properties collection.

IrepositoryItem Method | Description
Delete | Deletes a Repository item.
get_Interface | Retrieves an interface pointer to the specified item interface.
get_Name | Retrieves the name associated with an item.
get_Repository | Retrieves the IRepository interface pointer for an item's open Repository instance.
get_Type | Retrieves the type of an item.
Lock | Locks the item.
put_Name | Sets the name associated with an item.


IRepositoryItem::Delete

This method deletes a Repository item.

HRESULT Delete( void );

Return Value

S_OK

The method completed successfully.

Error

Values

This method failed to complete successfully.

Remarks

If the item to be deleted is a Repository object version, this method fails unless the object version satisfies the basic requirements for object-version deletion. Furthermore, if the object version is checked out to any workspace, the Delete method fails unless you invoke it from within the context of that workspace. If object version satisfies both of these restrictions, the Repository deletes it and any of its relationships — including any delete-propagating origin relationships. For each of these relationships, the Repository considers performing one or more propagated deletions. (See Propagation after removing an origin relationship.)

If the item to be deleted is an origin versioned relationship, this method fails unless the source object version is changeable. If the source object version is changeable, the Repository deletes the entire relationship (rather than merely removing one item from the relationship's TargetVersions collection). In other words, after this method finishes, no version of the destination object remains related to the origin object version. Then, if the relationship is a delete-propagating relationship, the Repository considers performing one or more propagated deletions. (See Propagation after removing an origin relationship.)

If the item to be deleted is a destination versioned relationship, the Repository performs object-version Resolution to yield a single origin object version from the relationship's TargetVersions collection. If that origin object version is unchangeable, this method fails. If that origin object version is changeable, the Repository removes it from the relationship's TargetVersions collection. Then, if the relationship is a delete-propagating relationship, the Repository considers performing one or more propagated deletions. (See Propagation after removing a delete-propagating destination relationship.)


IRepositoryItem::get_Interface

This method retrieves the interface pointer for an alternate interface that the item exposes. The specified interface must be an Automation interface; that is, it must support the methods of the IDispatch interface.

HRESULT get_Interface(
VARIANT whichInterface,
IDispatch **ppInterface
);

Parameters

whichInterface

[in]
Specifies the interface you wish to access. This parameter can be the name of the interface, the interface identifier, or the object identifier of the interface definition object in the Repository.

*ppInterface

[out]
The interface pointer for the Automation interface.

Return Value

S_OK

The method completed successfully.

Error

Values

This method failed to complete successfully.

Remarks

Some objects expose multiple interfaces. This method is provided as a mechanism for the Automation programmer to be able to easily access alternate interfaces, when no type library is available for the item's class.


IRepositoryItem::get_Name

Retrieves the name associated with a Repository item. For Repository relationships, this is the name defined by the relationship. For Repository objects, this is either:

  1. The Name property of the INamedObject interface, if the object exposes that interface.

  2. The name defined by a relationship for which the object is the destination object.

HRESULT get_Name( BSTR *pName );

Parameters

*pName

[out]
The name associated with the item.

Return Value

S_OK

The method completed successfully.

Error

Values

This method failed to complete successfully.

Remarks

When you try to retrieve the name of an object version, the Repository can look in several places for the name. (See Retrieving an object version's name.)


IRepositoryItem::get_Repository

Retrieves an IRepository interface pointer for the open Repository instance or workspace through which this Repository item was instantiated.

HRESULT get_Repository( IRepository **ppIRepository );

Parameters

*ppIRepository

[out]
The IRepository interface pointer for the open Repository instance or workspace.

Return Value

S_OK

The method completed successfully.

Error

Values

This method failed to complete successfully.

Remarks

The returned IRepository interface pointer can refer to either a Repository object or a Workspace object. If it refers to a Workspace object, you are manipulating the item within the context of that workspace. If it refers to a Repository object, you are not manipulating the item within the context of a workspace, but within the context of a shared Repository instance.


IRepositoryItem::get_Type

Use this method to obtain the object identifier of the Repository definition object to which the Repository item conforms. This is the type of the Repository item.

HRESULT get_Type( VARIANT *psTypeId );

Parameters

*psTypeId

[out]
The object identifier of this Repository item's definition object.

Return Value

S_OK

The method completed successfully.

Error

Values

This method failed to complete successfully.


IRepositoryItem::Lock

Use this method to lock a particular Repository item. Locking the item prevents other processes from locking the item while you are working with it. The lock is released when you end the current transaction.

HRESULT Lock( void );

Return Value

S_OK

The method completed successfully.

Error

Values

This method failed to complete successfully.


IRepositoryItem::put_Name

This method changes one or more of the item's names.

HRESULT put_Name( BSTR Name );

Parameters

Name

[in]
The name to be associated with the item.

Return Value

S_OK

The method completed successfully.

Error

Values

This method failed to complete successfully.

Remarks

The behavior of this method depends on whether the to-be-named item is an object version, an origin versioned relationship, or a destination versioned relationship. For more information, see:

  • Changing an object version's name

  • Changing an origin relationship's name

  • Changing a destination relationship's name

Note This method can, in some circumstances, try to change several names. For example, if you rename an object version that is the destination of three naming relationships and also implements the INamedObject interface, this method will try to change four names. The method returns success if any of the four attempts succeeds.


IRepositoryObject Interface

The IRepositoryObject interface provides methods to manage Repository objects.

When to Use

Use the IRepositoryObject interface to:

  • Retrieve the object identifier or the internal identifier for a Repository object.

  • Retrieve a Repository object's type or name.

  • Obtain a lock on a Repository object.

  • Change the name of a Repository object.

  • Refresh the cached image of a Repository object.

  • Delete a Repository object.

  • Get a pointer to an alternate interface that the object exposes.

  • Get the open Repository instance through which the object is accessed.

Methods

IUnknown Method | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.

IDispatch Method | Description
GetIDsOfNames | Maps a single member and a set of argument names to a corresponding set of dispatch identifiers.
GetTypeInfo | Retrieves a type information object, which can be used to get the type information for an interface.
GetTypeInfoCount | Retrieves the number of type information interfaces that an object provides (either 0 or 1).
Invoke | Provides access to properties and methods exposed by an Automation object.

IRepositoryDispatch Method | Description
get_Properties | Retrieves the IReposProperties interface pointer. The IReposProperties interface provides access to the Properties collection.

IRepositoryItem Method | Description
Delete | Deletes a Repository item.
get_Interface | Retrieves an interface pointer to the specified item interface.
get_Name | Retrieves the name associated with an item.
get_Repository | Retrieves the IRepository interface pointer for an item's open Repository instance.
get_Type | Retrieves the type of an item.
Lock | Locks the item.
put_Name | Sets the name associated with an item.

IRepositoryObject Method | Description
get_InternalID | Retrieves the internal identifier for a Repository object.
get_ObjectID | Retrieves the object identifier for a Repository object.
Refresh | Refreshes the cached image of the object.


IRepositoryObject::get_InternalID

Use this method to obtain the internal identifier for a Repository object.

HRESULT get_InternalID( VARIANT *psInternalId );

Parameters

*psInternalId

[out]
The internal identifier of this Repository object.

Return Value

S_OK

The method completed successfully.

Error Values

This method failed to complete successfully.

Remarks

This method retrieves the internal object identifier, not the internal object-version identifier.


IRepositoryObject::get_ObjectID

Use this method to retrieve the object identifier for a Repository object.

HRESULT get_ObjectID( VARIANT *psObjectId );

Parameters

*psObjectId

[out]
The object identifier of this Repository object.

Return Value

S_OK

The method completed successfully.

Error

Values

This method failed to complete successfully.

Remarks

This method retrieves the object identifier, not the object-version identifier.


IRepositoryObject::Refresh

Use this method to refresh the cached image of a particular Repository object version. Only unchanged cache data is refreshed.

HRESULT Refresh( long iMilliseconds );

Parameters

iMilliseconds

[in]
All unchanged data relating to the object version that has been in the cache for longer than iMilliseconds milliseconds is refreshed. Set to zero to refresh all unchanged data.

Return Value

S_OK

The method completed successfully.

Error

Values

This method failed to complete successfully.


IRepositoryObjectStorage Interface

The IRepositoryObjectStorage interface initializes the memory image for a Repository object. New Repository objects are initialized as empty objects. For existing Repository objects, the state of the object is retrieved from the Repository database.

When to Use

The IRepositoryObjectStorage interface is used by the Repository engine to materialize Repository objects in memory. It is not intended for use by Repository applications.

Methods

IUnknown Method | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.

IDispatch Method | Description
GetIDsOfNames | Maps a single member and a set of argument names to a corresponding set of dispatch identifiers.
GetTypeInfo | Retrieves a type information object, which can be used to get the type information for an interface.
GetTypeInfoCount | Retrieves the number of type information interfaces that an object provides (either 0 or 1).
Invoke | Provides access to properties and methods exposed by an Automation object.

IRepositoryObjectStorage Method | Description
get_PropertyInterface | Retrieves an IRepositoryDispatch interface pointer for accessing the persistent members of one of the item's supported interfaces.
InitNew | Initializes memory for a new Repository object.
Load | Initializes memory for an existing Repository object.


IRepositoryObjectStorage::get_PropertyInterface

This method retrieves an IRepositoryDispatch interface pointer for accessing the persistent members of one of the object's supported Automation interfaces.

The IRepositoryDispatch interface can be used to get and set member values for the interface specified by the InterfaceId input parameter. The interface must be one that is exposed by this object.

HRESULT get_PropertyInterface(
VARIANT InterfaceId,
IRepositoryDispatch **ppInterface
);

Parameters

InterfaceId

[in]
The interface identifier of the interface whose properties are to be accessed.

*ppInterface

[out]
The IRepositoryDispatch interface pointer.

Return Value

S_OK

The method completed successfully.

Error

Values

This method failed to complete successfully.

Remarks

IRepositoryDispatch does not perform any parameter validation, and cannot be used to access custom methods or non-persistent properties. It is intended for use by custom class implementers.


IRepositoryObjectStorage::InitNew

The Repository engine uses this method to initialize a new Repository object in memory.

HRESULT InitNew(
IRepository *pIRepository,
INTID sInternalId
);

Parameters

*pIRepository

[in]
The Repository that contains this object.

sInternalId

[in]
The internal identifier for the new object.

Return Value

S_OK

The method completed successfully.

Error

Values

This method failed to complete successfully.


IRepositoryObjectStorage::Load

The Repository engine uses this method to load a Repository object's state into memory from the Repository database.

HRESULT Load(
IRepository *pIRepository,
INTID sInternalId
);

Parameters

*pIRepository

[in]
The Repository that contains this object.

sInternalId

[in]
The internal identifier for the Repository object.

Return Value

S_OK

The method completed successfully.

Error

Values

This method failed to complete successfully.


IRepositoryObjectVersion Interface

A Repository object version is a particular rendition of a Repository object. Each version of an object can differ from other versions of that object in its property values and collections.

When to Use

Use the IRepositoryObjectVersion interface to manipulate any version of an object, including the original version which was established with IRepository::CreateObject.

Methods

IUnknown Method | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.

IDispatch Method | Description
GetIDsOfNames | Maps a single member and a set of argument names to a corresponding set of dispatch identifiers.
GetTypeInfo | Retrieves a type information object, which can be used to get the type information for an interface.
GetTypeInfoCount | Retrieves the number of type information interfaces that an object provides (either 0 or 1).
Invoke | Provides access to properties and methods exposed by an Automation object.

IrepositoryDispatch Method | Description
get_Properties | Retrieves the IReposProperties interface pointer. The IReposProperties interface provides access to the Properties collection.

IrepositoryItem Method | Description
Delete | Deletes a Repository item.
get_Interface | Retrieves an interface pointer to the specified item interface.
get_Name | Retrieves the name associated with an item.
get_Repository | Retrieves the IRepository interface pointer for an item's open Repository instance.
get_Type | Retrieves the type of an item.
Lock | Locks the item.
put_Name | Sets the name associated with an item.

IrepositoryObject Method | Description
get_InternalID | Retrieves the internal identifier for a Repository object.
get_ObjectID | Retrieves the object identifier for a Repository object.

IrepositoryObjectVersion Method | Description
CreateVersion | Creates a new version of an object as a successor to the current object version.
FreezeVersion | Disallows further modification of the (non-annotational) property values or origin collections of the current object version.
get_IsFrozen | Determines whether the current object version is frozen.
get_ObjectVersions | Retrieves an interface pointer to the collection of all versions of the current object.
get_PredecessorCreationVersion | Retrieves an interface pointer to the predecessor object version from which the current object version was created.
get_PredecessorVersions | Retrieves an interface pointer to the collection of all predecessor versions of the current object version.
get_ResolutionType | Returns an indication of which resolution technique the Repository used in returning the particular version of the current object to you.
get_SuccessorVersions | Retrieves an interface pointer to the collection of all successor versions of the current object version.
get_VersionID | Retrieves the object-version identifier of the current object version.
get_VersionInternalID | Retrieves the internal object-version identifier of the current object version.
IsVersionOfSameItemAs | Determines whether the current object version and another object version are versions of the same Repository object.
MergeVersion | Changes the current object version by combining its property values and collections with another object version's.


IRepositoryObjectVersion::CreateVersion

Creates a new version of an object as a successor to the current object version.

HRESULT CreateVersion(
VARIANT sVersionID
IRepositoryObjectVersion **ppCreatedVersion
);

Parameters

sVersionID

[in]
The object-version identifier to be assigned to the new object version. If you want the Repository to assign an object-version identifier, use a value of EXT_VERSIONID_NULL.

**ppCreatedVersion

[out]
The IRepositoryObjectVersion interface pointer for the newly created object version.

Return Value

S_OK

The method completed successfully.

Error

Values

This method failed to complete successfully.

Remarks

The current object version must be frozen.

The Repository creates the new version as unfrozen. Its property values are identical to the current object version's property values.

For each of the predecessor version's origin relationship collections, the Repository takes this action:

  • If the corresponding relationship type has the COLLECTION_NEWORGVERSIONSPARTICIPATE flag set, the Repository copies the collection to the newly created version.

  • If the corresponding relationship type does not have the COLLECTION_NEWORGVERSIONSPARTICIPATE flag set, the Repository does not copy the collection to the new version.

You cannot invoke this method while operating in a workspace.


IRepositoryObjectVersion::FreezeVersion

Disallows further modification of the (non-annotational) property values or origin collections of the current object version.

HRESULT FreezeVersion(void);

Return Value

S_OK

The method completed successfully.

Error

Values

This method failed to complete successfully.

Remarks

After you freeze an object version, you cannot change its non-annotational property values. However, you can change the value of any of its annotational properties.

After you freeze an object, you cannot enlarge or shrink any of its origin collections. You cannot pin, unpin, rename or resequence any of the items in any of its origin collections. Furthermore, you cannot change any of the individual versioned relationships in any of the origin collections. That is, you cannot enlarge an item's set of target object versions; pin a target object version, and you cannot unpin the pinned target object version.

If you call this method for an item currently checked out to any workspace (including the workspace in which you are working), it returns an error.

If the to-be-frozen object version includes any non-null origin collection whose corresponding collection type has the COLLECTION_REQUIRESFREEZE flag set, and that non-null collection includes an item whose TargetVersions collection contains a non-frozen object version, the method fails.


IRepositoryObjectVersion::get_IsFrozen

Determines whether the current object version is frozen.

HRESULT get_IsFrozen(
VARIANT_BOOL *pbFrozen
);

Parameters

*pbFrozen

[out]
TRUE if the current object version is frozen; FALSE if it is not frozen.

Return Value

S_OK

The method completed successfully.

Error

Values

This method failed to complete successfully.


IRepositoryObjectVersion::get_ObjectVersions

Retrieves an interface pointer to the collection of all versions of the current object.

HRESULT get_ObjectVersions(
IVersionCol **ppObjVersions
);

Parameters

**ppObjVersions

[out]
The IVersionCol interface pointer for the collection of object versions.

Return Value

S_OK

The method completed successfully.

Error

Values

This method failed to complete successfully.

Remarks

Within the returned collection, the Repository sequences the items in order of their creation, with the oldest object version first.

You cannot modify the collection. To add a new object version, use IRepositoryObjectVersion::CreateVersion.


IRepositoryObjectVersion::get_PredecessorCreationVersion

Retrieves an interface pointer to the predecessor object version from which the current object version was created.

HRESULT get_PredecessorCreationVersion(
IRepositoryObjectVersion **ppPredCreationVersion
);

Parameters

**ppPredCreationVersion

[out]
The IRepositoryObjectVersion interface pointer for the object version from which the current object version was created.

Return Value

S_OK

The method completed successfully.

Error

Values

This method failed to complete successfully.

Remarks

If you invoke this method for the first version of an object, it returns an error.


IRepositoryObjectVersion::get_PredecessorVersions

Retrieves an interface pointer to the collection of all predecessor versions of the current object version.

HRESULT get_PredecessorVersions(
IVersionCol **ppPredVersions
);

Parameters

**ppPredVersions

[out]
The IVersionCol interface pointer for the collection of predecessor object versions.

Return Value

S_OK

The method completed successfully.

Error

Values

This method failed to complete successfully.

Remarks

This method returns only the immediate predecessors of the current object version.

If you invoke this method for the first version of an object, it returns an empty collection.

Within the returned collection, the Repository sequences the items in order of their creation, with the oldest object version first.

You cannot modify the collection.


IRepositoryObjectVersion::get_ResolutionType

Returns an indication of the resolution technique by which the Repository chose to give you a reference to the current version (rather than a reference to any other version of the same object).

HRESULT get_ResolutionType(
LONG *pResolutionType
);

Parameters

*pResolutionType

[out]
One of four possible values:

  • VersionInWorkspace

  • PinnedVersion

  • LatestVersion

  • SpecifiedVersion

Return Value

S_OK

The method completed successfully.

Error

Values

This method failed to complete successfully.

Remarks

  • The Repository automatically sets the value of the ResolutionType property whenever you retrieve an object version.


IRepositoryObjectVersion::get_SuccessorVersions

Retrieves an interface pointer to the collection of all successor versions of the current object version.

HRESULT get_SuccessorVersions(
IVersionCol **ppSuccVersions
);

Parameters

**ppTargetVersions

[out]
The IVersionCol interface pointer for the collection of successor object versions.

Return Value

S_OK

The method completed successfully.

Error

Values

This method failed to complete successfully.

Remarks

This method returns only the immediate successors of the current object version.

If the current object version has no successors, this method returns an empty collection.

Within the returned collection, the Repository sequences the items in order of their creation, with the oldest object version first.

You cannot modify the collection. To add a new successor to the current object version, use IRepositoryObjectVersion::CreateVersion.


IRepositoryObjectVersion::get_VersionID

Retrieves the object-version identifier of the current object version.

HRESULT get_VersionID(
VARIANT *psVersionID
);

Parameters

*psVersionID

[out]
The object-version identifier of the current object version.

Return Value

S_OK

The method completed successfully.

Error

Values

This method failed to complete successfully.


IRepositoryObjectVersion::get_VersionInternalID

Retrieves the internal object-version identifier of the current object version.

HRESULT get_VersionInternalID(
VARIANT *psVersionID
);

Parameters

*psVersionID

[out]
The internal object-version identifier of the current object version.

Return Value

S_OK

The method completed successfully.

Error

Values

This method failed to complete successfully.


IRepositoryObjectVersion::IsVersionOfSameItemAs

Determines whether the current object version and another object version you supply are versions of the same Repository object.

HRESULT IsVersionOfSameItemAs(
IRepositoryObjectVersion *pReposVersion
VARIANT_BOOL *pbSameItem
);

Parameters

*pReposVersion

[in]
Interface pointer to the other object version.

*pbFrozen

[out]
TRUE if the current object version is frozen; FALSE if it is not frozen.

Return Value

S_OK

The method completed successfully.

Error

Values

This method failed to complete successfully.


IRepositoryObjectVersion::MergeVersion

Changes the current object version by combining its property values and origin collections with the property values and origin collections of another version of the same object.

HRESULT MergeVersion(
IRepositoryObjectVersion *pOtherVersion
long fFlags
);

Parameters

*pOtherVersion

[in]
The IRepositoryObjectVersion interface pointer for the predecessor of the merge — the object version whose property values and collections should be merged into the current version.

fFlags

[in]
Indicates which object version is the primary and which is secondary in the merge.

Return Value

S_OK

The method completed successfully.

Error

Values

This method failed to complete successfully.

Remarks

The two object versions must be versions of the same object.

The current object version must be unfrozen. The other object version must be frozen.

MergeVersion compares the property values and collections of each object version to a third version, called the Basis Version.

The Repository considers one of the two to-be-merged object versions to be the primary version, and the other to be the secondary version, according to the value of fFlags you supply. During the merge, the Repository considers each property and origin collection type in turn. For each property, MergeVersion uses this rule:

  • If the primary version differs from the Basis Version, the Repository uses the property value from the primary version. If only the secondary version differs from the Basis Version, the Repository uses the property value from the secondary version. If neither version differs from the Basis Version, the Repository leaves the property value in the current version unchanged.

For each origin collection type whose Collection_MergeWhole flag is set, MergeVersion uses this rule:

  • If the primary version's collection differs (see Comparing Collections) from the Basis Version's collection, the Repository uses the collection from the primary version. If only the secondary version's collection differs from the Basis Version's, the Repository uses the collection from the secondary version. If neither version differs from the Basis Version, the Repository leaves the property value in the current version unchanged.

For each origin collection type whose Collection_MergeWhole flag is not set, MergeVersion combines the items in the two collections as follows:

  • First, MergeVersion includes in the resulting collection each item in the Basis Version not changed in or deleted from either the primary version or secondary version. (See "Comparing Versioned Relationships.")

  • Second, MergeVersion includes in the resulting collection each item in the primary version's collection that differs from the Basis Version.

  • Third, MergeVersion includes in the resulting collection each item in the secondary version's collection that differs Basis Version — provided the corresponding items in the primary version and Basis Version do not differ from each other.

    Note The resulting collection can exclude some items found in the basis object version's collection. For example, if the primary version's collection excludes the item, the resulting collection will exclude the item. Similarly, if the primary version's collection includes an item that is identical to an item in the Basis Version's collection, but the secondary object version excludes the item, the resulting collection will exclude the item.


IRepositoryODBC Interface

The Repository engine stores information in an SQL database. The Repository engine connects to the database server through an ODBC connection. The IRepositoryODBC interface provides you with access to the database through the same (or a similar) ODBC connection.

Care should be taken when accessing the Repository database directly, especially when sharing the Repository's ODBC connection. Specific restrictions are defined in the detailed information for each interface method. Directly accessing the Repository database in a read-only manner is generally considered safe; however, if you tune your Repository application to be dependent upon specific features of your database server, you limit the portability of your application.

When to Use

Use the IRepositoryODBC interface to obtain or release an ODBC connection handle, or to retrieve the ODBC connection string used by the Repository engine.

To obtain a pointer to this interface, use the IRepository::QueryInterface method.

Methods

IUnknown Method | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.

IDispatch Method | Description
GetIDsOfNames | Maps a single member and a set of argument names to a corresponding set of dispatch identifiers.
GetTypeInfo | Retrieves a type information object, which can be used to get the type information for an interface.
GetTypeInfoCount | Retrieves the number of type information interfaces that an object provides (either 0 or 1).
Invoke | Provides access to properties and methods exposed by an Automation object.

IRepositoryODBC Method | Description
ExecuteQuery | Executes the specified SQL query against the Repository database.
FreeConnection | Releases an ODBC connection handle.
get_ConnectionString | Retrieves the ODBC connection string that the Repository engine uses to obtain an ODBC connection.
GetNewConnection | Obtains a new ODBC connection handle using the same connection settings that the Repository engine is using to access the Repository database.
get_ReposConnection | Retrieves the ODBC connection handle that the Repository engine is using to access the Repository database.


IRepositoryODBC::ExecuteQuery

This method executes the specified SQL query against the Repository database, and returns a collection of Repository objects. The columns that are returned by the query must be either just the internal identifier (IntID) column, or the internal identifier and the type identifier (IntID, TypeID) columns of the RTblVersions table.

HRESULT ExecuteQuery( BSTR queryString, IObjectCol **ppICol );

Parameters

queryString

[in]
The SQL query, or the name of a stored procedure.

**ppICol

[out]
The collection of objects that meet the selection criteria of the SQL query.

Return Value

S_OK

The method completed successfully.

Error

Values

This method failed to complete successfully.


IRepositoryODBC::FreeConnection

This method frees an ODBC connection handle.

HRESULT FreeConnection( long Hdbc );

Parameters

Hdbc

[in]
The ODBC connection handle to be released.

Return Value

S_OK

The method completed successfully.

Error

Values

This method failed to complete successfully.

Remarks

Use this method to free the handle obtained via either the get_ReposConnection method or the GetNewConnection method before releasing your open Repository instance.


IRepositoryODBC::get_ConnectionString

This method retrieves the ODBC connection string that the Repository engine uses to obtain an ODBC connection to the Repository database.

HRESULT get_ConnectionString( BSTR szString );

Parameters

szString

[out]
The ODBC connection string.

Return Value

S_OK

The method completed successfully.

Error

Values

This method failed to complete successfully.

Remarks

The ODBC connection string can contain user identification and password information. Take care to protect this information from exposure to unauthorized access.


IRepositoryODBC::GetNewConnection

This method obtains a new ODBC connection handle using the same ODBC connection string that the Repository engine is using to access the Repository database. Using a new ODBC connection handle isolates you from changes made by the Repository engine.

HRESULT GetNewConnection( long *pHdbc );

Parameters

*pHdbc

[out]
A new ODBC connection handle.

Return Value

S_OK

The method completed successfully.

Error

Values

This method failed to complete successfully.

Remarks

Be sure to free the handle obtained via this method before releasing your open Repository instance. To free the connection handle, use the FreeConnection method.


IRepositoryODBC::get_ReposConnection

This method retrieves the ODBC connection handle that the Repository engine is using to access the Repository database.

HRESULT get_ReposConnection( long *pHdbc );

Parameters

*pHdbc

[out]
A copy of the Repository engine's ODBC connection handle.

Return Value

S_OK

The method completed successfully.

Error

Values

This method failed to complete successfully.

Remarks

If you use the Repository engine's ODBC connection handle, you are not isolated from changes made by the Repository engine. For example, uncommitted changes made by the Repository engine will be visible to your application.

When using the Repository engine's ODBC connection handle, you must not change the state of the handle in a way that is incompatible with the Repository engine. Specifically, do not:

  • Change any ODBC connection options.

  • Perform any accesses concurrent with Repository method invocations.

  • Directly commit or roll back a database transaction. The IRepositoryTransaction interface must always be used to manage transactions.

Be sure to free the handle obtained through this method before releasing your open Repository instance. To free the connection handle, use the FreeConnection method.


IRepositoryTransaction Interface

The Repository supports transactional processing. Repository methods that are reading data from the Repository may be executed outside of a transaction, but methods that write data must be bracketed within a transaction. Only one transaction may be active at a time for each opened Repository instance. Nesting of Begin/Commit method invocations is permitted, but no actual nesting of transactions occurs.

When to Use

Use the Repository Transaction interface to begin, commit, or abort a Repository transaction. You can also use this interface to retrieve the information about the transactional state of an opened Repository instance, and to set transaction options.

Methods

IUnknown Method | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.

IDispatch Method | Description
GetIDsOfNames | Maps a single member and a set of argument names to a corresponding set of dispatch identifiers.
GetTypeInfo | Retrieves a type information object, which can be used to get the type information for an interface.
GetTypeInfoCount | Retrieves the number of type information interfaces that an object provides (either 0 or 1).
Invoke | Provides access to properties and methods exposed by an Automation object.

IRepositoryTransaction Method | Description
Abort | Cancels a currently active transaction.
Begin | Begins a new transaction.
Commit | Commits an active transaction.
Flush | Flushes uncommitted changes to the Repository database.
GetOption | Retrieves a transaction option.
get_Status | Tells whether or not there is a currently active transaction.
SetOption | Sets a transaction option.


IRepositoryTransaction::Abort

This method cancels the currently active transaction for an open Repository. All updates made during the transaction are undone. The nested transaction count is set to zero.

HRESULT Abort( void );

Return Value

S_OK

The method completed successfully.

Error

Values

This method failed to complete successfully.


IRepositoryTransaction::Begin

This method increments the nested transaction count by one. If there is no active transaction, this method begins a transaction for the open Repository instance.

HRESULT Begin( void );

Return Value

S_OK

The method completed successfully.

Error

Values

This method failed to complete successfully.


IRepositoryTransaction::Commit

This method decrements the nested transaction count for an open Repository instance. If the currently active transaction is not nested, all changes made to Repository data within the transaction are committed to the Repository database. A transaction is not nested if the nested transaction count equals one.

HRESULT Commit( void );

Return Value

S_OK

The method completed successfully.

Error

Values

This method failed to complete successfully.


IRepositoryTransaction::Flush

This method flushes cached changes to the Repository database.

Unless you have set the exclusive-write-through-mode transaction option, changes that you make within the scope of a transaction are cached, and are not written to the database until the transaction is committed. If a concurrent SQL query is run against the Repository database, the result of the query will not reflect the uncommitted changes (this is normally the desired behavior).

If your Repository application must be able to see uncommitted changes in SQL queries, you can use the Flush method to write uncommitted changes to the Repository database. All changes made within the scope of the current transaction are flushed. Flushing uncommitted changes does not affect your ability to cancel a transaction through the Abort method.

HRESULT Flush( void );

Return Value

S_OK

The method completed successfully.

Error

Values

This method failed to complete successfully.


IRepositoryTransaction::GetOption

Use this method to retrieve the value of a transaction option for an open Repository instance.

HRESULT GetOption(
long iOption,
VARIANT *psValue
);

Parameters

iOption [in]
The transaction option to retrieve. For a list of valid values and their meanings, see the TransactionFlags Enumeration.

*psValue

[out]
The value of the specified transaction option.

Return Value

S_OK

The method completed successfully.

Error

Values

This method failed to complete successfully.


IRepositoryTransaction::get_Status

Use this method to determine whether or not there is a currently active transaction.

HRESULT get_Status( long *piStatus );

Parameters

*piStatus

[out]
The current transaction status. If the value is zero, no transaction is active. If the value is nonzero, a transaction is active.

Return Value

S_OK

The method completed successfully.

Error

Values

This method failed to complete successfully.

Remarks

A transaction is considered active until the Commit method has successfully executed and the nested transaction count has been decremented to zero. Depending upon the data-flushing capabilities of the underlying database server, the data associated with a committed transaction may or may not be written to the physical storage device when the Commit method returns control to its caller.


IRepositoryTransaction::SetOption

Use this method to set one of the transaction options for an open Repository instance. You cannot set a transaction option while a transaction is active.

HRESULT SetOption(
ULONG iOption,
VARIANT sValue
);

Parameters

iOption [in]
The transaction option to set. For a list of valid values and their meanings, see the TransactionFlags Enumeration.

sValue

[in]
The value of the specified transaction option.

Return Value

S_OK

The method completed successfully.

Error

Values

This method failed to complete successfully.


IReposProperties Interface

The IReposProperties interface provides access to the Properties collection. The Properties collection gives you a convenient mechanism to enumerate through all of the persistent properties and collections of an interface, when you don't already know the names of all of the interface members.

When you instantiate an Automation object that represents an object from your tool information model, and that object conforms to a class for which there is no custom implementation (in other words, you have provided no software implementation of the class), the Repository will provide an interface implementation for you. This interface implementation uses IRepositoryDispatch as its dispatch interface. This dispatch interface contains one additional method, the get_Properties method, that returns an IReposProperties interface pointer.

This support enables the Automation programmer to use syntax like:

Dim firstProperty As ReposProperty
Set firstProperty = repObject.Properties(1)

The second statement is resolved like this:

  1. In this example, repObject is an Automation instantiation of a Repository object where the default implementation has been used.

  2. The Properties term is the Automation level name for the get_Properties method that is supplied by the IRepositoryDispatch dispatch interface.

  3. The get_Properties method returns the interface pointer to the IReposProperties interface.

  4. The default method of the IReposProperties interface is the get_Item method, which returns an IReposProperty interface pointer for the specified property object in the Properties collection.

At this point, the Automation programmer has access to the first property in the collection through the firstProperty object variable.

When to Use

Use the IReposProperties interface to access the properties and collections of a Repository object, when no custom implementation is available, and you do not already know what members are exposed by the object's interface. With the IReposProperties interface, you can:

  • Get a count of the number of members in the collection.

  • Retrieve an IReposProperty interface pointer to one of the members in the collection.

  • Enumerate the members in the collection.

Methods

IUnknown Method | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.

IDispatch Method | Description
GetIDsOfNames | Maps a single member and a set of argument names to a corresponding set of dispatch identifiers.
GetTypeInfo | Retrieves a type information object, which can be used to get the type information for an interface.
GetTypeInfoCount | Retrieves the number of type information interfaces that an object provides (either 0 or 1).
Invoke | Provides access to properties and methods exposed by an Automation object.

IReposProperties Method | Description
get_Count | Retrieves the count of the number of members in the collection.
get_Item | Retrieves the IReposProperty interface pointer for the specified member of the collection.
get_Type | Retrieves the type of the interface to which these properties are attached.
_NewEnum | Retrieves a standard Automation enumeration interface pointer for the collection.

Remarks

Only persistent members (that is, members that are stored in the Repository) are represented in the Properties collection.


IReposProperties::get_Count

This method is used to retrieve a count of the number of persistent members (properties and collections) that are in the Properties collection.

HRESULT get_Count( long *piCount );

Parameters

*piCount

[out]
The number of members in the collection.

Return Value

S_OK

The method completed successfully.

Error

Values

This method failed to complete successfully.


IReposProperties::get_Item

This method retrieves the specified member from the Properties collection.

HRESULT get_Item(
VARIANT sItem,
IReposProperty **ppIReposProperty
);

Parameters

sItem

[in]
Identifies the item to be retrieved from the collection. This parameter can be either the index or the name of the member, or the object identifier of the property definition object for the member.

*ppIReposProperty

[out]
The IReposProperty interface pointer for the specified collection member.

Return Value

S_OK

The method completed successfully.

Error

Values

This method failed to complete successfully.


IReposProperties::get_Type

Use the get_Type method to retrieve the object identifier for the interface definition of the interface to which these properties are attached. This object identifier is referred to as the type of the interface.

HRESULT get_Type( VARIANT *psTypeId );

Parameters

*psTypeId [out]
The object identifier for the interface definition object.

Return Value

S_OK

The method completed successfully.

Error

Values

This method failed to complete successfully.


IReposProperties::_NewEnum

This method retrieves an enumeration interface pointer for the Properties collection. This interface is a standard Automation enumeration interface. It supports the Clone, Next, Reset, and Skip methods. You can use the enumeration interface to step through the members in the collection.

HRESULT _NewEnum( IUnknown **ppIEnumProps );

Parameters

*ppIEnumProps

[out]
The enumeration interface pointer.

Return Value

S_OK

The method completed successfully.

Error

Values

This method failed to complete successfully.


IReposProperty Interface

The IReposProperty interface provides access to a persistent member (a property or collection) of a tool information model interface.

When you instantiate an Automation object that represents an object from your tool information model, and that object conforms to a class for which there is no custom implementation (in other words, you have provided no software implementation of the class), the Repository will provide an interface implementation for you. This interface implementation uses IRepositoryDispatch as its dispatch interface.

The IRepositoryDispatch interface is an enhanced IDispatch interface; in addition to all of the standard IDispatch methods, IRepositoryDispatch also provides access to the Properties collection. The Properties collection gives you a convenient mechanism to enumerate through all of the persistent properties and collections of an interface. The IReposProperty interface can be used to access the individual members in the Properties collection.

This support enables the Automation programmer to use syntax like:

Dim firstPropName As String
Let firstPropName = repObject.Properties(1).Name

The second statement resolves like this:

  1. In this example, repObject is an Automation instantiation of a Repository object where the default implementation has been used.

  2. The Properties term is the Automation level name for the get_Properties method that is supplied by the IRepositoryDispatch interface.

  3. The get_Properties method returns the interface pointer to the IReposProperties interface.

  4. The default method of the IReposProperties interface is the get_Item method, which returns an IReposProperty interface pointer for the specified property object in the Properties collection.

  5. The Name term is the Automation level name for the get_Name method that is supplied by the IReposProperty interface.

At this point, the Automation programmer has access to the name of the first property in the collection through the firstPropName variable.

When to Use

Use the IReposProperty interface to access a persistent interface member, when no custom implementation is available, and you do not already know the type or name of the member. With this interface, you can:

  • Retrieve the name of a property or collection.

  • Retrieve the type of a property or collection.

  • Get or set the value of a property.

Methods

IUnknown Method | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.

IDispatch Method | Description
GetIDsOfNames | Maps a single member and a set of argument names to a corresponding set of dispatch identifiers.
GetTypeInfo | Retrieves a type information object, which can be used to get the type information for an interface.
GetTypeInfoCount | Retrieves the number of type information interfaces that an object provides (either 0 or 1).
Invoke | Provides access to properties and methods exposed by an Automation object.

IReposProperty Method | Description
get_Type | Retrieves the type of a persistent interface member.
get_Name | Retrieves the name of a persistent interface member.
get_Value | Retrieves the value of a persistent interface member.
put_Value | Sets the value of a persistent property.

Remarks

Only persistent members (that is, members that are stored in the Repository) can be accessed by the IReposProperty interface.


IReposProperty::get_Name

This method is used to retrieve the name of a persistent interface member (a property or collection).

HRESULT get_Name( BSTR *pName );

Parameters

*pName

[out]
The name of the member.

Return Value

S_OK

The method completed successfully.

Error

Values

This method failed to complete successfully.


IReposProperty::get_Type

This method retrieves the type of a persistent property or collection; that is, it returns the object identifier of the definition object to which the member conforms.

HRESULT get_Type( VARIANT *psTypeId );

Parameters

*psTypeId

[out]
The object identifier of the member's definition object.

Return Value

S_OK

The method completed successfully.

Error

Values

This method failed to complete successfully.


IReposProperty::get_Value

This method retrieves the value of a persistent interface member (a property or collection). If the member is a collection, the retrieved value is a pointer to the interface that supports that type of collection.

HRESULT get_Value( VARIANT *psValue );

Parameters

*psValue

[out]
The property value.

Return Value

S_OK

The method completed successfully.

Error

Values

This method failed to complete successfully.


IReposProperty::put_Value

This method sets the value of a persistent interface property. The type of the input parameter is converted to the storage data type of the property. If the type of the input parameter cannot be successfully converted to the storage data type, this method will return an error.

HRESULT put_Value( VARIANT sValue );

Parameters

sValue

[in]
The property value to be set.

Return Value

S_OK

The method completed successfully.

Error

Values

This method failed to complete successfully.

Remarks

You cannot set the value of a read-only property or a collection.


ISummaryInformation Interface

The ISummaryInformation interface maintains Comments and ShortDescription properties for objects that expose this interface.

When to Use

Use the ISummaryInformation interface to access the Comments and ShortDescription properties of a Repository object.

Properties

Property | Description
Comments | General comments about the object.
ShortDescription | Brief description of the object.

Methods

IUnknown Method | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.

IDispatch Method | Description
GetIDsOfNames | Maps a single member and a set of argument names to a corresponding set of dispatch identifiers.
GetTypeInfo | Retrieves a type information object, which can be used to get the type information for an interface.
GetTypeInfoCount | Retrieves the number of type information interfaces that an object provides (either 0 or 1).
Invoke | Provides access to properties and methods exposed by an Automation object.

IRepositoryDispatch Method | Description
get_Properties | Retrieves the IreposProperties interface pointer. The IReposProperties interface provides access to the properties exposed by the ISummaryInformation interface.


ISummaryInformation Comments Property

This property contains general comments about an object. Up to 65,536 bytes of information may be stored in this property.

Dispatch Identifier: DISPID_Comments (66)

Property Data Type: Long varchar


ISummaryInformation ShortDescription Property

This property contains a short description of an object. Up to 255 bytes of information may be stored in this property.

Dispatch Identifier: DISPID_ShortDesc (67)

Property Data Type: varchar


ITargetObjectCol Interface

A target object collection is a set of Repository object versions that are attached to a particular source Repository object version through a relationship collection. At most one version of each Repository object is present in any target object collection.

When to Use

Use the ITargetObjectCol interface to manage the Repository objects that belong to a particular relationship collection. With this interface, you can:

  • Get a count of the number of objects in the collection.

  • Enumerate the objects in the collection.

  • Add and remove objects to and from the collection.

  • If the collection is sequenced, place an object in a specific spot in the collection sequence.

  • Retrieve an IRepositoryObject pointer to one of the objects in the collection.

  • Obtain the type of the collection.

  • Retrieve an interface pointer for the collection's source object.

  • Refresh the cached image of the target object collection.

Methods

IUnknown Method | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.

IDispatch Method | Description
GetIDsOfNames | Maps a single member and a set of argument names to a corresponding set of dispatch identifiers.
GetTypeInfo | Retrieves a type information object, which can be used to get the type information for an interface.
GetTypeInfoCount | Retrieves the number of type information interfaces that an object provides (either 0 or 1).
Invoke | Provides access to properties and methods exposed by an Automation object.

IObjectCol Method | Description
Count | Retrieves a count of the number of objects in the collection.
_NewEnum | Retrieves an enumeration interface pointer for the collection. This interface is a standard Automation enumeration interface. It supports the Clone, Next, Reset, and Skip methods.
Item | Retrieves an IRepositoryObject interface pointer for the specified collection object.
Refresh | Refreshes the cached image of the target object collection.

ITargetObjectCol Method | Description
Add | Adds an object to the collection.
get_Source | Retrieves an interface pointer for the collection's source object.
get_Type | Retrieves the object identifier for the collection's definition object.
Insert | Inserts an object into a specific spot in a sequenced collection.
Move | Moves an object from one spot to another in a sequenced collection.
Remove | Removes an object from the collection.

Remarks

The ITargetObjectCol interface is very similar to the IRelationshipCol interface. Use the ITargetObjectCol interface when you are primarily interested in working with objects. Use the IRelationshipCol interface when you are primarily interested in working with relationships between objects.


ITargetObjectCol::Add

This method is used to add a new item to a Repository object collection, when the sequencing of objects in the collection is not important. An interface pointer for the new relationship is passed back to the caller.

HRESULT Add(
IDispatch *plReposObj,
BSTR Name,
IRelationship **pplRelship
);

Parameters

*plReposObj

[in]
The Repository object version to be added to the collection.

Name

[in]
The name to be assigned to the object that is being added to the collection.

*pplRelship

[out]
The newly added object's relationship interface pointer.

Return Value

S_OK

The method completed successfully.

Error

Values

This method failed to complete successfully.

Remarks

Objects may only be added to a collection when the collection's source object is also the collection's origin object.

When you call this method, the origin version must be unfrozen.

You can use this method to create a new versioned relationship between the source object version and a version of the target object. You cannot use it to enlarge a versioned relationship. If the source object version already has a relationship to any version of the target object, this method will fail. You can include another version of the target object in the versioned relationship by adding an item to the versioned relationship's TargetObjects collection.

The value of plReposObj is the specific version of the target object.


ITargetObjectCol::get_Source

This method retrieves the IRepositoryObject interface pointer for the collection's source object version.

HRESULT get_Source( IRepositoryObject **ppIInterface );

Parameters

*ppIInterface

[out]
The interface pointer of the IRepositoryObject interface for the source object.

Return Value

S_OK

The method completed successfully.

Error

Values

This method failed to complete successfully.


ITargetObjectCol::get_Type

This method retrieves the type of the collection; that is, it returns the object identifier for the collection's definition object.

HRESULT get_Type( VARIANT *pColDefObjId );

Parameters

*pColDefObjId

[out]
The object identifier of the collection's definition object.

Return Value

S_OK

The method completed successfully.

Error

Values

This method failed to complete successfully.


ITargetObjectCol::Insert

This method adds an object to the collection at a specified point in the collection sequence. An interface pointer for the new relationship is passed back to the caller.

HRESULT Insert(
IDispatch *pIReposObj,
long iIndex,
BSTR Name,
IRelationship **ppIRelship
);

Parameters

*pIReposObj

[in]
The Repository object to be inserted into the collection sequence.

iIndex

[in]
The index of the sequence location where the object is to be inserted. If another object is already present at this sequence location, the new object is inserted before the existing object.

Name

[in]
The name of the object. Set this parameter to a null string if the object is not referred to by name.

*ppIRelship

[out]
The IRelationship interface pointer for the new object's relationship with the collection's origin object.

Return Value

S_OK

The method completed successfully.

Error

Values

This method failed to complete successfully.

Remarks

Objects may only be inserted into a collection when the collection's source object is also the collection's origin object.

This method can only be used for collections that are sequenced.

When you call this method, the origin version must be unfrozen.

You can use this method to insert a new versioned relationship between the source object version and a version of the target object. You cannot use it to enlarge a versioned relationship. If the source object version already has a relationship to any version of the target object, this method will fail. You can include another version of the target object in the versioned relationship by adding an item to the versioned relationship's TargetObjects collection.

The value of plReposObj is the specific version of the target object.


ITargetObjectCol::Move

This method moves an object from one point in the collection sequence to another point.

HRESULT Move( long iIndexFrom, long iIndexTo );

Parameters

iIndexFrom

[in]
The index of the object to be moved in the collection sequence.

iIndexTo

[in]
The index of the sequence location to which the object is to be moved.

Return Value

S_OK

The method completed successfully.

Error

Values

This method failed to complete successfully.

Remarks

This method can only be used for collections that are sequenced.

The origin object version must be unfrozen.


ITargetObjectCol::Remove

This method removes the specified object from the collection. The exact behavior of this method depends on whether the relationship collection is an origin collection or a destination collection.

If the relationship collection is an origin collection, this method deletes the versioned relationship.

If the relationship collection is a destination collection, this method first performs object-version resolution to yield a single target-object version, and then it removes that target-object version from the relationship's TargetVersions collection.

HRESULT Remove( VARIANT sItem );

Parameters

sItem

[in]
Identifies the item to be retrieved from the collection. This parameter can be either the index, the name, or the object identifier of the item.

Return Value

S_OK

The method completed successfully.

Error

Values

This method failed to complete successfully.

Remarks

An object can be removed by name only if it is the destination object of a naming relationship.

If the source is the origin, the origin version must be unfrozen.

If the relationship is a destination relationship and the resolution strategy yields a target object version that is frozen, this method fails.


IVersionAdminInfo Interface

Use this interface to retain and manipulate administrative information about Repository object versions.

When to Use

By default, no class implements this interface. But within your information models, any class can implement this interface, thereby ensuring that for each object conforming to that class, the Repository automatically retains the properties listed below.

Methods

IUnknown Method | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.

IDispatch Method | Description
GetIDsOfNames | Maps a single member and a set of argument names to a corresponding set of dispatch identifiers.
GetTypeInfo | Retrieves a type information object, which can be used to get the type information for an interface.
GetTypeInfoCount | Retrieves the number of type information interfaces that an object provides (either 0 or 1).
Invoke | Provides access to properties and methods exposed by an Automation object.

Properties

Property | Description
CreateByUser | The user who created the object version.
ModifyByUser | The user who made the most recent modification to the object version.
VersionCreateTime | Date and time the object version was created.
VersionModifyTime | Date and time of the most recent modification to the object version.


IVersionAdminInfo CreateByUser Property

This property indicates the user who created the object version.

Dispatch Identifier: DISPID_CreateByUser (83)

Property Data Type: String


IVersionAdminInfo ModifyByUser Property

This property indicates the user who most recently modified the object version. If the object version is frozen, this property indicates the user who froze the object version.

Dispatch Identifier: DISPID_ModifyByUser (84)

Property Data Type: String


IVersionAdminInfo VersionCreateTime Property

This property contains the date and time at which the object version was created.

Dispatch Identifier: DISPID_VersionCreateTime (81)

Property Data Type: DateTime


IVersionAdminInfo VersionModifyTime Property

This property contains the date and time at which the object version was most recently modified. If the object version is frozen, this property is the date and time at which the object version was frozen.

Dispatch Identifier: DISPID_VersionModifyTime (82)

Property Data Type: String


IVersionCol Interface

A version collection is a collection of object versions. There are several different version collections you can establish:

  • The set of all versions of an object. (See the Versions-of-Object collection.)

  • The predecessors of an object version. (See the Predecessor-Versions collection.)

  • The successors of an object version. (See the Successor-Versions collection.)

  • The set of versions of a particular target object that are related to a particular source object version. (See the Target-Versions collection.)

  • The set of object versions present in a workspace. (See the Versions-of-Workspace collection.)

  • The set of workspaces in which a particular item is present. (See the Workspaces-of-Version collection.)

  • The set of object versions checked out to a workspace. (See the Checkouts-of-Workspace collection.)

When to Use

Use the IVersionCol interface to manage the contents of a workspace, to manage the target object versions of a versioned relationship, to navigate an object’s version graph, or to manipulate all the versions of a particular object.

Methods

IUnknown Method | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.

IDispatch Method | Description
GetIDsOfNames | Maps a single member and a set of argument names to a corresponding set of dispatch identifiers.
GetTypeInfo | Retrieves a type information object, which can be used to get the type information for an interface.
GetTypeInfoCount | Retrieves the number of type information interfaces that an object provides (either 0 or 1).
Invoke | Provides access to properties and methods exposed by an Automation object.

IVersionCol Method | Description
Add | Adds an object version to the collection.
get_Count | Returns the number of items in the collection.
get_Item | Returns an interface pointer to an item of the collection.
_NewEnum | Retrieves an enumeration interface pointer for the collection.
Refresh | Refreshes the cached image of the collection.
Remove | Removes an object version from the collection.


IVersionCol::Add

Adds an object version to the collection.

HRESULT Add(
IRepositoryObjectVersion *pIReposVersion
);

Parameters

*pIReposVersion

[in]
The IRepositoryObjectVersion interface pointer to the object version to be added to the collection.

Return Value

S_OK

The method completed successfully.

Error

Values

This method failed to complete successfully.

Remarks

There are many different kinds of Object-Version collections. You can apply this method to some of them, but not to others. This method works for:

  • Target-Versions collections. You can use this method to enlarge the set of versions of a particular target object that are related to a particular source object.

  • Versions-of-Workspace collections. You can use this method to add an object version to the set of items contained in the workspace.

This method does not work for:

  • Predecessor-Versions collection. To enlarge an object version’s set of predecessors, use the MergeVersion method of the IRepositoryObjectVersion interface.

  • Successor-Versions collection. To enlarge an object version’s set of successors, use the CreateVersion method of the IRepositoryObjectVersion interface.

  • Versions-of-Object collection. To enlarge an object’s set of versions, use the CreateVersion method of the IRepositoryObjectVersion interface.

  • Workspaces-of-Version collection. To enlarge the set of workspaces to which an object version belongs, you do not add a workspace to an object version—rather you add the object version to a workspace. In other words, you use the Add method of the IVersionCol interface, but the version collection you are manipulating is the Versions-of-Workspace collection, not the Workspaces-of-Version collection.

  • Checkouts-of-Workspace collection To check out another item to a workspace, use the Checkout method of the IWorkspaceItem interface.


IVersionCol::get_Count

Retrieves count of the number of items in the collection.

HRESULT get_Count(
long *piCount
);

Parameters

*piCount

[out]
The number of items in the collection.

Return Value

S_OK

The method completed successfully.

Error

Values

This method failed to complete successfully.


IVersionCol::get_Item

Retrieves the specified object version from the collection.

HRESULT get_Item(
VARIANT sItem
IRepositoryObjectVersion **ppIReposVersion
);

Parameters

sItem

[in]
Identifies the item to be retrieved from the collection. This parameter can be the index, the object identifier, or the object-version identifier of the item.

**ppIReposVersion

[out]
The IRepositoryObjectVersion interface pointer for the retrieved object versions.

Return Value

S_OK

The method completed successfully.

Error

Values

This method failed to complete successfully.

Remarks

There are many different kinds of version collection. The sItem parameter can be an object identifier for some version collections, but not for others. It can be an object identifier only for the Versions-of-Workspace collection, the Workspaces-of-Version collection, or the Checkouts-of-Workspace collection.


IVersionCol::_NewEnum

This method retrieves an enumeration interface pointer for the relationship collection. This interface is a standard Automation enumeration interface. It supports the Clone, Next, Reset, and Skip methods. You can use the enumeration interface to step through the relationships in the collection.

HRESULT _NewEnum(
IUnknown **ppIEnum
);

Parameters

**ppIEnum

[out]
The enumeration interface pointer.

Return Value

S_OK

The method completed successfully.

Error

Values

This method failed to complete successfully.


IVersionCol::Refresh

This method refreshes the cached image of the collection. All unchanged data for items in the collection is flushed from the cache.

HRESULT Refresh(
long iMilliseconds
);

Parameters

iMilliseconds

[in]
All unchanged data relation to the collection that has been in the cache for longer than IMilliseconds milliseconds is refreshed. To refresh all unchanged data, set this value to zero.

Return Value

S_OK

The method completed successfully.

Error

Values

This method failed to complete successfully.


IVersionCol::Remove

Removes an object version from the collection.

HRESULT Remove(
VARIANT sItem
);

Parameters

sItem

[in]
Identifies the item to be removed from the collection. This parameter can be the index, the object identifier, or the Object-Version identifier of the item.

Return Value

S_OK

The method completed successfully.

Error

Values

This method failed to complete successfully.

Remarks

There are many different kinds of Object-Version collections. You can apply this method to some of them, but not to others. This method works for:

  • Target-Versions collections. You can use this method to reduce the set of versions of a particular target object that are related to a particular source object.

  • Versions-of-Workspace collections. You can use this method to remove an object version from the set of items contained in the workspace.

This method fails for:

  • Predecessor-Versions collections. To enlarge an object version’s set of predecessors, use MergeVersion.

  • Successor-Versions collections. To enlarge an object version’s set of successors, use the CreateVersion method of the IRepositoryObjectVersion interface.

  • Versions-of-Object collections. To enlarge an object’s set of versions, use the CreateVersion method of the IRepositoryObjectVersion interface.

  • Workspaces-of-Version collections. To remove a workspace from the set of workspaces in which an Object Version is present, you must explicitly remove the object version from that workspace’s Versions-of-Workspace collection.

  • Checkouts-of-Workspace collections. To reduce the number of items checked out to a workspace, use the Checkin method of the IWorkspaceItem interface.

The sItem parameter can be an object identifier for some version collections, but not for others. It can be an object identifier only for the Versions-of-Workspace collection, the Workspaces-of-Version collection, or the Checkouts-of-Workspace collection.


IVersionedRelationship Interface

A versioned relationship connects one source object version to any number of versions of a destination object. Versioned relationships are items within relationship collections.

When to Use

Use the IVersionedRelationship Interface to manipulate a relationship, or to retrieve the source, target, origin, or destination object for a relationship.

Methods

Iunknown Method | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.

Idispatch Method | Description
GetIDsOfNames | Maps a single member and a set of argument names to a corresponding set of dispatch identifiers.
GetTypeInfo | Retrieves a type information object, which can be used to get the type information for an interface.
GetTypeInfoCount | Retrieves the number of type information interfaces that an object provides (either 0 or 1).
Invoke | Provides access to properties and methods exposed by an Automation object.

IRepositoryDispatch Method | Description
get_Properties | Retrieves the IReposProperties interface pointer. The IReposProperties interface provides access to the Properties collection.

IRepositoryItem Method | Description
Delete | Deletes a Repository item.
get_Interface | Retrieves an interface pointer to the specified item interface.
get_Name | Retrieves the name associated with an item.
get_Repository | Retrieves the IRepository interface pointer for an item's open Repository instance.
get_Type | Retrieves the type of an item.
Lock | Locks the item.
put_Name | Sets the name associated with an item.

IRelationship Method | Description
get_Destination | Retrieves an interface pointer to the destination object.
get_Origin | Retrieves an interface pointer to the origin object.
get_Source | Retrieves an interface pointer to the source object.
get_Target | Retrieves an interface pointer to the target object.

IversionedRelationship Method | Description
get_TargetVersions | Returns an interface pointer to the set of target versions of the relationship.
Pin | Establishes one target version as the pinned target version.
Unpin | Ensures that no target version is pinned.


IVersionedRelationship::get_TargetVersions

Retrieves an IVersionCol interface pointer to a collection of object versions. Each item in the collection is a particular version of the target object to which a versioned relationship refers.

HRESULT get_TargetVersions(
IVersionCol **ppTargetVersions
);

Parameters

**ppTargetVersions

[out]
The IVersionCol interface pointer for the collection of target object versions.

Return Value

S_OK

The method completed successfully.

Error

Values

This method failed to complete successfully.


IVersionedRelationship::Pin

Declares a specific target object version of an origin relationship to be the pinned version.

HRESULT Pin(
IRepositoryObjectVersion *pIReposVersion
);

Parameters

*pIReposVersion

[in]
The IRepositoryObjectVersion interface pointer for the object version to be pinned.

Return Value

S_OK

The method completed successfully.

Error

Values

This method failed to complete successfully.

Remarks

You can use this method only for origin relationships. The origin object of the versioned relationship must be unfrozen.

If the origin object of the relationship is checked out to a workspace, the Pin method will work only from within that workspace.

When you pin a target object version for versioned relationship, any previously pinned target object version of the relationship becomes unpinned.

The target object version to be pinned must already participate in the relationship.


IVersionedRelationship::Unpin

Declares that no target object version of an origin versioned relationship is pinned.

HRESULT Unpin(void);

Return Value

S_OK

The method completed successfully.

Error

Values

This method failed to complete successfully.

Remarks

You can use this method only for origin relationships. The origin object of the versioned relationship must be unfrozen.

If the origin object of the versioned relationship is checked out to a workspace, the Unpin method will work only from within that workspace.


IWorkspace Interface

A workspace is a secluded area of the Repository within which you can operate on tool data in isolation from other Repository activity. The IWorkspace interface provides methods for operating on workspaces.

When to Use

Use the IWorkspace interface to manage the object versions present in the workspace, the object versions checked out to the workspace, and to manage the workspace containers in which the workspace is present. (In this release, there is only one workspace container, the Root Object.)

Methods

IUnknown Method | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.

IDispatch Method | Description
GetIDsOfNames | Maps a single member and a set of argument names to a corresponding set of dispatch identifiers.
GetTypeInfo | Retrieves a type information object, which can be used to get the type information for an interface.
GetTypeInfoCount | Retrieves the number of type information interfaces that an object provides (either 0 or 1).
Invoke | Provides access to properties and methods exposed by an Automation object.

IRepositoryDispatch Method | Description
get_Properties | Retrieves the IReposProperties interface pointer. The IReposProperties interface provides access to the Properties collection.

IWorkspace Method | Description
get_Checkouts | Returns the collection of object versions checked out to the workspace.
get_Contents | Returns the collection of object versions present in the workspace.

Collections

Collection | Description
Containers | The collection of objects containing the current workspace.


IWorkspace Containers Collection

This collection specifies the containers of this workspace. The collection contains exactly one item, the Root Object.

Dispatch Identifier: DISPID_WorkspaceContainers (85)

Collection descriptor Descriptor value

Relationship Type | WsContainer_Contains_Workspace
Source Is Origin | No
Minimum Collection Size | One
Maximum Collection Size | Many
Sequenced Collection | No
Deletes Propagated | No
Destinations Named | No
Case Sensitive Names | Not Applicable
Unique Names | Not Applicable

Remarks

Although the collection's maximum size is defined as many, the collection always contains exactly one object, because CReposRoot is the only class implementing IWorkspaceContainer and there is only one object (the Root Object) conforming to the CReposRoot class.


IWorkspace::get_Checkouts

Returns an IVersionCol interface pointer to a collection of object versions currently checked out to the workspace.

HRESULT get_Checkouts(
IVersionCol **ppWSVersions
);

Parameters

**ppWSVersions

[out]
The IVersionCol interface pointer to the collection of object versions checked out to the workspace.

Return Value

S_OK

The method completed successfully.

Error

Values

This method failed to complete successfully.

Remarks

For each Repository object, at most one version can be checked out to the current workspace.


IWorkspace::get_Contents

Returns an IVersionCol interface pointer to a collection of object versions currently present in the workspace.

HRESULT get_Contents(
IVersionCol **ppWSVersions
);

Parameters

**ppWSVersions

[out]
The IVersionCol interface pointer to the collection of object versions present in the workspace.

Return Value

S_OK

The method completed successfully.

Error

Values

This method failed to complete successfully.

Remarks

For each Repository object, at most one version can be present in the current workspace.


IWorkspaceContainer Interface

The IWorkspaceContainer interface contains methods for managing the collection of workspaces within a Repository.

When to Use

Use the IWorkspaceContainer interface to retrieve the collection of workspaces in a Repository.

Methods

IUnknown Method | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.

IDispatch Method | Description
GetIDsOfNames | Maps a single member and a set of argument names to a corresponding set of dispatch identifiers.
GetTypeInfo | Retrieves a type information object, which can be used to get the type information for an interface.
GetTypeInfoCount | Retrieves the number of type information interfaces that an object provides (either 0 or 1).
Invoke | Provides access to properties and methods exposed by an Automation object.

IRepositoryDispatch Method | Description
get_Properties | Retrieves the IReposProperties interface pointer. The IReposProperties interface provides access to the Properties collection.

Collections

Collection | Description
Workspaces | The collection of workspaces contained by this Repository object.


IWorkspaceContainer Workspaces Collection

This collection specifies the workspaces contained in the workspace container. Only the Root Object can be a workspace container.

Dispatch Identifier: DISPID_ContainedWorkspaces (84)

Collection descriptor | Descriptor value
Relationship Type | WsContainer_Contains_Workspace
Source Is Origin | Yes
Minimum Collection Size | Zero
Maximum Collection Size | Many
Sequenced Collection | No
Deletes Propagated | Yes
Destinations Named | Yes
Case Sensitive Names | No
Unique Names | Yes


IWorkspaceItem Interface

The IWorkspaceItem interface contains methods for managing workspace items — object versions that can be present in or checked out to a workspace.

When to Use

Use the IWorkspaceItem interface to manage the participation of object versions within workspaces.

Methods

IUnknown Method | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.

IDispatch Method | Description
GetIDsOfNames | Maps a single member and a set of argument names to a corresponding set of dispatch identifiers.
GetTypeInfo | Retrieves a type information object, which can be used to get the type information for an interface.
GetTypeInfoCount | Retrieves the number of type information interfaces that an object provides (either 0 or 1).
Invoke | Provides access to properties and methods exposed by an Automation object.

IrepositoryDispatch Method | Description
get_Properties | Retrieves the IReposProperties interface pointer. The IReposProperties interface provides access to the Properties collection.

IworkspaceItem Method | Description
Checkin | Terminates the ability to modify the current object version from within the current workspace
Checkout | Establishes the current workspace as the only workspace within which the current object version can be modified.
get_CheckedOutToWorkspace | Returns the workspace to which the current object version is checked out.
get_IsCheckedOut | Indicates whether any workspace has the current object version checked out.
get_Workspaces | Returns the collection of workspaces in which the current object version is present.


IWorkspaceItem::Checkin

Terminates the ability to modify the current object version from within the current workspace.

HRESULT Checkin();

Return Value

S_OK

The method completed successfully.

Error

Values

This method failed to complete successfully.

Remarks

When you call this method, you must be operating within the workspace to which the object version is checked out.


IWorkspaceItem::Checkout

Establishes the current workspace as the only workspace within which the current object version can be modified.

HRESULT Checkout();

Return Value

S_OK

The method completed successfully.

Error

Values

This method failed to complete successfully.

Remarks

If the object version is already checked out to a workspace, this method returns an error.


IWorkspaceItem::get_CheckedOutToWorkspace

Returns an IWorkspace interface pointer of the workspace to which the current object version is checked out.

HRESULT get_CheckedOutToWorkspace(
IWorkspace **ppIWorkspace
);

Parameters

**ppIWorkspace

[out]
The IWorkspace interface pointer of the workspace.

Return Value

S_OK

The method completed successfully.

Error

Values

This method failed to complete successfully.

Remarks

If the object version is not currently checked out to any workspace, this method returns an error.


IWorkspaceItem::get_IsCheckedOut

Determines whether the current workspace item is checked out to any workspace.

HRESULT get_IsCheckedOut(
VARIANT_BOOL *pbCheckedOut
);

Parameters

*pbCheckedOut

[out]
TRUE if the object version is checked out to a workspace; FALSE if the object version is not checked out to any workspace.

Return Value

S_OK

The method completed successfully.

Error

Values

This method failed to complete successfully.


IWorkspaceItem::get_Workspaces

Returns the collection of workspaces in which the current object version is present.

HRESULT get_Workspaces(
IVersionCol **ppIWorkspaces
);

Parameters

**ppIWorkspaces

[out]
The IVersionCol interface pointer to the collection of workspaces in which the object version is present.

Return Value

S_OK

The method completed successfully.

Error

Values

This method failed to complete successfully.

Remarks

If the current object version is not present in any workspaces, this method returns an empty collection.


IClassDef Interface

The IClassDef interface helps you create tool information models, by adding interfaces to a class. To insert a new class definition into a tool information model, use the IReposTypeLib interface.

To complete a class definition, once you have added all of the interfaces, commit the transaction that brackets your class definition modifications.

When to Use

Use the IClassDef interface to:

  • Add a new or existing interface to a class definition.

  • Retrieve the global identifier for the class.

  • Access the collection of interfaces that are part of a class definition.

Properties

Property | Description
ClassID | The global identifier of the class.

Methods

IUnknown Method | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.

IDispatch Method | Description
GetIDsOfNames | Maps a single member and a set of argument names to a corresponding set of dispatch identifiers.
GetTypeInfo | Retrieves a type information object, which can be used to get the type information for an interface.
GetTypeInfoCount | Retrieves the number of type information interfaces that an object provides (either 0 or 1).
Invoke | Provides access to properties and methods exposed by an Automation object.

IRepositoryDispatch Method | Description
get_Properties | Retrieves the IReposProperties interface pointer. The IReposProperties interface provides access to the Properties collection.

IClassDef Method | Description
AddInterface | Adds an existing interface to the class definition.
CreateInterfaceDef | Creates a new interface and adds it to the class definition.
ObjectInstances | Materializes an IObjectCol interface pointer for the collection of all objects in the Repository that conform to this class.

Collections

Collection | Description
Interfaces | The collection of all interfaces that are implemented by a class.


IClassDef::AddInterface

The AddInterface method adds an existing interface to the collection of interfaces that are implemented by a particular class.

HRESULT AddInterface(
IInterfaceDef *plInterfaceDef,
BSTR Flags
);

Parameters

plInterfaceDef

[in]
The interface pointer for the interface that is to be added to the collection of interfaces that are implemented by this class.

Flags

[in]
If the interface that you are adding is the default interface for the class, pass in the string "Default". Otherwise, pass in a null string.

Return Value

S_OK

The method completed successfully.

Error

Values

This method failed to complete successfully.


IClassDef ClassID Property

The global identifier that is assigned to this class.

Dispatch Identifier: DISPID_ClassID

Property Data Type: GUID


IClassDef::CreateInterfaceDef

The CreateInterfaceDef method creates a new interface definition, and adds the interface to the collection of interfaces that are implemented by the class.

HRESULT CreateInterfaceDef(
VARIANT sObjId,
BSTR Name,
VARIANT sIID,
IInterfaceDef *pIAncestor,
BSTR Flags,
IInterfaceDef **ppIInterfaceDef
);

Parameters

sIObjId

[in]
The object identifier to be assigned to the new interface definition object. If this parameter is set to OBJID_NULL, the Repository assigns an object identifier for you.

Name

[in]
The name of the interface that is to be created.

sIID

[in]
The global identifier associated with the signature for this interface. If there is none, set this parameter to zero.

*pIAncestor

[in]
The interface pointer to the base interface from which the interface being added is derived.

Flags

[in]
If the interface that you are adding is the default interface for the class, pass in the string "Default". Otherwise, pass in a null string.

*pplInterfaceDef

[out]
The interface pointer for the new interface.

Return Value

S_OK

The method completed successfully.

Error

Values

This method failed to complete successfully.


IClassDef Interfaces Collection

The collection of all interfaces that are implemented by this class.

Dispatch Identifier: DISPID_Ifaces (32)

Collection descriptor | Descriptor value
Relationship Type | Class-Implements-Interface
Source Is Origin | Yes
Minimum Collection Size | Zero
Maximum Collection Size | Many
Sequenced Collection | No
Deletes Propagated | No
Destinations Named | No
Case Sensitive Names | Not applicable
Unique Names | Not applicable


IClassDef::ObjectInstances

This method materializes an IObjectCol interface pointer for the collection of all objects in the Repository that conform to this class.

HRESULT ObjectInstances( IObjectCol **ppIObjectCol );

Parameters

*ppIObjectCol [out]
The interface pointer for the object collection.

Return Value

S_OK

The method completed successfully.

Error

Values

This method failed to complete successfully.

Remarks

The retrieved collection contains one version of each object that conforms to the class. For each such object, the Repository uses its Resolution strategy to choose which version appears in the collection.


ICollectionDef Interface

A collection type (also referred to as a collection definition) defines how instances of a particular type of collection will behave. The properties of the collection type determine:

  • The minimum and maximum number of items in a collection.

  • Whether or not the collection type is an origin collection type.

  • Whether or not the collection type permits the naming of destination objects, and if so, whether those names are case-sensitive, and required to be unique.

  • Whether or not the collection type permits the explicit sequencing of items in the collection.

  • What happens to related objects when objects or relationships in the collection are deleted.

  • Whether or not origin collections of this type are automatically copied to new object versions by the CreateVersion method.

  • Whether the MergeVersion method combines origin collections of this type as a whole, or item by item.

  • Whether the FreezeVersion method requires that destination object versions of relationships of this type be frozen before the attendant origin object versions can be frozen.

The kind of relationship that a particular collection type uses to relate objects to each other is determined by its CollectionItem collection. The CollectionItem collection associates a single relationship type to the collection type.

To add a new collection type, use the IInterfaceDef interface.

When to Use

Use the ICollectionDef interface to retrieve or modify the properties of a collection type, or to determine the kind of relationship that the collection implements.

Methods

IUnknown Method | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.

IDispatch Method | Description
GetIDsOfNames | Maps a single member and a set of argument names to a corresponding set of dispatch identifiers.
GetTypeInfo | Retrieves a type information object, which can be used to get the type information for an interface.
GetTypeInfoCount | Retrieves the number of type information interfaces that an object provides (either 0 or 1).
Invoke | Provides access to properties and methods exposed by an Automation object.

IRepositoryDispatch Method | Description
get_Properties | Retrieves the IreposProperties interface pointer. The IreposProperties interface provides access to the Properties collection.

Properties

Property | Description
Flags | Flags that determine the behavior of this type of collection.
IsOrigin | Indicates whether or not collections of this type are origin collections.
MaxCount | The maximum number of target objects that can be contained in a collection of this type.
MinCount | The minimum number of target objects that must be contained in a collection of this type.

Collections

Collection | Description
CollectionItem | The collection of one relationship type that defines the relationship between target objects of this type of collection and a single source object.


ICollectionDef Flags Property

For a particular type of collection, the Flags property determines:

  • Whether or not the collection type permits the naming of destination objects, and if so, whether those names are case-sensitive, and required to be unique.

  • Whether or not the collection type permits the explicit sequencing of items in the collection.

  • What happens to related objects when objects or relationships in the collection are deleted.

  • Whether or not origin collections of this type are automatically copied to new object versions by the CreateVersion method.

  • Whether the MergeVersion method combines origin collections of this type as a whole, or item by item.

  • Whether the FreezeVersion method requires that destination object versions of relationships of this type be frozen before the attendant origin object versions can be frozen.

See the CollectionDefFlags Enumeration for a list of values and their specific purposes.

Dispatch Identifier: DISPID_ColFlags (54)

Property Data Type: long


ICollectionDef IsOrigin Property

This property indicates whether or not collections of this type are origin collections.

Dispatch Identifier: DISPID_IsOrigin (57)

Property Data Type: Boolean


ICollectionDef MaxCount Property

This property specifies the maximum number of target objects that can be contained in a collection of this type. This property is maintained for informational purposes, and is not enforced by the Repository engine.

Dispatch Identifier: DISPID_MaxCount (56)

Property Data Type: short


ICollectionDef MinCount Property

This property specifies the minimum number of target objects that must be contained in a collection of this type. This property is maintained for informational purposes, and is not enforced by the Repository engine.

Dispatch Identifier: DISPID_MinCount (55)

Property Data Type: short


ICollectionDef CollectionItem Collection

The collection of one relationship type that defines the relationship between target objects of this type of collection and a single source object.

Dispatch Identifier: DISPID_CollectionItem (38)

Collection descriptor | Descriptor value
Relationship Type | Collection-Contains-Items
Source Is Origin | Yes
Minimum Collection Size | Zero
Maximum Collection Size | One
Sequenced Collection | No
Deletes Propagated | No
Destinations Named | No
Case Sensitive Names | Not applicable
Unique Names | Not applicable


IInterfaceDef Interface

The properties, methods, and collections that a class implements are organized into functionally related groups. Each group is implemented as a COM interface. The properties, methods, and collections of each interface are members of the interface. An interface definition is the template to which an interface conforms.

To add a new interface to the Repository, use the IClassDef interface or the IReposTypeLib interface.

When to Use

Use the IInterfaceDef interface to:

  • Retrieve or modify properties of an interface definition.

  • Determine which members are attached to an interface definition.

  • Determine which classes implement an interface.

  • Determine the base interface from which an interface derives.

  • Determine what interfaces derive from a particular interface.

  • Determine what Repository objects expose a particular interface.

  • Add a new property, method, or collection type to an interface definition.

Properties

Property | Description
Flags | Flags that specify whether the interface is extensible, and whether the interface should be visible to Automation interface queries.
InterfaceID | The global interface identifier for the interface.
TableName | The name of the SQL table that is used to store instance information for the properties of the interface.

Methods

IUnknown Method | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.

IDispatch Method | Description
GetIDsOfNames | Maps a single member and a set of argument names to a corresponding set of dispatch identifiers.
GetTypeInfo | Retrieves a type information object, which can be used to get the type information for an interface.
GetTypeInfoCount | Retrieves the number of type information interfaces that an object provides (either 0 or 1).
Invoke | Provides access to properties and methods exposed by an Automation object.

IRepositoryDispatch Method | Description
get_Properties | Retrieves the IReposProperties interface pointer. The IReposProperties interface provides access to the Properties collection.

IInterfaceDef Method | Description
CreateMethodDef | Creates a new method definition, and attaches it to the interface definition.
CreatePropertyDef | Creates a new property definition, and attaches it to the interface definition.
CreateRelationshipColDef | Creates a relationship collection type. The collection type is attached to the interface definition.
ObjectInstances | Materializes an IObjectCol interface pointer for the collection of all objects in the Repository that expose this interface.

Collections

Collection | Description
Ancestor | The collection of one base interface from which this interface derives.
Classes | The collection of classes that implement the interface.
Descendants | The collection of other interfaces that derive from this interface.
Members | The collection of members that are attached to the interface definition.


IInterfaceDef Flags Property

This property contains flags that specify whether the interface is extensible, and whether the interface should be visible to Automation interface queries. (See the InterfaceDefFlags Enumeration for a list of values and their specific purposes.)

Dispatch Identifier: DISPID_IfaceFlags (50)

Property Data Type: long


IInterfaceDef InterfaceID Property

This property is the global interface identifier for the interface.

Dispatch Identifier: DISPID_InterfaceID (48)

Property Data Type: GUID


IInterfaceDef TableName Property

The name of the SQL table that is used to store instance information for the properties of the interface. The length of the name must be 30 characters or less.

Dispatch Identifier: DISPID_TableName (49)

Property Data Type: string


IInterfaceDef::CreateMethodDef

This method creates a new method definition and attaches it to the interface definition.

HRESULT CreateMethodDef(
VARIANT sObjId,
BSTR Name,
long iDispId,
IInterfaceMember **ppIMethodDef
);

Parameters

sObjId

[in]
The object identifier to be used for the new method definition object. The Repository engine will assign an object identifier if you set this parameter to OBJID_NULL.

Name

[in]
The name of the new method.

iDispId

[in]
The dispatch identifier to be used for accessing the new method.

*ppIMethodDef [out]
The interface pointer for the newly created method definition.

Return Value

S_OK

The method completed successfully.

Error

Values

This method failed to complete successfully.


IInterfaceDef::CreatePropertyDef

This method creates a new property definition and attaches it to the interface definition.

HRESULT CreatePropertyDef (
VARIANT sObjId,
BSTR Name,
long iDispId,
short iCType,
IPropertyDef **ppIPropertyDef
);

Parameters

sObjId

[in]
The object identifier to be used for the new property definition object. The Repository engine will assign an object identifier if you set this parameter to OBJID_NULL.

Name

[in]
The name of the new property.

iDispId

[in]
The dispatch identifier to be used for accessing the new property.

iCType [in]
The C data type of the property. For a definition of valid values, see the ODBC Programmer's Reference.

*ppIPropertyDef [out]
The interface pointer for the newly created property definition.

Return Value

S_OK

The method completed successfully.

Error

Values

This method failed to complete successfully.


IInterfaceDef::CreateRelationshipColDef

This method creates a new collection type, attaches it to this interface, and associates it with the specified relationship type.

HRESULT CreateRelationshipColDef(
VARIANT sObjId,
BSTR Name,
long iDispId,
boolean IsOrigin,
short fFlags,
IReposTypeInfo *pIRelshipDef,
ICollectionDef **pICollectionDef
);

Parameters

sObjId [in]
The object identifier for the collection type. The Repository engine will assign an object identifier if you set this parameter to OBJID_NULL.

Name

[in]
The name of the new collection type.

iDispId [in]
The dispatch identifier to be used for Automation access to collections of this type.

IsOrigin [in]
Specifies whether collections of this type are origin collections.

fFlags

[in]
Flags that specify naming, sequencing, and delete propagation behavior for the collection type. (See the CollectionDefFlags Enumeration for a list of values and their specific purposes.)

*pIRelshipDef [in]
The interface pointer for the relationship definition object to which this collection type is connected.

*ppICollectionDef

[out]
The interface pointer for the new collection definition object.

Return Value

S_OK

The method completed successfully.

Error

Values

This method failed to complete successfully.

Remarks

By default, the collection definition specifies that zero to many items are permitted in collections of this type. To specify a different minimum and maximum item count for the new collection type, change the MinCount and MaxCount properties before committing the transaction that contains this method invocation.


IInterfaceDef::ObjectInstances

This method materializes an IObjectCol interface pointer for the collection of all objects in the Repository that expose this interface.

HRESULT ObjectInstances( IObjectCol **ppIObjectCol );

Parameters

*ppIObjectCol [out]
The interface pointer for the object collection.

Return Value

S_OK

The method completed successfully.

Error

Values

This method failed to complete successfully.

Remarks

The retrieved collection contains one version of each object that conforms to a class exposing this interface. For each such object, the Repository uses its Resolution strategy to choose which version appears in the collection.


IInterfaceDef Classes Collection

This collection specifies which classes implement the interface.

Dispatch Identifier: DISPID_Classes (33)

Collection descriptor | Descriptor value
Relationship Type | Class-Implements-Interface
Source Is Origin | No
Minimum Collection Size | Zero
Maximum Collection Size | Many
Sequenced Collection | No
Deletes Propagated | No
Destinations Named | No
Case Sensitive Names | Not Applicable
Unique Names | Not Applicable


IInterfaceDef Members Collection

This collection specifies which members are attached to the interface.

Dispatch Identifier: DISPID_Members (36)

Collection descriptor | Descriptor value
Relationship Type | Interface-Has-Members
Source Is Origin | Yes
Minimum Collection Size | Zero
Maximum Collection Size | Many
Sequenced Collection | Yes
Deletes Propagated | Yes
Destinations Named | Yes
Case Sensitive Names | No
Unique Names | Yes


IInterfaceDef Ancestor Collection

This collection specifies the one base interface from which this interface derives.

Dispatch Identifier: DISPID_Ancestor (34)

Collection descriptor | Descriptor value
Relationship Type | Interface-InheritsFrom-Interface
Source Is Origin | Yes
Minimum Collection Size | One
Maximum Collection Size | One
Sequenced Collection | No
Deletes Propagated | No
Destinations Named | No
Case Sensitive Names | Not applicable
Unique Names | Not applicable


IInterfaceDef Descendants Collection

This collection specifies other interfaces that derive from this interface.

Dispatch Identifier: DISPID_Descendants (35)

Collection descriptor | Descriptor value
Relationship Type | Interface-InheritsFrom-Interface
Source Is Origin | No
Minimum Collection Size | Zero
Maximum Collection Size | Many
Sequenced Collection | No
Deletes Propagated | No
Destinations Named | No
Case Sensitive Names | Not applicable
Unique Names | Not applicable


IInterfaceMember Interface

The properties, methods, and collections that a class implements are organized into functionally related groups. Each group is implemented as a COM interface. The properties, methods, and collections of each interface are members of the interface.

The IInterfaceMember interface maintains this information for an interface member:

  • The member dispatch identifier.

  • Information about member visibility.

  • The relationship to the interface that exposes a particular interface member.

This information is common to properties, methods, and collection types. The PropertyDef, MethodDef, and CollectionDef classes all implement this interface.

When to Use

Use the IInterfaceMember interface to access the common properties of an interface member, or to determine which interface definition has a member of a particular property, method, or collection type.

Properties

Property | Description
DispatchID | The dispatch identifier to use when accessing an instance of this type of member.
Flags | Flags that specify details about this type of member.

Methods

IUnknown Method | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.

IDispatch Method | Description
GetIDsOfNames | Maps a single member and a set of argument names to a corresponding set of dispatch identifiers.
GetTypeInfo | Retrieves a type information object, which can be used to get the type information for an interface.
GetTypeInfoCount | Retrieves the number of type information interfaces that an object provides (either 0 or 1).
Invoke | Provides access to properties and methods exposed by an Automation object.

IRepositoryDispatch Method | Description
get_Properties | Retrieves the IReposProperties interface pointer. The IReposProperties interface provides access to the Properties collection.

Collections

Collection | Description
Interface | The collection of one interface that exposes this type of member.


IInterfaceMember DispatchID Property

This property contains the dispatch identifier to use when accessing an instance of this type of member.

Dispatch Identifier: DISPID_DispID (51)

Property Data Type: long


IInterfaceMember Flags Property

This property contains a flag that specifies whether or not the interface member should be visible to Automation queries. (See the InterfaceMemberFlags Enumeration for a list of values and their specific purposes.)

Dispatch Identifier: DISPID_IfaceMemFlags (52)

Property Data Type: long


IInterfaceMember Interface Collection

For a particular property, method, or collection definition, the Interface collection specifies which interface exposes a member of this type.

Dispatch Identifier: DISPID_Iface (37)

Collection descriptor | Descriptor value
Relationship Type | Interface-Has-Members
Source Is Origin | No
Minimum Collection Size | One
Maximum Collection Size | One
Sequenced Collection | Yes
Deletes Propagated | Yes
Destinations Named | Yes
Case Sensitive Names | No
Unique Names | Yes


IManageReposTypeLib Interface

Each tool information model that is stored in the Repository is represented by a Repository type library.

When to Use

Use the IManageReposTypeLib interface to:

  • Create a Repository type library for a new tool information model.

  • Determine what tool information models are currently stored in the Repository.

Methods

IUnknown Method | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.

IDispatch Method | Description
GetIDsOfNames | Maps a single member and a set of argument names to a corresponding set of dispatch identifiers.
GetTypeInfo | Retrieves a type information object, which can be used to get the type information for an interface.
GetTypeInfoCount | Retrieves the number of type information interfaces that an object provides (either 0 or 1).
Invoke | Provides access to properties and methods exposed by an Automation object.

IRepositoryDispatch Method | Description
get_Properties | Retrieves the IReposProperties interface pointer. The IReposProperties interface provides access to the Properties collection.

IManageReposTypeLib Method | Description
CreateTypeLib | Creates a Repository type library for a new tool information model.

Collections

Collection | Description
ReposTypeLibs | The collection of Repository type libraries that are currently stored in the Repository.


IManageReposTypeLib::CreateTypeLib

This method creates a new Repository type library and attaches it to the root of the Repository. Each Repository type library represents a tool information model.

HRESULT CreateTypeLib(
VARIANT sObjId,
BSTR Name,
VARIANT TypeLibId,
IReposTypeLib **ppIRepTypeLib
);

Parameters

sObjId

[in]
The object identifier to be used for the new Repository type library object. The Repository engine will assign an object identifier if you set this parameter to OBJID_NULL.

Name

[in]
The name of the new Repository type library.

TypeLibId

[in]
The global identifier by which this Repository type library is referenced.

*ppIRepTypeLib [out]
The IReposTypeLib interface pointer to the new Repository type library object.

Return Value

S_OK

The method completed successfully.

Error

Values

This method failed to complete successfully.


IManageReposTypeLib ReposTypeLibs Collection

The collection of Repository type libraries that are currently stored in the Repository. Each Repository type library represents a tool information model.

Dispatch Identifier: DISPID_ReposTypeLibs (40)

Collection descriptor | Descriptor value
Relationship Type | TlbManager-ContextFor-ReposTypeLibs
Source Is Origin | Yes
Minimum Collection Size | Zero
Maximum Collection Size | Many
Sequenced Collection | No
Deletes Propagated | Yes
Destinations Named | Yes
Case Sensitive Names | No
Unique Names | Yes


IPropertyDef Interface

A property definition object specifies the characteristics of a particular type of property. These characteristics are defined by the properties of the property definition object.

To create a new property definition:

  1. Use the CreatePropertyDef method of the IInterfaceDef interface.

  2. Define any non-default characteristics of your new property definition by manipulating the properties of the property definition object.

  3. Commit your changes to the Repository database.

RepositoryUse the IPropertyDef interface to retrieve or modify the characteristics of a property definition.

Properties

Property | Description
APIType | The C data type of the property.
ColumnName | The name of the column in the SQL table for this property.
Flags | Specifies details about the property.
SQLScale | The number of digits to the right of the decimal point for a numeric property.
SQLSize | The size in bytes of the property.
SQLType | The SQL data type of the property.

Methods

IUnknown Method | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.

IDispatch Method | Description
GetIDsOfNames | Maps a single member and a set of argument names to a corresponding set of dispatch identifiers.
GetTypeInfo | Retrieves a type information object, which can be used to get the type information for an interface.
GetTypeInfoCount | Retrieves the number of type information interfaces that an object provides (either 0 or 1).
Invoke | Provides access to properties and methods exposed by an Automation object.

IRepositoryDispatch Method | Description
get_Properties | Retrieves the IReposProperties interface pointer. The IReposProperties interface provides access to the Properties collection.


IPropertyDef APIType Property

The C data type of the property. For a definition of valid values, see the ODBC Programmer's Reference.

Dispatch Identifier: DISPID_APIType (59)

Property Data Type: short


IPropertyDef ColumnName Property

An SQL table is used to store instance information for the properties of an interface. By default, there is a column in this table for each property that is defined as a member of the interface. The ColumnName property specifies the name of the column in the SQL table for the property definition. The length of the column name must be 30 bytes or less.

Dispatch Identifier: DISPID_ColumnName (58)

Property Data Type: string


IPropertyDef Flags Property

A flag that specifies whether or not a column is created in the SQL table for the interface to which this property is attached. If no column is created, instances of this property are only attached to individual objects, when the property value is set for that particular object. By default, a column is created for each property.

See the PropertyDefFlags Enumeration for the symbolic and numeric values of this flag.

Dispatch Identifier: DISPID_PropFlags (63)

Property Data Type: long


IPropertyDef SQLScale Property

The number of digits to the right of the decimal point for a numeric property. This parameter is ignored unless the SQLType property specifies an SQL_NUMERIC, SQL_DECIMAL, or SQL_TIME data type.

Dispatch Identifier: DISPID_SQLScale (62)

Property Data Type: short


IPropertyDef SQLSize Property

The size in bytes of the property. This parameter is ignored when the data type of the property inherently specifies the size of the property.

Dispatch Identifier: DISPID_SQL_Size (61)

Property Data Type: short


IPropertyDef SQLType Property

The SQL data type of the property. For a definition of valid values, see the ODBC Programmer's Reference.

Dispatch Identifier: DISPID_SQLType (60)

Property Data Type: short


IReposRoot Interface

The IReposRoot interface is a placeholder interface; it contains no properties, methods, or collections beyond Automation dispatch methods. It is provided as a convenient connection point to the root object. When you create a tool information model, you can attach a relationship collection to this interface that provides a navigational connection to the primary objects of your tool information model.

When to Use

Use the IReposRoot interface as a starting point to navigate to other objects in the Repository.

Methods

IUnknown Method | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.

IDispatch Method | Description
GetIDsOfNames | Maps a single member and a set of argument names to a corresponding set of dispatch identifiers.
GetTypeInfo | Retrieves a type information object, which can be used to get the type information for an interface.
GetTypeInfoCount | Retrieves the number of type information interfaces that an object provides (either 0 or 1).
Invoke | Provides access to properties and methods exposed by an Automation object.

IRepositoryDispatch Method | Description
get_Properties | Retrieves the IReposProperties interface pointer. The IReposProperties interface provides access to the Properties collection.


IReposTypeInfo Interface

This interface relates class, interface, and relationship definition objects to Repository type libraries.

When to Use

Use the IReposTypeInfo interface to:

  • Determine which Repository type libraries contain a particular class, interface, or relationship type.

  • Determine what collection types are associated with a particular relationship type.

Methods

IUnknown Method | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.

IDispatch Method | Description
GetIDsOfNames | Maps a single member and a set of argument names to a corresponding set of dispatch identifiers.
GetTypeInfo | Retrieves a type information object, which can be used to get the type information for an interface.
GetTypeInfoCount | Retrieves the number of type information interfaces that an object provides (either 0 or 1).
Invoke | Provides access to properties and methods exposed by an Automation object.

IRepositoryDispatch Method | Description
get_Properties | Retrieves the IReposProperties interface pointer. The IReposProperties interface provides access to the Properties collection.

Collections

Collection | Description
ItemInCollections | The origin and destination collection types that are connected to a relationship definition object.
ReposTypeLibScopes | The collection of Repository type libraries that contain a particular class, interface, or relationship type.


IReposTypeInfo ItemInCollections Collection

This collection contains the origin and destination collection types that are associated with a particular relationship type. This collection is empty for definition objects that are not relationship definitions.

Dispatch Identifier: DISPID_Collection (39)

Collection descriptor | Descriptor value
Relationship Type | Collection-Contains-Items
Source Is Origin | No
Minimum Collection Size | Zero
Maximum Collection Size | Two
Sequenced Collection | No
Deletes Propagated | No
Destinations Named | No
Case-Sensitive Names | Not Applicable
Unique Names | Not Applicable


IReposTypeInfo ReposTypeLibScopes Collection

The collection of Repository type libraries that contain a particular class, interface, or relationship type.

Dispatch Identifier: DISPID_ReposTypeLibScopes (43)

Collection descriptor | Descriptor value
Relationship Type | ReposTypeLib-ScopeFor-ReposTypeInfo
Source Is Origin | No
Minimum Collection Size | One
Maximum Collection Size | Many
Sequenced Collection | No
Deletes Propagated | Yes
Destinations Named | Yes
Case-Sensitive Names | No
Unique Names | Yes


IReposTypeLib Interface

There is one Repository type library for every tool information model contained in the Repository. Each tool information model provides a logical grouping of all of the type definitions related to a particular tool (or tool set).

To add a new Repository type library to the Repository, use the IManageReposTypeLib interface.

When to Use

Use the IReposTypeLib interface to:

  • Define new classes, relationship types, and interfaces for a tool information model.

  • Retrieve or modify the global identifier associated with a Repository type library.

  • Determine which type definitions are associated with a particular Repository type library.

Properties

Property | Description
TypeLibID | The global identifier for the Repository type library.

Methods

IUnknown Method | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.

IDispatch Method | Description
GetIDsOfNames | Maps a single member and a set of argument names to a corresponding set of dispatch identifiers.
GetTypeInfo | Retrieves a type information object, which can be used to get the type information for an interface.
GetTypeInfoCount | Retrieves the number of type information interfaces that an object provides (either 0 or 1).
Invoke | Provides access to properties and methods exposed by an Automation object.

IRepositoryDispatch Method | Description
get_Properties | Retrieves the IReposProperties interface pointer. The IReposProperties interface provides access to the Properties collection.

IReposTypeLib Method | Description
CreateClassDef | Creates a new class definition object.
CreateInterfaceDef | Creates a new interface definition object.
CreateRelationshipDef | Creates a new relationship definition object.

Collections

Collection | Description
ReposTypeInfos | The collection of all classes, interfaces, and relationship types that are defined in the Repository type library.
ReposTypeLibContexts | The collection of one Repository root object that is the context for the Repository type library.


IReposTypeLib TypeLibID Property

This property is the global identifier for the Repository type library.

Dispatch Identifier: DISPID_TypeLibID (64)

Property Data Type: GUID


IReposTypeLib::CreateClassDef

This method creates a new class definition object. No interfaces are attached to the class.

HRESULT CreateClassDef(
VARIANT sObjId,
BSTR Name,
VARIANT sClsId,
IClassDef **ppIClassDef
);

Parameters

sObjId

[in]
The object identifier to be used for the new class definition object. The Repository engine will assign an object identifier if you set this parameter to OBJID_NULL.

Name

[in]
The name of the new class.

sClsId

[in]
The global identifier by which this class is referenced.

*ppIClassDef [out]
The interface pointer to the new class definition object.

Return Value

S_OK

The method completed successfully.

Error

Values

This method failed to complete successfully.


IReposTypeLib::CreateInterfaceDef

The CreateInterfaceDef method creates a new interface definition object. Use the IClassDef::AddInterface method to attach the interface to a class definition object.

HRESULT CreateInterfaceDef(
VARIANT sObjId,
BSTR Name,
VARIANT sIId,
IInterfaceDef *pIAncestor,
IInterfaceDef **ppIInterfaceDef
);

Parameters

sObjId

[in]
The object identifier to be assigned to the new interface definition object. If this parameter is set to OBJID_NULL, the Repository assigns an object identifier for you.

Name

[in]
The name of the interface that is to be created.

sIId

[in]
The interface identifier associated with the signature for this interface. If there is none, set this parameter to zero.

*pIAncestor

[in]
The IInterfaceDef interface pointer for the base interface from which the new interface is derived.

*pplInterfaceDef

[out]
The interface pointer for the new interface.

Return Value

S_OK

The method completed successfully.

Error

Values

This method failed to complete successfully.


IReposTypeLib::CreateRelationshipDef

This method creates a relationship definition object for a new relationship type. Once the relationship definition is created, use the IInterfaceDef::CreateRelationshipColDef method to create origin and destination collection definitions for the new relationship type.

HRESULT CreateRelationshipDef(
VARIANT sObjId,
BSTR Name,
IReposTypeInfo **ppIRelshipDef
);

Parameters

sObjId [in]
The object identifier for the new relationship type. The Repository engine will assign an object identifier if you set this parameter to OBJID_NULL.

Name

[in]
The name of the new relationship type.

*ppIRelshipDef

[out]
The COM interface pointer to the new relationship definition object.

Return Value

S_OK

The method completed successfully.

Error

Values

This method failed to complete successfully.


IReposTypeLib ReposTypeLibContexts Collection

The collection of one Repository root that is the context for a Repository type library.

Dispatch Identifier: DISPID_ReposTLBContexts (41)

Collection descriptor | Descriptor value
Relationship Type | TlbManager-ContextFor-ReposTypeLibs
Source Is Origin | No
Minimum Collection Size | One
Maximum Collection Size | Many
Sequenced Collection | No
Deletes Propagated | Yes
Destinations Named | Yes
Case Sensitive Names | No
Unique Names | Yes


IReposTypeLib ReposTypeInfos Collection

The collection of all classes, interfaces, and relationship types that are associated with a Repository type library. The Repository engine uses this collection to enforce the unique naming of all classes, interfaces, and relationship types for a Repository type library.

Dispatch Identifier: DISPID_ReposTypeInfos (42)

Collection descriptor | Descriptor value
Relationship Type | ReposTypeLib-ScopeFor-ReposTypeInfo
Source Is Origin | Yes
Minimum Collection Size | Zero
Maximum Collection Size | Many
Sequenced Collection | No
Deletes Propagated | Yes
Destinations Named | Yes
Case Sensitive Names | No
Unique Names | Yes


Collection Descriptors

  • Relationship Type Descriptor

  • Source Is Origin Descriptor

  • Maximum Collection Size Descriptor

  • Minimum Collection Size Descriptor

  • Deletes Propagated Descriptor

  • Sequenced Collection Descriptor

  • Destinations Named Descriptor

  • Case-Sensitive Names Descriptor

  • Unique Names Descriptor


Relationship Type Descriptor

The type of relationship by which all items of the collection are connected to a common source object.


Source Is Origin Descriptor

Specifies whether or not the source object for the collection is also the origin object. Value can be set to Yes or No.


Maximum Collection Size Descriptor

The maximum number of items that can be contained in the collection. Value can be set to Zero, One, a specific numeric value, or Many. The Repository engine does not enforce this maximum.


Minimum Collection Size Descriptor

The minimum number of items that must be contained in the collection. Value can be set to Zero, One, a specific numeric value, or Many. The Repository engine does not enforce this minimum.


Deletes Propagated Descriptor

Specifies whether or not the deletion of an origin object or deletion of a relationship in the collection will cause the deletion of the corresponding destination object. Value can be set to Yes or No.


Sequenced Collection Descriptor

Specifies whether or not the items in the destination collection have an explicitly defined sequence. Collections of origin objects are never sequenced. Value can be set to Yes or No.


Destinations Named Descriptor

Specifies whether or not the relationship type for the collection permits the naming of destination objects. Value can be set to Yes or No.


Case-Sensitive Names Descriptor

Specifies whether or not the relationship type for the collection permits the use of case-sensitive names for destination objects. This descriptor is meaningful only for collections whose relationship type permits destination objects to be named. Value can be set to Yes, No, or Not Applicable.


Unique Names Descriptor

Specifies whether or not the relationship type for the collection requires that the name of a destination object be unique within the collection of destination objects. This descriptor is meaningful only for collections whose relationship type permits destination objects to be named. Value can be set to Yes, No, or Not Applicable.


Repository Data Structures and Constants

The various declarations and definitions for Microsoft® Repository can be found in these files:

  • The Repapi.h source file contains C++ definitions specific to the Repository engine.

  • The Reptim.h source file contains the constant definitions specific to the Type Information Model. Most of the various identifiers (class, interface, object, local, internal, and dispatch) that you may find useful are defined in this file.

  • The Repauto.h file contains the definitions of the external enumerations, classes, and interfaces of the Repository engine and the Type Information Model. All of the interfaces found in this file support Automation level access.


Repository Constants

These constants are defined for the Microsoft Repository application programming interface.

Constant | Value | Description
CARD_NOLIMIT | 0xFFFF | The maximum count value for a collection with an unlimited number of items.
COLUMNNAMESIZE | 32 | Maximum length, in bytes, of an SQL column name.
INTID_NULL | 0xFFFFFFFF | The null internal identifier.
MEMBERNAMESIZE | 64 | Maximum length, in bytes, of a property, method, or collection type name.
OBJID_NULL | See reptim.h | The null object identifier. Use this value when you want the Repository to assign an object identifier for you.
PASSWORDSIZE | 64 | Maximum length, in bytes, of the password string that is used to connect to the Repository database.
PROPVALSIZE | 225 | Maximum length, in bytes, of an annotational property string.
RELSHIPNAMESIZE | 260 | Maximum length, in bytes, of a name that a relationship assigns to its destination object.
REPOSERROR_OBJKNOWN | 0x00000001L | Returned in the fFlags field of the REPOSERROR structure. Indicates that the object identifier is known.
REPOSERROR_SQLINFO | 0x00000002L | Returned in the fFlags field of the REPOSERROR structure. Indicates that the SQL error information is valid.
REPOSERROR_HELPAVAIL | 0x00000004L | Returned in the fFlags field of the REPOSERROR structure. Indicates that the rcHelpFile and dwHelpContext fields are valid.
REPOSERROR_MSG_SIZE | 256 | Maximum length, in bytes, of the message in the rcMsg field of the REPOSERROR structure.
TABLENAMESIZE | 32 | Maximum length, in bytes, of an SQL table name.
TIMESTAMP_NULL | {9999, 12, 31, 0, 0, 0, 0} | The null timestamp value.
TYPEINFONAMESIZE | 64 | Maximum length, in bytes, of a class, interface, or relationship type name.
TYPELIBNAMESIZE | 64 | Maximum length, in bytes, of a Repository type library name.
USERSIZE | 64 | Maximum length, in bytes, of the user name that is used to connect to the Repository database.


CollectionDefFlags Enumeration

These values are used to define the behavior of a Relationship collection. These flags are bit flags, and may be combined to set multiple options. The absence of a flag signifies that the option is not set.

enum { COLLECTION_NAMING                          = 1,
       COLLECTION_UNIQUENAMING                    = 2,
       COLLECTION_CASESENSITIVE                   = 4,
       COLLECTION_SEQUENCED                       = 8,
       COLLECTION_PROPAGATEDELETE                 = 16,
       COLLECTION_NEWORGVERSIONSPARTICIPATE      = 32,
       COLLECTION_MERGEWHOLE                      = 128,

} CollectionDefFlags;

Value | Description
COLLECTION_CASESENSITIVE | Specifies that the relationship type for the collection permits the use of case-sensitive names for destination objects. This descriptor is meaningful only for collections whose relationship type permits destination objects to be named.
COLLECTION_NAMING | Specifies that the relationship type for the collection permits the naming of destination objects.
COLLECTION_SEQUENCED | Specifies that the items in the collection have an explicitly defined sequence. Collections of origin objects are never sequenced.
COLLECTION_UNIQUENAMING | Specifies that the relationship type for the collection requires that the name of a destination object be unique within the collection of destination objects. This descriptor is meaningful only for collections whose relationship type permits destination objects to be named.
COLLECTION_PROPAGATEDELETE | Specifies that the relationship type for the collection requires that deletes be propagated to destination objects. The destination object is only deleted if this is the last relationship of this type that is connected to the object.
COLLECTION_NEWORGVERSIONSPARTICIPATE | If this flag is set, the CreateVersion method copies origin collections of this type from the predecessor creation version to the newly created (successor) version.
COLLECTION_MERGEWHOLE | If this flag is set, the MergeVersion method sets any origin collection of this type in the successor version to be identical to corresponding collection of either the primary version or the secondary version of the merge. If this flag is not set, MergeVersion combines the individual origin versioned relationships from the primary version and the secondary version into the successor version. For details about how MergeVersion combines the origin version relationship for inclusion in the successor version’s origin collection, see The Details of Merge BehaviorreconThe_Details_of_Merge_Behavior.


ConnectionFlags Enumeration

These values are used to define the characteristics of a connection to a Repository database. These flags are bit flags, and may be combined to set multiple options. The absence of a flag signifies that the option is not set.

enum { REPOS_CONN_EXCLUSIVE  = 1,
       REPOS_CONN_NEWCACHE   = 2
} ConnectionFlags;

Value | Description
REPOS_CONN_EXCLUSIVE | Open the Repository database in exclusive mode. No other users will be allowed access to the database.
REPOS_CONN_NEWCACHE | Create a new cache for this open Repository instance. This will consume additional resources.


InterfaceDefFlags Enumeration

These values are used to define specific characteristics of an interface definition. These flags are bit flags, and may be combined to set multiple options. The absence of a flag signifies that the option is not set.

enum { INTERFACE_EXTENSIBLE  = 1,
       INTERFACE_HIDDEN      = 2
} InterfaceDefFlags;

Value | Description
INTERFACE_EXTENSIBLE | Specifies that the interface will support extensions.
INTERFACE_HIDDEN | Specifies that the interface is not to be visible to Automation queries.


InterfaceMemberFlags Enumeration

This enumeration is used to define specific characteristics of an interface member. The absence of the flag signifies that the option is not set.

enum { INTERFACEMEMBER_HIDDEN  = 1
} InterfaceMemberFlags;

Value | Description
INTERFACEMEMBER_HIDDEN | Specifies that the interface member is not to be visible to Automation queries.


PropertyDefFlags Enumeration

This enumeration is used to define specific characteristics of a property definition. The absence of the flag signifies that the option is not set.

enum { PROPERTY_INVERTED  = 1
} PropertyDefFlags;

Value | Description
PROPERTY_INVERTED | Specifies that the property is to be stored in inverted form; that is, a column is not reserved in the SQL table that contains the properties for the implementing interface. Instances of this property will only exist for objects that have a value set for the property. The property is restricted to the string data type.


TransactionFlags Enumeration

This enumeration is used to specify which transaction option is to be retrieved or set.

enum { TXN_RESET_OPTIONS           = 1,
       TXN_NORMAL                  = 2,
       TXN_EXCLUSIVE_WRITEBACK     = 3,
       TXN_EXCLUSIVE_WRITETHROUGH  = 4,
       TXN_TIMEOUT_DURATION        = 5,
       TXN_START_TIMEOUT           = 6,
       TXN_QUERY_TIMEOUT           = 7,
       TXN_DBMS_READONLY           = 8
} TransactionFlags;

Value | Description
TXN_RESET_OPTIONS | Valid only for setting transaction options. Specifies that all options are to be reset to their default values. Any associated option value is ignored.
TXN_NORMAL | Specifies the nonexclusive write-back mode transaction option.
TXN_EXCLUSIVE_WRITEBACK | Specifies the exclusive write-back mode transaction option.
TXN_EXCLUSIVE_WRITETHROUGH | Specifies the exclusive write-through mode transaction option.
TXN_TIMEOUT_DURATION | Specifies the transaction option that determines the maximum time to wait for a lock.
TXN_START_TIMEOUT | Specifies the transaction option that determines the maximum time to wait before starting a transaction.
TXN_QUERY_TIMEOUT | Specifies the transaction option that determines the maximum number of seconds to wait while a database query is executing.
TXN_DBMS_READONLY | Specifies the option that indicates whether you can make changes to the Repository database. If the value is zero, you can make changes. If the value is nonzero, the database is read-only. You can read the value of this option, but you cannot set it.


Repository Data Types

The following structures and data types are defined for the Microsoft Repository application programming interface.

Internal Identifier

struct INTID
{
   ULONG  iSiteID;
   ULONG  iLocalID;
};

typedef const INTID &REFINTID;

An INTID or a REFINTID variable is an internal identifier for a specific Repository object that uniquely identifies the object within a particular Repository database. It is not unique across all repositories. This is not the same thing as the interface identifier for an interface, or the class identifier that is used to create an instance of a class.

The internal identifier is composed of an internal site identifier (iSiteID), and an internal local identifier (iLocalID).

Internal Version Identifier

struct VERSIONID
{
    INTID           sIntID;
    BRANCHID       iBranchID;
    VERSIONNUM    iVersionStart;
};

typedef const VERSIONID &REFVERSIONID;

A VERSIONID or a REFVERSIONID variable is an internal identifier for a specific Repository object version that uniquely identifies the object version within a particular Repository database. It is not unique across all repositories.

The internal identifier is composed of an internal identifier (sIntID), a branch identifier (iBranchID), and a version-within-branch identifier (iVersionStart).

Object Identifier and Object-Version Identifier

typedef const OBJECTID OBJID;
typedef const OBJID    &REFOBJID;

An OBJID or a REFOBJID variable can be used in either of two ways:

  • It can be an object identifier for a specific Repository object in a particular Repository database. An object identifier is unique across all repositories.

  • It can be an object-version identifier for a specific version of a Repository object in a particular Repository database. An object-version identifier is unique across all repositories.

An OBJID or a REFOBJID variable is composed of a global identifier (GUID) and a four-byte local identifier appended to the GUID. The GUID portion of the variable specifies where the identifier was created, and the local identifier has a value that is unique within the Repository database. When you use an OBJID or a REFOBJID variable to contain an object-version identifier, the four-byte local identifier is not the branch ID or the version-within-branch id of the object version.


REPOSERROR Data Structure

Repository methods return an HRESULT value that indicates whether or not the method completed successfully. If a Repository method fails to complete successfully, an error object is created that contains details about the failure. The REPOSERR data structure contains the following details.

struct REPOSERROR
{
   ULONG    iSize;
   ULONG    fFlags;
   HRESULT  hr;
   TCHAR    rcMsg[REPOSERROR_MSG_SIZE];
   TCHAR    rcHelpFile[_MAX_PATH];
   ULONG    dwHelpContext;
   long     iNativeError;
   TCHAR    rcSqlState[6];
   short    iReserved;
   OBJID    sObjID;
   GUID     clsid;
   GUID     iid;
};

iSize

The size in bytes of this data structure.

fFlags

Bit flags that define the validity of certain members of this data structure. Valid values are REPOSERROR_OBJKNOWN, REPOSERROR_SQLINFO, and REPOSERROR_HELPAVAIL. (See Repository Constants for the meaning of these constants.)

hr

The HRESULT return value that was returned from the method that logged this error.

rcMsg

The text message that is associated with this error.

rcHelpFile

The name of the help file that contains more information about this error.

dwHelpContext

The help context identifier that is associated with this error.

iNativeError

The error code that was returned from the database engine. The value of this member is only valid if the fFlags member indicates that SQL information is present.

rcSqlState

SQL state information supplied by the database engine. The value of this member is only valid if the fFlags member indicates that SQL information is present.

iReserved

Reserved for use by the Repository engine.

sObjID

The object identifier of the object that is associated with this error. The value of this member is only valid if the fFlags member indicates that the object is known.

clsid

The class identifier of the object that is associated with this error. The value of this member is only valid if the fFlags member indicates that the object is known.

iid

The interface identifier of the interface that is associated with this error. If the interface is not known, or not applicable, the value of this member is set to GUID_NULL.


Repository Errors

Nearly all Repository methods return an HRESULT value that indicates whether or not the method succeeded in performing its function. The facility field of these HRESULT values is always set to FACILITY_ITF, which indicates that the meaning for any given error code value is specific to the interface from which the error is being reported. All of the standard Repository interfaces (that is, interfaces that are automatically supplied with the Repository) use the same set of error codes. These codes are listed in numerical order, and in alphabetical order.


Repository Errors (Numerical Order)

The error codes that can be returned as a part of the HRESULT return value by Repository methods are listed here in numerical order. These codes are also listed in alphabetical order.

(0x1000) EREP_BADPARAMS

(0x1001) EREP_BADNAME

(0x1002) EREP_BADDRIVER

(0x1003) EREP_BADERROR

(0x1004) EREP_BUFFER_OVERFLOW

(0x1011) EREP_NOROWSFOUND

(0x1012) EREP_ODBC_CERROR

(0x1013) EREP_ODBC_MDBNOTFOUND

(0x1014) EREP_NEED_DATA

(0x1015) EREP_ODBC_UNKNOWNDRIVER

(0x1016) EREP_ODBC_CREATEFAILED

(0x1017) EREP_ODBC_WARNINGS

(0x1030) EREP_DB_EXISTS

(0x1031) EREP_DB_NOTCONNECTED

(0x1032) EREP_DB_ALREADYCONNECTED

(0x1033) EREP_DB_DBMSONETHREAD

(0x1034) EREP_DB_CORRUPT

(0x1035) EREP_DB_NOSCHEMA

(0x1036) EREP_DB_DBMSOLD

(0x1037) EREP_DB_READONLY

(0x1041) EREP_TXN_NOTXNACTIVE

(0x1042) EREP_TXN_AUTOABORT

(0x1043) EREP_TXN_TOOMANY

(0x1044) EREP_TXN_TIMEOUT

(0x1045) EREP_TXN_NODATA

(0x1046) EREP_TXN_NOSETINTXN

(0x1047) EREP_TXN_OBJABORTED

(0x1048) EREP_TXN_COLABORTED

(0x1070) EREP_REPOS_CACHEFULL

(0x1071) EREP_REPOS_NONEXTDISPID

(0x1100) EREP_RELSHIP_EXISTS

(0x1101) EREP_RELSHIP_INVALID_PAIR

(0x1102) EREP_RELSHIP_NOTFOUND

(0x1105) EREP_RELSHIP_ORGONLY

(0x1106) EREP_RELSHIP_OUTOFDATE

(0x1107) EREP_RELSHIP_INVALIDFLAGS

(0x1108) EREP_RELSHIP_NAMEINVALID

(0x1109) EREP_RELSHIP_DUPENAME

(0x1120) EREP_TYPE_TABLEMISMATCH

(0x1121) EREP_TYPE_COLMISMATCH

(0x1122) EREP_TYPE_NOTNULLABLE

(0x1123) EREP_TYPE_MULTIDEFIFACES

(0x1124) EREP_TYPE_INVERTEDNOTALLOWED

(0x1125) EREP_TYPE_INVALIDSCALE

(0x1200) EREP_LOCK_TIMEOUT

(0x1250) EREP_QRY_BADCOLUMNS

(0x1300) EREP_OBJ_NOTINITIALIZED

(0x1301) EREP_OBJ_NOTFOUND

(0x1302) EREP_OBJ_NONAMINGRELSHIP

(0x1303) EREP_OBJ_EXISTS

(0x1400) EREP_PROP_MISMATCH

(0x1401) EREP_PROP_SETINVALID

(0x1402) SREP_PROP_TRUNCATION

(0x1403) EREP_PROP_CANTSETREPTIM

(0x1404) EREP_PROP_READONLY

(0x1405) EREP_PROP_NOTEXISTS

(0x1501) EREP_TIM_FLAGSDEST

(0x1502) EREP_TIM_RELTYPEINVALID

(0x1503) EREP_TIM_CTYPEINVALID

(0x1504) EREP_TIM_TOOMANYCOLS

(0x1505) EREP_TIM_SQLTYPEINVALID


Repository Errors (Alphabetical Order)

The error codes that can be returned as a part of the HRESULT return value by Repository methods are listed here in alphabetical order, according to the symbolic name for each error code. These codes are also listed in numerical order.

EREP_BADDRIVER (0x1002)

EREP_BADERROR (0x1003)

EREP_BADNAME (0x1001)

EREP_BADPARAMS (0x1000)

EREP_BUFFER_OVERFLOW (0x1004)

EREP_DB_ALREADYCONNECTED (0x1032)

EREP_DB_CORRUPT (0x1034)

EREP_DB_DBMSOLD (0x1036)

EREP_DB_DBMSONETHREAD (0x1033)

EREP_DB_EXISTS (0x1030)

EREP_DB_NOSCHEMA (0x1035)

EREP_DB_NOTCONNECTED (0x1031)

EREP_DB_READONLY (0x1037)

EREP_LOCK_TIMEOUT (0x1200)

EREP_NEED_DATA (0x1014)

EREP_NOROWSFOUND (0x1011)

EREP_OBJ_EXISTS (0x1303)

EREP_OBJ_NONAMINGRELSHIP (0x1302)

EREP_OBJ_NOTFOUND (0x1301)

EREP_OBJ_NOTINITIALIZED (0x1300)

EREP_ODBC_CERROR (0x1012)

EREP_ODBC_CREATEFAILED (0x1016)

EREP_ODBC_MDBNOTFOUND (0x1013)

EREP_ODBC_UNKNOWNDRIVER (0x1015)

EREP_ODBC_WARNINGS (0x1017)

EREP_PROP_CANTSETREPTIM (0x1403)

EREP_PROP_MISMATCH (0x1400)

EREP_PROP_NOTEXISTS (0x1405)

EREP_PROP_READONLY (0x1404)

EREP_PROP_SETINVALID (0x1401)

EREP_QRY_BADCOLUMNS (0x1250)

EREP_RELSHIP_DUPENAME (0x1109)

EREP_RELSHIP_EXISTS (0x1100)

EREP_RELSHIP_INVALIDFLAGS (0x1107)

EREP_RELSHIP_INVALID_PAIR (0x1101)

EREP_RELSHIP_NAMEINVALID (0x1108)

EREP_RELSHIP_NOTFOUND (0x1102)

EREP_RELSHIP_ORGONLY (0x1105)

EREP_RELSHIP_OUTOFDATE (0x1106)

EREP_REPOS_CACHEFULL (0x1070)

EREP_REPOS_NONEXTDISPID (0x1071)

EREP_TIM_CTYPEINVALID (0x1503)

EREP_TIM_FLAGSDEST (0x1501)

EREP_TIM_RELTYPEINVALID (0x1502)

EREP_TIM_SQLTYPEINVALID (0x1505)

EREP_TIM_TOOMANYCOLS (0x1504)

EREP_TXN_AUTOABORT (0x1042)

EREP_TXN_COLABORTED (0x1048)

EREP_TXN_NODATA (0x1045)

EREP_TXN_NOSETINTXN (0x1046)

EREP_TXN_NOTXNACTIVE (0x1041)

EREP_TXN_OBJABORTED (0x1047)

EREP_TXN_TIMEOUT (0x1044)

EREP_TXN_TOOMANY (0x1043)

EREP_TYPE_COLMISMATCH (0x1121)

EREP_TYPE_INVALIDSCALE (0x1125)

EREP_TYPE_INVERTEDNOTALLOWED (0x1124)

EREP_TYPE_MULTIDEFIFACES (0x1123)

EREP_TYPE_NOTNULLABLE (0x1122)

EREP_TYPE_TABLEMISMATCH (0x1120)

SREP_PROP_TRUNCATION (0x1402)


EREP_BADDRIVER

EREP_BADDRIVER (0x1002)

The currently installed ODBC driver is too old, and is incompatible with Microsoft Repository. Update your ODBC driver.


EREP_BADERROR

EREP_BADERROR (0x1003)

An internal error has occurred. Release and restart the Repository.


EREP_BADNAME

EREP_BADNAME (0x1001)

The name that you have supplied for a table or column name either contains invalid characters or is a reserved word for the database management system (DBMS). Change the name and try your request again.


EREP_BADPARAMS

EREP_BADPARAMS (0x1000)

One or more invalid parameters have been passed to a Repository method. Correct the input parameters and try again.


EREP_BUFFER_OVERFLOW

EREP_BUFFER_OVERFLOW (0x1004)

An overflow error occurred while building an SQL statement. Reduce the number of changed properties or Repository objects in the operation and try again.


EREP_DB_ALREADYCONNECTED

EREP_DB_ALREADYCONNECTED (0x1032)

You have attempted to connect to a Repository database when you are already connected. Skip the redundant Open method invocation and proceed with the Repository interactions that follow that Open invocation.


EREP_DB_CORRUPT

EREP_DB_CORRUPT (0x1034)

The Repository database has been damaged. See your database server documentation to determine what facilities are available for restoring or rebuilding the database.


EREP_DB_DBMSOLD

EREP_DB_DBMSOLD (0x1036)

The SQL Server® DBMS is too old for the Repository. Upgrade the SQL Server DBMS to version 6.5 or later.


EREP_DB_DBMSONETHREAD

EREP_DB_DBMSONETHREAD (0x1033)

The Repository database that you have attempted to access is managed by a database server that does not support multithreaded access. The thread attempting the access is not the same as the thread that currently has the open Repository instance for the database. Either move your Repository database to a database server that supports multithreaded access, or modify the logic of your program to use a single thread for Repository database access.


EREP_DB_EXISTS

EREP_DB_EXISTS (0x1030)

You have requested that a Repository database be created with a name that is the name of an already existing database. If you can use the existing database, use the Open method instead of the Create method. If the existing database is no longer needed, delete it. Otherwise, choose a different name and try again.


EREP_DB_NOSCHEMA

EREP_DB_NOSCHEMA (0x1035)

The Repository database does not contain the Type Information Model schema. If your Repository has not yet been populated with data, install the Type Information Model schema by using the Create method to open the Repository database. If your Repository has been populated with data, restore the database from a backup copy.


EREP_DB_NOTCONNECTED

EREP_DB_NOTCONNECTED (0x1031)

You have requested an operation that requires a connection to an open Repository database, and you do not currently have such a connection. Open the appropriate Repository and try your request again.


EREP_DB_READONLY

EREP_DB_READONLY (0x1037)

You have attempted to change a read-only DBMS. Contact the system administrator.


EREP_LOCK_TIMEOUT

EREP_LOCK_TIMEOUT (0x1200)

An attempt to obtain a lock on a Repository item has timed out. Either increase the lock time-out value and try again, or wait for the item to become available and then try again. For details on how to change the lock time-out value, see the SetOption method.


EREP_NEED_DATA

EREP_NEED_DATA (0x1014)

An ODBC error occurred indicating that a variable-length data item (such as a name) was needed at run time, and has never been supplied. Check input parameters.


EREP_NOROWSFOUND

EREP_NOROWSFOUND (0x1011)

A query operation against the Repository database yielded no rows. If you expected data to be returned, verify that your query is properly constructed.


EREP_OBJ_EXISTS

EREP_OBJ_EXISTS (0x1303)

You have attempted to create a Repository object that already exists in the Repository. This situation can occur if multiple users are attempting to add the same object to the Repository concurrently. If this is not the case, eliminate the redundant Add, CreateObject, or Insert method invocation from your program.


EREP_OBJ_NONAMINGRELSHIP

EREP_OBJ_NONAMINGRELSHIP (0x1302)

The retrieval of the name associated with a Repository item has failed because the item is not a participant in a naming relationship. Check your tool information model to see if the relationship type is correctly defined. If it is, and the relationship type does not specify that destination objects are to be named, consider adding logic to your program to check for the presence of a naming relationship before requesting the Repository item name.


EREP_OBJ_NOTFOUND

EREP_OBJ_NOTFOUND (0x1301)

You have attempted to retrieve a Repository object that does not exist. If multiple users are accessing the Repository concurrently, this error can occur if one user deletes a Repository object while a second user is attempting to retrieve the object. It can also occur if you are using an object identifier that has been saved from prior interactions with the Repository, and the object has been deleted between the time that you obtained the object identifier and the time that you attempted to retrieve the Repository object. Consider handling this exception with special processing for the case where a Repository object no longer exists.


EREP_OBJ_NOTINITIALIZED

EREP_OBJ_NOTINITIALIZED (0x1300)

An attempt has been made to interact with a Repository object that has not been initialized with valid data from the Repository database. Ensure that all Repository objects in your program are initialized before attempting to interact with them.


EREP_ODBC_CERROR

EREP_ODBC_CERROR (0x1012)

A database error has occurred; check the error queue for more information. Determine the source of the problem and correct it, and try again.


EREP_ODBC_CREATEFAILED

EREP_ODBC_CREATEFAILED (0x1016)

The creation of an .mdb file has failed. You either supplied a wrong path, or you tried to create an .mdb file that already existed. Check the path or delete the .mdb file, and try again.


EREP_ODBC_MDBNOTFOUND

EREP_ODBC_MDBNOTFOUND (0x1013)

You have specified a Repository database that does not exist or is not accessible. Make sure that the database exists and the name is correct, and try again.


EREP_ODBC_UNKNOWNDRIVER

EREP_ODBC_UNKNOWNDRIVER (0x1015)

The specified ODBC driver is not a valid driver, or is not known to the Repository engine. Obtain an ODBC driver that is compatible with Microsoft Repository. (See the product release notes for information about compatible drivers.)


EREP_ODBC_WARNINGS

EREP_ODBC_WARNINGS (0x1017)

The ODBC driver issued warnings. Check the error queue for the error text.


EREP_PROP_CANTSETREPTIM

EREP_PROP_CANTSETREPTIM (0x1403)

You have attempted to modify a property of a definition object that is part of the Type Information Model. Modification of Type Information Model properties is not supported.


EREP_PROP_MISMATCH

EREP_PROP_MISMATCH (0x1400)

An attempt to update a property value in the Repository has failed. The data type of the input property cannot be converted to the storage data type. Correct the data type of the input property and try the update again.


EREP_PROP_NOTEXISTS

EREP_PROP_NOTEXISTS (0x1405)

You have attempted to reference a property that does not exist. Check the property reference (name or dispatch identifier) and try again.


EREP_PROP_READONLY

EREP_PROP_READONLY (0x1404)

Your request to set the value of a property has failed because the property is a read-only property.


EREP_PROP_SETINVALID

EREP_PROP_SETINVALID (0x1401)

You have attempted to modify a collection as if it were a property. Microsoft Repository does not support this type of operation.


EREP_QRY_BADCOLUMNS

EREP_QRY_BADCOLUMNS (0x1250)

An ad hoc query is missing the IntID column, has too many columns, or is otherwise unsuitable for execution.


EREP_RELSHIP_DUPENAME

EREP_RELSHIP_DUPENAME (0x1109)

You have attempted to add a relationship with a name that is not unique within the collection, and the collection requires unique names. Either choose a different name for the relationship, or delete the existing relationship with the same name, if it is no longer needed.


EREP_RELSHIP_EXISTS

EREP_RELSHIP_EXISTS (0x1100)

You have attempted to create a relationship that already exists in the Repository. Either ignore this error, or eliminate the redundant Add or Insert method invocation from your program.


EREP_RELSHIP_INVALIDFLAGS

EREP_RELSHIP_INVALIDFLAGS (0x1107)

Your attempt to add or modify a Relationship collection has failed. Either the combinations of flags are invalid, or you are attempting to set flag values on a destination collection. Verify that the origin collection is being used for the operation, and that the flag combinations are valid. (See CollectionDefFlags for details on relationship collection flags.)


EREP_RELSHIP_INVALID_PAIR

EREP_RELSHIP_INVALID_PAIR (0x1101)

An attempt to add a new relationship between two objects has failed. One or both of the classes to which these objects conform does not support this type of relationship. Verify that the relationship type and the object classes are correct. Check your tool information model to verify that it supports the type of relationship that you are trying to create.


EREP_RELSHIP_NAMEINVALID

EREP_RELSHIP_NAMEINVALID (0x1108)

You have attempted to add a relationship that has an invalid name specified for the destination object. Verify that the name is non-null, and is not longer than the maximum allowed length. For details about Repository text string lengths, see Repository Constants.


EREP_RELSHIP_NOTFOUND

EREP_RELSHIP_NOTFOUND (0x1102)

You have attempted to retrieve a specific relationship that does not exist, or you have attempted to retrieve a relationship from an empty collection. If multiple users are accessing the Repository concurrently, this error can occur if one user deletes a relationship while a second user is attempting to retrieve the relationship. Consider handling this exception with special processing for the case where a collection is empty or a specific relationship no longer exists.


EREP_RELSHIP_ORGONLY

EREP_RELSHIP_ORGONLY (0x1105)

An attempt to move or insert a relationship in a sequenced collection has failed because the Move or Insert method was invoked through the destination object instead of the origin object. Use the origin object to move or insert a relationship in a sequenced collection.


EREP_RELSHIP_OUTOFDATE

EREP_RELSHIP_OUTOFDATE (0x1106)

Your request has failed because the sequenced Relationship collection that you are attempting to update has been changed by another process. Refresh the collection and try the update again.


EREP_REPOS_CACHEFULL

EREP_REPOS_CACHEFULL (0x1070)

The Repository cache is full. If you are writing new and changed data to the Repository, and you cannot reduce the number of steps in the transaction, consider setting either the TXN_EXCLUSIVE_WRITEBACK or the TXN_EXCLUSIVE_WRITETHROUGH transaction option to avoid this problem.


EREP_REPOS_NONEXTDISPID

EREP_REPOS_NONEXTDISPID (0x1071)

You have attempted to add a member to an interface that is defined in the Repository, but there are no more dispatch identifier values available. Factor the interface into several smaller interfaces.


EREP_TIM_CTYPEINVALID

EREP_TIM_CTYPEINVALID (0x1503)

You have chosen an invalid C data type for a property. Use a valid C data type.


EREP_TIM_FLAGSDEST

EREP_TIM_FLAGSDEST (0x1501)

Collection flags cannot be set on destination collections.


EREP_TIM_RELTYPEINVALID

EREP_TIM_RELTYPEINVALID (0x1502)

The type of a RelationshipDef object for a collection is incorrect.


EREP_TIM_SQLTYPEINVALID

EREP_TIM_SQLTYPEINVALID (0x1505)

You have chosen an invalid SQL data type for a property. Use a valid SQL data type.


EREP_TIM_TOOMANYCOLS

EREP_TIM_TOOMANYCOLS (0x1504)

Too many collections are used per RelationshipDef object. Release the collections that are not in use.


EREP_TXN_AUTOABORT

EREP_TXN_AUTOABORT (0x1042)

You have released the resources for an open Repository instance, and that Repository instance had a transaction active. The transaction has been canceled; all changes associated with the transaction will be undone. You should always complete an active transaction (through either the Commit or the Abort method) before releasing an open Repository instance.


EREP_TXN_COLABORTED

EREP_TXN_COLABORTED (0x1048)

The collection has been deleted or the last transaction that updated the collection has been aborted. In the latter case, release all the pointers to the collection and re-instantiate it.


EREP_TXN_NODATA

EREP_TXN_NODATA (0x1045)

You have attempted to retrieve the value of a property that is null, or does not exist. The corrective action that you must take is dependent upon the requirements of your task. Consider handling this exception with special processing for the case where a property has a null value.


EREP_TXN_NOSETINTXN

EREP_TXN_NOSETINTXN (0x1046)

You have attempted to modify the current transaction option settings while a transaction is active. Either complete the current transaction and then modify the transaction options, or set the transaction options prior to beginning the transaction.


EREP_TXN_NOTXNACTIVE

EREP_TXN_NOTXNACTIVE (0x1041)

You have attempted to update the Repository database, but there is no transaction active. Bracket your Repository updates between Begin and Commit transaction method invocations.


EREP_TXN_OBJABORTED

EREP_TXN_OBJABORTED (0x1047)

The object has been deleted or the last transaction that updated the object has been aborted. In the latter case, release all the pointers to the object and re-instantiate it.


EREP_TXN_TIMEOUT

EREP_TXN_TIMEOUT (0x1044)

Your transaction has timed out while waiting to begin. Either increase the start transaction time-out value and retry the transaction, or wait for the item to become available and then retry the transaction. For details on how to change the start transaction time-out value, see the SetOption method.


EREP_TXN_TOOMANY

EREP_TXN_TOOMANY (0x1043)

A new transaction cannot be started because the maximum number of concurrent transactions has been exceeded. Reduce the number of concurrently executing transactions (within the same process).


EREP_TYPE_COLMISMATCH

EREP_TYPE_COLMISMATCH (0x1121)

The conversion of a property value between the stored data type and the data type as specified by the caller has failed. Check the caller-specified data type to verify that it can be converted to the storage data type, as defined by the associated property definition object.


EREP_TYPE_INVALIDSCALE

EREP_TYPE_INVALIDSCALE (0x1125)

You have attempted to set the SQLScale property of a property definition to an invalid value. Correct the value that you are using and try the operation again.


EREP_TYPE_INVERTEDNOTALLOWED

EREP_TYPE_INVERTEDNOTALLOWED (0x1124)

You have attempted to add a property to an interface using the PROPERTY_INVERTED option, and the option is not permitted for the interface. Correct either the property definition or the interface definition.


EREP_TYPE_MULTIDEFIFACES

EREP_TYPE_MULTIDEFIFACES (0x1123)

You have attempted to set more than one interface as the default interface for a class definition. Choose one of the interfaces to be the default interface.


EREP_TYPE_NOTNULLABLE

EREP_TYPE_NOTNULLABLE (0x1122)

You have attempted to set a property value to the null value, and the property definition does not allow this. Choose one of the permitted property values and try the update operation again.


EREP_TYPE_TABLEMISMATCH

EREP_TYPE_TABLEMISMATCH (0x1120)

An attempt to extend an interface for a tool information model has failed. The SQL table that is designated as the table to be used for storing property values for the interface does not contain the expected columns. Check the table to determine if it has been damaged or if columns have been dropped from the table. Restore the table to its prior state and try the request again.


SREP_PROP_TRUNCATION

SREP_PROP_TRUNCATION (0x1402)

Your request to set the value of a property has succeeded; however, the value of the property has been truncated because the input property value was too long.


Repository SQL Schema

The Repository SQL schema consists of a standard schema and an extended schema. The standard schema consists of tables that contain the core information needed to manage all Repository objects, relationships, and collections. The standard schema also contains tables that are used by the Repository to store the definition information for information models.

SQL schema extensions are automatically generated by the Repository engine when you create or extend an information model. Normally, one table is created for each interface that is defined in the Repository. The table contains the instance data for persistent properties that are attached to the interface. One column in the table is created for each property. If an interface is defined that has no member properties, a table is not created.

Although the extended schema is automatically generated, you can tune the extended schema to optimize performance and data retrieval, if you are an experienced SQL administrator. For example, by default, the properties of each interface are stored in a separate SQL table. You can map the properties of multiple interfaces to a single table. You can also specify the column names and data types to be used for property data. You can add indexes to tables, but you must not remove indexes that have been automatically defined by the Repository.

You can construct an SQL query to extract specific information from the Repository. You need to be familiar with the SQL schema to build such a query. The set of SQL tables that comprise the standard schema is shown below.

SQL table name Description

RTblClassDefs | Contains information about classes that are defined in the Repository.
RTblRelColPairs | Contains information about collections.
RTblDatabaseVersion | Contains the version and the build of the engine that created the Repository database.
RTblIfaceDefs | Contains information about interfaces that are defined in the Repository.
RTblPropDefs | Contains information about property definitions.
RTblProps | Contains property values for annotational properties that are attached to Repository objects.
RTblRelshipProps | Contains property values for annotational properties that are attached to relationships.
RTblRelships | Contains information about relationships.
RTblRelColDefs | Contains information about collection types.
RTblRoot | Contains the internal identifier of the Repository root.
RTblSites | Translates local site identifiers to global site identifiers.
RTblTypeLibs | Contains information about Repository type libraries.
RTblVersions | Contains information about Repository object versions.
RTblWorkspaceItems | Contains information about the inclusion of object versions in workspaces.

Microsoft Repository can access Repository databases that are managed by either Microsoft Jet or Microsoft SQL Server. Since the underlying database management system (DBMS) can vary, the utilities and tools that you use to administer the Repository database (at the database level) also vary. For example, if your Repository database is damaged due to a power outage or system failure, you should use the recovery tools that are provided with your DBMS to repair the damage. Similarly, if your Repository database requires periodic defragmentation, you should use the defragmentation tools that are provided with your DBMS.


Repository SQL Data Types

Because data types can vary between database management systems, the Repository engine maps its own set of Repository data types to the SQL data types that are supported by the underlying database server.

This table translates Repository data types into SQL data types known by the database server. For data types that vary between different database servers, the data type used for each database server is shown. In these cases, the Microsoft® SQL Server™ data type is shown with (S) appended to it, and the Microsoft Jet server data type is shown with (J) appended to it.

Repository
data type 		Database
data type
Description

RTBoolean | bit (S) boolean (J) | A true/false value.
RTBrID | 4-byte integer | A branch identifier.
RTCount | 2-byte integer | The count, or cardinality of a collection.
RTDBVersion | 40-byte varchar | A string indicating the engine version that created the database.
RTDispID | 4-byte integer | An Automation dispatch identifier.
RTFlags | 2-byte integer | Flag bits that define the behavior of an entity or indicate what kind of row exists in a table.
RTGUID | 16-byte binary | A globally unique identifier.
RTIntID | 8-byte binary | An internal identifier.
RTLClock | 4-byte integer | Logical clock value.
RTLocalID | 4-byte binary | A local identifier; part of an internal identifier.
RTLongBinary | image (S) longbinary (J) | A long binary stream of data.
RTLongString | text (S) memo (J) | A string with a maximum length of approximately 1 gigabyte.
RTNameString | 200-byte varchar | A special truncated name string used for indexing.
RTScale | 2-byte integer | Scale for numeric data; the number of digits after the decimal point.
RTShortString | 220-byte varchar | A special shortened string value used for indexing.
RTSiteID | 4-byte binary | A site identifier; part of an object identifier.
RTSize | 2-byte integer | The size of a data type, in bytes.
RTSQLName | 30-byte varchar | An SQL identifier; a table or column name.
RTSQLType | 2-byte integer | The ODBC representation of an SQL data type.
RTVerID | 4-byte integer | A version-within-branch identifier.


RTblClassDefs SQL Table

This SQL table contains one row for each class that is defined in the Repository. The IntID, Z_BranchID_Z, and Z_VS_Z columns form the primary key for this table. A unique index is defined on the set of columns IntID, Z_BranchID_Z, and Z_VS_Z.

Column name Data type Description

IntID | RTIntID | The internal identifier for the class object.
Z_BranchID_Z | RTBrID | The value of this column is always zero.
Z_VS_Z | RTVerID | The value of this column is always zero.
Z_VE_Z | RTVerID | The value of this column is always VERINFINITY.
ClassID | RTGUID | The global identifier of the class, as recorded in the system registry.
VerPropDescs | RTLongBinary | Definition information for the class. Reserved for proprietary usage by the Repository engine. This field can be null.
PropDescs | RTLongBinary | For compatibility with Repository 1.0 RTblClassDefs structure. In Repository 2.0, this column always has the value NULL.

Remarks

Remember that you can make only one version of each Class Definition. Nevertheless, this table includes the columns Z_BranchID_Z, Z_VS_Z, and Z_VE_Z because there are implementation advantages to including these columns. Similarly, the primary key includes the columns Z_BranchID_Z and Z_VS_Z for implementation reasons only.


RTblDatabaseVersion SQL Table

This SQL table contains the version and the build of the engine that created the Repository database.

Column name Data type Description

DatabaseVersion RTDBVersion The version and the build of the engine in the following format:

V1.V2.B1.B2

where:

V1: major version number.

V2: minor version number.

B1: major build number.

B2: minor build number.

Example:

2.0.8042.0 means that the Repository database was created using the engine 2.0 and the build 8042.0.


RTblIfaceDefs SQL Table

This SQL table contains one row for each interface that is defined in the Repository. The IntID, Z_BranchID_Z, and Z_VS_Z columns form the primary key for this table. A unique index is defined on the set of columns IntID, Z_BranchID_Z, and Z_VS_Z.

Column name Data type Description

IntID | RTIntID | The internal identifier for the interface definition object.
Z_BranchID_Z | RTBrID | The value of this column is always zero.
Z_VS_Z | RTVerID | The value of this column is always zero.
Z_VE_Z | RTVerID | The value of this column is always VERINFINITY.
InterfaceID | RTGUID | The global identifier of the interface, as recorded in the system registry.
SQLTableName | RTSQLName | The name of the SQL table used to store property instance data for the interface. This field can be null.
Flags | RTFlags | Flags that determine interface behavior according to these values: 1: Interface extensible. 2: Interface hidden.

Remarks

Remember that you can make only one version of each Interface Definition. Nevertheless, this table includes the columns Z_BranchID_Z, Z_VS_Z, and Z_VE_Z because there are implementation advantages to including these columns. Similarly, the primary key includes the columns Z_BranchID_Z and Z_VS_Z for implementation reasons only.


RTblIfaceMem SQL Table

This SQL table contains one row for each property definition, method definition, and collection definition that is stored in the Repository. The information contained in this table is used by the Repository to create interface-specific SQL tables when an interface is added to the Repository. The IntID, Z_BranchID_Z, and Z_VS_Z columns form the primary key for this table.

Column Name Data Type Description

IntID | RTIntID | The internal identifier for the property definition object.
Z_BranchID_Z | RTBrID | The value of this column is always zero.
Z_VS_Z | RTVerID | The value of this column is always zero.
Z_VE_Z | RTVerID | The value of this column is always VERINFINITY.
DispID | RTDispID | The Automation dispatch identifier for the member. This field can be null.
Flags | RTFlags | Flags that determine member behavior. For a list of valid values and their meanings, see the InterfaceMemberFlags Enumeration.

Remarks

Remember that you can make only one version of each property definition, method definition, or collection definition. Nevertheless, this table includes the columns Z_BranchID_Z, Z_VS_Z, and Z_VE_Z because there are implementation advantages to including these columns. Similarly, the primary key includes the columns Z_BranchID_Z and Z_VS_Z for implementation reasons only.


RTblPropDefs SQL Table

This SQL table contains one row for each property definition object that is stored in the Repository. The information contained in this table is used by the Repository to create interface-specific SQL tables when an interface is added to the Repository. The IntID, Z_BranchID_Z, and Z_VS_Z columns form the primary key for this table.

Column Name Data Type Description

IntID | RTIntID | The internal identifier for the property definition object.
Z_BranchID_Z | RTBrID | The value of this column is always zero.
Z_VS_Z | RTVerID | The value of this column is always zero.
Z_VE_Z | RTVerID | The value of this column is always VERINFINITY.
SQLColName | RTSQLName | The name of the column in the SQL table for this property. This field can be null.
APIType | RTSQLType | The C language data type for the property. This is the type of the property when it is passed through a Repository programming interface.
SQLType | RTSQLType | The SQL data type for the property.
SQLSize | RTSize | The length in bytes of the property in terms of its SQL data type.
SQLScale | RTScale | The scale for a numeric property; the number of digits after the decimal point. This field can be null.
Flags | RTFlags | Flags that determine property behavior. See the PropertyDefFlags Enumeration for a list of values and their specific purposes.

Remarks

Remember that you can make only one version of each Property Type Definition. Nevertheless, this table includes the columns Z_BranchID_Z, Z_VS_Z, and Z_VE_Z because there are implementation advantages to including these columns. Similarly, the primary key includes the columns Z_BranchID_Z and Z_VS_Z for implementation reasons only.


RTblProps SQL Table

An annotational property is a property that is associated with an individual Repository object or relationship, and is not required to exist for all Repository objects or relationships of a particular type. This SQL table contains one row for each annotational property instance that is attached to a Repository object. The IntID and PropID columns comprise the primary key for this table. A single non-unique index is defined on the concatenation of the PropID and PropValue columns.

Column Name Data Type Description

IntID | RTIntID | The internal identifier for the object to which this annotational property is attached.
PropID | RTIntID | The internal identifier for the inverted property definition object to which this annotational property instance conforms.
PropValue | RTShortString | The value of the annotational property instance.

Remarks

Remember that each annotation property value applies to an object as a whole – not to an individual version of that object. That’s why this table does not include columns such as Z_BranchID_Z and Z_VS_Z – columns that help identify individual versions of Repository objects.


RTblRelshipProps SQL Table

An annotational property is a property that is associated with an individual Repository object or relationship, and is not required to exist for all Repository objects or relationships of a particular type. This SQL table contains one row for each annotational property instance that is attached to a relationship. The OrgID, RelTypeID, DstID, and PropID columns compose the primary key for this table. A single non-unique index is defined on the concatenation of the PropID and PropValue columns.

Column Name Data Type Description

OrgID | RTIntID | The internal identifier for the origin object of the relationship.
RelTypeID | RTIntID | The internal identifier for the relationship type.
DstID | RTIntID | The internal identifier for the destination object of the relationship.
PropID | RTIntID | The internal identifier for the inverted property definition object to which this annotational property instance conforms.
PropValue | RTShortString | The value of the annotational property instance.

Remarks

Remember, when you set an annotational property on a relationship, the property applies to every version-to-version relationship of that type between any version of the origin object and any version of the destination object. That’s why this table does not include columns such as Z_OrgBrID_Z, Z_OrgVS_Z, Z_DstBrID_Z and Z_DstVS_Z – columns that help identify version-to-version relationships.


RTblRelships SQL Table

This SQL table describes the relationships stored in the Repository. The primary key for this table includes these columns: OrgID, RelTypeID, Z_OrgBrID_Z, Z_OrgVS_Z, DstID, Z_DstBrID_Z, Z_DstVS_Z, and Z_RelFlags_Z.

Column Name Data Type Description

OrgID | RTIntID | The internal identifier for the origin object of the relationship.
Z_OrgBrID_Z | RTBrID | Indicates the branch of the version graph containing the origin object version.
Z_OrgVS_Z | RTVerID | Indicates the lower bound of the range of origin object versions having version-to-version relationships described by this row.
Z_OrgVE_Z | RTVerID | Indicates the upper bound of the range of origin object versions having version-to-version relationships described by this row. Can be a special value indicating that the range is unbounded.
Z_OrgLClock_Z | RTLClock | For internal use only.
DstID | RTIntID | The internal identifier for the destination object of the relationship.
Z_DstBrID_Z | RTBrID | For Relationship rows, indicates the branch of the version graph containing the destination object version. For Auxiliary rows, can indicate the branch containing the pinned object version of an origin versioned relationship.
Z_DstVS_Z | RTVerID | For Relationship rows, indicates the lower bound of the range of destination object versions having version-to-version relationships described by this row. For Auxiliary rows, can indicate the pinned object version of an origin versioned relationship.
Z_DstVE_Z | RTVerID | Indicates the upper bound of the range of destination object versions having version-to-version relationships described by this row.
Z_DstLClock_Z | RTLClock | For internal use only.
OrgTypeID | RTIntID | The internal identifier for the class to which the origin object conforms. Redundantly stored in this table for performance reasons.
RelTypeID | RTIntID | The internal identifier for the relationship type.
DstTypeID | RTIntID | The internal identifier for the class to which the destination object conforms. Redundantly stored in this table for performance reasons.
PrevDstID | RTIntID | For each auxiliary row describing an item in a sequenced relationship collection, this column contains the internal identifier of the previous relationship in the collection sequence. For other auxiliary rows and for relationship rows, this column is null.
DstName | RTNameString | The name of the destination object. More precisely, the name (as defined by this naming relationship) by which each origin version (in the range of origin versions) refers to each destination version (in the range of destination versions). If the relationship is not a naming relationship, then this field is null.
DstNameLong | RTLongString | If the name of the destination object is longer than what can be fit into the DstName field, then this field contains the full name. Otherwise, this field is null.
Z_RelFlags_Z | RTFlags | A value of 2 indicates that the row is a Relationship row; 1 indicates it is an Auxiliary row.

Remarks

There are two kinds of row in this table: Relationship rows and Auxiliary rows.

Each Relationship row describes one or more Version-to-Version relationships:

  • In the simplest case, a Relationship row describes exactly one version-to-version relationship. (See Example 1.)

  • In the ideal case, a Relationship row describes as large a range as possible. (See Example 2.)

  • A Relationship row can describe an unbounded range. (See Example 3.)

  • In some situations, several Relationship rows exist when one would theoretically suffice. (See Example 4.)

Each Auxiliary row contains pinning and sequencing information for an origin versioned relationship:

  • An Auxiliary row can contain sequencing information. (See Example 5.)

  • An Auxiliary row can contain pinning information. (See Example 6.)

  • An Auxiliary row can contain both pinning and sequencing information. (See Example 7.)

Not every origin versioned relationship has a corresponding auxiliary row. If the origin versioned relationship is not part of a sequencing collection and does not have any member of its TargetVersions collection pinned, it does not have an auxiliary row.


RTblRelships Example 1

RTblRelships Example One

In the simplest case, a Relationship row describes exactly one version-to-version relationship. If Z_OrgVS_Z = Z_OrgVE_Z, then the range of origin versions contains exactly one item. Similarly, if Z_DstVS_Z = Z_DstVE_Z, then the range of destination versions contains exactly one item. If both these equalities hold, the row describes exactly one version-to-version relationship. For example, if a row has the following values, it indicates that there is a version-to-version relationship between a version of the object whose internal ID is 7 and a version of the object whose internal ID is 888.

OrgID = 7
Z_OrgBrID_Z = 1
Z_OrgVS_Z = 3
Z_OrgVE_Z = 3
DstID = 888
Z_DstBrID_Z = 4
Z_DstVS_Z = 2
Z_DstVE_Z = 2
RelTypeID = 465
Z_RelFlags_Z = 2

Note that some column values are not shown here.


RTblRelships Example 2

RTblRelships Example Two

Within a Relationship row, if Z_OrgVS_Z < Z_OrgVE_Z, then the row describes more than one version-to-version relationship. For example, suppose that Z_DstVS_Z = Z_DstVE_Z, but that Z_OrgVS_Z < Z_OrgVE_Z. The set of destination versions referred to by this row includes exactly one item, but the set of origin versions referred to by this row includes n (n > 1) items. In this situation, this row of the table indicates the existence of n different version-to-version relationships.

For example, if a row contains the following values, it describes three version-to-version relationships.

OrgID = 7
Z_OrgBrID_Z = 1
Z_OrgVS_Z = 3
Z_OrgVE_Z = 5
DstID = 888
Z_DstBrID_Z = 4
Z_DstVS_Z = 2
Z_DstVE_Z = 2
RelTypeID = 465
Z_RelFlags_Z = 2


RTblRelships Example 3

RTblRelships Example Three

Within a Relationship row, if Z_OrgVE_Z = VERINFINITY, then the row describes one or more verstion-to-version relationships, depending on the shape of the Version Graph.

For example, consider the following two rows and the accompanying Version Graph of the origin object.

OrgID = 7
Z_OrgBrID_Z = 2
Z_OrgVS_Z = 5
Z_OrgVE_Z = VERINFINITY
DstID = 888
Z_DstBrID_Z = 4
Z_DstVS_Z = 2
Z_DstVE_Z = 2
RelTypeID = 465
Z_RelFlags_Z = 2

OrgID = 7
Z_OrgBrID_Z = 3
Z_OrgVS_Z = 4
Z_OrgVE_Z = VERINFINITY
DstID = 888
Z_DstBrID_Z = 4
Z_DstVS_Z = 2
Z_DstVE_Z = 2
RelTypeID = 465
Z_RelFlags_Z = 2

The first row describes exactly three version-to-version relationships, because within branch 2, there are three object versions whose version-within-branch identifiers are 5 or higher.

The second row describes exactly one version-to-version relationship, because within branch 3, there is exactly one object version whose version-within-branch identifier is 4 or higher.

(Insert figure “SchemaExampleRTblRelshipsVeEqualsVerinfinity” here)


RTblRelships Example 4

RTblRelships Example Four

In some situations, several relationship rows exist where one would theoretically suffice. For example, consider a row including these values:

OrgID = 7
Z_OrgBrID_Z = 4
Z_OrgVS_Z = 3
Z_OrgVE_Z = 8
DstID = 888
Z_DstBrID_Z = 4
Z_DstVS_Z = 2
Z_DstVE_Z = 2
RelTypeID = 465
Z_RelFlags_Z = 2

The row indicates that a version-to-version relationship (to a specific version of the destination object) exists from every branch-four version of the origin object whose version-within-branch identifier is between 3 and 8.

Compare the preceding row to those shown below. In particular, notice that the two rows below are effectively equivalent to the row above. Taken together, the first two rows below indicate exactly what the single row above indicates.

OrgID = 7
Z_OrgBrID_Z = 4
Z_OrgVS_Z = 3
Z_OrgVE_Z = 5
DstID = 888
Z_DstBrID_Z = 4
Z_DstVS_Z = 2
Z_DstVE_Z = 2
RelTypeID = 465
Z_RelFlags_Z = 2

OrgID = 7
Z_OrgBrID_Z = 4
Z_OrgVS_Z = 6
Z_OrgVE_Z = 8
DstID = 888
Z_DstBrID_Z = 4
Z_DstVS_Z = 2
Z_DstVE_Z = 2
RelTypeID = 465
Z_RelFlags_Z = 2


RTblRelships Example 5

RTblRelships Example Five

For each item in a sequenced origin versioned relationship, an auxiliary row in RTblVersions exists. For example, consider the following sequenced origin versioned relationship.

(figure SchemaRshipExampleSequencing to be inserted)

The figure shows a sequenced origin versioned relationship. Because the versioned relationship has two items, there are two sets of rows in the RTblVersions table. One set consists of one relationship row and one auxiliary row, with these values:

OrgID = 008
Z_OrgBrID_Z = 2
Z_OrgVS_Z = 3
Z_OrgVE_Z = 3
DstID = 984
Z_DstBrID_Z = 0
Z_DstVS_Z = 5
Z_DstVE_Z = 5
RelTypeID = 522
PrevDstID = null
Z_RelFlags_Z = 2

OrgID = 008
Z_OrgBrID_Z = 2
Z_OrgVS_Z = 3
Z_OrgVE_Z = 3
DstID = 984
Z_DstBrID_Z = 0
Z_DstVS_Z = 5
Z_DstVE_Z = 5
RelTypeID = 522
PrevDstID = SEQUENCE_END
Z_RelFlags_Z = 1

The other item has two version-to-version relationships. The RTblVersions table expresses this as a set of three rows with the following values:

OrgID = 008
Z_OrgBrID_Z = 2
Z_OrgVS_Z = 3
Z_OrgVE_Z = 3
DstID = 777
Z_DstBrID_Z = 2
Z_DstVS_Z = 2
Z_DstVE_Z = 2
RelTypeID = 522
PrevDstID = null
Z_RelFlags_Z = 2

OrgID = 008
Z_OrgBrID_Z = 2
Z_OrgVS_Z = 3
Z_OrgVE_Z = 3
DstID = 777
Z_DstBrID_Z = 2
Z_DstVS_Z = 3
Z_DstVE_Z = 3
RelTypeID = 522
PrevDstID = null
Z_RelFlags_Z = 2

OrgID = 008
Z_OrgBrID_Z = 2
Z_OrgVS_Z = 3
Z_OrgVE_Z = 3
DstID = 777
Z_DstBrID_Z = NULLBRANCH
Z_DstVS_Z = NULLVERSION
Z_DstVE_Z = null
RelTypeID = 522
PrevDstID = 984
Z_RelFlags_Z = 1


RTblRelships Example 6

RTblRelships Example Six

If an origin versioned relationship has a pinned target version, the RTblVersions table includes an auxiliary row to indicate which target version is pinned. For example, the following figure shows an origin versioned relationship with a pinned target version.

(include figure SchemaRshipExamplePinning)

To accommodate this origin versioned relationship, RTblVersions includes four rows with the following values:

OrgID = 008
Z_OrgBrID_Z = 2
Z_OrgVS_Z = 3
Z_OrgVE_Z = 3
DstID = 984
Z_DstBrID_Z = 0
Z_DstVS_Z = 4
Z_DstVE_Z = 4
RelTypeID = 522
Z_RelFlags_Z = 2

OrgID = 008
Z_OrgBrID_Z = 2
Z_OrgVS_Z = 3
Z_OrgVE_Z = 3
DstID = 984
Z_DstBrID_Z = 0
Z_DstVS_Z = 5
Z_DstVE_Z = 5
RelTypeID = 522
Z_RelFlags_Z = 2

OrgID = 008
Z_OrgBrID_Z = 2
Z_OrgVS_Z = 3
Z_OrgVE_Z = 3
DstID = 984
Z_DstBrID_Z = 0
Z_DstVS_Z = 6
Z_DstVE_Z = 6
RelTypeID = 522
Z_RelFlags_Z = 2

OrgID = 008
Z_OrgBrID_Z = 2
Z_OrgVS_Z = 3
Z_OrgVE_Z = 3
DstID = 984
Z_DstBrID_Z = 0
Z_DstVS_Z = 5
Z_DstVE_Z = null
RelTypeID = 522
Z_RelFlags_Z = 1


RTblRelships Example 7

RTblRelships Example Seven

An auxiliary row can include both sequencing and pinning information. For example, if a sequenced origin collection includes an origin versioned relationship with a pinned target version, the RTblVersions table includes an auxiliary row to indicate 1) which target version is pinned, and 2) which item in the sequenced origin collection precedes the current one . For example, the following figure shows a sequences origin collection, one of whose items has a pinned target version.

(include figure SchemaRshipExampleSequencingAndPinning)

To accommodate this relationship collection, RTblVersions includes

  • Five relationship rows; one for each version-to-version relationship

  • Two auxiliary rows; one for each origin versioned relationship.

The auxiliary rows have the following values:

OrgID = 008
Z_OrgBrID_Z = 2
Z_OrgVS_Z = 3
Z_OrgVE_Z = 3
DstID = 984
Z_DstBrID_Z = 0
Z_DstVS_Z = 5
Z_DstVE_Z = null
RelTypeID = 522
PrevDstID = SEQUENCE_END
Z_RelFlags_Z = 1

OrgID = 008
Z_OrgBrID_Z = 2
Z_OrgVS_Z = 3
Z_OrgVE_Z = 3
DstID = 777
Z_DstBrID_Z = NULLBRANCH
Z_DstVS_Z = NULLVERSION
Z_DstVE_Z = null
RelTypeID = 522
PrevDstID = 984
Z_RelFlags_Z = 1


RTblRelColDefs SQL Table

Each relationship in the Repository is associated with two relationship collections: an origin collection and a destination collection. Each relationship collection conforms to a collection type (also referred to as a collection definition). The collection type defines the role that the collection plays in the relationship. This SQL table contains one row for each collection type that is defined in the Repository. The IntID, Z_BranchID_Z, and Z_VS_Z columns form the primary key for this table. A non-unique index is defined for the RelTypeID column.

Column Name Data Type Description

IntID | RTIntID | The internal identifier for the collection definition object.
Z_BranchID_Z | RTBrID | The value of this column is always zero.
Z_VS_Z | RTVerID | The value of this column is always zero.
Z_VE_Z | RTVerID | The value of this column is always VERINFINITY.
RelTypeID | RTIntID | Internal identifier of the relationship definition object.
Flags | RTFlags | Flags that determine the behavior of collections that conform to this collection type. See CollectionDefFlags for a list of values and their specific purposes.
MinCount | RTCount | The minimum number of Repository items that are expected for this type of collection. This field can be null.
MaxCount | RTCount | The maximum number of Repository items that are expected for this type of collection. This field can be null.
IsOrigin | RTBoolean | Determines whether or not collections that conform to this collection type are origin collections (True), or destination collections (False).

Remarks

Remember that you can make only one version of each Relationship Collection Type. Nevertheless, this table includes the columns Z_BranchID_Z, Z_VS_Z, and Z_VE_Z because there are implementation advantages to including these columns. Similarly, the primary key includes the columns Z_BranchID_Z and Z_VS_Z for implementation reasons only.


RTblRelColPairs SQL Table

This SQL table contains information about collections. The RelTypeID, OrgTypeID, and DstTypeID columns form the primary key for this table.

Column Name Data Type Description

RelTypeID | RTIntID | The internal identifier of the relationship type.
OrgTypeID | RTIntID | The internal identifier of the collection’s origin object.
DstTypeID | RTIntID | The internal identifier of the collection’s destination object.

Remarks

This table is not versioned in Repository 2.0 engine.


RTblRoot SQL Table

This SQL table contains the internal identifier of the Repository root. The IntID, Z_BranchID_Z, and Z_VS_Z columns form the primary key for this table.

Column Name Data Type Description

IntID | RTIntID | The internal identifier of the Repository root.
Z_BranchID_Z | RTBrID | The value of this column is always equal to zero.
Z_VS_Z | RTVerID | The value of this column is always equal to zero.
Z_VE_Z | RTVerID | The value of this column is always equal to VERINFINITY.

Remarks

The root is not versioned in the Repository 2.0 engine.

Remember that you can make only one version of each Class Definition. Nevertheless, this table includes the columns Z_BranchID_Z, Z_VS_Z, and Z_VE_Z because there are implementation advantages to including these columns. Similarly, the primary key includes the columns Z_BranchID_Z and Z_VS_Z for implementation reasons only.


RTblSites SQL Table

This SQL table contains one row for each Repository site that is known to this Repository. The table provides a translation capability between the global site identifier that uniquely identifies a site across all repositories and the local site identifier, which is unique only within the current Repository. The smaller local site identifier is a part of the internal identifier that is used to identify a Repository object within the Repository.

The SiteID column is the primary key for this table. There is a unique index defined on the SiteGUID column.

Column Name Data Type Description

SiteID | RTSiteID | The site identifier for a Repository site that is known to this Repository.
SiteGUID | RTGUID | The global identifier for the site.
NextLocalID | RTLocalID | Reserved for proprietary usage by the Repository engine.


RTblTypeLibs SQL Table

This SQL table relates the internal object identifiers for Repository type libraries (information models) to their corresponding global identifiers. The IntID, Z_BranchID_Z, and Z_VS_Z columns form the primary key for this table.

Column Name Data Type Description

IntID | RTIntID | The internal identifier for the Repository type library.
Z_BranchID_Z | RTBrID | The value of this column is always zero.
Z_VS_Z | RTVerID | The value of this column is always zero.
Z_VE_Z | RTVerID | The value of this column is always VERINFINITY.
TypeLibID | RTGUID | The global identifier for the Repository type library, as recorded in the system registry.

Remarks

Remember that you can make only one version of each TypeLib object. Nevertheless, this table includes the columns Z_BranchID_Z, Z_VS_Z, and Z_VE_Z because there are implementation advantages to including these columns. Similarly, the primary key includes the columns Z_BranchID_Z and Z_VS_Z for implementation reasons only.


RTblVersions SQL Table

This SQL table describes Repository object versions. The IntID, Z_BranchID_Z, Z_VS_Z, Z_PredBrID_Z, and Z_PredVer_Z columns form the primary key for this table.

Column Name Data Type Description

IntID | RTIntID | The internal identifier for the object.
Z_BranchID_Z | RTBrID | A branch identifier. Indicates the branch of the Version Graph containing this object version.
Z_VS_Z | RTVerID | A version-within-branch identifier. Differentiates the version described by this row from other versions on the same branch.
Z_PredBr_Z | RTBrID | A branch identifier. For a Version Row, this column indicates the branch containing the predecessor creation version of the current object version. For a Merge Row, this column indicates the branch containing the object version that was the predecessor of the merge operation.
Z_PredVer_Z | RTVerID | A version-within-branch identifier. For a Version Row, this column indicates the predecessor creation version of the current object version. For a Merge Row, this column indicates the object version that was the predecessor of the merge operation.
TypeID | RTIntID | The internal identifier of the class to which the version conforms.
VerIntID | RTIntID | The internal identifier of this version.
Z_VState_Z | RTFlags | Indicates whether the object version is frozen or not and whether it is checked out or not. The object version is frozen only if the last (least significant) bit is set. the object version is checked out only if the second-last bit is set.
Z_PredFlags_Z | RTFlags | Indicates whether this row is a Version row or a Merge row. 1 = Version row; 2 = Merge row.
Z_SuccInc_Z | RTSuccInc | For internal use only.
Z_LClock_Z | RTLClock | For internal use only.

Remarks

Each row of this table is either a Version Row or a Merge Row. Each Version row describes an object version. Each Merge row indicates that one or more merge operations occurred between the same pair or object versions.

Because a Repository object can have many versions, it can have many Version rows. But each object has exactly one version row that describes the first version of the object. Within that Version row, the values of Z_PredBrID_Z and ZPredVer__Z are special constants indicating that the first version has no predecessor.

Because an object version can have zero, one, or many non-creation predecessors, each object version can have zero, one, or many Merge rows.


RTblWorkspaceItems SQL Table

The table describes the inclusion of Repository object versions within workspaces. The IntID, Z_BranchID_Z, Z_VS_Z, Z_ItemIntID_Z, Z_ItemBranchID_Z, and Z_ItemVS_Z columns form the primary key for this table.

Column Name Data Type Description

IntID | RTIntID | The internal identifier for the object.
Z_BranchID_Z | RTBrID | The value of this column is always zero.
Z_VS_Z | RTVerID | The value of this column is always zero.
Z_VE_Z | RTVerID | The value of this column is always VERINFINITY.
Z_ItemIntID_Z | RTIntID | The internal identifier of the object version present in the workspace.
Z_ItemBranchID_Z | RTBrID | The branch identifier of the object version present in the workspace.
Z_ItemVS_Z | RTVerID | The version-within-branch identifier of the object version present in the workspace.
Z_ItemFlag_Z | RTFlags | A set of flags indicating whether the object version is checked out to the worksapce: 0—not checked out. 2—checked out.


Topic Not Found

No matching topic was found. Some possible reasons and remedies are as follows:

  • The file (.chm) that contains the destination topic is not in the expected location.

    Remedy: Rerun the MSDN Library Setup.

  • The file (.chm) that contains the current topic or destination topic is out-of-date and the link is no longer valid.

    Remedy: Install the latest version of the MSDN Library.

  • The MSDN Library CD is not in the CD-ROM drive.

    Remedy: Insert the MSDN Library CD into the CD-ROM drive.


Changing a Destination Relationship's Name

Remember, the name associated with a naming relationship is the origin object version's name for the destination object. So changing the name of a destination naming relationship really means changing an origin version's name for the destination object. If the destination relationship has multiple items in its TargetVersions collection, each of those origin versions could have a different name for the destination object. The Repository uses its Resolution strategy to choose a particular origin object version from the destination relationship's TargetVersions collection. Then the Repository changes the origin object version's name for the destination object, unless the origin object version is unchangeable.


Changing an Object Version's Name

When you try to change the name of an object version, there might be several names the Repository tries to change:

  • If the object version implements the INamedObject interface, the Repository changes the name property exposed by INamedObject unless the object version is unchangeable.

  • If the object version has one or more destination naming relationships, the Repository tries to change a name for each of those relationships. (See changing a destination relationship's name.)


Changing an Origin Relationship's Name

When you try to change the name of an origin versioned relationship, the Repository succeeds in changing the name unless the origin object version is unchangeable.


Documentation Map

The principal sections of the Microsoft Repository documentation are the Overview, Browser, Migration Wizard, Programmer's Guide and Reference. Many of the topics in the Programmer's Guide refer to the COM Reference and Automation Reference for further information about objects, interfaces, and interface members (properties, methods, and collections).

Section | Describes | Who should read it
Repository Overview | Overview of Repository features, functions, and architecture | All users
What's New In Microsoft Repository 2.0 | New features for this release | All users
The Repository Engine Object Model | Fundamental object model | All users
Information Models | Principles of information models | All users
The Type Information Model | Object model that Repository uses to describe tool information models | Information model creators
Moving Through the Repository's Contents | Techniques for programmatically inspecting the Repository's contents | All users
Information Model Creation | Process and issues of designing information models and inserting them into the Repository | Information model creators
Repository Error Handling | Repository's error-handling mechanisms | All users
Transaction and Thread Management | Repository's transaction management capabilities | Programmers who create or populate information models; programmers who write or modify data in the Repository
Version Management | Repository's version management capabilities | Developers or users of tools that employ Repository's version management capabilities
Workspace Management | Repository's transaction management capabilities | Programmers who use Repository in a team environment
Storage Strategy in the Repository Database | How Repository stores data efficiently | Developers or users of tools that employ Repository's version management capabilities
Delete Propagation | Repository's strategy for deleting object versions and attendant relationships | Developers or users of tools that employ Repository's version management capabilities
Repository Automation Reference | Automation interfaces | Visual Basic programmers who are developing information models
Repository COM Reference | COM interfaces | C++ programmers who are developing information models
Repository Data Structure and Constants | Repository declarations and definitions | Programmers who create or populate information models; programmers who write or modify data in the Repository
Repository Errors | Error messages | All users
Repository SQL Schema | Tables for managing objects and storing information | SQL database programmers
Repository Browser | Repository interface | All users
Converting Repository 1.0 Databases | Upgrading a database from Repository 1.0 to Repository 2.0 | Users with a Repository 1.0 database
Using the Repository with Visual Basic | Using the Microsoft Development Objects Model and the Repository Add-in for Visual Basic | Visual Basic programmers


Retrieving an Object Version's Name

When you try to retrieve the name of an object version, the Repository can look in several places for the name:

  • If the object version implements the INamedObject interface, the Repository retrieves the name property exposed by that interface.

  • If the object version does not implement the INamedObject interface, the Repository seeks a destination naming relationship for the object version. With that destination naming relationship, the Repository performs object-version resolution, yielding a particular origin object version from the relationship's TargetVersions collection. The Repository retrieves the name by which that origin object version refers to the destination object.


annotational property <definition>

annotational property

A special class of repository property that can be associated with individual repository objects or relationships. Properties that are not annotational are defined for all objects of a class, and cannot be associated with relationships.


class <definition>

class

The definition of a COM object. The class is the template from which an object instance is created. The class specifies which interfaces the object implements.


collection <definition>

collection

  1. A set of repository relationships of the same relationship type that are all connected to a common source object.

  2. A set of repository objects that are all connected via instances of the same relationship type to a common source object. See origin collection, destination collection.

  3. A set of items returned from a query to a repository.


collection type <definition>

collection type

The type of a collection. It is determined by the relationship type associated with the collection relative to the role that the objects in the collection play; that is, whether the objects are origin objects or destination objects. See origin collection type, destination collection type.


COM object <definition>

COM object

An object that conforms to the Component Object Model. A COM object implements the COM interfaces that support object interaction, as well as interfaces that are specific to that class of object. All repository objects are instantiated as COM objects.


default interface <definition>

default interface

The primary interface of a class. Visual Basic allows programmers to refer to the members of the default interface directly, without having to specify the interface by name.


definition <definition>

definition

Sometimes used as a synonym for type; for example relationship definition is a synonym for relationship type.


destination collection <definition>

destination collection

A collection of repository items that all have a common destination object.


destination collection type <definition>

destination collection type

The type of a collection of repository items that all have a common destination object.


destination object <definition>

destination object

A repository object that is the destination of a relationship. Consider the relationship: Project-Has-Component. Project is the origin of the relationship, and Component is the destination of the relationship.


global identifier <definition>

global identifier

A globally unique identifier, or GUID. Used to uniquely identify COM classes and interfaces.


information model <definition>

information model

An object model that is stored in a repository. Built using the basic elements of the type information model: relationship types, classes, interfaces, properties, methods, and collection types. The term Tool Information Model and the acronym TIM are both replaced by Information Model in Repository 2.0.


instance <definition>

instance

An item that conforms to a particular definition, class, or template. For example, the instance of a class is an object; the instance of a relationship type is a relationship.


interface <definition>

interface

A defined set of properties, methods, and collections that form a logical grouping of behaviors and data. Classes are defined by the interfaces that they implement. An interface may be implemented by many different classes.


interface definition <definition>

interface definition

A synonym for interface; used when the perspective is manipulating the definition of an interface in the repository, as opposed to conforming to an interface during the execution of a program.


internal identifier <definition>

internal identifier

Internal identifier of an object within the repository. The internal identifier represents a more compact form of an object identifier. An internal identifier is only guaranteed to be unique within a single repository. An object identifier is guaranteed to be unique across all repositories.


inverted property <definition>

inverted property

Synonym for annotational property.


item <definition>

item

A repository object or relationship. More specifically, any instance of a repository-supplied class that implements the IRepositoryItem interface.


MDO Model <definition>

MDO Model

The Microsoft Development Objects Model.


member <definition>

member

A property, method, or collection type that has been defined to be a part of an interface.


metadata <definition>

metadata

Metadata is data about data.


metaproperty <definition>

metaproperty

Metaproperty is a property of a property.


method <definition>

method

An invocable function that is defined to be a member of an interface.


Microsoft Development Objects Model <definition>

Microsoft Development Objects Model

An information model provided with the repository that models Visual Basic projects.


naming collection <definition>

naming collection

A collection of repository items whose associated relationship type requires the naming of destination objects.


naming relationship <definition>

naming relationship

A repository relationship that provides a name for its destination object.


object <definition>

object

An instance of a class. The term object is not a synonym for the term repository object. While all repository objects are indeed objects, all objects are not repository objects. See COM object, repository object.


object identifier <definition>

object identifier

The identifier of an object within the repository. An object identifier is guaranteed to be unique across all repositories. See internal identifier.


object-versions version collection <definition>

object-versions version collection

A version collection that you obtain using the get_ObjectVersions method of the IRepositoryObjectVersion interface.


origin and destination

In each repository relationship, there is an origin and a destination. Consider this relationship example: Fred drives a black truck. "Person drives vehicle" is the relationship type, Fred is the origin of the relationship, and the black truck is the destination of the relationship.

Don't confuse the terms origin and destination with the terms source and target. For any particular relationship, the source and target are dependent upon whether you are navigating via the collection of origin objects or the collection of destination objects. The origin and destination for the relationship are not dependent upon which collection is being navigated.


origin collection <definition>

origin collection

A collection of repository items that all have a common origin object.


origin collection type <definition>

origin collection type

The type of a collection of repository items that all have a common origin object.


origin object <definition>

origin object

A repository object that is the origin of a relationship. Consider the relationship: Project-Has-Component. Project is the origin of the relationship, and Component is the destination of the relationship.


populate <definition>

populate

To provide with instances. For example, you populate the MDO Model with projects, components, and references.


predecessors version collection <definition>

predecessors version collection

A version collection that you obtain using the get_PredecessorVersions method of the IRepositoryObjectVersion interface.


property <definition>

property

A scalar attribute that is defined as a member of an interface. A property has an assigned data type; for example, string, or 32 bit integer. A property is a part of the definition of an interface. A property value is an instance of a property.


property value <definition>

property value

The value stored for a particular instance of an interface property.


relationship <definition>

relationship

A logical connection between one object, the origin object, and a second object, the destination object. Relationships are instantiated by the repository as COM objects.


relationship type <definition>

relationship type

The definition of a kind of relationship.


repository <definition>

repository

A database containing information models, in conjunction with the executable software that manages the database. An installation of the Microsoft Repository.


repository database <definition>

repository database

A database used as persistent storage for tool information. The type information model is also stored in the repository database.


repository engine <definition>

repository engine

The object-oriented Microsoft Repository software that provides management support for and customer access to a repository database.


repository instance <definition>

repository instance

An instance of the Repository class. A repository instance represents an open connection to a specific repository database.

Note An instance of the Repository class is typically not referred to as a repository object to avoid confusion between instances of the Repository class and instances of the RepositoryObject class.


repository item <definition>

repository item

A repository object or a repository relationship.


repository object <definition>

repository object

An instance of the RepositoryObject class. All repository objects are COM objects; however, not all COM objects are repository objects. See object, COM object.


repository type library <definition>

repository type library

A repository type library groups together the various definition objects that comprise an information model. Repository type libraries are used by the repository engine to provide Automation support. Not the same as a type library; see type library.


RepVB <definition>

RepVB

The Microsoft Repository Add-in module for Visual Basic. It populates and maintains the MDO Model with tool information about the customer's Visual Basic projects.


sequenced collection <definition>

sequenced collection

A collection of repository items whose associated relationship type supports the explicit sequencing of destination objects.


sequenced relationship <definition>

sequenced relationship

A repository relationship that provides an explicitly specified position for its destination object among the collection of destination objects.


source and target

When navigating into or out of a repository collection, the source object is the one object to which all objects in the collection are related. The target object can be any one of the objects in the collection.

Don't confuse the terms source and target with the terms origin and destination. For any particular relationship, the source and target are dependent upon whether you are navigating via the collection of origin objects or the collection of destination objects. The origin and destination for the relationship are not dependent which collection is being navigated.


source object <definition>

source object

The single object to which all objects in a particular collection are connected via relationships that are all of the same relationship type. For destination collections, the source object is the destination object. For origin collections, the source object is the origin object.


successors version collection <definition>

successors version collection

A version collection that you obtain using the get_SuccessorVersions method of the IRepositoryObjectVersion interface.


target object <definition>

target object

One of the objects in a particular collection to which a source object is connected via a relationship. For destination collections, the target objects are origin objects. For origin collections, the target objects are destination objects.


target objects version collection <definition>

target objects version collection

A version collection that you obtain using the get_TargetObjectVersions method of the IVersionedRelationship interface.


tool information <definition>

tool information

Instance data for an information model.


tool information model <definition>

tool information model

See Information Model.


type <definition>

type

The definition of a particular kind of data.


type information model <definition>

type information model

The object model that the repository uses to store information models.


type library <definition>

type library

A file (or component within another file) that contains Automation standard descriptions of exposed objects, properties, methods, and collections. Object library (.OLB) files contain type libraries. Type libraries that are shipped as stand-alone files use the extension .TLB


unique-naming collection <definition>

unique-naming collection

A collection of repository items whose associated relationship type requires the unique naming of destination objects.


unique-naming relationship <definition>

unique-naming relationship

A repository relationship that provides a name for its destination object that is unique among the collection of destination objects.


workspace-checkouts version collection <definition>

workspace-checkouts version collection

A version collection that you obtain using the get_Checkouts method of the IWorkspace interface.


workspace-contents version collection <definition>

workspace-contents version collection

A version collection that you obtain using the get_Contents method of the IWorkspace interface.


workspaces-of-item version collection <definition>

workspaces-of-item version collection

A version collection that you obtain using the get_Workspaces method of the IWorkspaceItem interface.


Accessibility for People with Disabilities

Microsoft is committed to making its products and services easier for everyone to use. This Help file provides information about the following features, products, and services, which make Microsoft Windows, Microsoft Windows NT, and Microsoft Visual Studio more accessible for people with disabilities:

Microsoft services for people who are deaf or hard-of-hearing

Microsoft documentation in alternative formats

Third-party utilities to enhance accessibility

Customizing Windows or Windows NT

More Accessibility Information

Microsoft Visual Studio product-specific accessibility information

Note The information in this section applies only to users who purchased Windows or Windows NT in the United States. If you purchased Windows or Windows NT outside the United States, your Windows package contains a subsidiary information card listing Microsoft Support Services telephone numbers and addresses. You can contact your subsidiary to find out whether the type of products and services described in this Help file are available in your area.


Copyright

Microsoft® Visual Studio™ 6.0 Development System

Information in this document is subject to change without notice. The names of companies, products, people, characters, and/or data mentioned herein are fictitious and are in no way intended to represent any real individual, company, product, or event, unless otherwise noted. Complying with all applicable copyright laws is the responsibility of the user. No part of this document may be reproduced or transmitted in any form or by any means, electronic or mechanical, for any purpose, without the express written permission of Microsoft Corporation. If, however, your only means of access is electronic, permission to print one copy is hereby granted.

Microsoft may have patents, patent applications, trademarks, copyrights, or other intellectual property rights covering subject matter in this document. Except as expressly provided in any written license agreement from Microsoft, the furnishing of this document does not give you any license to these patents, trademarks, copyrights, or other intellectual property.

© 1991-1998 Microsoft Corporation. All rights reserved.

MSDN, the Microsoft Developer Network.

Microsoft, MS, MS-DOS, MSN, ActiveX, DataTips, FoxPro, the Fox head design, IntelliSense, Developer Studio, J/Direct, Microsoft Press, Microsoft QuickBasic, PivotTable, Rushmore, Visual Basic, Visual C++, Visual FoxPro, Visual InterDev, Visual J++, Visual SourceSafe, Windows, Windows NT, Win32, and Win32s are either registered trademarks or trademarks of Microsoft Corporation in the U.S.A. and/or other countries.

Java is a trademark of Sun Microsystems, Inc.

MMX is a registered trademark of Intel Corporation.

TrueType is a registered trademark of Apple Computer, Inc.

Other product and company names mentioned herein may be the trademarks of their respective owners.


Customizing Windows or Windows NT

There are many ways you can customize Windows or Windows NT to make your computer more accessible.

  • Beginning with Windows 95, accessibility features are built in to Windows. These features are useful for individuals who have difficulty typing or using a mouse, have moderately impaired vision, or who are deaf or hard-of-hearing. The features can be installed during setup, or you can add them later from your Windows 95 installation disks. Look up "accessibility" in the Windows Help Index for information about installing and using these features.

  • Many of the features which make Windows 95 more accessible can be added to Windows NT, earlier versions of Microsoft Windows, and MS-DOS through Access Packs. You can download these files by modem, or you can order them on disks from Microsoft.

  • You can also use Control Panel and other built-in features to adjust the appearance and behavior of Windows or Windows NT to suit varying vision and motor abilities. These include adjusting colors and sizes, sound volume, and the behavior of the mouse and keyboard.

  • Dvorak keyboard layouts make the most frequently typed characters on a keyboard more accessible if you have difficulty using the standard "QWERTY" layout. There are three Dvorak layouts: one if you are a two-handed user, one if you type with your left hand only, and one if you type with your right hand only. You do not need to purchase any special equipment to use these features.

The specific features available, and whether they are built-in or must be obtained separately, depend on which operating system you are using.

For full documentation on the accessibility features available in the operating system you are using, obtain the appropriate application notes listed below. Accessibility features are also documented in the Microsoft Windows 95 Resource Kit and the Microsoft Windows NT Resource Kit.

Which Files to Download or Order

You can obtain these files by downloading them with your modem, or you can order them on disks by phone. Specific information about downloading or ordering these files immediately follows this list of files.

These files include:

  • Application notes providing more complete documentation on ways to customize Windows and Windows NT

  • Access Packs and Dvorak keyboard layouts provide additional features for versions of Windows or Windows NT in which they are not already included
For | You need
Application notes for Microsoft Windows 95 | Ww1062.exe
Application notes for Microsoft Windows NT 3.1 and 3.5 (includes Access Pack for Microsoft Windows NT) | Wn0789.exe
Application notes for Microsoft Windows for Workgroups 3.1 | Wg0788.txt
Application notes for Microsoft Windows 3.1 | Ww0787.txt
Application notes for Microsoft Windows 3.0 | Ww0786.txt
Access Pack for Microsoft Windows 3.0 and 3.1 | Accp.exe
Dvorak keyboard layouts for people who type with one hand (already included in Windows NT 3.5 and higher) | Ga0650.exe (Most network services), Ga0650.zip (Microsoft Download Service)

To Download the Access Packs, Application Notes, and Alternative Keyboard Layouts by Modem

If you have a modem, you can download these files from the following network services:

  • Microsoft's World Wide Web site on the Internet. On the www.microsoft.com home page, click Support. click Knowledge Base, and select MS-DOS as the product. Enter KBFILE GA0650.EXE, and click GO! Open the article, and click the button to download the file.

  • Microsoft’s Internet servers, ftp.microsoft.com and gopher.microsoft.com, in /softlib/mslfiles

  • MSN™, The Microsoft Network online service

  • CompuServe®, type GO MSL.

  • GEnie™

  • Microsoft Download Service (MSDL), which you can reach by calling (206) 936-6735 any time except between 1:00 A.M. and 2:30 A.M. Pacific time.

  • MSDL supports 1200, 2400, 9600, 14400, or 28800 baud rates (V.32 and V.42), with 8 data bits, no parity, and 1 stop bit.

  • Various user-group bulletin boards (such as the bulletin-board services on the Association of PC User Groups network)

To Order the Access Packs, Application Notes, and Alternative Keyboard Layouts on Disks by Phone

If you do not have a modem, within the United States you can order the Access Packs, Application Notes, and Alternative Layouts on disks by calling Microsoft Sales Information Center at (800) 426-9400 (voice) or (800) 892-5234 (text telephone).

In Canada, you can call (905) 568-3503 or (905) 568-9641 (text telephone).


Microsoft Documentation in Alternative Formats

In addition to the standard forms of documentation, many Microsoft products are also available in other formats to make them more accessible.

Many of the Visual Studio 6.0 documents are also available in online viewer format, or in print. If you have difficulty reading or handling printed documentation, you can obtain many Microsoft publications from Recording for the Blind & Dyslexic, Inc. Recording for the Blind & Dyslexic distributes these documents to registered, eligible members of their distribution service, either on audio cassettes or on floppy disks. The Recording for the Blind & Dyslexic collection contains more than 80,000 titles, including Microsoft product documentation and books from Microsoft Press.

You can contact Recording for the Blind & Dyslexic at the following address or phone numbers for information about eligibility and availability of Microsoft product documentation and books from Microsoft Press:

Recording for the Blind & Dyslexic, Inc.

20 Roszel Road, Princeton

NJ 08540

Phone:(609) 452-0606

Fax:(609) 987-8116

World Wide Web:http://www.rfbd.org


Microsoft Services for People Who Are Deaf or Hard-of-Hearing

If you are deaf or hard-of-hearing, complete access to Microsoft product and customer services is available through a text telephone (TT/TDD) service.

Sales Information

You can contact Microsoft Sales Information Center on a text telephone by dialing (800) 892-5234 between 6:30 a.m. and 5:30 p.m. Pacific time.

Technical Assistance

For technical assistance in the United States, you can contact Microsoft Support Network on a text telephone at (206) 635-4948 between 6:00 a.m. and 6:00 p.m. Pacific time, Monday through Friday, excluding holidays. In Canada, dial (905) 568-9641 between 8:00 a.m. and 8:00 p.m. Eastern time, Monday through Friday, excluding holidays. Microsoft support services are subject to Microsoft prices, terms, and conditions in place at the time the service is used.


(Untitled)

Microsoft Visual Basic Accessibility

Enlarging Toolbar Buttons

To view enlarged toolbar buttons, click Toolbars on the View menu, and click Customize, then select the Large Icons check box on the Options tab.

Enlarging Text in the Code Window

To view enlarged text in the Code window, click Options on the Tools menu. Click the Editor Format tab, and then set the font and size you want.

Customizing the Keyboard

Microsoft Visual Basic for Windows supports Dvorak keyboard layouts, which make the most frequently typed characters more accessible.

Rearranging Windows

Windows in Visual Basic can be rearranged to best suit the way you work. You can select the windows you want docked by using the list on the Docking tab of the Options dialog box, available on the Tools menu.

Customizing the Toolbox

You can customize the Toolbox by adding tabs to it or by adding controls to either the General tab or a custom tab, using the Components command on the Project menu.

Providing Visual Cues While Editing Code

Margin Indicators in the Code window allow you to provide visual cues to certain actions while editing your code. The Indicators appear on the left margin of the Code window. You can click to select or clear the Margin Indicator Bar in the Editor Format tab of the Options dialog box.

Adding Prompts for Parameters

You can also choose to display pop-up windows in the Code window. The pop-up windows can prompt you with the parameters to complete a function or statement. You can click to select or clear Parameter Info using the Parameter Info command on the Edit menu.


Microsoft Visual FoxPro Accessibility

Enlarging Toolbar Buttons

To view enlarged toolbar buttons

  1. On the View menu, click Toolbars.

  2. Select the Large buttons check box.

Enlarging Text in the Code Window

To view enlarged text in the Code window

  • On the Format menu, click Enlarge Font.

- OR -

  • On the Format menu, click Font and choose the font size you want.

- OR -

  1. With the Command window active, right-click and choose Properties on the Shortcut menu.

  2. In the Edit Properties dialog box, click the Font button and choose the font size you want.

Enlarging Text in the Debugger

To view enlarged text in the Debugger

  1. On the Options menu, click the Debug tab, then click Font.

  2. Select the font and font size you want.


Microsoft Visual Studio Product-Specific Accessibility Information

Microsoft is committed to making its products and services easier for everyone to use. This Help file provides information about the following features, products, and services, which make Microsoft Windows, Microsoft Windows NT, and Microsoft Visual Studio more accessible for people with disabilities:

Microsoft Visual Basic Accessibility

Microsoft Visual FoxPro Accessibility


More Accessibility Information

Other products, services, and resources are available from Microsoft and other organizations.

Additional Microsoft Products and Services for People with Disabilities

For more information, contact:

Microsoft Sales Information Center
One Microsoft Way
Redmond, WA 98052-6393 		World Wide Web:
Voice telephone:
Text telephone: 		http://www.microsoft.com
(800) 426-9400
(800) 892-5234

Directories of Computer Products that Help People with Disabilities

The Trace R&D Center at the University of Wisconsin–Madison produces a book and a compact disc that describe products that help people with disabilities use computers. The book, titled Trace ResourceBook, provides descriptions and photographs of about 2,000 products. The compact disc, titled CO-NET CD, provides a database of more than 18,000 products and other information for people with disabilities. It is issued twice a year.

To obtain these directories, contact:

Trace R&D Center
University of Wisconsin
S-151 Waisman Center
1500 Highland Avenue
Madison, WI 53705-2280 		World Wide Web:
Fax:
 http://trace.wisc.edu
(608) 262-8848

Referrals to Assistive Technology Programs and Trained Evaluators

For general information and recommendations on how computers can help specific needs, you should consult a trained evaluator. An assistive technology program in your area will provide referrals to programs and services that are available to you.

To locate the assistive technology program nearest you, contact:

National Information System
University of South Carolina
Center for Developmental Disabilities
Columbia, SC 29208 		Voice/text telephone:
Fax: 		(803) 935-5231
(803) 935-5059


Third-Party Utilities to Enhance Accessibility

A wide variety of third-party hardware and software products are available to make it easier to use personal computers. Among the different types of products available for the MS-DOS, Windows, and Windows NT operating systems are:

  • Programs that enlarge or alter the color of information on the screen for people with visual impairments.

  • Programs that describe information on the screen in Braille or synthesized speech for people who are blind or have difficulty reading.

  • Hardware and software utilities that modify the behavior of the mouse and keyboard.

  • Programs that enable people to "type" using a mouse or their voice.

  • Word or phrase prediction software that enables people to type more quickly and with fewer keystrokes.

  • Alternate input devices, such as single switch or puff-and-sip devices, for people who cannot use a mouse or a keyboard.

To learn more about these products, see the topic "Getting More Information."