\input manualMacros.tex
\manBegin
\manPageInfo{RCCL Reference Manual}{}{}
\manTitle{setTransBinding}{3}
\manSection{NAME}
{\rightskip=0ptplus1fil
{\tt \manName{setTransBinding}},
{\tt \manName{getTransBinding}}
-- set and get the function binding of an RCCL transform (general interface).

}
\manSection{USAGE}
\cverbatim
#include <rccl.h>

setTransBinding (tr, binding)
  TRSF *tr;
  TRANS_BINDING *binding;

getTransBinding (tr, binding)
  TRSF *tr;
  TRANS_BINDING *binding;
@endcverbatim
\manSection{ARGUMENTS}
\manItem{{\tt tr} --}
Pointer to the transform.
\manItem{{\tt binding} --}
Pointer to the transform binding structure. The definition of
this structure is given below.
\manSection{RESTRICTIONS}
{\tt setTransBinding()} must be called from the planning level.
\manSection{DESCRIPTION}
These routines
provide a general way of setting or getting the functional binding of an RCCL
transform. Transform function bindings can also be set with the routines
{\tt setTransConst()}, {\tt setTransVarb()}, 
{\tt transEval()}, and {\tt transMotionEval()} (q.v.). 
{\tt setTransBinding()} does the same things those routines do,
but uses a format that is symmetrical with the one used by
{\tt getTransBinding()}, which reads back the binding status of a 
transform. For a description of the
companion routines and more discussion of what transform binding is
all about, see the manual page {\tt setTransVarb(3)}.

Only transforms allocated using the {\tt allocTrans()} 
routines can take a binding.

Transform binding is controlled with {\tt TRANS_BINDING} structure,
whose definition is
\cverbatim
        typedef struct {
                int code;
                int (*fxn)();
                int arg;
                MANIP *mnp;
        } TRANS_BINDING; @endcverbatim
The field {\tt code} is the binding status, and is one of the following
values:

\manItem{{\tt TRANS_CONST} --}
The transform is considered to be {\it constant} by the trajectory generator.
When a motion request is made whose target position contains this transform,
the trajectory generator makes a private copy of the
transform which it uses for the duration of the motion. 
Subsequent changes to the transform will affect only
subsequent motions. Adjacent constant transforms are
multiplied together to optimize computation.

\manItem{{\tt TRANS_VARB} --}
The transform is considered {\it variable} by the trajectory generator.
When a motion request is made whose target position contains this transform,
the trajectory generator will continue to reference the original
transform. Subsequent changes made to the transform by application code
(running in either the planning or control level) are tracked by the motion.

\manItem{{\tt TRANS_EVAL} --}
The transform is continuously updated by the trajectory generator
with the function {\tt fxn} and the application supplied argument 
{\tt arg}. It is also considered variable.

\manItem{{\tt TRANS_MOTION_EVAL} --}
The transform is updated by the trajectory generator
with the function {\tt fxn} and the application supplied argument 
{\tt arg}, but only when it appears as part of a motion target position for 
the manipulator {\tt mnp}. It is also considered variable.
(This is like the function binding mechanism in the original RCCL.)

In the case of {\tt TRANS_EVAL} and {\tt TRANS_MOTION_EVAL}, the fields
{\tt fxn} and {\tt arg} contain the updating function and its
supplied argument. Otherwise, these fields are set to {\tt NULLF} and {\tt 0}.

In the case of {\tt TRANS_MOTION_EVAL},
the {\tt mnp} field is set to the manipulator associated with the function
binding. Otherwise, this field is set to {\tt NULL}.

{\tt setTransBinding()} takes the binding description {\tt binding} and
applies it to the specified transform. Depending on the binding
code, this function call is equivalent to one of four
synonymous routines:
\cverbatim
        TRANS_CONST        ->   setTransConst()
        TRANS_VARB         ->   setTransVarb()
        TRANS_EVAL         ->   transEval()
        TRANS_MOTION_EVAL  ->   transMotionEval()
@endcverbatim
The field settings in {\tt binding} should match the corresponding
arguments that would be
passed to these routines (inappropriate fields are ignored).

{\tt getTransBinding()} returns the transform binding in effect
for the indicated transform. It returns {\tt 0} if the transform was not
allocated by one of the {\tt allocTrans()} routines.

\manSection{DIAGNOSTICS}
These routines return {\tt -1} in the event of an error.
They will automatically abort the program if the option {\tt RCCL_ERROR_EXIT}
is set (see {\tt rcclSetOptions(3)}). 
Error codes and messages are placed on the {\it errorStack} (q.v.). 
The following error codes may be set:

\manItem{{\tt EDescriptor} --}
Invalid transform pointer.
\manItem{{\tt EInternal} --}
Unexpected internal software or communication failure.

{\tt setTransBinding()} may also set the following:

\manItem{{\tt EBadArg} --}
{\tolerance=10000
In the case of {\tt TRANS_EVAL} or {\tt TRANS_MOTION_EVAL}, the 
specified function is not contained in the program's control segment.

{\tt setTransBinding()} will abort the program if called from the control
level.

}
\manSection{BUGS}
These routines are not interlocked against simultaneous accesses.

\manSection{SEE ALSO}
\rightskip=0ptplus1fil
{\tt setTransVarb(3)}, {\tt allocTrans(3)}, 
{\tt allocTransXyz(3)}, 
{\tt rcclSetOptions(3)}, {\tt errorStack(3)}.
\manEnd
\end
