protect

This command does not affect view-private objects. For this reason, entering a protect command sometimes seems to have no effect:

• Changing an element's permissions has no effect on its checked-out versions. After you check in the element, your view selects the checked-in version, thus making the updated permissions appear.
• Changing a DO's permission has no effect on the way the DO appears in the view where it was originally created or in the dynamic views where it has been winked in. To have your dynamic view use a shared DO with updated permissions:
  1. Use protect to change the permissions on the DO in the VOB database.
  2. Use rm to remove the DO from your view.
  3. Use clearmake or the winkin command to wink in the DO, with its new permissions.

You can change the permissions on any view-private object (including a checked-out version), with the standard operating system commands.

A winked-in DO is not really a view-private object, but it behaves like one (so that users in different views can build software independently). Moreover, changing the permissions of a winked-in DO actually converts it to a view-private file in your view. See VersionVault Guide to Building Software.

The initial owner of an element is the user who creates it with mkelem or mkdir. The initial owner of a named VOB object is the user who creates it. The initial owner of a derived object is the user who builds it with clearmake. When the derived object is winked in and becomes shared, its data container is promoted to a VOB storage pool. This process preserves the derived object's ownership, no matter who performs the build that causes the winkin.

For a list of operations that can be performed by an element's owner, see the permissions reference page .

The initial group of an element or named VOB object is the principal group of its creator. The new group specified in a protect –chgrp command must be one of the groups on the VOB's group list.

See the permissions reference page for a list of operations that can be performed by members of an element's or derived object's group.

The read and execute permissions of an element or a shared derived object control access to its data in the standard manner. The permissions are also applied to all its associated data containers. Read and execute permissions do not apply to non-file-system objects such as branch types and hyperlinks.

The meaning of the write permission varies with the kind of object:

For a file element, write permission settings are ignored. To obtain write permission to a file element, you must check it out (see the checkout reference page).

For a directory element, write permission allows view-private files to be created within it. VersionVault permissions control changes to the directory element itself. (See the permissions reference page.)

For a shared derived object, write permission allows it to be overwritten with a new derived object during a target rebuild. (The shared derived object is not actually affected; rather, the view sees the new, unshared derived object in its place.)

Changing the protection of a global type or a local copy of a global type changes the protection of the global type and all its local copies. You must have permission to change the protection of the global type.

If the protection cannot be changed on one or more of the local copies, the operation fails and the global type's protection is not changed. You must fix the problem and run the protect command again.

For more information, see the Help.

Default

None.

–cho/wn login-name

New owner for the elements or VOB objects.

UNIX and Linux: The argument must be in chown(1) format. The owner may be either a decimal user ID or a login name found in the passwd(4) file.

Windows: The login-name must specify a domainwide user account.

–chg/rp group

New group for the elements or VOB objects.

UNIX and Linux: The argument must be in chgroup(1) format. The group may be either a decimal group ID or a group name found in the group(4) file.

Windows: The group must be registered in the domainwide account database.

–chm/od permissions

New permissions—owner, group, other (world)—for the elements or derived objects. Both symbolic and absolute codes are valid, such as go–x (symbolic) or 666 (absolute). Following is a summary (UNIX and Linux users may read chmod(1) for details):

Specify symbolic permissions in one or more of the following forms:

[identity]+permission

[identity]-permission

[identity]=permission

where identity is any combination of

u	user/owner
g	group
o	other
a	all (owner, group, and other)

When identity is unspecified, its default value is a.

permission can be any combination of

r	read
w	write
x	execute

To combine the forms, separate them with a comma (no white space). For example, to specify read and write permissions for an element's owner and no access by group or other:

cmd-context protect –chmod u=rw,go-rwx test.txt

Absolute permissions are constructed from the OR of any of the following octal numbers:

400	read by owner
200	write by owner
100	execute (and directory search) by owner
700	read, write, and execute (and directory search) by owner
040	read by group
020	write by group
010	execute (and directory search) by group
070	read, write, and execute (and directory search) by group
004	read by others
002	write by others
001	execute (and directory search) by others
007	read, write, and execute (and directory search) by others

For example, the value 600 specifies read/write permission for the owner and no access by any other identity. The value 764 gives all permissions to the owner, read/write permissions to the group, and read permission to others.

Note: This option does not apply to non-file-system objects such as branch types and hyperlinks.

–chrolemap rolemap-selector

Changes the rolemap associated with an object, thus changing the object's security definition from the existing rolemap to

the specified rolemap-selector. If the object is an element, the storage containers for the element and its versions are reprotected (with native operating system file system ACLs) to implement the effective ACL of the new rolemap.

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. See the comments reference page.

Default

None.

–fil/e

Restricts the command to changing file elements only. This option is especially useful in combination with the –recurse option.

–d/irectory

Restricts the command to changing directory elements only. This option is especially useful in combination with the –recurse option.

[ –pna/me ] pname ...

One or more pathnames, each of which specifies an element or shared derived object. If pname has the form of an object selector, you must use the –pname option to indicate that pname is a pathname. An extended pathname to a version or branch is valid, but keep in mind that protect affects the entire element. Shared derived objects can be referenced by DO ID.

If you specify multiple pname arguments, but you do not have permission to change the permissions on a particular object, protect quits as soon as it encounters this error.

object-selector ...

One or more named VOB objects. Specify object-selector in one of the following forms:

object-selector ...

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]
hlink-selector	hlink:hlink-id[@vob-selector]
oid-obj-selector	oid:object-oid[@vob-selector]
policy	policy:policy-name[@vob-selector]
rolemap-selector	rolemap;rolemap-name[@vob-selector]
vob-object-selector	vob:pname-in-vob or vob:/vobtag)
The following object selector is valid only if you use MultiSite:
replica-selector	replica:replica-name[@vob-selector]

Default

Any pname argument that specifies a directory causes the directory element itself to be changed.

–r/ecurse

Changes the entire tree of elements including and below any pname argument specifying a directory element. UNIX or Linux VOB symbolic links are not traversed during the recursive descent. (Use –file or –directory to restrict the changes to one kind of element.)

When recursively protecting elements, only those elements visible in the current view are reprotected. There may be other elements on other branches or older/newer versions of directories on the same branches used by the current view, and those elements retain their existing protections. This applies to all variants of protect operations on elements: chrolemap, chown, chgrp, and chmod. For example, if you run a recursive protection operation in a UCM integration stream, any elements in developer/child streams but not yet delivered to the integration stream are not be reprotected. Another example: after a rmname operation, the element formerly visible in versions of a directory element is not be reprotected by a recursive protect.