mkhlink

Attaches a hyperlink to an object

APPLICABILITY

ProductCommand type
ClearCasecleartool subcommand
ClearCase LTcleartool subcommand

Platform
UNIX
Windows

SYNOPSIS

mkhlink [ –uni·dir ] [ –tte·xt to-text ] [ –fte·xt from-text ]
[ –fpn·ame ] [ –tpn·ame ] [ –acq·uire ]
[ –c·omment comment | –cfi·le comment-file-pname |–cq·uery | –cqe·ach
| –nc·omment ] hlink-type-selector from-obj-selector [ to-obj-selector ]

DESCRIPTION

The mkhlink command creates a hyperlink between two objects, each of which may be an element, branch, version, VOB symbolic link, or non-file-system VOB object (except another hyperlink).

Logically, a hyperlink is an “arrow” attached to one or two VOB-database objects:

  • A bidirectional hyperlink connects two objects, in the same VOB or in different VOBs, with optional text annotations at either end. It can be navigated in either direction: from-object → to-object or to-object → from-object.
  • A unidirectional hyperlink connects two objects in different VOBs, with optional text annotations at either end. It can be navigated only in the from-object → to-object direction.
  • A text-only hyperlink associates one object with a user-defined text string (for example, an element that implements a particular algorithm with the name of a document that describes it).
  • A null-ended hyperlink has only a from-object. Use this kind of hyperlink to suppress hyperlink inheritance (see “Hyperlink Inheritance”).

Contrast with Other Kinds of Metadata

Like other kinds of metadata annotations—version labels, attributes, and triggers—a hyperlink is an instance of a type object: the mkhlink command creates an instance of an existing hyperlink type object. However, hyperlinks differ from other kinds of metadata annotations:

  • The hyperlink created by mkhlink is also an object in itself. Each hyperlink object has a unique ID (see “Hyperlink IDs”) and can itself be annotated with attributes. By contrast, a mklabel, mkattr, or mktrigger command does not create a new object; it simply annotates an existing object.
  • You can attach several hyperlinks of the same type to one object, but only one instance of a particular label, attribute, or trigger type. (For example, you can attach two different DesignFor hyperlinks to the same object, but not two different ECOnum attributes.)

Hyperlink IDs

Each new hyperlink object gets a unique identifier, its hyperlink ID. You can specify any hyperlink by appending its hyperlink ID to the name of the hyperlink type. Following are some examples.

Note: In the UNIX examples that follow, arguments and output that show multicomponent VOB tags are not applicable to ClearCase LT, which recognizes only single-component VOB tags. In this manual, a multicomponent VOB tag is by convention a two-component VOB tag of the form /vobs/vob-tag-leaf—for example, /vobs/src. A single-component VOB tag consists of a leaf only—for example, /src. In all other respects, the examples are valid for ClearCase LT.

cmd-context  describe hlink:DesignFor@52179@/vobs/doctn 

In this example, DesignFor is the name of a hyperlink type, and @52179@/vobs/doctn is the hyperlink ID. Note that the hyperlink ID includes a pathname: the VOB tag of the VOB in which the hyperlink is created.

  • When specifying a hyperlink in UNIX, you can use any pathname within the VOB in place of the VOB tag pathname:

    cd /vobs
    cmd-context describe hlink:DesignFor@52179@doctn

    You can omit the pathname if the current working directory is in that VOB:

    cd /vobs/doctn 
    cmd-context  describe hlink:DesignFor@52179 

  • When specifying a hyperlink in Windows, you can omit the pathname if the current working directory is in that VOB:

    cd \doctn_vb\src 
    cmd-context  describe hlink:DesignFor@52179 

A hyperlink ID is unique in that it is guaranteed to differ from the hyperlink ID of all other hyperlinks. But it can change over time; when a VOB's database is processed with reformatvob, the numeric suffixes of all hyperlink IDs change:

before 'reformatvob':@52179@/vobs/doctn
after 'reformatvob':@8883@/vobs/doctn

Similarly, the VOB tag part of a hyperlink ID can change over time and can vary from host to host.

Hyperlink Inheritance

By default, a version implicitly inherits a hyperlink attached to any of its ancestor versions, on the same branch or on a parent branch. Inherited hyperlinks are listed by the describe command only if you use the –ihlink option.

