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

mid = stop (mnp, sigma)
  MANIP *mnp;
  float sigma;
@endcverbatim
\manSection{ARGUMENTS}
\manItem{{\tt mnp} --}
Manipulator reference structure.
\manItem{{\tt sigma} --}
Length of time the manipulator is to be stopped for (milliseconds).
\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 stop()}.
\manSection{RESTRICTIONS}
This routine must be called from the planning level.
\manSection{DESCRIPTION}
The {\it stop} primitive
queues a request to stop the manipulator at the target position of the
previously specified motion,
for a length of time {\tt sigma}.
Ordinarily, the stop request call returns
immediately, before the stop has actually happened. 
The call will block
only if the motion queue for that manipulator is full
(see {\tt setMotionQueueSize(3)}).

If {\tt sigma} is given as {\tt F_DEFAULT}, then the system checks
to see if an explicit motion time has been specified by {\tt setTime()} since
the manipulator's last motion request. If so, this value is used
for the stop time.
If not, then a stop time of 0 milliseconds is assumed.
If {\tt sigma} is given as {\tt F_UNDEF}, then a stop of indefinite
duration will be generated; such a stop request will have to terminated
explicitly using a routine such as {\tt stopMotion()}.
Other values of {\tt sigma} which are less than 0 will cause an error.

In RCCL, stopping is accomplished (internally) by simply issuing another
motion request to the previously specified position (according to the same
paradigm described in Richard Paul's book).
When a manipulator is ``stopped'' at a target position, and that target is
changing 
in time (as a result of its containing variable transforms or joint
biases), then the manipulator will 
continue to {\it track} the position. Stopping
at a position, therefore, does not necessarily mean that the manipulator
will come to rest.

Stop requests are implemented as motion requests:
the returned motion ID value can be used to obtain status information
about the motion (see {\tt motionStatus(3)}), terminate it
(see {\tt stopMotion(3)}), or wait for it to start or stop
(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.
\manItem{{\tt ERange} --}
The indicated stop time was negative.

The routine will abort the program if called from the control level.
\manSection{SEE ALSO}
\rightskip=0ptplus1fil
{\tt rcclCreate(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
