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