\input manualMacros.tex
\manBegin
\manPageInfo{RCCL Reference Manual}{}{}
\manTitle{move}{3}
\manSection{NAME}
{\rightskip=0ptplus1fil
{\tt \manName{move}}
-- RCCL motion request primitive.
}
\manSection{USAGE}
\cverbatim
#include <rccl.h>

mid = move (mnp, pos)
  MANIP *mnp;
  POS *pos;
@endcverbatim
\manSection{ARGUMENTS}
\manItem{{\tt mnp} --}
Manipulator reference structure.
\manItem{{\tt pos} --}
Data structure describing the target position (produced by the command {\tt
makePosition()}). 
\manItem{{\tt mid} --}
Motion ID. This is a non-negative number either assigned automatically
by the system or specified explicitly using {\tt setMotionFlag()}
before the call to {\tt move()}.
\manSection{RESTRICTIONS}
This routine must be called from the planning level.
\manSection{DESCRIPTION}
The {\it move()} primitive queues a request to move a manipulator
to a target location specified by {\tt pos}.
The trajectory generator will move the robot
so the its T6 transform is equal to the solved value of
the T6 transform in the target position. If any of the 
component transforms of the target position are varying in time
(see {\tt setTransVarb(3)}) the robot will track these changes
while the motion is in progress.

Parameters controlling various aspects of
the motion (e.g., velocity or acceleration) are set {\it prior} to the call
using various 
{\it set} primitives. Ordinarily, {\tt move()} returns
immediately, before the motion request has completed. {\tt move()} 
will block
only if the motion queue for that manipulator is full. It is possible to
combine this effect with changing the motion queue size (see
{\tt setMotionQueueSize(3)}) to obtain different blocking behaviours.

The returned motion ID value can be used to obtain status information
about the motion request (see {\tt motionStatus(3)}), cancel it
(see {\tt stopMotion(3)}), or wait for it to either begin executing
or finish
(see {\tt waitForStop(3)}). Motion IDs assigned by the system
are automatically invalidated and reused after {\tt NUM_SYSMFLAGS} subsequent
motion requests (on all manipulators). If this is undesirable, 
a motion ID can be explicitly
set by the program with the primitive 
{\tt setMotionFlag()}.

\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 ENoSpace} --}
The motion queue does not have enough space to store the requested motion
request packet (NOTE: this depends on more than just the
motion queue size, because the size of a motion request is variable).
\manItem{{\tt ENoT6} --}
The position equation for the motion request did not contain
a T6 transform.

The routine will abort the program if called from the control level.
\manSection{SEE ALSO}
\rightskip=0ptplus1fil
{\tt rcclCreate(3)}, {\tt makePosition(3)}, {\tt stop(3)}, 
{\tt setMotionQueueSize(3)}, {\tt setMotionFlag(3)},
{\tt waitForMotion(3)}, {\tt motionStatus(3)}, {\tt stopMotion(3)}, 
{\tt setMotionHold(3)},
{\tt rcclSetOptions(3)}, {\tt errorStack(3)}.
\manEnd
\end
