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 busy→saved and saved→proposed
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 (busy→saved, performed by programmer)
sbmt (saved→proposed, performed by programmer)
accpt (proposed→published, performed by project
administrator)
accs (published→accessed, performed by any project
member)
release (accessed→frozen, 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, like 1,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 does 1,3
usually not include the hostname)
cachekey unique key for cached versions compound numeric built from 3
creation date, process id, and a serial
number e.g. ``740148430.18469.6''
clead comment line leader symbol dependent on file type 1
e.g. ``# '' for Shapefiles
ctime time of last status change as atime
Description descriptive text for module multi line text 2
dsize size of delta to previous numeric
version in bytes
generation major revision number numeric 1,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 history as author 3
ltime time of last lock transaction as atime 3
mode access pprotection e.g. ``-rw-r--r--'' 1
mtime time of last modification as atime 3
name name part of an object identifier e.g. ``foo'' for ``foo.c'' 3
note short note describing the multi line text 1, 2
changes in this version
owner user who owns the repository in as author 1,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 numeric 1,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 for e.g. ``/usr/proj/sample/foo.c[3.23]''
this version including path
size size of the version in bytes numeric 3
state/status version status symbolic integers (busy, 1,3
saved, proposed, published,
accessed, and frozen)
stime time when the version was saved as atime 3
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 version e.g. ``foo.c''
unixpath UNIX file name of this version e.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
