Provided by: atfs-dev_1.4pl6-14_amd64 bug

NAME

       atBindVersion,    atBindSet,   atBindCache,   atBindNoMsg,   atScanBinding,   atBindTrace,
       atBindExpandMacro, atBindOptions, atBindModeOption, atBindSetArgv, atBindUsage  -  version
       binding

SYNOPSIS

       #include <atfs.h>
       #include <atfstk.h>

       Af_key*atBindVersion (char *name, *binding);

       Af_set*atBindSet (char *pattern, char *binding, int bindMode);

       Af_set*atBindCache (char *pattern, *binding);

       int  atBindNoMsg;

       int  atScanBinding  (char  *binding,  char  **resultStr,  int  *resultGen, int *resultRev,
       time_t *resultDate);

       int  atBindTrace;

       char *(*atBindExpandMacro)(char *inputString);

       int  atBindOptions (int argc, char **argv, int newArgc, char *(*newArgv[]));

       int  atBindModeOption;

       int  atBindSetArgv (int *argc, char *(*argv[]));

       void atBindUsage (char *extraText);

DESCRIPTION

       atBindVersion performs a version binding, that means, it selects a unique version  from  a
       named history. It expects name to be either a string of the form historyName[binding] or a
       plain name. With a version bind directive (binding) given in brackets  after  the  history
       name,  the  second  argument is ignored. Otherwise the second argument is taken as version
       bind directive. With no binding given, atBindVersion performs the  default  binding.  This
       may  be  explicitly  defined  by  afBindOptions (see below), or it selects the most recent
       (modification/saving date) version. See below a list of different forms  of  version  bind
       directives. atBindVersion returns the appropriate version key, if the bind operation leads
       to a unique version selection, otherwise NULL.

       atBindSet works similar to atBindVersion, with the difference that the first argument  may
       be  a  name pattern (a sh(1) pattern to be precise) instead of a unique file name. It uses
       the af_histories (manual page af_history(3)) call, to generate a  list  of  history  names
       from  the  given  pattern.  After that, it performs a version binding for each name with a
       version bind directive given either in square brackets or as binding argument (see above).
       atBindSet  returns  a set of version keys containing all found versions, or a NULL pointer
       if something went wrong.

       Another option of atBindSet is nonunique version selection within a history. In this case,
       multiple  versions from one history may be included in the result set. In detail atBindSet
       supports four options:

       AT_BIND_UNIQUE
                     Behave like atBindVersion for each name generated from  pattern.   Generates
                     no error condition in case of nonunique or empty selection.

       AT_BIND_SET   (default) Do not require uniqueness. If more than one version from a history
                     meets the binding specifications, all these versions will be included in the
                     result set.

       AT_BIND_LAST  Selects the last (modification/saving date) version from the binding hit set
                     of each history. The resulting hit set contains at most one version of  each
                     history involved in the bind operation.

       AT_BIND_LASTSAVED
                     Similar to AT_BIND_LAST but ignores busy versions.

       atBindCache tries to bind versions from the derived object cache. It expects a pattern and
       binding argument similar to atBindSet.

       The atBindNoMsg switch allows the output of version binding rules, generated by predicates
       like  'msg`  or 'confirm`, to be suppressed. This can be done by setting atBindNoMsg TRUE.
       Initially, it is set FALSE. When evaluating a 'confirm` predicate,  where  user  input  is
       expected,  with  atBindNoMsg  set  true,  the  version  binding algorithm proceeds without
       halting as if the user had accepted the default input.

       atScanBinding scans the version bind directive binding.   It  returns  the  binding  type,
       which is one of

       AT_BIND_ALIAS
                     A  version  alias  (symbolic  name).  Example foo[release-2]. The alias name
                     returned in resultStr resides in allocated memory.

       AT_BIND_CACHEKEY
                     A unique identifier for cached objects. This is automatically generated  for
                     each    cached    object    and    consists    of    three   numbers   (like
                     foo.o[739564427.16390.22]).

       AT_BIND_DATE  A date specification. (see stMktime (manual pape sttime(3)) for  a  list  of
                     valid  date  formats)  Examples:  foo[Jan 8, 1993], foo[8.1.93]. The date is
                     returned in resultDate.

       AT_BIND_DEFAULT
                     Default binding. This is the case when either an empty binding was given  or
                     something like foo[].

       AT_BIND_RULE  Version  bind  Rule.  Example foo[bind_rule:]. A rule may also have the form
                     foo[bind_rule(arg1,arg2,...argN):] additionally passing the given  arguments
                     to  bind  rule  evaluation.  The  rule name returned in resultStr resides in
                     allocated memory.

       AT_BIND_VNUM  Version number. Example foo[1.2].  The  resulting  generation  and  revision
                     number are returned in resultGen and resultRev.

       One  important  issue  is,  that each version alias will also be tried as rule name, if it
       turns out to be no known symbolic name. This implies that rule names  may  also  be  given
       without the trailing colon, when there are no naming conflicts with version aliases.

       The atBindTrace switch enables tracing of each version bind operation when set TRUE. Trace
       output is sent to standard error.  Initially, its value is FALSE.

       The atBind module provides a hook for  an  external  macro  processor  to  preprocess  any
       version  bind rule just before applying it. The bind rule text may contain macro citations
       of the form $C or $(macroName) (like in Make-/Shapefiles) to be expanded by  the  external
       macro  processor.  This  should  expect any string containing macro citations as input and
       return  a  string  with  expanded  macros.   When  assigned  to  the   function   variable
       atBindExpandMacro, the macro expansion routine will be invoked for each evaluated rule.

       atBindOptions  calls  stParseArgs  (manual page atparseargs(3)) with an internally defined
       standard option vector for command line version binding options. The vbind(1) manual  page
       contains  a description of these options. atBindOption should be called before parsing the
       application specific options It fetches the version binding options off the  command  line
       (input arguments argc and argv) and returns all remaining tokens (output arguments newArgc
       and newArgv). Return value is the number of erroneous options (e.g. with argument missing)
       found. A negative return value indicates an internal error, zero is returned un success.

       atBindOptions  defines  the  default version selection policy as given on the command line
       for the whole application. Each subsequent call of atBindVersion and atBindSet (see above)
       will conform to this policy unless an explicit version bind directive is given.

       atBindSetArgv  preprocesses  a  command  line  (arguments argc and argv) by evaluating and
       fetching off version binding  options  and  replacing  all  filename  arguments  by  bound
       filenames  (e.g.   foo[1.4]).  It returns the number of arguments remaining on the command
       line.

       atBindUsage calls stShortUsage (manual page atparseargs(3)) with the current program name,
       the  bind  standard  options  vector,  and  the  given  extraText. Result is a short usage
       description written to standard error.

DIAGNOSTICS

       Upon error, the version  binding  functions  (atBindVersion,  atBindSet  and  atBindCache)
       return   a  null  pointer.  atScanBinding  has  no  error  conditions.  atBindOptions  and
       atBindSetArgv return -1 on error and a value greater or equal null  on  success.   On  any
       error,  the  variable  atBindError  is  set  true (non-zero), and an explaining message is
       copied to the atBindErrorMsg string buffer.  The  atBindError  variable  is  cleared  upon
       successfull calls, the message buffer remains unchanged.

FILES

       $SHAPETOOLS/BindRules

SEE ALSO

       atfstkintro(3), vbind(1), stparseargs(3)