NAME

       retrv - retrieve a revision of a file

SYNOPSIS

       retrv [ version binding options ] [ options ] files ..

       Options: [ -?cfilq ] [ -help ] [ -copy ] [ -dest path ] [ -fix ] [ -force ] [ -intent message ] [ -lock ]
                [ -quiet ] [ -stdin ] [ -version ] [ -xpoff ]

       vcat [ version binding options ] [ options ] files ..

       Options: [ -?q ] [ -help ] [ -quiet ] [ -version ] [ -xpoff ]

DESCRIPTION

       Retrv retrieves a specified, previously saved version of a file from the version object base. The version
       archive  is  expected to reside in the AtFS subdirectory. A selected version will by default be retrieved
       into a file in the directory where it was originally saved.  If just a copy of a file  version  shall  be
       retrieved,  this  behavior can be overridden with the -dest option. If a busy version is created with the
       -lock option, it must be created in the directory from where it was saved. This is necessary to  maintain
       the  spatial relationship between the busy version and the corresponding history archive, residing in the
       AtFS subdirectory.

       Retrieve tries to be careful if an attempt is made to  overwrite  an  existing  busy-version:  unless  -f
       (-force)  is  specified,  retrv  will  ask  the caller for permission.  If no busy version exists, one is
       created with the same modes as the formerly saved version. If  a  busy  version  exists,  its  modes  are
       preserved.

       If the program is invoked as vcat, the specified version(s) will be printed on standard output. No status
       change of the object base will occur in this case.  vcat behaves similar to the cat(1) command: if just a
       filename  is given, vcat displays the most recent status of the referenced object. If a busy version does
       exist it will be selected as most recent status. If no  busy  version  exists,  vcat  displays  the  most
       recently saved version.

ATTRIBUTE CITATIONS

       It is possible to cite any of a file-version's attributes within the the body of the version. This can be
       done  by  using  attribute  citation  expressions.  These  expressions have the form "$__attributename$".
       Version attributes that are cited within the text of a stored revision are expanded by default.  In  this
       case,  the  citation  expression  will  be  substituted  by  the  cited  attribute's value. For a list of
       predefined attribute names, check the vadm(1) manual page.

       There are three basic kinds of attribute values: genuine values, reference values, and execution  values.
       Genuine  values  are  simply strings that are assigned to an attribute.  Reference values are pointers to
       files or AtFS-versions whose contents will be substituted in place of an  attribute-citation.   Reference
       values  are  strings  that  begin  with  a  circumflex-character,  typically  followed  by pathname, e.g.
       ^/usr/local/lib/std-header[2.4]. Execution values are names of executable programs, whose standard output
       is substituted in place of an attribute-citation.  Execution  values  are  strings  that  begin  with  an
       exclamation-mark  character,  typically  followed  by the name of the program, e.g. !/bin/date. Execution
       values can be used to generate highly dynamic attributes or a primitive form of event-triggers.

       When expanding an attribute citation, retrv first looks for an attribute of the mentioned name within the
       version's set of associated attributes. If no attribute of that name can be  found,  the  environment  is
       searched  for  a  variable of that name. In case the cited attribute exists and has a value, the value is
       itself searched for attribute-citations that are expanded recursively.  If neither an  attribute  nor  an
       environment  variable of the cited name can be found, no substitution takes place and the expression will
       be left unchanged. The same is true if a referenced object of a reference value does  not  exist,  or  an
       execution  value happens to not be executable.  Attribute citation expressions are also left unchanged if
       a revision is retrieved with the -lock option.  Expansion of attribute citation within documents  can  be
       controlled by the pseudo-attribute citations "$__xpoff$" and "$__xpon$".

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.

       Additional options are:

       -?, -help
              print brief instructions about using this program.

       -c, -copy
              Do not check for equality. Usually, retrv checks whether an existing destination file is identical
              to the version to be retrieved and suppresses copying in this case. This behaviour is  mainly  for
              efficiency reasons and may be disabled by the -c switch.

       -dest path
              retrieve the specified version from the object base and install a copy it in the directory denoted
              by  path.  As  this  directory  may  be  a  long  way apart from the directory containing the AtFS
              archives, this copy of the retrieved version  is  separated  from  its  history  and  subsequently
              unrelated  to  the object history it came from. Proper object histories require a constant spatial
              relationship of any busy versions and the corresponding archives. This relationship  requires  the
              archives to reside in a subdirectory named AtFS.

       -fix   attempt  to  reserve  the  privilege to add a new version to an old generation (insert a new minor
              revision into an old major revision) within the object history. If successful, the user who issued
              the command holds a generation lock. There  can  be  only  one  lock  per  generation,  preventing
              simultaneous  updates  of  the  generation. The generation lock is, by convention, a revision lock
              (see vadm -lock) attached to the version with the highest version number within a generation.

              The -fix switch is intended to support concurrency of the main development process and maintenance
              activities (such as bug fixing) for older releases. When a version is retrieved with  the  purpose
              to  fix  it, it is called the fixpoint version. The fixpoint version accumulates all fixes applied
              to a baseline version within  a  generation.  One  important  advantage  of  this  policy  is  the
              elimination  of  the  need  to  create  a  branch  for each fix that must later be merged with the
              ``mainline'' version, containing previous fixes. So, if retrv is invoked  with  ``-fix''  it  will
              restore the fixpoint version (the most recent minor revision within the implied generation) rather
              than  the explicitly referenced version. However, retrv issues a warning, if the baseline- and the
              fixpoint version are not identical.

              To insert a fix into an old generation, use the -fix option of the save command.  When  setting  a
              lock  on  a generation, the requesting user is prompted for an optional description of the planned
              changes.  The -fix switch is incompatible with -lock.

       -f, -force
              force the reinstallation of the specified version as busy version without asking the user, even if
              a writable (possibly unsaved) busy version exists.

       -i message
              set message as intent text describing the changes that are  intended  to  be  applied  to  a  busy
              version  that is installed by retrv. When message starts with an at sign (@), it is interpreted as
              filename and the text contained in the file is takes as intent text.  If  message  is  ``-'',  the
              change  intent is read from standard input. The latter case is identical to specifying the command
              line switch -stdin. This option requires the -lock switch to be set in order to be effective.

       -l, -lock
              attempt to reserve the privilege to add a new version to the main development line  of  an  object
              history,  thus  preventing multiple programmers working upon the same object base from interfering
              with each other by saving concurrent updates.  When setting a  new  lock  on  an  object  history,
              prompt  the  requesting user for an optional description of the planned changes.  The -lock switch
              is incompatible with -fix.

       -q, -quiet
              quiet operation. No messages are printed on standard output.  If a current busy version exists, it
              will not be overwritten by the specified version unless -f is set. This option is useful for batch
              operation.

       -stdin force retrv to read the message describing the change  intent  from  stdin  rather  than  fork  an
              editor.

       -version
              print version identification for this program.

       -xpoff Do not expand attribute citations in the restored file.

FILES

       All revisions of documents are retrieved from archive files located in the subdirectory AtFS.

SEE ALSO

       vbind(1), save(1), vadm(1)

BUGS

       Redirection of stdin in conjunction with option -stdin doesn't work.

AUTHOR

       Axel.Mahler@cs.tu-berlin.de

retrv-4.5                                   Thu Jun 17 14:03:56 1993                                    retrv(1)