\input manualMacros.tex
\manBegin
\manPageInfo{RCCL Reference Manual}{}{}
\manTitle{updateTrans}{3}
\manSection{NAME}
{\rightskip=0ptplus1fil
{\tt \manName{updateTrans}}
-- solve for a transform at end of next requested RCCL motion.

} 
\manSection{USAGE}
\cverbatim
updateTrans (mnp, tr, pos, t1, tx)
  MANIP *mnp;
  TRSF *tr, *t1, *tx;
  POS *pos;
@endcverbatim
\manSection{ARGUMENTS}
\manItem{{\tt mnp} --}
Manipulator reference structure.
\manItem{{\tt tr} --}
Place for the trajectory generator to
put the solved transform. This must be a transform allocated
with the {\tt allocTrans()} routines.
\manItem{{\tt pos} --}
Position equation containing the transform to be solved for.
\manItem{{\tt t1} --}
The transform being solved for. 
This must be a component
transform of {\tt pos} (including {\tt T6}).
\manItem{{\tt tx} --}
Instantiation value for {\tt T6}. This argument
is necessary if {\tt pos} contains {\tt T6} and {\tt T6} is 
{\it not} the transform
being solved for, because {\tt T6} has no particular value.
Otherwise, this argument may
be specified as {\tt NULL}.
If specified, this must be a transform allocated
with the {\tt allocTrans()} routines.
\manSection{RESTRICTIONS}
This routine must be called from the planning level.
\manSection{DESCRIPTION}
This routine tells the trajectory generator to solve for the value of
a transform within a particular position equation
at the end of the next requested motion. 
The trajectory generator will evaluate the transform at the same time it
updates the {\tt here} transform in the {\tt MANIP} structure.

This is equivalent to having the trajectory generator perform a
{\tt solveTrans()} at the end of the next requested motion.
The argument syntax and semmantics of {\tt updateTrans()} are identical
to {\tt solveTrans()}, and the manual page for {\tt solveTrans()}
should be consulted for additional information.
Unlike {\tt solveTrans()}, the argument transforms {\tt tr} and {\tt tx}
(if specified) must have been created using the {\tt allocTrans()} routines
so that they can be accessed by the trajectory generator.

{\tt updateTrans()} requests are cancelled when the trajectory
generator is turned off (see {\tt rcclRelease(3)}). 
An update request will also not be honored
if the associated motion is aborted on the queue before it has started
executing (this is an implementation constraint).
Only one update request is permitted per motion and per manipulator.

Unlike with the {\tt move()} requests, the system does
{\bf not} make a private copy of the constant transforms in the
position equation of an update request. 
This was done for reasons of generality, but it might
be changed if it causes problems. 
\manSection{DIAGNOSTICS}
This routine returns {\tt -1} in the event of an error.
It 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 EBadArg} --}
The variable transform {\tt tx} was either not provided when it is needed,
or not allocated using the {\tt allocTrans()} routines.

\manItem{{\tt ERange} --}
The transform {\tt t1} is not
contained in the position equation {\tt pos}.

\manItem{{\tt ETooMany} --}
The position to be solved for contains more than {\tt MAX_UPDATE_POS}
terms.

The routine will abort the program if called from the control level.
\manSection{BUGS}
We should implement {\tt updateChain()} and {\tt updateInvChain()}
as well; this may be done if there is demand for it.

Performing an update request can be expensive, in that the trajectory
generator has to multiply together all the transforms in the position data
structure during
one control cycle.

\manSection{SEE ALSO}
{\tt solveTrans(3)}, {\tt makePosition(3)}, {\tt setTransVarb(3)}.
\rightskip=0ptplus1fil
\manEnd
\end
