mkview

Creates and registers a view

Applicability

Product

Command type

VersionVault

cleartool subcommand

VersionVault Remote Client

rcleartool subcommand

Platform

UNIX®

Linux®

Windows®

Synopsis

  • VersionVault on UNIX® and Linux®--Create and register a dynamic view:
    mkview -tag dynamic-view-tag [ -tco/mment tag-comment ]
    [ -tmo/de { insert_cr | transparent | strip_cr } ]

    [ -reg/ion network-region | -str/eam stream-selector ] [ -ln remote-storage-dir-pname ]

    [ -nca/exported ] [ -cac/hesize size ]

    [ -sha/reable_dos | -nsh/areable_dos ]

    { -stg/loc { view-stgloc-name | -aut/o }

    | [ -hos/t hostname -hpa/th host-storage-pname

    -gpa/th global-storage-pname ] dynamic-view-storage-pname }

  • VersionVault on Windows--Create and register a dynamic view:
    mkview -tag dynamic-view-tag [ -tco/mment tag-comment ]
    [ -tmo/de { insert_cr | transparent | strip_cr } ]

    [ -reg/ion network-region | -str/eam stream-selector ] [ -cac/hesize size ]

    [ -sha/reable_dos | -nsh/areable_dos ]

    { -stg/loc { view-stgloc-name | -aut/o }

    | [ -hos/t hostname -hpa/th host-storage-pname

    -gpa/th global-storage-pname ] dynamic-view-storage-pname }

  • VersionVault--Create and register a snapshot view:
    mkview -sna/pshot [ -tag snapshot-view-tag ]
    [ -tco/mment tag-comment ]

    [ -tmo/de { insert_cr | transparent | strip_cr } ]

    [ -cac/hesize size ] [ -pti/me ] [ -str/eam stream-selector ]

    [ -stg/loc view-stgloc-name | -col/ocated_server

    [ -hos/t hostname -hpa/th host-snapshot-view-pname

    -gpa/th global-snapshot-view-pname ] | -vws view-storage-pname

    [ -hos/t hostname -hpa/th host-storage-pname

    -gpa/th global-storage-pname ] snapshot-view-pname

  • VersionVault Remote Client--Create and register a web view:
    mkview [ -tag web-view-tag ] [ -tmo/de { insert_cr | transparent | strip_cr } ]
    [ -str/eam stream-selector ] copyarea

  • VersionVault Remote Client--Create and register an automatic view:
    mkview -automatic -tag automatic-view-tag ] [ -tco/mment tag-comment ]
    [ -tmo/de { insert_cr | transparent | strip_cr } ]
    [ -ptime ] [ -str/eam stream-selector ]
    [ -clt/xt_storage cltxt-cache-storage-pname ] automatic-view-storage-pname

Description

The mkview command creates a new view as follows:

  • For a dynamic or snapshot view, creates a view storage directory. The view storage directory maintains information about the view. For a web view, creates a copy area. For an automatic view, creates cleartext and view storage areas.
  • Creates a view tag, the name by which users access a dynamic view or an automatic view. Snapshot views and web views also have view tags, but these are for administrative purposes; users access such views by setting their working directory to the snapshot view directory or the copy area.
  • For a snapshot view, creates the snapshot view directory. This is the directory into which your files are loaded when you populate the view using update. This directory is distinct from the view storage directory. For a web view, creates a copy area, into which the files are loaded.
  • Places entries in the network's view registry; use the lsview command to list view tags.
  • For a dynamic or snapshot view, starts a view_server process on the specified host. The view_server process manages activity in a particular view. It communicates with VOBs during checkout, checkin, update, and other operations. For an automatic view, starts an rview_agent process that communicates with the WAN server for remote clients (VersionVault WAN server).

Interop text modes

Operating systems use different character sequences to terminate lines of text files. In UNIX® and Linux®, the line terminator for text files is a single <LF> character. On Windows® systems, the standard line terminator is <CR><LF>. Each view has an interop text mode--specified by the -tmode option--that determines the line terminator sequence for text files in that view. The interop text mode also determines whether line terminators are adjusted before a text file is presented to the view (at checkout time, for example). For example, a text file element created by a Windows® client that is accessed through a UNIX® or Linux® view is stripped of <CR> characters, and the <CR> characters are reinserted when the file was written to the VOB as a new version.

