vbind(1)							    ShapeTools								  vbind(1)

NAME

       vbind - bind name to version

SYNOPSIS

       vbind [ options ] filenames ..

       General version binding options:
	    [ -bind version binding ] [ -before baseline ] [ -since baseline ] [ -last ] [ -lastsaved ] [ -uniq ] [ -nonuniq ] [ -rule rule-
	    body | rulename ] [ -rulefile filename ] [ -trace ]

       vbind command specific options:
	    [ -? (or -help) ] [ -alias version alias ] [ -date date ] [ -vnum version number ] [ -nomsg ] [ -ruledump ] [ -ruleerr ] [ -rulelist ]
	    [ -ruletest ] [ -version ]

OVERVIEW

       This manual page describes the ShapeTools Version Binding mechanism, available in most commands of the toolkit. The general version binding
       options described on this page are available in many commands such like vl(1), vcat(1), vadm(1), save(1) and retrv(1)  (just  to  name  the
       most important ones). The vbind command specific options are private to the vbind command (see below).

       Version	binding is the process of selecting one or more versions from a filenames history in order to provides access to these version(s).
       This is conducted by version bind directives (or just version bindings), which may be one of the following:

       version numbers
		     "1.2" (version), "1." (generation), ".2" (revision)

       version alias names
		     "ShapeTools-1.4", or "AtFS-2.0"
		     Version alias names are symbolic names tagged to single versions.	They must be unique throughout a history.

       date specifications
		     "10.2.93" or "4.3." (European), "Feb 10, 1993" or "Mar 4{ (American)
		     A date may additionally contain a time in the form hh:mm or hh:mm:ss. See sttime(3) for a complete list  of  recognized  date
		     formats.

       bind rule names
		     "most_recent:" (plain), "from_release(VC-4.0):" (with argument)
		     The  colon  is  not  part	of the rule name. See the bindrules(7) manual page for a description on how to define version bind
		     rules.

       By default, version binding selects all versions fulfilling the given version bind requirements. The -uniq option changes this behavior and
       treats  only  unique identification as success. With this option given, version bind ignores all histories with more than one selected ver-
       sion. The -last and -lastsaved options unify a non unique selection by choosing the last version (modification/saving  time)  or  the  last
       saved version (saving time) from the bind hit set of each name.

       The  file  $SHAPETOOLS/lib/shape/BindRules  contains  predefined rules for various cases. You may also define your own rule file and invoke
       this by either the -rulefile option or by extending the search space defined by the SHAPETOOLS environment variable. For information on how
       to write version bind rules, see the bindrules(7) manual page.

VERSION BINDING IN ACTION

       Version	bind  directives  can be given either in brackets, directly following the name to be bound, or as option arguments. Options may be
       user to set version bindings to be applied to all name arguments (-bind and -rule options) or to define version ranges (-since and  -before
       options).

       Version	identification	by  version number or version alias either results in a unique selection or fails, when no appropriate version was
       found.

       foo[1.2]        Identifies a specific version by it's version number.

       foo[release-2]  Is interpreted as identification by version alias name.

       Version identification by date selects the versions from a history that have been the most recently saved versions at the given date. Iden-
       tification  by  date may lead to multiple versions when development work in multiple generations happened simultaneously at the given date.
       Vbind understands various date formats such as in the list below. The sttime(3) manual page lists all recognized date formats.

       foo[Jan 31, 1992]

       foo[92/01/31]

       foo[10.5.92 7:00:00]

       Version bind rules describe general version binding policies.  They are usually not dependent on  particular  file  histories  and  may	be
       applied to all histories. Version bind rules may have arguments enclosed in parentheses following the name.

       foo[bind_rule:]

       foo[bind_rule(arg1,arg2,...argN):]

       When  the colon at the end of the rule name in brackets is omitted, vbind first interprets the given string as version alias.  When no ver-
       sion with this alias name was found, vbind treats the string as rule name and gives it a second try.

       Plain filenames are those not followed by any version bind directive in square brackets. Without a rule given with the -rule option on  the
       command	line,  plain  filenames  are  bound  using the default version bind rule. It selects the busy version if there is one, or the most
       recent non busy version otherwise.

       eq (state, busy); max (version).

       The default version binding may also be indicated by an empty pair of brackets: foo[]

