Rational ClearCase Commands Reference: lock

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

lock

Locks an object

APPLICABILITY

Product	Command type
ClearCase	cleartool subcommand
ClearCase LT	cleartool subcommand

Platform
UNIX
Windows

SYNOPSIS

lock [ –rep·lace ] [ –nus·ers login-name[,...] | –obs·olete ]: [ –c·omment comment | –cfi·le comment-file-pname |–cq·uery | –cqe·ach
| –nc·omment ] { [ –pna·me ] pname ... | object-selector ... }

DESCRIPTION

The lock command creates a lock on an entire VOB or on one or more file system objects, type objects, or VOB storage pools. A lock on an object disables operations that modify the object; a lock has no effect on read operations, such as lshistory. (Exception: see the section on cleartext pools in “Storage Pool Lock”.)

The VOB does not need to be mounted for you to lock type objects, storage pools, or the VOB itself. However, you need a view context (and therefore a mounted VOB if you're using a dynamic view) to lock elements or versions.

The following sections describe the several kinds of locks.

VOB Lock

Locking an entire VOB disables all write operations to that VOB and forces a database checkpoint by causing a state flush. A typical application is locking a VOB to prevent it from being modified during backup.

You must lock a VOB before backing it up, and you cannot use the –nusers option. With –nusers, it is possible that the VOB will be modified during the backup, and locking with the –nuser option does not perform a database checkpoint.

Note: Locking a VOB does not lock its cleartext storage pools, because this would prevent read access to text_file, compressed_text_file, and binary_delta_file elements. (For example, it would prevent a locked VOB from being backed up.) To completely lock a VOB, you must also lock its cleartext pools, using one or more lock pool: commands. You may want to do this to move a cleartext pool.

Type Lock

In general, locking a type object disables these kinds of operations:

Operations that create, delete, or modify instances of the type
Operations that delete or modify the type object itself (for example, renaming it)

The following sections describe how these general rules apply to the different kinds of type objects.

Element type. If an element type is locked, you cannot do the following:
- Use the type in an rmtype or rename command
- Create an element of that type with mkelem or mkdir
- Change an existing element to that type with chtype
- Modify the element's version tree with checkout, checkin, or mkbranch
Branch type. If a branch type is locked, you cannot do the following:
- Use the type in an rmtype, rename, or mkbrtype –replace command
- Create a branch of that type with mkbranch
- Rename (that is, change the type of) an existing branch to or from that type with chtype
- Modify the branch with checkout or checkin
- Cancel a checkout using uncheckout
- Attach a label using mklabel
- Remove a label using rmlabel or mklabel -replace
  You can create a subbranch at any version on a locked branch, using mkbranch. (Creating a subbranch does not modify the branch itself.)
Label type. If a label type is locked, you cannot do the following:
- Use the type in an rmtype, rename, or mklbtype –replace command
- Attach or remove a version label of that type with mklabel or rmlabel (This includes moving a label from one version to another with mklabel –replace.)
Attribute type. If an attribute type is locked, you cannot do the following:
- Use the type in an rmtype, rename, or mkattype –replace command
- Attach or remove an attribute of that type with mkattr or rmattr (This includes moving an attribute from one version to another with mkattr –replace.)
Hyperlink type. If a hyperlink type is locked, you cannot do the following:
- Use the type in an rmtype, rename, or mkhltype –replace command
- Create or remove a hyperlink of that type with mkhlink or rmhlink
Trigger type. If a trigger type is locked, you cannot do the following:
- Use the type in an rmtype, rename, or mktrtype –replace command
- (If created with mktrtype –element) Create or remove a trigger of that type with mktrigger or rmtrigger
In general, locking a trigger type does not inhibit triggers of that type from firing. Exception: Trigger firing is inhibited if a trigger type created with mktrtype –element –all, mktrtype –ucm –all or if mktrtype –type is made obsolete (using lock –obsolete).

Storage Pool Lock

Locking a VOB storage pool inhibits commands that create or remove the pool's data containers. It also prevents the pool's scrubbing parameters from being modified with mkpool –update. The following sections describe how this principle applies to the different kinds of storage pools.

Source pool. If a source storage pool is locked, you cannot do the following:
- Create an element that would be assigned to that pool, with mkelem or mkdir. (A new element inherits its pool assignments from its parent directory element.)
- Change an existing element's pool assignment to/from that pool, with chpool.
- Change an element's element type with chtype, if the change would require recreation of source data containers (for example, changing from type file to type text_file).
- Check in a new version of an element assigned to that pool.
- Create or remove a branch of an element assigned to that pool, with mkbranch or rmbranch.
- Remove a version of an element assigned to that pool, or remove the element itself, with rmver or rmelem.
Derived object pool. If a derived object storage pool is locked:
- clearmake cannot winkin a previously unshared derived object in a directory assigned to that pool. (The invocation of promote_server to copy the data container from view-private storage to the derived object storage pool fails.)
- scrubber cannot remove data containers from the pool.
- An rmdo command fails for a derived object whose data container is in that pool.
Cleartext pool. If a cleartext storage pool is locked, an attempt to read a version of an element assigned to that pool may fail. (It fails if a new cleartext data container for that version would have been created and cached in the cleartext pool.)

Locking or Unlocking Global Types

Locking or unlocking a global type or one of its local copies locks or unlocks the global type and all local copies. For more information, see the Administrator's Guide.

Obsolete Objects

An object becomes obsolete if it is processed with a lock –obsolete command. An obsolete type object or obsolete storage pool is not only locked, but is also invisible to certain forms of the lstype, lslock, lspool, and lsvtree commands. An obsolete VOB or obsolete VOB object is no different from one with an ordinary lock. You can change an object's status from obsolete to locked by using a lock –replace command:

cmd-context lock –obsolete brtype:test_branch (make a branch type obsolete) Locked branch type "test_branch".cmd-context lock –replace brtype:test_branch (change the branch type to 'just locked')

Similarly, you can use a lock –replace command to make a locked object obsolete.

Removing Locks

The unlock command removes a lock from an object, reenabling the previously prohibited operations.

RESTRICTIONS

Identities

Kind of object to be locked	Identity required for ClearCase and ClearCase LT on UNIX	Identity required for ClearCase on Windows	Identity required for ClearCase LT on Windows
Type object	Type owner, VOB owner, root	Type owner, VOB owner, member of the ClearCase administrators group	Type owner, VOB owner, local administrator of the ClearCase LT server host
Storage pool	VOB owner, root	VOB owner, member of the ClearCase administrators group	VOB owner, local administrator of the ClearCase LT server host
VOB	VOB owner, root	VOB owner, member of the ClearCase administrators group	VOB owner, local administrator of the ClearCase LT server host
Element	Element owner, VOB owner, root	Element owner, VOB owner, member of the ClearCase administrators group	Element owner, VOB owner, local administrator of the ClearCase LT server host
Branch	Branch creator, element owner, VOB owner, root	Branch creator, element owner, VOB owner, member of the ClearCase administrators group	Branch creator, element owner, VOB owner, local administrator of the ClearCase LT server host

Locks

An error occurs if one or more of these objects are locked: the VOB containing the object.

Mastership

(Replicated VOBs only) With –obsolete, your current replica must master the object.

OPTIONS AND ARGUMENTS

Replacing an Existing Lock

Default: None.
–rep·lace: Uses a single atomic transaction to replace an existing lock with a new lock. (If you use two commands to unlock the object and then lock it again, there is a short interval during which the object is unprotected.)
You can use this option to change a object's status from just locked to obsolete.

Specifying the Degree of Locking

Default: Locks an object to all users, but does not make the object obsolete.
–nus·ers login-name [,...]: Allows the specified users to continue using the object, which becomes locked to all other users. The list of user names must be comma-separated, with no white space.
–obs·olete: Locks an object for all users and also makes it obsolete.

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 Objects to Be Locked

Default

The final arguments are assumed to be the names of elements and/or branches. To lock another kind of object, you must use an object-selector prefix.

When locking type objects and storage pools, the command processes objects in the VOB containing the current working directory. To lock an entire VOB, you must specify a VOB.

[ –pna·me ] pname ... , object-selector ... (mutually exclusive)

One or more names, specifying the objects to be locked. To lock an element, you can specify the element itself (for example, foo.c@@) or any of its versions (for example, foo.c or foo.c@@/RLS1.3).To lock a branch, use an extended pathname (for example, foo.c@@\main\rel2_bugfix). If pname has the form of an object selector, you must use the –pname option to indicate that pname is a pathname.

Specify object-selector in one of the following forms:

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-selectors apply to the UCM usage model^[a]
activity-selector	activity:actvity-name[@vob-selector]
baseline-selector	baseline:baseline-name[@vob-selector]
component-selector	component:component-name[@vob-selector]
folder-selector	folder:folder-name[@vob-selector]
project-selector	project:project-name[@vob-selector]
stream-selector	stream:stream-name[@vob-selector]
In UCM object selectors, @vob-selector refers to a UCM project VOB

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.

Lock three label types for all users.
cmd-context lock lbtype:REL1 lbtype:REL1.1 lbtype:REL2
Locked label type "REL1". Locked label type "REL1.1". Locked label type "REL2".
Obsolete a branch type.
cmd-context lock -obsolete brtype:rel2_bugfix
Locked branch type "rel2_bugfix".
Lock the VOB containing the current working directory.
cmd-context lock vob:. Locked versioned object base "/usr/hw".
Lock the test branch type for all users except gomez and jackson.
cmd-context lock –nusers gomez,jackson brtype:test
Locked branch type "test".
Lock elements with a .c extension for all users. Then try to check out one of the locked elements.
cmd-context lock *.c
Locked file element "hello.c". Locked file element "msg.c". Locked file element "util.c".
cmd-context checkout –nc msg.c
cleartool: Error: Lock on file element prevents operation "checkout". cleartool: Error: Unable to check out "msg.c".
Lock the pool cdft, which resides in jazz_vob:
cmd-context lock pool:cdft@\jazz_vob
Locked pool "cdft".

Rational ClearCase Commands Reference