Rational ClearCase Commands Reference: type

Commands Index:

  * intro
  annotate
  apropos
  catcr
  catcs
  cc.icon
  cc.magic
  cd
  chactivity
  chbl
  checkin
  checkout
  checkvob
  chevent
  chflevel
  chfolder
  chmaster
  chpool
  chproject
  chstream
  chtype
  chview
  clearaudit
  clearbug
  cleardescribe
  cleardiffbl
  cleardiff
  clearexport_ccase
  clearexport_cvs
  clearexport_pvcs
  clearexport_rcs
  clearexport_sccs
  clearexport_ssafe
  clearfsimport
  cleargetlog
  clearhistory
  clearimport
  clearjoinproj
  clearlicense
  clearmake
  clearmake.options
  clearmrgman
  clearprojexp
  clearprompt
  cleartool
  clearviewupdate
  clearvobadmin
  comments
  config_ccase
  config_spec
  cptype
  credmap
  creds
  deliver
  describe
  diffbl
  diffcr
  diff
  dospace
  edcs
  endview
  env_ccase
  events_ccase
  export_mvfs
  exports_ccase
  file
  find
  findmerge
  fmt_ccase
  getcache
  get
  getlog
  help
  hostinfo
  init_ccase
  ln
  lock
  lsactivity
  lsbl
  lscheckout
  lsclients
  lscomp
  lsdo
  lsfolder
  lshistory
  ls
  lslock
  lsmaster
  lspool
  lsprivate
  lsproject
  lsregion
  lsreplica
  lssite
  lsstgloc
  lsstream
  lstype
  lsview
  lsvob
  lsvtree
  makefile_aix
  makefile_ccase
  makefile_gnu
  makefile_pmake
  makefile_smake
  makefile_sun
  man
  merge
  mkactivity
  mkattr
  mkattype
  mkbl
  mkbranch
  mkbrtype
  mkcomp
  mkdir
  mkelem
  mkeltype
  mkfolder
  mkhlink
  mkhltype
  mklabel
  mklbtype
  mkpool
  mkproject
  mkregion
  mkstgloc
  mkstream
  mktag
  mktrigger
  mktrtype
  mkview
  mkvob
  mount_ccase
  mount
  msdostext_mode
  mvfslog
  mvfsstorage
  mvfstime
  mvfsversion
  mv
  omake
  pathnames_ccase
  permissions
  profile_ccase
  promote_server
  protect
  protectvob
  pwd
  pwv
  query_language
  quit
  rebase
  recoverview
  reformatview
  reformatvob
  register
  relocate
  rename
  reqmaster
  reserve
  rgy_backup
  rgy_check
  rgy_passwd
  rgy_switchover
  rmactivity
  rmattr
  rmbl
  rmbranch
  rmcomp
  rmdo
  rmelem
  rmfolder
  rmhlink
  rmlabel
  rmmerge
  rmname
  rmpool
  rmproject
  rmregion
  rmstgloc
  rmstream
  rmtag
  rmtrigger
  rmtype
  rmver
  rmview
  rmvob
  schedule
  schemes
  scrubber
  setactivity
  setcache
  setcs
  setplevel
  setsite
  setview
  shell
  snapshot.conf
  softbench_ccase
  space
  startview
  type_manager
  umount
  uncheckout
  unlock
  unregister
  unreserve
  update
  version_selector
  view_scrubber
  vob_restore
  vob_scrubber
  vob_sidwalk
  vob_snapshot
  vob_snapshot_setup
  wildcards_ccase
  winkin
  xclearcase
  xcleardiff
  xmldiffmrg

type_manager

Manages contents of element versions

APPLICABILITY

Product	Command Type
ClearCase	data structure
ClearCase LT	data structure

Platform
UNIX
Windows

SYNOPSIS

UNIX—Type manager directory:
ccase-home-dir/lib/mgrs/manager-name
Windows—Type manager map file:
ccase-home-dir\lib\mgrs\map
Methods, some or all of which are supported by each type manager:
annotate, compare, construct_version, create_branch, create_element, create_version, contex_merge, delete_branches_versions, get_cont_info, merge, xcompare, xmerge

DESCRIPTION

A type manager is a suite of programs that manipulates files with a particular data format; different type managers process files with different formats. A directory type manager provides programs that compare and/or merge versions of directory elements. ClearCase and ClearCase LT provide several type managers. On UNIX, users can create additional ones.

Several version-control methods for file elements are implemented in two phases:

