update

Updates elements in a snapshot view, web view or automatic view

Applicability

Product

Command type

VersionVault

cleartool subcommand

VersionVault Remote Client

rcleartool subcommand

Platform

UNIX

Linux

Windows

Synopsis

  • VersionVault--Update elements using the graphical update tool:
    update -g/raphical [ pname ... ]
    Note: If the environment variable CCASE_USE_GUI is set, options other than –graphical are not supported.
  • VersionVault--Update elements from the command line:
    update [ -print ] [-f/orce ] [ -ove/rwrite | -nov/erwrite | -ren/ame ]
    [ -cti/me | -pti/me ] [ -log pname ] [ pname ... ]
  • VersionVault--Load elements from the command line by specifying one or more load rules:
    update -add/_loadrules [ -print ] [ -f/orce ] [ -ove/rwrite
    | -nov/erwrite | -ren/ame ] [ -cti/me | -pti/me ]

    [ -log pname ] pname [ pname ... ]

  • VersionVault Remote Client--Update elements in a web view from the command line:
    update [ -print ] [ -ove/rwrite | -nov/erwrite | -ren/ame ] [ -ptime ] [ pname ... ]
  • VersionVault Remote Client--Load elements into a web view from the command line by specifying one or more load rules:
    update -add/_loadrules [ -print ] [ -ove/rwrite | -nov/erwrite | -ren/ame ] [ -ptime ] pname [ ... ]
  • VersionVault Remote Client--Update elements in an automatic view from the command line:
    update [ -print ] [ -ove/rwrite | -nov/erwrite | -ren/ame ] [ pname ... ]
  • VersionVault Remote Client--Load elements into an automatic view from the command line by specifying one or more load rules:
    update -add/_loadrules [ -print ] [ -ove/rwrite | -nov/erwrite | -ren/ame ] pname [ ... ]

Description

Updating Loaded Elements

For one or more loaded elements, the update command does the following:

  • Reevaluates the config spec to select versions of loaded elements in the VOB and loads them if they differ from the currently loaded versions
  • Unloads the file or directory from the view if a loaded element is no longer visible (that is, a new directory version does not have an entry for the element). To unload a directory element, update does the following:
    • Recursively deletes all loaded elements.
    • Renames the directory to directory-name.unloaded if necessary, thus preserving all view-private files and view-private directories.
  • Copies the version selected by the config spec into the view, if the version in the view is different from the version in the VOB selected by the config spec. The version in the view can be different if, for example, the selected version in the VOB is newer, or if a label is attached to the selected version in the VOB, but not to the version in the view.

update does not apply to files or directories that are checked out to the current view.

If update cannot access a VOB (perhaps because of problems in the network), any elements from that VOB remain loaded, but are put in a special state (rule unavailable).

The update command accounts for the fact that VOB elements specified by your config spec may change while an update is in progress. To avoid loading an inconsistent set of element versions, update ignores versions that meet both of the following criteria:

  • The version is selected by a config spec rule that specifies the LATEST version label.
  • The version was checked in after the moment the update operation began.

update also accounts for the fact that the system clocks on different hosts may not be synchronized.

The following cleartool and rcleartool commands invoke update at the completion of the command:

  • edcs
  • findmerge (only when used to merge versions of a directory)
  • ln
  • merge (only when used to merge versions of a directory)
  • mkdir
  • mkelem
  • mv
  • rmname
  • setcs
  • uncheckout

Loading new elements

The form of the update command that specifies the -add_loadrules option enables you to add new load rules to your config_spec and load the elements that those rules specify.

Behavior when ACLs are enabled

When an update operation encounters an element that the principal cannot access, a warning is displayed. If a loaded element is no longer accessible to the principal, the element (and any children) are unloaded from the view. For loaded elements that have been hijacked or checked out, the unload operation behaves as if a directory change caused the element to be no longer visible (the file is kept or removed depending on the preference). At the completion of the operation, elements that the principal cannot access are reported as skipped objects.

In the case of a symbolic link, the principal must have access to both the link and its target.

Restrictions

Multi-hop symbolic links are not supported in snapshot or web views. When loading an element that is a VOB symbolic link, update behaves differently on different platform types.
  • On Windows, the symbolic link and its target are both loaded as copies.
  • On the UNIX system and Linux, the symbolic link is loaded as a file system symbolic link to the target, which is loaded as a copy.
In cases where the target of a symbolic link is itself a symbolic link, update does not attempt to resolve the target of that link.

Options and arguments

Using the graphical update tool

Default
The update is performed in the command window.
-g/raphical
Invokes the graphical update tool.

Using the preview mode

Default
None.
-print
Produces a preview of the update operation: instead of copying or removing files, update prints a report to standard output of the actions it would take for each specified element.

Confirmation step

Default
update prompts for confirmation of the elements to be updated. However, update does not in all circumstances prompt you to confirm all the elements to be updated. Sometimes there are no confirmation prompts when you update elements, even though you have not specified -force.
-f/orce
Suppresses the confirmation prompts.

Handling hijacked files

Default
-noverwrite
-ove/rwrite
Overwrites all hijacked files with the version selected by the config spec.
-nov/erwrite
Leaves all hijacked files in the view with their current modifications.
-ren/ame/
Renames hijacked files to filename.keep and copies the version in the VOB selected by the config spec into the view.

Determining the modification time stamp

Default
cleartool: The initial default is set by the mkview command. Thereafter, the most recently used time scheme is retained as part of the view's state and is used as the default behavior for the next update.

rcleartool: The time at which the version was copied into the view.

-cti/me
Sets the time stamp of a file element to the current time, that is, the time at which the version is copied into the view. -ctime has no effect on directories (directories always use the current time).
-pti/me
Sets the time stamp of a file element to the time at which the version was checked into the VOB. -ptime has no effect on directories. (Directories always use the current time.)

Specifying a file transfer log

Default
A log file named update.timestamp.updt that is written to the root of the snapshot view directory.
-log pname
Specifies a log file for the operation. The log file lists the actions taken by the update command, as well as an indication of any errors that occur during the operation.

To suppress generation of the log file, use -log  /dev/null (UNIX and Linux) or -log NUL (Windows). You can also set the CCASE_NO_LOG EV, which suppresses generation of the log file for any command that initiates the update operation.

Specifying new load rules

Default
None.
-add_loadrules
Specifies that the pname argument is a new load rule. The new rule is appended to the view's config spec, and the elements it specifies are loaded.

Specifying the elements to be updated or added

Default
If you do not specify -add_loadrules, the current view; if you specify -add_loadrules, none.
pname ...
If you do not specify -add_loadrules, this argument specifies the files and directories to update. All specified directories, including the root directory of the view, are updated recursively.

If you specify -add_loadrules, this argument is interpreted as a new load rule. The elements specified by the rule are loaded and the rule is appended to the config spec of the current view. pname must be either a pathname relative to your current location in the directory structure of the view or an absolute path that includes the view path.

Examples

The UNIX system and Linux examples in this section are written for use in csh. If you use another shell, you might 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 might 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.

  • On a Windows system, preview an update of the view xml_snapshot and produce a log file log.txt in the C:\temp directory.

    cmd-context update -print -log C:\temp\log.txt E:\views\xml_snapshot

  • Update the file ./foo.c using the current time as the time stamp.

    cmd-context update -ctime foo.c

  • Update the current directory; if there are any hijacked files, rename them filename.keep and copy the VOB versions specified by the config spec into the view.

    cmd-context update -rename

  • Load into the current view the new elements in .\doc\user_manual, adding the rule load \doc\user_manual to the view's config spec.

    cmd-context update -add_loadrules .\doc\user_manual