NAME PATTERNS

       The ShapeTools version binding mechanism performs filename substitution for given name patterns similar to sh(1).  This	is  necessary,	as
       shell filename substitution does not recognize the names of saved versions. Magic cookies are are:

       *       matching any string, including the empty string,

       ?       matching any single character,

       [c...]  matching any one of the characters enclosed in the square brackets,

       [l-r]   matching any character lexically between the left (l) and the right (r) character, inclusive, and

       [!c...]

       [!l-r]  matching any character not recognized by their counterparts above.

       As  square  brackets  on  the command line may either be part of a pattern (e.g. *.[ch]) or a version binding (e.g. *[release-2]), this may
       lead to some confusion. The leftmost pair of brackets is always interpreted as version binding. Hence, in the first case, the  string  will
       be misinterpreted and you must add an explicit version binding to avoid this (e.g. *.[ch][], default version binding added).

GENERAL VERSION BINDING OPTIONS

       -before baseline
	      Define  the  lower boundary of a time interval for selecting all versions evolved in this interval. Baseline can be any version bind
	      directive uniquely selecting a version (e.g. version number, version alias, or date). The saving date of the baseline version is the
	      interval start time. The boundary version (exactly matching the time given) is not included in the result set.

       -bind version binding
	      Use version binding for binding each name on the command line, that has no explicit version binding in brackets.

       -last  Select the last (modification/saving time) version of each nonunique selection. This causes the resulting version list to contain at
	      most one version of each history. -last may be combined with other version bindings.

       -lastsaved
	      Like -last, but busy versions are ignored.

       -nonuniq
	      Force non-unique version identification. This option can be used to swich off the default behavior of some commands (e.g. vadm) that
	      suggests unique version identification.

       -rule rulename | rulebody
	      With  a  name  argument, this option sets the named rule as default rule for binding all names on the command line. Alternatively, a
	      rule body (a version selection rule without a name) may be given as argument, which will be evaluated for each name on  the  command
	      line.  This option disables any previous -bind or -rule definition. It does not affect names with a version binding in brackets.

       -rulefile filename
	      Read  in	the  named rule file and add all contained rules to the list of known rules. A syntactical error, detected while parsing a
	      rule causes the according rule to be skipped. Use vbind(1) with the -ruleerr option for inspecting bind rule files.   Multiple  rule
	      files may be specified on the command line.

       -since baseline
	      Define  the  upper boundary of a time interval for selecting all versions evolved in this interval. Baseline can be any version bind
	      directive uniquely selecting a version (e.g. version number, version alias, or date. The saving date of the baseline version is  the
	      interval end time. The boundary version (exactly matching the time given) is not included in the result set.

       -trace Trace  the  evaluation.  Each  evaluated	predicate is reported to standard output. Additionally, the set of versions fulfilling the
	      expressed  (the hits set) is displayed after evaluation of each predicate.

       -uniq  Require unique version identification. All history names on the command line, where multiple versions meet the version bind require-
	      ments are ignored.

THE VBIND COMMAND

       Vbind  performs a version binding and returns a bound filename for each selected version. A bound filename is a filename followed by a ver-
       sion number enclosed in brackets (e.g. foo[1.2]).

       -?, -help
	       Display a short usage description.

       -alias version alias
	       Use version alias for binding all names on the command line. This disables any previous -alias, -bind, -date, -rule or -vnum  defi-
	       nition.	It does not affect names in pseudo bound version notation.

       -date date
	       Use  date for binding all names occurring on the command line. This disables any previous -alias, -bind, date, -rule or -vnum defi-
	       nition.	It does not affect names in pseudo bound version notation.

       -nomsgSuppress output produced by version bind rules.

       -ruledump
	       The -ruledump option causes all known version bind rules to be written to standard output. The generated output contains  all  rule
	       definitions in regular format and may be used as input rulefile for subsequent calls of vbind.

       -ruleerr
	       This  option  makes  sense,  when  testing a new, hand written file containing bind rules. The -ruleerr option causes syntax errors
	       detected in the rule file to be reported to standard error. Make sure, that this option occurs on the command  line  prior  to  the
	       rulefile to be inspected.

       -rulelist
	       Write a list of all known rule names to standard output.

       -ruletest
	       Interpret all names on the command line as rule names and test the existence of equally named rules in the list of known rules.

       -version
	       Print version identification of vbind command and used libraries.

       -vnum version number
	       Use version number for binding all names on the command line. This disables any previous -alias, -bind, -date, -rule or -vnum defi-
	       nition.	It does not affect names in pseudo bound version notation.

ENVIRONMENT

       SHAPETOOLS - list of path names as search space for files containing version bind rules. The bind  rule	files  must  be  named	BindRules.
       Default path is /usr/local/lib/shape.

FILES

       $SHAPETOOLS/lib/shape/BindRules

SEE ALSO

       vl(1), sttime(3), bindrules(7)

AUTHOR

       Andreas.Lampen@cs.tu-berlin.de

AtFStk-1.12						     Thu Mar 10 12:15:43 1994							  vbind(1)