Contents

Repository Overview

Installation

Repository 2.0 Issues

Limitations and More Information

Repository Overview

What Is Microsoft Repository?

Microsoft Repository is an enabling technology for defining and populating information models. It is used by engineering and software development tools to share information about engineered artifacts. Engineered artifacts are things like software components, manufactured components, documents, maps, Web pages - anything about which you might want to share information that has complex structure. Microsoft Repository stores repository data in a relational database. Two database management systems are supported: Microsoft® SQL Server version 6.5 or later and the Microsoft Jet database engine version 3.0 or later.

What Is New in Microsoft Repository 2.0?

Microsoft Repository 2.0 contains significant enhancements in the areas of version management and team development while maintaining backward compatibility with Microsoft Repository 1.0 interfaces.

The major areas of new functionality are:

• Versioning of objects: allows the repository user to maintain multiple versions of repository objects.
• Versioning of relationships: allows the repository user to maintain multiple versions of relationships between objects.
• Workspace management: provides a virtual repository for users in which they can manipulate private versions of objects and relationships. A Checkin/Checkout model allows users to control what information is visible in the users' workspaces and what changes are made visible to other users. This new functionality is described in detail in the user documentation and specifications that accompany the software.

Important Information for Release 2.0 Customers

Users should also be aware of the following:

• Microsoft Repository 2.0 is backward-compatible with version 1.0 functionality and interfaces. If all of the applications using a repository database use only version 1.0 functionality, no incompatibilities will occur. Likewise, if all the applications using a repository database are version- and workspace-aware, they should be successful. Mixing applications that are version-aware with applications that are not version- and workspace-aware on the same repository database is not recommended.
• The Microsoft Repository 2.0 SQL schema is an extension of the Microsoft Repository 1.0 schema because of the introduction of versioning. Applications that bypass repository interfaces to access SQL tables directly may have to modify queries or provide views for backward compatibility.
• The migration wizard (MigRepV2.exe) converts Microsoft Repository underlying database information from version 1.0 to version 2.0 (SQL to SQL, and Jet to Jet). You must have the Microsoft Repository engine version 2.0 (V2 engine) registered before running the migration wizard. Notice that the migration is one way only, from version 1.0 to version 2.0.
• Microsoft Repository 2.0 provides no support for the WRITETHROUGH mode of transaction execution.
• Microsoft Repository 2.0 supports Intel x86 and Alpha platforms.

Installation

Repository Installation Notes

Microsoft Repository is installed during a Visual Basic installation.

Microsoft Repository requires that the Data Access component be installed. By default, the Data Access component is installed during a Visual Basic installation. However, if you choose not to install the Data Access component, and then install a third party tool that uses Microsoft Repository, you will encounter the following error when starting Visual Basic 98:

"An error occurred while opening the Microsoft Repository database. Specified driver could not be loaded due to system error 126 (Microsoft Access Driver (*.MDB)). Microsoft Repository Add-in for Visual Basic is shutting down."

To correct this problem, install the Data Access component.

Repository Files on Your Hard Disk

The following files will be added to the Windows SYSTEM (or SYSTEM32) directory:

• REPUTIL.DLL - Utilities for the Repository engine

The following files will be added to the "Program Files\Common Files\Microsoft Shared\Repostry" directory:

• REPODBC.DLL - The Repository Engine
• REPRC.DLL - Resources for the Repository Engine
• REPBROWS.EXE - A basic Repository Browser
• REPBRRC.DLL - Resources for the Repository Browser
• MIGREPV2.EXE - The Migration Wizard User Interface
• MIGV2RC.DLL - Resources for the Migration Wizard
• MIGV2.DLL - The Migration Wizard Algorithm
• REPCDLG.DLL - The Repository Common Dialog
• REPCDLG.OCX - ActiveX controls for the Repository Common Dialog
• REPCDRC.DLL - Resources for the Repository Common Dialog

The following files will be added to the "Program Files\Common Files\Microsoft Shared\Repostry\infoMdl" directory:

