Man Linux: Main Page and Category List

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)