A hyperlink stops being passed down to its descendents if it is superseded by another hyperlink of the same type, explicitly attached to some descendent version. You can use a null-ended hyperlink (from-object, but no to-object) as the superseding hyperlink to effectively cancel hyperlink inheritance.

RESTRICTIONS

Identities

You must have one of the following identities:

  • Element owner
  • Element group member
  • Object owner
  • Object group member
  • VOB owner
  • root (UNIX)
  • Member of the ClearCase administrators group (ClearCase on Windows)
  • Local administrator of the ClearCase LT server host (ClearCase LT on Windows)

Locks

An error occurs if one or more of these objects are locked: VOB, element type, element, branch type, branch, hyperlink type, object or object type (for non-file-system objects).

Mastership

(Replicated VOBs only) If the hyperlink's type is unshared, your current replica must master the type. If the hyperlink's type is shared, there are no mastership restrictions. If the hyperlink's type is global and shared, your current replica must contain a local copy of the type, or the administrative VOB at the current site must master the type.

OPTIONS AND ARGUMENTS

Unidirectional/Bidirectional

Default
Creates a bidirectional hyperlink. If the objects being linked are in different VOBs, a notation is made in the VOB database of the to-object, making it possible to see the hyperlink from either VOB.

–uni·dir
Creates a unidirectional hyperlink; no notation is made in the VOB database of the to-object (if that object is in a different VOB).

Note: In all cases, a single hyperlink object is created, in the VOB of the from-object.

Text Annotations

Default
The hyperlink has no text annotations.

–tte·xt to-text
Text associated with the to-end of a hyperlink. If you also specify to-obj-pname, the text is associated with that object. If you do not specify to-obj-pname, cleartool creates a text-only hyperlink, originating from from-obj-pname. If you omit both –ttext and to-obj-pname, cleartool creates a null-ended hyperlink.

–fte·xt from-text
Text associated with the from-end of a hyperlink.

Handling Eclipsed Hyperlink Types

Default
If the hyperlink type in a client VOB would eclipse an existing hyperlink type in an administrative VOB, hyperlink type creation fails.

–acq·uire
Converts eclipsing types to local copies of the new global type.

Event Records and Comments

Default
 Creates one or more event records, with commenting controlled by your .clearcase_profile file (default: –nc). See the comments reference page. Comments can be edited with chevent.

–c·omment comment | –cfi·le comment-file-pname |–cq·uery | –cqe·ach | –nc·omment
Overrides the default with the option you specify. See the comments reference page.

Specifying the Hyperlink Type

Default
None.

hlink-type-selector
An existing hyperlink type. The hyperlink type must exist in each VOB containing an object to be hyperlinked, or (if hlink-type-selector is a global type) in the administrative VOB hierarchy associated with each VOB. Specify hlink-type-selector in the form [hltype:]type-name[@vob-selector]
type-name Name of the hyperlink type
vob-selector Object-selector for a VOB, in the form [vob:]pname-in-vob. The pname-in-vob can be the pathname of the VOB tag (whether or not the VOB is mounted) or of any file system object within the VOB (if the VOB is mounted)

Objects to Be Hyperlinked

Default
None. You must specify at least one object.

