NAME
vadm - manipulate and administer version object base
SYNOPSIS
vadm [ version binding options ] [ options ] [ action ] name..
Options: [ -?fq ] [ -cache ] [ -force ] [ -help ] [ -nomail ]
[ -quiet ] [ -stdin ] [ -version ]
Actions: [ -alias version alias name ] [ -attr attribute ]
[ -chaut user ] [ -chmod protection ] [ -chown user ]
[ -delattr attribute name ] [ -d (or -delete) ]
[ -l (or -lock) [version binding] ] [ -newgen ] [ -promote ]
[ -set description | note | intent ] [ -setc comment leader ]
[ -unlock [version binding] ] [ -unpromote ]
vattr [ version binding options ] attribute name..
vrm [ version binding options ] name..
sbmt [ version binding options ] name..
publ [ version binding options ] name..
accs [ version binding options ] name..
frze [ version binding options ] name..
DESCRIPTION
vadm is a general purpose command to perform all sorts of actions upon
parts of an AtFS object repository. It can be used to lock or unlock an
AtFS object for modification, to delete a particular object instance,
to associate symbolic (alias) names with version objects, to promote or
unpromote certain version objects from one status to another, to modify
an objects access permissions, to set or modify a descriptive entry of
particular version objects, to set or modify an eventual change
intention, and to set or unset various object attributes such as the
author or any user defined attributes.
vattr and vrm are short forms for vadm -attr and vadm -delete. See the
descriptions of the -attr and the -delete options for details.
sbmt, publ, accs, and frze are alternate program names for vadm that
represent status-change operations for version objects. See the
description of option -promote for details.
The typical command invocation is supplemented by one or more command
options, version binding options defining the versions to be acted
upon, an action specifier indicating the sort of action to be
performed, and a set of object names defining the initial subset of the
object base that’s going to be manipulated.
Object names may be given in bound version notation, i.e. a notation
that identifies a particular version of an object (e.g.
mkattr.c[2.4]). It is also possible to use a previously assigned
symbolic name rather than a numerical version identification (e.g.
mkattr.c[tools-V4R3]). Make sure to escape the bracket-symbols when
using csh(1) or tcsh(1) because they have meaning to these shells.
OPTIONS
For version selection, any version binding option, as described on the
vbind(1) manual page, may be given, or a version bind directive may be
given in brackets added to the file name.
-?, -help
print brief instructions about using vadm
-cache apply the requested operation to objects residing in the derived
object cache. The set of actions that may be performed on binary
pool objects is limited.
-f, -force
don’t ask for confirmation when deleting versions from a
history.
-nomail
Suppress the notification mail to the user who holds the lock on
a history when breaking this lock (-unlock option).
-q, -quiet
suppress any prompts, informal messages and user dialogues.
Default values are assumed for everything that might otherwise
be inquired interactively. This option is useful for batch
operation.
-stdin forces vadm to read a descriptive text, note or intent from
standard input if action -set is selected. The note is used for
all specified AtFS objects. Otherwise your favorite editor
(taken from the EDITOR environment variable) is invoked.
-version
print version information about the vadm program itself. No
action will be performed on the database.
vadm will perform all of its operations upon a specified set of AtFS
version objects. In case no such set is specified, the operation will
be applied to the most recently saved versions of the named object(s).
ACTIONS
The kind of action to be performed upon a specified set of AtFS objects
is indicated by a keyword. The following actions are defined:
-alias version alias name
assigns the version alias name to the specified version. The
name works as an alias for the version number, so it must be
different from any other symbolic name assigned to any version
object in a particular object history. It is, however, possible
to assign the same symbolic name to version objects in different
object histories. An object history is usually denoted by a
name, similarly to a files name.
The use of alias names is a simple but effective way to
associate component members of a system configuration. Typical
symbolic names will look something like Mysystem_Release_4.22,
indicating that version objects with this name are part of
release 4.22 of the system in question.
-attr attrname
Return rthe value of the named attribute. This may be a standard
attribute or a user defined attribute. Check the list below for
a complete list of standard attribute names.
-attr attrname[+|-]=[@|^|!|*]value
defines a user defined attribute with name attrname and sets it
to the value value for all specified version objects. This
option may also be used to set the value of certain standard
attributes (see list below). If attrname is followed by a
single equal-symbol, the respective value of the object is set
(or reset) to the specified value. Any previous values will be
overwritten. If attrname is immediately followed by the symbols
‘‘plus-equal’’ (+=), the specified attribute value will be
appended to the current value of the referenced attribute.
Accordingly, ‘‘minus-equal’’ (-=) should remove the specified
value from the given attribute. In the current implementation,
removal of single values is not supported.
There are four basic kinds of user defined attribute values:
genuine values, reference values, execution values, and pointer
values. The kind of an attribute value is determined when it is
set. If the first character of value is an at character (@),
the rest of value is taken to be the name of a file the contents
of which will be taken as the value of the attribute. This
substitution takes place immediately, i.e. the attribute has a
genuine value. If the filename is specified as ‘‘-’’, the
attributes value will be read from standard input. If the first
character is a circumflex character (^), the rest of value is
interpreted as the name of a file whose contents will be
substituted for the attribute when it is cited. If the first
character of value is an exclamation mark character (!), the
rest of value is interpreted as the name of a program whose
standard output will be substituted for the attribute when it is
cited. Execution values can be used to generate highly dynamic
attributes or even a primitive form of event triggers. An
asterisk (*) as first character of value indicates a pointer to
another version. In this case, the remainder of value must be a
valid bound filename.
User defined attributes may be of arbitrary length. Any sequence
of ASCII characters - with the exception of \01 (control-A) - is
allowed to make up an attribute value. If attrname was already
set to some value, the previous value will be replaced by the
newly specified one.
-attr @attrfile
With a @filename argument, the -attr option reads names and
values of user defined attributes from the named file Each entry
(each line) in the attribute file must have a format as
described above. The files last character must be a newline
character.
-chaut user
sets user the author of a particular revision. Normally, the
author of a revision is considered the user who saved that
revision. However, as certain permissions are tied to the author
attribute of a revision, circumstances may occur that make it
necessary to change the author.
-chmod protection
changes the access permission code of the specified version
objects to the supplied three-octal-digit protection. Currently,
the access permissions are centered around UNIX’ notions of
owner, group, and world access as well as the access categories
read, write, and execute. These permissions are inherited upon
save from the permissions of the file representing the busy
object of an AtFS history. See chmod(2) for details.
-chown user
sets user the owner of an entire object history. This option is
not supported on BSD type systems, as only the superuser may
change the owner of a file.
-delattr attrname
deletes the user defined attribute attrname from the set of
attributes associated with the specified version objects.
-d, -delete
removes the specified version objects from the object base,
provided the objects’ status is saved. Any other status
indicates that some kind of project interaction concerning this
object might be in progress. If the programmer wants to delete
such a version object anyway, he has to -unpromote the
respective objects status to saved before it can actually be
deleted.
-l, -lock [version binding]
tries to reserve the privilege to add a new version to an
objects history, thus preventing multiple programmers working
upon the same object base from interfering with each other by
saving concurrent updates. If the locking operation succeeds,
write permission is given for the corresponding files in the
development directory. When setting a new lock on an object
history, the requesting user is prompted for an optional
description of the planned changes.
In order to lock an object history successfully, the history
must not be locked by any other programmer, and the programmer
requesting the lock must have write permission on the AtFS
subdirectory hosting the object base.
As ShapeTools allows locking of single generations within a
history, -lock optionally expects an argument denoting a
generation. Default is the most recent generation. The argument
may be a generation number (e.g. 2), a version number (e.g.
1.4), or a version alias (e.g. release-4.7).
-newgen
opens a new generation by duplicating the identified version.
The version must be locked. Any existing busy versions are
ignored by this action. If no version binding is specified, the
last saved version is taken by default.
-promote
assigns the next-better value to the specified objects’ state
attribute. There are six states that an object instance can be
in: busy, saved, proposed, published, accessed, and frozen.
Version states are intended to relate to visibility and
operational restrictions (see for example -delete) within a
complex project environment.
Due to the current lack of project library support, the version
states have very little actual functionality. Implemented to its
full extent, certain state transitions may only be triggered by
appropriately authorized users. The transitions busysaved and
savedproposed will be triggered by regular programmers, whereas
the remaining transitions have to be initiated by the project
administrator.
Each transition corresponds to a specific action or interaction
within a general software project communication scheme. As these
actions/interactions will be functionally supported by the
project support system currently under development, the explicit
manipulation of object states will no longer be necessary
(except, perhaps for manual adjusting of ill situations).
The following actions relate to the state transitions:
save (busysaved, performed by programmer)
sbmt (savedproposed, performed by programmer)
accpt (proposedpublished, performed by project administrator)
accs (publishedaccessed, performed by any project member)
release (accessedfrozen, performed by project administrator)
A different interface to the status control facilities of vadm
is provided by the program aliases sbmt, publ, accs, and frze.
These commands correspond to conceptual project interactions
like submit, publish, access, and freeze.
Submit is the operation performed by a team programmer when a
work result (such as a completed change request) is proposed for
inclusion into the official system configuration. The associated
status is proposed.
Publish is an operation that is typically performed by members
of the quality assurance group, when a work result, as proposed
by a team programmer is approved and thus included into the
current official system configuration. The associated status is
published.
Access is an operation that is performed during configuration
identification, when component versions of a (sub-)product are
incorporated into some other (partial) (sub-)system
configuration. The associated status is accessed.
Freeze is an operation that is performed during configuration
identification, when a global release of the entire system
configuration is established. The associated status is frozen
-set [description | note | intent]
allows to set or modify the descriptive text for an AtFS history
object (i.e. an entire version history), the note usually
describing the differences of a version object with respect to
its preceding version, or an entry describing a planned change.
(Re-) setting the change intention may be appropriate, if a
previously set change intent has been consumed by a sbmt command
that retained the lock on an object history.
vadm will check the callers environment for the EDITOR variable
and invoke the program identified therein. If the EDITOR
variable is not set, the systems default editor will be
activated. The user may write an arbitrary length descriptive
or note entry using the editor. When the user leaves the editor,
the resulting text is stored with the object history or the
specified version objects.
-setc comment_string
sets commentstring as the (sequence of) character(s) that opens
a comment line within the formalism of the document. This
comment_string will be prepended to the lines of the log history
when the $__log$ attribute is expanded within the text of a
revision.
-unlock
gives up the previously reserved privilege to update the history
of an AtFS object and clears the write-permission for the
corresponding files. -unlock may be used by the owner of an
object history to break a lock previously set by any programmer.
This option is useful to resolve deadlock situations resulting
from careless use of -lock, or exceptional circumstances that
require immediate updating of an object history, even if the
lock holder is not present. The previous owner of a broken lock
is notified by a mail message. Under some circumstances mail-
notifications upon broken locks can be annoying (e.g. when a
development tree has been moved to another system or domain with
locked busy-versions; in this case the owner must break the
locks to check the busy-versions back into the version archives
at the new site). To avoid this effect, the switch -nomail can
be used to suppress mail notification.
An eventually expressed change intention (see -lock) will be
cleared.
Technically, the owner of an objects history is the owner of the
AtFS subdirectory hosting the object base.
-unpromote
reverses a state transition carried out through a prior
-promote. The same remarks about functional embedding (and thus
hiding the state transitions) of state transitions made for
-promote hold for -unpromote.
PREDEFINED ATTRIBUTE NAMES
Name Meaning Value Remarks
alias version alias names list of alias names, like1,3
‘‘vadm-4.2pre7’’ or ‘‘ShapeTools-1.4’’
atime time of last access e.g. ‘‘Tue Jan 14 18:47:06 1992’’3
author user who saved a version user@do.ma.in (domain name does1,3
usually not include the hostname)
cachekey unique key for cached versionscompound numeric built from3
creation date, process id, and a serial
number e.g. ‘‘740148430.18469.6’’
clead comment line leader symbol dependent on file type1
e.g. ‘‘# ’’ for Shapefiles
ctime time of last status change as atime
Description descriptive text for modulemulti line text2
dsize size of delta to previous numeric
version in bytes
generation major revision number numeric1,3
Header RCS-style version header text
Intent change intent multi line text 2
host name of current host e.g. ‘‘avalanche’’ 3
Log cumulative descriptive entries multi line text
of all versions from the first
up to this one
lock/locker user who locks a historyas author3
ltime time of last lock transaction as atime3
mode access pprotection e.g. ‘‘-rw-r--r--’’ 1
mtime time of last modification as atime3
name name part of an object identifier e.g. ‘‘foo’’ for ‘‘foo.c’’3
note short note describing the multi line text1, 2
changes in this version
owner user who owns the repository in as author1,3
which this version is archived
pred bound version identifier of e.g. ‘‘foo.c[3.22]’’ or ‘‘n/a’’
preceding version
revision minor revision number numeric1,3
rtime last time when history was locked as atime
self bound version identifier for e.g. ‘‘foo.c[3.23]’’
this version
selfpath bound version identifier fore.g. ‘‘/usr/proj/sample/foo.c[3.23]’’
this version including path
size size of the version in bytes numeric3
state/status version status symbolic integers (busy,1,3
saved, proposed, published,
accessed, and frozen)
stime time when the version was saved as atime3
succ bound version identifier of as pred
successive version
syspath pathname part of an object e.g. ‘‘/usr/proj/sample’’3
identifier for ‘‘/usr/proj/sample/foo.c’’
type suffix part of an object e.g. ‘‘c’’ for ‘‘foo.c’’3
identifier
unixname UNIX file name of this versione.g. ‘‘foo.c’’
unixpath UNIX file name of this versione.g. ‘‘/usr/proj/sample/foo.c’’
including path
version compound version number e.g. ‘‘3.22’’1,3
consisting of generation
and revision number
vtime version time, modification time as atime
for busy versions od save time
for saved/cached versions
xpoff pseudo attribute that turns none
off subsequent attribute
expansions
xpon pseudo attribute that turns none
subsequent attribute
expansion on
1 - may be modified by vadm -attr name=value.
2 - may be modified by vadm -set <type>.
3 - recognized by attr* predicates in version bind rules (see bindrules(7)).
ENVIRONMENT
EDITOR
SEE ALSO
save(1), retrv(1), vl(1), vbind(1)
AUTHORS
Uli.Pralle@cs.tu-berlin.de, Axel.Mahler@cs.tu-berlin.de,
Andreas.Lampen@cs.tu-berlin.de