• REPCDE.DLL - The Component Description Information Model
• REPCOM.DLL - The COM Information Model
• REPDTM.DLL - The Data Type Information Model
• REPGEN.DLL - The Generic Information Model
• UML.DLL - The Unified Modeling Language (UML) Information Model
• REPUMX.DLL - The UML Extension Information Model
• REPVCM.DLL - The Visual Component Manager Model

The following files will be added to the Visual Basic directory:

• REPVB.DLL - The Repository Add-in for Visual Basic
• REPVBRC.DLL - Resource file for Repository Add-in
• REPVBTIM.DLL - Type definitions for the MDO Model

Repository 2.0 Issues

Differences Between Repository 1.0 and Repository 2.0

Repository 1.0 Usage

If the repository database was created using the Repository 1.0 engine and has been used for information model creation, population, and retrieval only through this engine, there will be some differences when you run the same application with the Repository 2.0 engine. The differences arise from the treatment of relationships, as listed below:

• In Repository 1.0, if an application inserts a name-unique relationship with an existing name, the name-uniqueness violation is caught immediately. In Repository 2.0, the violation is caught immediately only if the existing relationship is in the cache (for example, created as part of the same transaction or retrieved into the cache already). Otherwise, the name-uniqueness validation occurs at commit time.

• Enumerators in the Repository 1.0 engine, except those for relationship collections, have static contents, so added items do not appear until a new enumerator is requested from the collection. In the Repository 2.0 engine, enumerators are dynamic, so added items appear immediately in the enumerator.

• In Repository 1.0, if the insertion position in IRelationshipCol::Insert() is larger than the current count of the collection, the call is treated as IRelationshipCol::Add(). In Repository 2.0, if the specified insertion position is one greater than the current count, then the call reduces to IRelationshipCol::Add(). For higher insertion positions, the call returns an error since the user presumably made a mistake (it would be bad programming in any case).

• Invoking IRelationshipCol::Insert() on a nonsequenced or destination collection results in an error in Repository 2.0. In Repository 1.0, the call performs IRelationshipCol::Add() on the origin if the collection is sequenced.

Mixed-mode Repository 1.0 and Repository 2.0 Usage

It is conceivable that a Repository 1.0 application might be run on the Repository 2.0 engine, in which versioning operations are performed by other applications on the same repository. The engine of course has to respect the semantics of versioning, and some of those semantics will necessarily be visible to the nonversioning application. A Repository 1.0 application can only see these effects when operating on a repository database in which Repository 2.0 applications are performing version and workspace operations. These effects do not arise when all applications on a repository database are following Repository 1.0 semantics. In addition to the effects mentioned above, the following could arise:

• A Repository 1.0 application can retrieve an object using get_Object() (it gets the resolved version), delete it (the version is deleted), and still use get_Object() a second time (the call resolves to a different version).

• Since all objects are unfrozen in Repository 1.0, updates never failed in Repository 1.0. However, in Repository 2.0, all update operations (property and origin collection updates) on a frozen version or a checked-out version will fail.

• In Repository 2.0, a delete operation on a checked-out version or a version with a successor will fail. Neither of these situations could arise in Repository 1.0.

• In Repository 1.0, IRelationship::Delete() removes the relationship entirely so that the relationship no longer exists at the origin or the destination objects. In Repository 2.0, if we have navigated from the destination side, the relationship from the origin version to any other versions of the destination continues to exist after the deletion. If we have navigated from the origin side, the relationship from that version to all versions of the destination in the relationship is removed. Similar behavior holds true for IRelationshipCol::Remove() and ITargetObjectCol::Remove().

• In Repository 1.0, delete propagation stops at an object if it is the destination of some other relationship of the same type. In Repository 2.0, in addition to this condition, delete propagation stops at an unchangeable version (frozen or checked out to a different workspace) and versions that have incoming relationships (of any type) from a frozen origin (that is, no error).

SQL Tables

• The Repository 2.0 SQL tables are extensively revised for versioning. SQL views that match Repository 1.0 SQL queries executed on a repository database in which all objects have one version should work with no change.

