--- name: "atbind" section: "3" platform: "linux" package: "atfs-dev" version: "1.4pl6-15+b1" release: "Debian 12 (Bookworm)" platforms: ["linux"] url: "https://new.carta.tech/atbind" --- # atbind(3) version binding ## NAME atBindVersion, atBindSet, atBindCache, atBindNoMsg, atScanBinding, atBindTrace, atBindExpandMacro, atBindOptions, atBindModeOption, atBindSetArgv, atBindUsage - version binding ## SYNOPSIS \#include \\ \#include \ 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)](/sh/1.md) pattern to be precise) instead of a unique file name. It uses the af\_histories (manual page [af\_history(3)](/af_history/3.md)) 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)](/sttime/3.md)) 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)](/vbind/1.md) 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)](/atfstkintro/3.md), [vbind(1)](/vbind/1.md), [stparseargs(3)](/stparseargs/3.md)