setTransBinding(3)

NAME
setTransBinding, getTransBinding -- set and get the function binding of an RCCL transform (general interface).

USAGE
#include <rccl.h>

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

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

ARGUMENTS

tr --
    Pointer to the transform.

binding --
    Pointer to the transform binding structure. The definition of this structure is given below.

RESTRICTIONS
setTransBinding() must be called from the planning level.

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 setTransConst(), setTransVarb(), transEval(), and transMotionEval() (q.v.). setTransBinding() does the same things those routines do, but uses a format that is symmetrical with the one used by 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 setTransVarb(3).

Only transforms allocated using the allocTrans() routines can take a binding.

Transform binding is controlled with TRANS_BINDING structure, whose definition is
        typedef struct {
                int code;
                int (*fxn)();
                int arg;
                MANIP *mnp;
        } TRANS_BINDING;

The field code is the binding status, and is one of the following values:

TRANS_CONST --
    The transform is considered to be 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.

TRANS_VARB --
    The transform is considered 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.

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

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

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

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

setTransBinding() takes the binding description binding and applies it to the specified transform. Depending on the binding code, this function call is equivalent to one of four synonymous routines:
        TRANS_CONST        ->   setTransConst()
        TRANS_VARB         ->   setTransVarb()
        TRANS_EVAL         ->   transEval()
        TRANS_MOTION_EVAL  ->   transMotionEval()

The field settings in binding should match the corresponding arguments that would be passed to these routines (inappropriate fields are ignored).

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

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

EDescriptor --
    Invalid transform pointer.

EInternal --
    Unexpected internal software or communication failure.

setTransBinding() may also set the following:

EBadArg --
    In the case of TRANS_EVAL or TRANS_MOTION_EVAL, the specified function is not contained in the program's control segment.

setTransBinding() will abort the program if called from the control level.

BUGS
These routines are not interlocked against simultaneous accesses.

SEE ALSO
setTransVarb(3), allocTrans(3), allocTransXyz(3), rcclSetOptions(3), errorStack(3).