.ig
 Copyright (C) 1993,1994 by the author(s).
 
 This software is published in the hope that it will be useful, but
 WITHOUT ANY WARRANTY for any part of this software to work correctly
 or as described in the manuals. See the ShapeTools Public License
 for details.

 Permission is granted to use, copy, modify, or distribute any part of
 this software but only under the conditions described in the ShapeTools 
 Public License. A copy of this license is supposed to have been given
 to you along with ShapeTools in a file named LICENSE. Among other
 things, this copyright notice and the Public License must be
 preserved on all copies.


Author: Andreas Lampen (Andreas.Lampen@cs.tu-berlin.de)

$Header: atbind.3[7.0] Fri Jun 25 16:39:30 1993 andy@cs.tu-berlin.de frozen $
..
.TH atbind 3 "Fri Jun 25 16:39:30 1993" "AtFStk-1.12" "AtFS Toolkit Library"
.SH NAME
atBindVersion, atBindSet, atBindCache, atBindNoMsg, atScanBinding,
atBindTrace, atBindExpandMacro, atBindOptions, atBindModeOption,
atBindSetArgv, atBindUsage \- version binding
.SH SYNOPSIS
#include <atfs.h>
.br
#include <atfstk.h>
.sp
.ta 1.2c
Af_key	*atBindVersion (char *name, *binding);
.sp
Af_set	*atBindSet (char *pattern, char *binding, int bindMode);
.sp
Af_set	*atBindCache (char *pattern, *binding);
.sp
int	atBindNoMsg;
.sp
int	atScanBinding (char *binding, char **resultStr, int *resultGen, int *resultRev, time_t *resultDate);
.sp
int	atBindTrace;
.sp
char	*(*atBindExpandMacro)(char *inputString);
.sp
int	atBindOptions (int argc, char **argv, int newArgc, char *(*newArgv[]));
.sp
int	atBindModeOption;
.sp
int	atBindSetArgv (int *argc, char *(*argv[]));
.sp
void	atBindUsage (char *extraText);
.sp
.SH DESCRIPTION
\fIatBindVersion\fP performs a version binding, that means, it selects
a unique version from a named history. It expects \fIname\fP to be
either a string of the form \fIhistoryName[binding]\fP 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. \fIatBindVersion\fP returns the
appropriate version key, if the bind operation leads to a unique
version selection, otherwise NULL.
.LP
\fIatBindSet\fP works similar to atBindVersion, with the difference
that the first argument may be a name \fIpattern\fP (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
\fIbinding\fP argument (see above). atBindSet returns a set of version
keys containing all found versions, or a NULL pointer if something
went wrong.
.LP
Another option of \fIatBindSet\fP 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:
.TP 3.5c
AT_BIND_UNIQUE
Behave like atBindVersion for each name generated from \fIpattern\fP.
Generates no error condition in case of nonunique or empty selection.
.TP
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.
.TP
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.
.TP
AT_BIND_LASTSAVED
Similar to AT_BIND_LAST but ignores busy versions.
.LP
\fIatBindCache\fP tries to bind versions from the derived object
cache. It expects a \fIpattern\fP and \fIbinding\fP argument similar
to atBindSet.
.LP
The \fIatBindNoMsg\fP 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.
.LP
\fIatScanBinding\fP scans the version bind directive \fIbinding\fP.
It returns the binding type, which is one of
.TP 3.5c
AT_BIND_ALIAS
A version alias (symbolic name). Example \f(CBfoo[release-2]\fP. The
alias name returned in \fIresultStr\fP resides in allocated memory.
.TP
AT_BIND_CACHEKEY
A unique identifier for cached objects. This is automatically
generated for each cached object and consists of three numbers
(\f(CBlike foo.o[739564427.16390.22]\fP).
.TP
AT_BIND_DATE
A date specification. (see stMktime (manual pape sttime(3)) for a list
of valid date formats) Examples: \f(CBfoo[Jan 8, 1993]\fP,
\f(CBfoo[8.1.93]\fP. The date is returned in \fIresultDate\fP.
.TP
AT_BIND_DEFAULT
Default binding. This is the case when either an empty binding was
given or something like \f(CBfoo[]\fP.
.TP
AT_BIND_RULE
Version bind Rule. Example \f(CBfoo[bind_rule:]\fP. A rule may also
have the form \f(CBfoo[bind_rule(arg1,arg2,...argN):]\fP additionally
passing the given arguments to bind rule evaluation. The rule name
returned in \fIresultStr\fP resides in allocated memory.
.TP
AT_BIND_VNUM
Version number. Example \f(CBfoo[1.2]\fP. The resulting generation and
revision number are returned in \fIresultGen\fP and \fIresultRev\fP.
.LP
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.
.LP
The \fIatBindTrace\fP switch enables tracing of each version bind
operation when set TRUE. Trace output is sent to standard error.
Initially, its value is FALSE.
.LP
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 \fI$C\fP or
\fI$(macroName)\fP (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 \fIatBindExpandMacro\fP, the
macro expansion routine will be invoked for each evaluated rule.
.LP
\fIatBindOptions\fP 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 \fIargc\fP and \fIargv\fP) and returns all remaining
tokens (output arguments \fInewArgc\fP and \fInewArgv\fP). 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.
.LP
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.
.LP
\fIatBindSetArgv\fP preprocesses a command line (arguments \fIargc\fP
and \fIargv\fP) by evaluating and fetching off version binding options
and replacing all filename arguments by bound filenames (e.g.
\fCfoo[1.4]\fP). It returns the number of arguments remaining on the
command line.
.LP
\fIatBindUsage\fP calls stShortUsage (manual page atparseargs(3)) with
the current program name, the bind standard options vector, and the
given \fIextraText\fP. Result is a short usage description written to
standard error.
.SH 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 \fIatBindError\fP is set true (non-zero),
and an explaining message is copied to the \fIatBindErrorMsg\fP string
buffer. The atBindError variable is cleared upon successfull calls,
the message buffer remains unchanged.
.SH FILES
$SHAPETOOLS/BindRules
.SH SEE ALSO
atfstkintro(3), vbind(1), stparseargs(3)