Updating of the VOB database. This phase is independent of the element's data format and is handled directly by cleartool.
Manipulation of the element's data. In this phase, the data format is extremely significant, and so is handled by a particular type manager. The type manager is invoked as a separate program, rather than as a subroutine. This provides flexibility and openness, allowing users to integrate their own data-manipulation routines with ClearCase or ClearCase LT.

For example, checking in a text_file element involves the following:

Storing information in the VOB database about the creator of the new version, when it was created, and so on
Computing and storing the delta (incremental difference) between the new version and its predecessor.

For a different type of element—for example, a bitmap file—the delta is computed differently, or not at all, and so requires a different type manager.

TYPE MANAGERS

Following are descriptions of the type managers:

Manager	Function
whole_copy	Stores any data. Stores a whole copy of each version in a separate data container file.
z_whole_copy	Stores any data. Stores each version in a separate, compressed data container file using the gzip compression program. Note that compressed files generally take more time to check in (because they must be compressed) and to reconstruct when first accessed (first cleartext fetch).
text_file_delta	Stores text files only (including those with multibyte text characters). Stores all versions in a single structured data container file. (On UNIX, similar to an SCCS s. file or an RCS ,v file.) Uses incremental file differences to reconstruct individual versions on the fly.
z_text_file_delta	Stores text files only. Stores all versions in a single structured data container file, in compressed format using both the gzip compression program and deltas.
binary_delta	Stores any data. Stores each branch's versions in a separate, structured compressed data container file using gzip. Uses incremental file differences to reconstruct individual versions on the fly. Version deltas are determined by comparing files on a per-byte basis.
_html	Stores HTML source. Stores information and reconstructs versions in the same way as the text_file_delta manager from which it is derived. Has its own compare, xcompare, merge and xmerge methods.
_html2	Same as the _html manager, except that _html2 is based on the binary_delta manager.
_ms_word	Stores Microsoft Word documents. Stores information and reconstructs versions in the same way as the z_whole_copy manager from which it is derived. On Windows, has its own xcompare and xmerge methods.
_rose	Stores Rational Rose artifacts. Stores information and reconstructs versions in the same way as the text_file_delta manager from which it is derived. On Windows, has its owncompare, xcompare, merge, and xmerge methods.
_rose2	Same as the _rose manager, except that _rose2 is based on the binary_delta manager.
_rosert	Stores Rational Rose RealTime artifacts. Stores information and reconstructs versions in the same way as the binary_delta manager from which it is derived. On Windows, has its owncompare, xcompare, merge, and xmerge methods
_xde	Stores Rational XDE artifacts. Stores information and reconstructs versions in the same way as the text_file_delta manager from which it is derived. On Windows, has its own merge, xmerge, compare, and xcompare methods.
_xde2	Same as the _xde manager, except that _xde2 is based on the binary_delta manager and it provides a context_merge method.
_xml	Stores XML source. Stores information and reconstructs versions in the same way as the text_file_delta manager from which it is derived. On Windows, has its own compare, xcompare, merge, and xmerge methods.
_xml2	Same as the _xml manager, except that _xml2 is based on the binary_delta manager.
directory	Not involved in storing/retrieving directory versions, which reside in the VOB database, not in a source storage pool. This type manager compares and merges versions of the same directory element.

USING A TYPE MANAGER

To have a particular file element use a particular type manager, you must establish two connections as indicated:

file element – > element type – > type manager

Verify that the VOB has an element type that is associated with the desired type manager. Use the lstype command to identify an existing element type. Alternatively, use the mkeltype –manager command to create a new element type that is associated with the desired type manager.
Create the file element, specifying the element type with the –eltype option. If the file element already exists, use the chtype command to change its element type.

You can automate the assignment of the new element type to newly created elements using the file-typing facility, driven by .magic files. For more information, see the cc.magic reference page.

TYPE MANAGER STRUCTURE

A type manager uses different methods to manipulate ClearCase and ClearCase LT data. Methods are invoked at the appropriate time by a version-control command.

On UNIX, a type manager is a collection of programs in a subdirectory of ccase-home-dir /lib/mgrs; the subdirectory name is the name by which the type manager is specified with the –manager option in a mkeltype command. Each program in a type manager subdirectory implements one method (data-manipulation operation). A method can be a compiled program, a shell script, or a link to an executable. It is invoked at the appropriate time by a ClearCase or ClearCase LT version-control command.

A type manager can include the following methods, which are invoked by a command or server process:

