rmelem

Removes an element or symbolic link from a VOB

Applicability

Product

Command type

VersionVault

cleartool subcommand

VersionVault Remote Client

rcleartool subcommand

Platform

UNIX®

Linux®

Windows®

Synopsis

  • VersionVault:
    rmelem [ -f/orce ] [ -c/omment comment | -cfi/le comment-file-pname
    | -cq/uery | -cqe/ach | -nc/omment ] pname ...
  • VersionVault Remote Client:
    rmelem [ -f/orce ] [ -c/omment comment | -cq/uery | -cqe/ach | -nc/omment ] pname ...

Description

The rmelem command completely deletes one or more elements or symbolic links. In a snapshot view, rmelem also unloads the element from the view. In a web view, the deletion becomes apparent only after the view has been updated.

Important:

This command destroys information irretrievably. Use it carefully to avoid compromising your organization's ability to support old releases. The use of this command is not recommended in UCM environments. In that case, and most other cases, use the rmname command instead of rmelem. .

For each element, rmelem does the following:

  • Removes the entire version tree structure from the VOB database: element object, branch objects, and version objects.
  • Removes all metadata (labels, attributes, hyperlinks, and triggers) attached to the element.
  • Removes all event records for the element.
  • (File elements) Removes the data containers that hold the element's file system data from its source storage pool.
  • Removes all references to the element from versions of the VOB's directory elements. (As a result, subsequent listings and comparisons of those directory versions are historically inaccurate.)
  • Creates a destroy element event record in the element's VOB; this event record is displayed by lshistory vob:.

For each symbolic link, rmelem does the following:

  • Removes the symbolic link and link object from the VOB.
  • Removes all metadata (attributes and hyperlinks) attached to the symbolic link .
  • Removes all event records for the symbolic link.
  • Removes all references to the symbolic link from versions of the VOB's directory elements. (As a result, subsequent listings and comparisons of those directory versions will be historically inaccurate.)
Note: rmelem does not create an event record when you remove a symbolic link.

rmelem deletes only the instance of an element type object that is attached to the element. To delete the element type object or to delete the type object and all its instances, use the rmtype command.

Deleting a directory element

Deleting a directory element may cause some other elements (and symbolic links, if the VOB is replicated) to be orphaned; that is, it is no longer cataloged in any version of any directory. rmelem displays a message and moves an orphaned element or symbolic link to the VOB's lost+found directory:

cleartool: Warning: Object "foo.c" no longer referenced.
cleartool: Warning: Moving object to vob lost+found directory
as "foo.c.a0650992e2b911ccb4bc08006906af65".

Each derived object in the deleted directory is also moved to lost+found. (Only dynamic views have derived objects.) The derived object has no data, but you can use it in such commands as lsdo and catcr. View-private objects in the deleted directory are temporarily stranded, but can be transferred to the view's own lost+found directory, as follows:

  1. Use lsprivate to locate stranded files and to determine the identifier of the deleted directory element:
    cmd-context  lsprivate -invob /tmp/david_phobos_hw 
    .
    .
    .
    #<Unavailable-VOB-1>/<DIR-c8051152.e2ba11cc.b4c0.08:00:69:06:af:65>/myfile
  2. Use recoverview to move all the stranded files that resided in the deleted directory:
    cmd-context  recoverview -dir c8051152.e2ba11cc.b4c0.08:00:69:06:af:65 \
     -tag myview 
    Moved file /usr/people/david/myview.vws/.s/lost+found/5ECC880E.00A5.myfile

Deleting elements and symbolic links from the lost+found directory

Use rmelem carefully when deleting elements or symbolic links from the lost+found directory. While the content of lost+found typically consists of unwanted elements and symbolic links, in some circumstances it can contain elements that are cataloged elsewhere in the VOB (that is, not orphaned). For this reason, do not run rmelem recursively in lost+found.

If you need an element in lost+found, catalog it in a versioned directory using mv.

Restrictions

ACL authorization

If ACLs are enabled, the principal must have the following permissions to remove an element:
  • read-info on VOB object
  • read-info on element
  • delete on element
  • rmelem on VOB
To remove an element symlink, the principal must assume one of the non-ACL authorization identities and have the following permissions:
  • read-info on VOB object
  • read-info on object
  • rmelem on VOB

Non-ACL authorization

You must be the VOB owner, the symbolic link owner, or any of the following:

  • root (UNIX® and Linux®)
  • Member of the VersionVault administrators group (VersionVault on Windows®)

If the element you want to remove has no versions with attached metadata and you created all of the element's branches, you need only be the element owner.

Locks

An error occurs if one or more of these objects are locked: VOB, element type, element, pool (nondirectory elements).

Mastership

(Replicated VOBs) Your current replica must master the element or symbolic link.

Other

You cannot remove an element if any of its versions are checked out. (You do not have to check out the parent directory before removing one of its elements.)

Options and arguments

Confirmation step

Default
rmelem prompts for confirmation before deleting anything.
-f/orce
Suppresses the confirmation step.

Event records and comments

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.

Specifying the elements to be removed

Default
None.
pname ...
One or more pathnames, indicating the elements or symbolic links to be deleted. An extended pathname to a particular version or branch of an element references the element itself.

Examples

The UNIX system and Linux 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 system and Linux shells or Windows command interpreter prompt, followed by the cleartool command. In cleartool interactive mode, cmd-context represents the interactive cleartool prompt.

  • Delete the file element rotate.c.

    cmd-context  rmelem rotate.c
    Element "rotate.c" has 1 branches, 2 versions, and is entered
    in 6 directory versions.
    Remove element, all its branches and versions and modify all directory
    versions containing element? [no]
    yes
    Removed element "rotate.c".

  • Delete the directory element release. Note that an orphaned element, hello, is moved to the VOB's lost+found directory.

    cmd-context rmelem release
    Element "release" has 1 branches, 9 versions, and is entered
    in 35 directory versions.
    Remove element, all its branches and versions and modify all directory
    versions containing element? [no]
    yes
    cleartool: Warning: Object "hello" no longer referenced.
    Object moved to vob lost+found directory as
    "hello.5d400002090711cba06a080069061935".
    Removed element "release".

  • Delete the symbolic link text.c from the lost+found directory.

    cmd-context rmelem \dev\lost+found\text.c
    CAUTION! This will destroy the symbolic link, and will remove the
    symbolic link from all directory versions that now contain it.  Once you
    destroy the  symbolic link, it will be hard to restore it to its current
    state. If you want to preserve the symbolic link, but remove references
    to it from future directory versions, use the "rmname" command.
    Symbolic link "text.c" is entered in 3 directory versions.
    Destroy symbolic link?
    yes
    Removed symbolic link "text.c".