[ –fpn·ame ] from-obj-selector , [ –tpn·ame ] to-obj-selector
from-obj-selector specifies the from-object, and to-obj-selector specifies the to-object. to-obj-selector is optional; omitting it creates a text-only hyperlink (if you use –ttext) or a null-ended hyperlink (if you don't).

Note: An error occurs if you try to make a unidirectional hyperlink whose to-obj-selector is a checked-out version in another VOB.

Specify from-obj-selector and to-obj-selector in one of the following forms:

pname
  • A standard or view-extended pathname to an element specifies the version in the view.

  • A version-extended pathname specifies an element, branch, or version, independent of view.

  • The pathname of a VOB symbolic link.

    Note: If pname has the form of an object selector, you must include the –fpname or –tpname option to indicate that pname is a pathname.

    Examples:

foo.cVersion of foo.c selected by current view
/view/gam/usr/project/src/foo.cVersion of foo.c selected by another view
foo.c@@\main\5Version 5 on main branch of foo.c
foo.c@@/REL3Version of foo.c with version label REL3
foo.c@@Version of foo.c with version label REL3
foo.c@@\mainThe main branch of element foo.c
vob-selector vob:pname-in-vob
 pname-in-vob can be the pathname of the VOB tag (whether or not the VOB is mounted) or of any file system object within the VOB (if the VOB is mounted). It cannot be the pathname of the VOB storage directory.
attribute-type-selector attype:type-name[@vob-selector]
branch-type-selector brtype:type-name[@vob-selector]
element-type-selector eltype:type-name[@vob-selector]
hyperlink-type-selector hltype:type-name[@vob-selector]
label-type-selector lbtype:type-name[@vob-selector]
trigger-type-selector trtype:type-name[@vob-selector]
pool-selector pool:pool-name[@vob-selector]
oid-obj-selector oid:object-oid[@vob-selector]
  
The following object selector is valid only if you use MultiSite:
replica-selector replica:replica-name[@vob-selector]

EXAMPLES

The UNIX examples in this section are written for use in csh. If you use another shell, you may need to use different quoting and escaping conventions.

The Windows examples that include wildcards or quoting are written for use in cleartool interactive mode. If you use cleartool single-command mode, you may need to change the wildcards and quoting to make your command interpreter process the command appropriately.

In cleartool single-command mode, cmd-context represents the UNIX shell or Windows command interpreter prompt, followed by the cleartool command. In cleartool interactive mode, cmd-context represents the interactive cleartool prompt.

Note: In the UNIX examples that follow, arguments and output that show multicomponent VOB tags are not applicable to ClearCase LT, which recognizes only single-component VOB tags. In this manual, a multicomponent VOB tag is by convention a two-component VOB tag of the form /vobs/vob-tag-leaf—for example, /vobs/src. A single-component VOB tag consists of a leaf only—for example, /src. In all other respects, the examples are valid for ClearCase LT.

  • Create a hyperlink type. Then create a unidirectional, element-to-element hyperlink between an executable and its GUI counterpart in another VOB.

    cmd-context  mkhltype -nc gui_tool 
    Created hyperlink type "gui_tool". 
    cmd-context  mkhlink -unidir gui_tool monet@@ /vobs/gui/bin/xmonet@@ 
    Created hyperlink "gui_tool@1239@/usr/hw". 

  • Create a hyperlink of type design_spec connecting the versions of a source file and design document labeled REL2.

    cmd-context  mkhlink design_spec util.c@@\REL2  \users_hw\doc\util.doc@@\REL2 
    Created hyperlink "design_spec@685@\users_hw".

  • Create three hyperlinks of the same type from the same version of a design document; each hyperlink points to a different source file element.

    cmd-context mkhlink design_for sortmerge.doc ../src/sort.c 
    Created hyperlink "design_for@4249@/vobs/proj".
    cmd-context  mkhlink design_for sortmerge.doc ../src/merge.c 
    Created hyperlink "design_for@4254@/vobs/proj".
    cmd-context  mkhlink design_for sortmerge.doc ../src/sortmerge.h 
    Created hyperlink "design_for@4261@/vobs/proj".

  • Create an element-to-element hyperlink between a source file and a script that tests it. Specify both from-text and to-text for further annotation.

    cmd-context  mkhlink -ttext "regression A" -ftext "edge effects" ^
    tested_by cm_add.c@@ edge.sh@@
     
    Created hyperlink "tested_by@714@\users_hw".

  • Create a hyperlink of type fixes between the version of util.c in your view and the element bug.report.21. Use to-text to indicate the bug number (“fixes bug 21”).

    cmd-context  mkhlink -ttext "fixes bug 21" fixes  util.c /usr/hw/bugs/bug.report.21@@ 
    Created hyperlink "fixes@746@/usr/hw".

  • Create a text only hyperlink of type design_spec to associate the algorithm convolution.c with the third-party document describing that algorithm. Make the hyperlink between the element convolution.c and the to-text that describes it.

    cmd-context  mkhlink -ttext "Wilson: Digital Filtering, p42-50" ^
    design_spec convolution.c@@
     
    Created hyperlink "design_spec@753@\users_hw".

SEE ALSO

describe, lstype, mkhltype, rename, rmhlink, xclearcase



Copyright© 2003 Rational Software. All Rights Reserved.