• Repository 1.0 SQL queries executed on a repository in which multiple versions of objects exist will likely execute to completion, but their semantics should be reviewed in light of versioning. In certain situations multiple versions of the same object may be returned by the queries, which a Repository 1.0 application might not expect.

• The table RTblSites does not have the NextLocalID column in Repository 2.0.

• The table RTblClassDefs has a new column called VerPropDescs where the class definition is stored in Repository 2.0. The column PropDescs contains only null values and is no longer used. However, it is retained for compatibility.

Miscellaneous

The following table shows other differences between Repository 1.0 and Repository 2.0.

Asynchronous Operation

Loading of object collections in response to IRepositoryODBC::ExecuteQuery() can be asynchronous. The calling thread should check to determine whether the load is complete. If the calling thread tries to read data, refresh the collection, or construct an enumerator while loading is in progress, it will be blocked until the load is complete.

• For setting/clearing "async" option:

• For loading status of object:

READY = 1                // Loading is complete

INPROGRESS = 2           // Loading in progress

CANCELLED = 3            // Loading has been cancelled (by caller)

FAILED = 4               // Loading failed (reason unknown)

• IObjectCol2 -- inherits from IObjectCol.

Additional methods:

• LoadStatus: Obtains the load status of the collection.

Signature

HRESULT LoadStatus(long *piStatus)                   // Automation

HRESULT get_LoadStatus(long *piStatus)            // COM

Arguments

piStatus

[out, retval]

One of READY/INPROGRESS/CANCELLED/FAILED.

Return value

S_OK if successful, EREP_BADPARAMS if no output argument is provided.

• Cancel: Requests the cancellation of the ongoing load operation.

Signature

HRESULT Cancel()

Return value

S_OK.

• IRepositoryODBC2 -- inherits from IRepositoryODBC.

Additional methods:

• GetOption: Obtains the value of the load option.

SetOption: Sets the option for loading the collection. The async flag can be set if and only if the underlying database system supports the async operation.

Signature

HRESULT SetOption(long iOption, VARIANT sValue)

Input Arguments

iOption RODBC_ASYNCH and sValue TRUE sets the async mode of load.

iOption RODBC_ASYNCH and sValue FALSE clears the async mode.

iOption RODBC_RESET_OPTIONS resets the async mode of load.

Return value

S_OK if successful, EREP_TYPE_COLMISMATCH if a value other than TRUE or FALSE is specified in sValue when iOption is RODBC_ASYNCH.

• Class ObjectCol supports both IObjectCol [default] and IObjectCol2.

• IObjectCol2::Refresh() asynchronously refreshes the object collection (reloads object collection and refreshes target objects) when the async mode is in effect. The calling thread should check to determine whether refresh is complete. If the calling thread tries to read data, refresh the collection, or construct an enumerator while refresh is in progress, it will be blocked until refresh is complete.

SQL and API Types Used in Property Definitions

The following two tables show the API types recognized by the Repository engine, as well as the SQL types. These values appear in the APIType and SQLType properties of a PropertyDef Object. For information on conversion between SQL and API types, please refer to the ODBC Programmer's Reference.

New Features

Properties

Two new properties have been added to the IRepository2 interface to indicate the version of the database file.

• MajorDBVersion

Signature

HRESULT MajorDBVersion(long *piMajorDBVersion)             // Automation

HRESULT get_MajorDBVersion( long *piMajorDBVersion)      // COM

Arguments

piMajorDBVersion

[out, retval]

The major version number of the first Repository engine version that introduced this database format.

• MinorDBVersion

Signature

HRESULT MinorDBVersion(long *piMinorDBVersion)             // Automation

HRESULT get_MinorDBVersion( long *piMinorDBVersion)      // COM

Arguments

piMinorDBVersion

[out, retval]

The minor version number of the first Repository engine version that introduced this database format.

Methods

A new method CreateObjectEx() has been added to the interface IRepository2. It creates the first version of a new Repository object of the specified type. The newly created version is assigned the object-version identifier passed in as an argument, unlike IRepository::CreateObject(), in which the Repository assigns the version ID. It has the following syntax:

Signature

