Ubuntu Manpage: atBindVersion, atBindSet, atBindCache, atBindNoMsg, atScanBinding, atBindTrace,

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

NAME

SYNOPSIS

DESCRIPTION

DIAGNOSTICS

FILES

SEE ALSO