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)