create_element	Invoked by mkelem to create an element's initial data container.
create_branch	Invoked by mkbranch to create a branch in an element's version tree.
create_version	Invoked by checkin to store a new version of an element.
annotate	Invoked by annotate to produce an annotated listing of a version's contents.
construct_version	Invoked by a view's view_server process when a file element is opened, from versions stored in delta or compressed format. This method constructs a readable, cleartext copy of a particular version. After the cleartext version is constructed, its line terminators may be adjusted by the view_server, according to the view's text mode. See the mkeltype and mkview reference pages.
get_cont_info	Invoked by checkvob to determine the contents of a container. This method must be implemented to enable checkvob to fix container problems for the type manager.
delete_branches_versions	Invoked by rmver and rmbranch to delete versions of an element.
compare, xcompare	Invoked by diff to run a file-comparison program that is specific to the element's data format.
merge, xmerge	Invoked by merge to run a file-merge program that is specific to the element's data format.

A type manager need not implement every method. For example, a type manager for bitmap graphics images may omit the merge method, because the operation doesn't make sense for that file format. In this case, the command cleartool merge produces an error when invoked on an element that uses this type manager.

UNIX—Method Inheritance and Links

A type manager can use symbolic links to inherit one or more of its methods from another type manager. A typical use of symbolic links is to have individual methods be links to a master type manager program, which implements several (or all) of the methods. For an example, see directory ccase-home-dir/lib/mgrs/z_whole_copy.

A link to the cleardiff program can implement the compare and/or merge method for text files. Similarly, a link to the xcleardiff program can implement the xcompare and/or xmerge method. Again, see directory ccase-home-dir/lib/mgrs/z_whole_copy for an example.

Windows—The Type Manager Map File

The map file, located in the ccase-home-dir\lib\mgrs directory, associates type manager methods with the programs that carry them out. A map file entry has three fields: type manager, method, and program. Below are some example entries from the map file:

Manager	Method	Implementing Program
text_file_delta	construct_version	..\..\bin\tfdmgr.exe
text_file_delta	compare	..\..\bin\cleardiff.exe
z_whole_copy	create_branch	..\..\bin\zmgr.exe
_rose	xmerge	HKEY_LOCAL_MACHINE\SOFTWARE \Software\Rose\AddIns\Rose Model Integrator \Install Path

When a type manager is invoked by a ClearCase or ClearCase LT command, it scans through the map file, finds the matching type manager and method in the first and second fields, and then runs the program specified in the third field. Note that the entry in the third field must be either a pathname relative to ccase-home-dir\lib\mgrs; for example, ..\..\bin\cleardiff.exe, a Windows Registry key under HKEY_LOCAL_MACHINE that points to an absolute pathname, or an absolute pathname.

Data Containers

Type managers process data containers, each of which stores the actual data for one or more versions of some element. (Although growth may cause a container to split, versions never span container boundaries.) All data containers are files, and are stored in the VOB's source pools, which are directories. Only type managers deal with data containers directly; users always manipulate data using the names of elements and UNIX links.

Performing the data manipulation for a version-control operation involves several programs. For example, when ClearCase or ClearCase LT create a new version of an element:

The pathname (within a source pool) is generated for a new data container.
On the VOB host (where the VOB storage area resides), a vob_server process creates an empty file at that pathname.
On the client host (where the user is working), the type manager fills the new data container with the data for the new version. (If the type manager implements deltas, it writes the data for one or more other versions to the new container, too.)
The vob_server changes the access mode of the new data container, making it unwritable.
The db_server updates the VOB database to reference the new container.
Using the MGR_DELETE_KEEP_JUST_NEW exit status returned by the type manager, the vob_server deletes the old data container.

Note: Even with a type manager that implements deltas, a new data container is created each time a new version is created. In this case, the old container (which may have stored 27 versions) is replaced by the new container (which stores 28 versions). A type manager must never write to an old container or delete a old container (it usually does not have rights to do so).

Source Pool Data Container Names

A container leaf name includes a type manager ID to aid checkvob in salvaging nonreferenced containers. Here is the format of a source pool data container name (in s/sdft, for example):

./nn/nn/type-mgr-id–orig-oid-str–xx

type-mrg-id is a one-, two-, or three-character string. One-character values correspond to the predefined type managers. Two-digit values correspond to type managers with names that begin with underscore (_), and three-digit values are computed by hashing user-defined type manager names.

Names of user-defined type managers must not begin with underscore.

UNIX FILES

ccase-home-dir/lib/mgrs/*
ccase-home-dir/lib/mgrs/mgr_info.h
ccase-home-dir/lib/mgrs/mgr_info.sh

WINDOWS FILES

ccase-home-dir\lib\mgrs\map

Rational ClearCase Commands Reference