For more information, see the reference pages for msdostext_mode and mkeltype.

Views and UCM streams

Views are attached to streams in the UCM model. Only views can modify a UCM stream. Views cannot be moved between streams or detached from a stream without removing the view.

Setting the cache size for dynamic and snapshot views

Although both kinds of local-client view types use caches, cache size is more significant for a dynamic view than for a snapshot view. The dynamic view's cache size determines the number of VOB lookups that can be stored. You can set the size of the cache with the -cachesize option. This creates the following line in the .view file for the view:

-cache size

When a view_server process is started, it uses this value. For more information about the view_server cache and changing its size, see the setcache and chview reference pages and the Help.

Reconfiguring a dynamic view

A dynamic view's associated view_server process reads a configuration file when it starts up. You can revise this file, for example, to make the view read-only. See the Help.

Backing up a view

For information about performing view backups, see the Help.

If you create a snapshot view in which the view-storage directory is located outside the snapshot view directory, you must back up recursively both the view storage directory and the snapshot view directory.

Deleting a view

The view created by this command is the root of a standard directory tree; but a view must be deleted only with the rmview command, never with an operating system file deletion command. See the rmview reference page for details.

Information specific to products, view types, and platforms

This section contains information about view creation that differs depending on the product, view type, and platform you are using.

VersionVault dynamic views: Using express builds

You can configure a dynamic view to use the express builds feature by creating the view with the -nshareable_dos option. When you invoke clearmake or omake in this kind of view, clearmake or omake builds nonshareable derived objects (DOs). Information about these DOs is not written into the VOB, so the build is faster; however, nonshareable DOs cannot be winked in by other views.

If you do not specify -shareable_dos or -nshareable_dos, mkview uses the site-wide default set in the registry (with the setsite command). If there is no site-wide default, mkview configures the view so that builds in the view create shareable DOs.

To change the DO property for an existing view, use the chview command. For more information on shareable and nonshareable DOs, see the VersionVault Guide to Building Software.

VersionVault dynamic views on UNIX® and Linux®: Marking a view for export

A dynamic view to be used for NFS export of one or more VOBs (for access by applications other than those in the VersionVault Product Family) must be marked in the registry as an export view. Each export view is assigned an export ID, which ensures that NFS-exported view/VOB combinations have stable NFS file handles across server reboots or shutdown and restart of VersionVault.

If the dynamic view is registered in multiple regions, the export marking must be on the view tag in the server host's default region. To create an export view, use the -ncaexported option. You can register an existing dynamic view or VOB for export by using mktag -replace -ncaexported. For information about exporting view-VOB combinations, see the export_mvfs reference page.

VersionVault dynamic views on UNIX® and Linux®: Activating a view

