\input manualMacros.tex
\manBegin
\manPageInfo{RCCL Reference Manual}{}{}
\manTitle{stopMotion}{3}
\manSection{NAME}
{\rightskip=0ptplus1fil
{\tt \manName{stopMotion}},
{\tt \manName{startMotion}}
-- cancel an RCCL motion or control its start time.

}
\manSection{USAGE}
\cverbatim
stopMotion (mid, stopCode)
  int mid;
  int stopCode;

startMotion (mid, startCode)
  int mid;
  int startCode;
@endcverbatim
\manSection{ARGUMENTS}
\manItem{{\tt mid} --}
Motion ID. This is a number returned by the motion request primitive.
Its value is either
assigned automatically, or specified explicitly
by the program with {\tt setMotionFlag()} 
before the request is issued.
\manItem{{\tt stopCode} --}
Code value indicating why the motion was cancelled.
Considered to be undefined if less than 0.
\manItem{{\tt startCode} --}
Code value indicating conditions under which the motion was started.
Considered to be undefined if less than 0.
\manSection{DESCRIPTION}
These routines provide the ability to cancel RCCL motions,
or control when they start. A motion is referenced
using the ID value returned by the primitive that originally requested 
the motion.

{\tt stopMotion()} cancels a motion.
The motion's stop code is set to {\tt stopCode}, unless
{\tt stopCode} is undefined (less than 0), in which case the stop
code is set to {\tt ON_ABORT}. The stop code can later
be referenced with the primitive {\tt motionStopCode()}.
If the cancelled motion is still on the motion queue, it will simply
be removed from
the queue. If it is currently executing, it will be aborted. If the
motion has already completed, the old stop code is
overwritten with the new stop code.

{\tt startMotion()} gives permission for a motion to start.
This is necessary only for motions whose requests have been 
preceded by the primitive {\tt setMotionHold()}; otherwise, the
motion request will automatically give start permission to the motion
and assign it the start code {\tt ON_NORMAL}.
{\tt startMotion()} assigns the motion a 
start code given by the value in {\tt startCode}. 
If {\tt startCode}
is undefined (less than 0), then the start code is set to
{\tt ON_NORMAL}.
The start code 
can later be referenced with the primitive {\tt motionStartCode()}.
{\tt startMotion()} can be called any time after a motion request has
been issued. If {\tt startMotion()} is called for a motion that has 
already been given
start permission, the old start code is overwritten
with the new start code.

\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} --}
A motion ID was specified that was either illegal or no longer valid.

\manSection{SEE ALSO}
\rightskip=0ptplus1fil
{\tt move(3)}, {\tt motionStatus(3)},
{\tt setMotionHold(3)}, 
{\tt setMotionFlag(3)}, 
{\tt rcclSetOptions(3)}, {\tt errorStack(3)}.
\manEnd
\end

