mkhlink

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

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.

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 path name: the VOB tag of the VOB in which the hyperlink is created.

• When specifying a hyperlink in UNIX® or Linux®, you can use any path name within the VOB in place of the VOB tag path name:

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

  You can omit the path name 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 path name 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:

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

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.

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.

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.

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.

Default

Creates one or more event records, with commenting controlled by your .versionvault_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.

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]

hlink-type-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)

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 path name to an element specifies the version in the view.
• A version-extended path name 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 path name.

  Examples:

Table

foo.c	Version of foo.c selected by current view
/view/gam/usr/project/src/foo.c	Version of foo.c selected by another view
foo.c@@\main\5	Version 5 on main branch of foo.c
foo.c@@/REL3	Version of foo.c with version label REL3
foo.c@@	Version of foo.c with version label REL3
foo.c@@\main	The 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]
policy-selector	[policy:]policy-name[@vob-selector]
rolemap-selector	[rolemap:]rolemap-name[@vob-selector]
The following object selector is valid only if you use MultiSite:
replica-selector	replica:replica-name[@vob-selector]