Creating a view tag also runs the startview command, which activates the dynamic view on the current host (unless the tag's target network region does not include the local host.) It also places an entry in the host's viewroot directory. (For example, specifying -tag gamma creates the entry /view/gamma.)

After it is activated, a dynamic view can be set with the setview command; it can also be accessed with view-extended naming. (For details, see the startview and pathnames_ccase reference pages.)

VersionVault dynamic views on Windows®: Activating a view

Creating a view tag also executes the startview command, which activates the dynamic view on the current host (unless the tag's target network region does not include the local host.) It also places an entry in the host's dynamic-views root directory (by default, drive M). (For example, specifying -tag gamma creates the entry gamma.)

After a dynamic view is activated, you can assign it to a drive letter with the net use command or by clicking Tools > Map Network Drive in Windows® Explorer; it can also be accessed with view-extended naming. (For details, see the startview and pathnames_ccase reference pages.)

VersionVault snapshot views: Activating a view

Snapshot views cannot be explicitly activated and cannot be accessed using view-extended naming. However, a snapshot view becomes active when you change to the view directory and issue a VersionVault command.

VersionVault snapshot views: Location of the view storage directory

When you create a snapshot view that you intend to use when connected over a WAN, performance of some operations can be improved if you create the view storage directory on a host that remains on the local area network, as described here.

  • Create the snapshot view directory on the client host (the computer that may sometimes be connected on a wide area network, rather than the local area network that hosts the VOBs).
  • Create the view storage directory in a location that is consistently connected to the local area network, on a host where VersionVault has been installed or on a NAS device that provides storage for such a host. This location could be a server storage location (specified by -stgloc) or a location specified by the -vws option. Do not use -colocated_server; this option creates the view storage directory as a subdirectory of the snapshot view directory (where it can be disconnected from the network).

VersionVault on UNIX® and Linux®: View creator identity and umask permissions

Avoid creating views as root. This often causes problems with remote access to a view, because root on one host often becomes user ID -2 (user nobody) when accessing other hosts.

Your current umask(1) setting determines which users can access the view. For example, a umask value of 2 allows anyone to read data in the view, but only you (the view's owner) and others in your group can write data to it--create view-private files, build derived objects, and so on. If your umask value is 22, only you can write data to the new view.

VersionVault: View storage directory on a network attached storage device

You can create a view with storage on a supported network attached storage (NAS) device. Use a server storage location for this purpose. See the mkstgloc reference page for information. To use mkview to create a view that resides on a NAS device, you must specify the option set, -host -hpath -gpath. (NAS devices must be specially configured for use with VersionVault. For details, see the Help.)

Restrictions

None.

Options and arguments

Specifying the view tag

Default
Dynamic views: None.

Snapshot views: A generated tag.

-tag view-tag
Dynamic view: Specifies a name for the view, in the form of a simple file name. This name appears in the local host's file system as a subdirectory of the viewroot directory. For example, the view experiment appears as /view/experiment (UNIX® and Linux®) or M:\experiment (Windows®).

Snapshot, web, and automatic views: Specifies a name for the view as it is recorded in the registry.

VersionVault dynamic view: If your network has multiple regions, use the mktag command to create an additional view tag for each additional region.

-tco/mment tag-comment
Adds a comment to the view tag's entry in the view_tag registry. Use lsview -long to display the tag comment.

Specifying the kind of view for the local client

Default
Dynamic view.
-sna/pshot
Specifies a snapshot view. For a discussion of views and the differences between snapshot and dynamic views, see the Help.

Specifying the kind of view for the remote client

Default
Web view.
-automatic
Specifies an automatic view.

Specifying the interop text mode

Note: VOBs that are to be accessed by interop text mode views must be enabled to support such views. See the msdostext_mode reference page.
Default
-tmode transparent for views created on UNIX® or Linux® or those created through by the cleartool mkview command on Windows®. -tmode transparent is also the default for views created through the Windows® GUI unless a different site-wide interop text mode has been set with setsite.
-tmo/de transparent
A transparent interop text mode view is created. The line terminator for text files is a single <NL> character. The view does not transform text file line terminators in any way.
-tmo/de insert_cr
Creates an insert_cr interop text mode view. The view converts <NL> line terminators to the <CR><NL> sequence when reading from a VOB, and <CR><NL> line terminators to single <NL> characters when writing to the VOB.
-tmo/de strip_cr
Creates a strip_cr interop text mode view. The view converts <CR><NL> line terminators to <NL> when reading from a VOB, and <NL> line terminators back to the <CR><NL> sequence when writing to the VOB.

Specifying a network region (dynamic views)

Default
The local host's network region, as listed by the hostinfo -long command. For a discussion of network regions, see the Help.
-reg/ion network-region
Creates the view tag in the specified network region. An error occurs if the region does not exist. (Cannot be used with -str/eam.)
Restriction: The view tag created with mkview must be for the network region to which the view server host belongs. Thus, use this option only when you are logged on to a remote host that is in another region. Moreover, a view tag for the view's home region must always exist.

Remote private storage area (dynamic views)

Default
Creates the view's private storage area as an actual subdirectory of dynamic-view-storage-pname. This subdirectory, named .s, holds checked-out versions, newly created derived objects, and other view-private objects.
-ln remote-storage-dir-pname
Creates the .s directory at the location specified by remote-storage-dir-pname. A UNIX® or Linux® symbolic link to pname is created at view-storage-dir-pname/.s, providing access to the remote storage area. Restrictions:
  • remote-storage-dir-pname must be a valid path name on every host (regardless of its network region) from which users will access the view.
  • This view cannot be used to export a VOB to a non-VersionVault host. (See the exports_ccase reference page.)
  • Some operations performed by root in this view may fail. This is another symptom of the root-becomes-nobody problem explained in VersionVault on UNIX and Linux: View creator identity and umask permissions.

This mechanism is independent of the network storage registry facility. The path name to a remote storage area must be truly global, not global within a particular network region.

Marking a dynamic view for export

Default
The view is not marked as an exporting view.
-nca/exported
Assigns an export ID to the view tag.

Setting the cache size for a dynamic view

Default
Set to the value of the site-wide default (set with setcache -); if this default is not set, the cache size is set to 4096000 bytes.
-cac/hesize size
Specifies a size for the view_server cache. size is an integer number of bytes, optionally followed by the letter k to specify kilobytes or m to specify megabytes; for example, 800k or 3m.

Specifying the kind of derived objects to create in a dynamic view

Default
mkview uses the site-wide default. If a site-wide default is not set, mkview configures the view to create shareable DOs.
-sha/reable_dos
Specifies that DOs created in the dynamic view can be winked in by other views.
-nsh/areable_dos
Specifies that DOs created in the dynamic view cannot be winked in by other views.

In UCM, the integration view has a default of -sha/reable_dos. In other UCM views, such as the development view, the default is -nsh/areable_dos. For -sha/reable_dos, UCM views are not affected by the site-wide default.

Setting an initial default for modification time stamps for a view

Default
The initial default for the time stamps of files copied into the view as part of the view update operation is the time at which the file is copied into the view. Using the update command, users can change the default time-stamp mode: 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.
-pti/me
Changes the initial default for file time stamps copied into the view to the time at which the version was created (as recorded in the VOB).

Attaching a view to a stream

Default
None.
-str/eam stream-selector
Specifies a UCM stream. The view being created is attached to this stream. (Cannot be used with -reg/ion.)

stream-selector is of the form [stream:]stream-name[@vob-selector], where vob-selector specifies the stream's project VOB.

Specifying the view storage directory location (dynamic view)

Default
Either dynamic-view-pname or snapshot-view-pname is always a required argument. In addition, default behavior related to specifying view storage location is as follows:

Dynamic views: None; a server storage location must be specified explicitly using -stgloc or indirectly using -auto.

For dynamic views, automatic server storage selection proceeds as follows:

  1. Server storage locations that have no global path (-ngpath) are disqualified.
  2. Server storage locations on heterogeneous hosts are disqualified.
  3. Local server storage locations are preferred over remote ones.
  4. A server storage location is selected at random from the remaining candidates.

VersionVault snapshot views: An automatically selected server storage location, if any can be found; else -colocated_server.

-stg/loc { view-stgloc-name | -aut/o }
Specifies a server storage location to hold the view storage directory. (You must have previously used mkstgloc to create the server storage location.) Either specify the server storage location by name, or specify -auto to indicate a server storage location is to be automatically selected as described previously. You must not specify a snapshot view directory as the view storage directory of another view, dynamic or snapshot.

For information on using this option to create snapshot views for disconnected use, see VersionVault snapshot views: Location of the view storage directory under Information specific to products, view types, and platforms. The only type of view you can create on a remote heterogeneous host is a snapshot view in a no-global-path (-ngpath) server storage location.

-col/ocated_server
Specifies a view storage directory that is colocated with the snapshot view directory; specifically, the view storage directory is created as a subdirectory of the snapshot view directory (snapshot-view-pname).

We recommend that you use -stgloc rather than this option whenever possible.

-vws
Specifies the location for the snapshot view storage directory. On Windows® systems, this must be a UNC name.

For information on using this option to create snapshot views for disconnected use, see VersionVault snapshot views: Location of the view storage directory under Information specific to products, view types, and platforms.

Use -stgloc rather than this option whenever possible.

-hos/t hostname -hpa/th local-pname -gpa/th global-pname
See the mkstgloc reference page for information on these options.
Note: The argument names shown above are generalizations of the argument names as they appear in the synopses for this command in association with the -colocated_server and -vws options.

When you use one or more of the -host/-hpath/-gpath options in combination with -colocated_server, the values you specify for -host/-hpath/-gpath must correspond to the snapshot view directory (snapshot-view-pname), not the colocated view storage directory.

When you use one or more of the -host/-hpath/-gpath options in combination with -vws, the values you specify for -host/-hpath/-gpath must correspond to the view storage directory (view-storage-pname), not the snapshot view directory.

To create a view that resides on a supported network attached storage (NAS) device, you must specify the option set, -host -hpath -gpath.

dynamic-view-storage-pname
The location at which a new view storage directory is to be created for a dynamic view. (An error occurs if something already exists at this path name.) You can create a view storage directory at any location in the file system where operating system permissions allow you to create a subdirectory, with these restrictions:
  • You cannot create a view storage directory under the dynamic views root directory (on UNIX® and Linux®, this directory is /view; on Windows®, drive M)
  • dynamic-view-storage-pname must not be a subdirectory of a snapshot view directory.
  • dynamic-view-storage-pname must not be a subdirectory of an existing view storage directory.
  • dynamic-view-storage-pname must specify a location on a host where VersionVault has been installed or a location on a supported network attached storage device attached to such a host; the view database files must physically reside on a VersionVault host or a supported network attached storage device to enable access by the view_server process.

UNIX® and Linux® systems-See the description of CCASE_GPATH_HINTS in the env_ccase reference page for related information.

In addition, on Windows® systems:
  • dynamic-view-storage-pname must be a UNC name
  • The directory must not be within a Windows® special share, such as the share that is designated by drive$ and that allows administrators to access the drive over the network.
snapshot-view-pname
The location at which the snapshot view directory is to be created. (An error occurs if something already exists at this path name.) You can create a snapshot view directory at any location in the file system where operating system permissions allow you to create a subdirectory, with these restrictions:
  • You cannot create a snapshot view under the dynamic views root directory (on UNIX® and Linux®, this directory is /view; on Windows®, drive M).
  • snapshot-view-pname must not be a subdirectory of an existing view storage directory.

UNIX® and Linux® systems--See the description of CCASE_GPATH_HINTS in the env_ccase reference page for related information.

In addition, on Windows® systems:
  • snapshot-view-pname must be a UNC name only if the storage is colocated (colocated storage can be the default in the circumstances described previously).
  • For a colocated server, the snapshot view directory must not be within a Windows® special share, such as the share that is designated by drive$ and that allows administrators to access the drive over the network.

Specifying a copy area for a web view

Default
None.
copyarea
Specifies the parent directory of elements that are to be loaded into the web view.

Specifying storage for an automatic view

Default
None.
-clt/xt_storage cltxt-cache-storage-pname
Specifies the parent directory for cleartext storage, which should be a directory on the local host. Further, all automatic views residing on the same host that are owned by the same user should share a single cleartext storage area for best performance (after a filesystem object has been fetched from the server by an automatic view, the object is locally accessible to other automatic views that share cleartext storage).
automatic-view-storage-pname
Specifies the parent directory for view storage. You must specify a local drive (not mapped shared storage) for best performance.

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.

  • On a UNIX® or Linux® system, create a dynamic view storage directory and assign it the view tag mainr2.

    cmd-context mkview -tag mainr2 /net/host3/view_store/mainr2.vws
    Created view.
    Host-local path: host3:/view_store/mainr2.vws
    Global path: /net/host3/view_store/mainr2.vws
    It has the following rights:
    User : anne : rwx
    Group: dev : rwx
    Other: : r-x

  • On a Windows® system, create a dynamic view and assign it the view tag main_r2. This example assumes that host pluto shares drive C as c_share. 
    cmd-context mkview -tag main_r2 \\pluto\c_share\vw_store\winproj\main_r2.vws 
Created view.
Host: pluto
Local path: c:\vw_store\winproj\main_r2.vws
Global path: \\pluto\c_share\vw_store\winproj\main_r2.vws
It has the following rights:
User : anne : rwx
Group: dev : rwx
Other: : r-x
  • On a UNIX® or Linux® system, create a dynamic view storage directory, assign it the view tag main_exp, and mark it for export. 
    cmd-context  mkview -tag main_exp -ncaexported /net/neon/views/main_exp.vws
  • On a UNIX® or Linux® system, create a dynamic view storage directory named Rel2.vws in the current working directory, but with its private storage area on a remote host.

    cmd-context mkview -tag Rel2 \
    -ln /net/host4/priv_view_store/Rel2.vps Rel2.vws
    Created view.
    Host-local path: host3:/view-store/Rel2.vws
    Global path: /net/host3/view-store/Rel2.vws
    It has the following rights:
    User : anne : rwx
    Group: dev  : rwx
    Other:      : r-x

  • On a UNIX® or Linux® system, create a dynamic view on the local host. Then activate the view on a remote host.

    cmd-context mkview -tag anneRel2 /view_store/anneRel2.vws
    Created view.
    Host-local path: host3:/view-store/anneRel2.vws
    Global path: /net/host3/view-store/anneRel2.vws
    It has the following rights:
    User : anne : rwx
    Group: dev : rwx
    Other: : r-x
    rsh host4 cleartool startview anneRel2

    The remote shell command is named remsh on some systems.

  • On a UNIX® or Linux® system, create a dynamic view storage directory, assign it the view tag smg_bigvw, and specify a large cache size. 
    cmd-context mkview -tag smg_bigvw -cachesize 1m /home/smg/vws/smg_bigvw.vws 
Created view.
Host-local path: neon:/home/smg/vws/smg_bigvw.vws
Global path:  /net/neon/home/smg/vws/smg_bigvw.vws
It has the following rights:
User : susan    : rwx
Group: user     : rwx
Other:           : r-x
  • On a Windows® system, create a dynamic view, assign it the view tag smg_bigvw, and specify a large cache size.

    cmd-context mkview -tag smg_bigvw -cachesize 1m \\neon\vws\smg_bigvw.vws
    Created view.
    Host-local path: neon:C:\USERS\vws\smg_bigvw.vws
    Global path:  \\neon\vws\smg_bigvw.vws

  • On a UNIX® or Linux® system, create a snapshot view tagged dev with the view path ~bert/my_views.

    cmd-context  mkview -tag dev -snapshot ~bert/my_views
    Created view.
    Host-local path: peroxide:/export/home/bert/my_views/.view.stg
    Global path: /net/peroxide/export/home/bert/my_views/.view.stg
    It has the following rights:
    User : bert : rwx
    Group: user     : r-x
    Other:          : r--
    Created snapshot view directory
    "/net/peroxide/export/home/bert/my_views".

  • On a UNIX® or Linux® system, create a UCM view and attach it to the specified stream.

    cmd-context  mkview -stream java_int@/vobs/core_projects -tag java_int
    /usr1/views/java_int.vws
    Created view.
    Host-local path: propane:/usr1/views/java_int.vws
    Global path: /net/propane/usr1/views/java_int.vws
    It has the following rights:
    User : bill     : rwx
    Group: user     : rwx
    Other:          : r-x
    Attached view to stream "java_int".

  • On a UNIX® or Linux® system, create a dynamic view at a server storage location that has been established for views.

    cmd-context  mkview -tag viewbert -stgloc view_stgloc
    Created view.
    Host-local path: dioxin:/export/home/frank/view_stgloc/bert/viewbert.vws
    Global path: /net/dioxin/export/home/frank/view_stgloc/bert/viewbert.vws
    It has the following rights:
    User: bert : rwx
    Group: user : rwx
    Other: : r-x