atBindVersion, atBindSet, atBindCache, atBindNoMsg, atScanBinding, atBindTrace,
atBindExpandMacro, atBindOptions, atBindModeOption, atBindSetArgv, atBindUsage
- version binding
#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);
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.
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.
$SHAPETOOLS/BindRules
atfstkintro(3),
vbind(1),
stparseargs(3)