HRESULT IRepository2::CreateObjectEx(

VARIANT TypeID,

VARIANT ObjectID,

VARIANT ExtVersionID,

IRepositoryObjectVersion **ppRepObjVer);

Arguments

TypeID

[in]

It does the same work as IRepository::CreateObject

 

ObjectID

[in]

It does the same work as IRepository::CreateObject 

 

ExtVersionID

[in]

This is the object-version identifier (20 bytes) to be assigned to the first version of the object

 

ppRepObjVer

[out]

This is the IRepositoryObjectVersion pointer to the newly created version

Known Limitations in Microsoft Repository 2.0

1. Limitations related to interfaces and associated methods

IRepositoryObjectVersion

• MergeVersion(): Relationships are inserted at the end of the sequenced collection.

IRelationshipCol and ITargetObjectCol

• Remove(): Removal from a sequenced collection does not update the collection sequence order.

IVersionAdminInfo

• VersionModifyTime(): Does not change when an origin relationship or target object collection is modified.
• ModifyByUser(): Does not change when an origin relationship or target object collection is modified.

IRepository2

• CreateObject(): Can only be called from the shared repository but not from a workspace. The workaround is to create the object through the central repository and include it in the workspace.

IClassDef and IInterfaceDef

• ObjectInstances(): Not workspace scoped.

2. Repository constants

In the Repository documentation, it is mentioned that the maximum length, in bytes, of a name that a relationship assigns to its destination object is 260 as defined by the constant RELSHIPNAMESIZE. This value is actually 249.

3. Conventions for names

Names of relationships and objects must follow these conventions:

1. Names can be no longer than 249 characters.

2. Any characters can be used in a name.

3. The name can contain leading or trailing spaces. It can also be an empty string.

4. If the name is all spaces, it is treated as an empty string.

This applies to names used inside quotation marks or stored inside variables. For example, the following "IFolder" interface must meet these restrictions:

oFolder("IFolder").FolderName

oFolder(sIFolder).FolderName

However, these guidelines are not accurate for names specified outside of quotation marks (such as property names or relationship collection names). For example, the relationship collection "RcFolderContains" below:

oFolder("IFolder").RcFolderContains.Count

4. Stored Procedures

The stored procedure name for a table is generated by prefixing the table name with the string "R_i". Since table names are unique, this will generate unique stored procedure names. If the table name’s length is greater than MaxIdentifierLength-3, however, the table name generation algorithm fails. For this reason, a user may not supply a table name longer than MaxIdentifierLength-3. Supplying a longer name causes the error EREP_BADNAME.

When the user supplies no table name for an interface, the engine automatically generates the table name from the interface name. If the interface name, with the leading "I" stripped off, is less than MaxIdentifierLength-4, the interface name will be used as the table name. Otherwise, the interface name is truncated to MaxIdentifierLength-7, and a 4-character number (called a "uniqifier") is appended to the name to make it unique, before prefixing R_i.

The engine uses named arguments to call the stored procedures. A named argument starts with the "@" character and is not longer than MaxIdentifierLength. Therefore, the property names, which are also column names, must be no longer than MaxIdentifierLength-1.

MaxIdentifierLength’s are:

• 30 characters for SQL Server 6.5
• 128 characters for SQL Server 7.0

5. Table Definitions

• RTblSumInfo
• RTblNamedObj
• RTblVersionAdminInfo

RTblSumInfo

RTblNamedObj

RTblNamedObj is an interface-specific table; its columns correspond to the properties exposed by the INamedObject interface. By default, no class of the Repository Type Information Model implements INamedObject. Thus the Repository database does not, by default, include the table RTblNamedObj. Instead, the Repository omits the table from the database to save space. However, as soon as you insert into the Repository any class that implements INamedObject, Repository creates the table.

• If a SQLSize is set to a value greater than 65535, the engine divides the entered number by 65536 and sets SQLSize to the value of the remainder of the division, but no error is returned.

• In the help topic "The Migration Algorithm" there are references to two tables, RTblRelColPairs and RTblTimestamp. In the Repository 2.0 database, the first table does not exist, and the second table has been replaced by RTblVersionAdminInfo.