\input manualMacros.tex
\manBegin
\manPageInfo{RCCL Reference Manual}{}{}
\manTitle{waitForStop}{3}
\manSection{NAME}
{\rightskip=0ptplus1fil
{\tt \manName{waitForStop}},
{\tt \manName{waitForStart}},
{\tt \manName{waitForCompleted}}
-- syncronize with RCCL motion requests.
}
\manSection{USAGE}
\cverbatim
waitForStop(mid)
  int mid;

waitForStart(mid)
  int mid; 

waitForCompleted(mnp)
  MANIP *mnp; 
@endcverbatim
\manSection{ARGUMENTS}
\manItem{{\tt mid} --}
Motion ID (returned by the motion request primitive).
\manItem{{\tt mnp} --}
Manipulator reference structure.
\manSection{RESTRICTIONS}
These primitives should probably not be called from the control level
(although it is legal to do so) because if they block for any appreciable
length of time the control level will timeout. An ``appreciable length
of time'' would be any time greater than the trajectory
generator sample interval.
\manSection{DESCRIPTION}
These functions allow an RCCL
program to wait for motion requests to start or complete. 

{\tt waitForStop()} waits until the motion request associated with
the specified motion ID has terminated.
A {\it stop code} that provides information about the conditions
under which the motion terminated may be obtained using {\tt motionStopCode()}
(q.v.). Typical values for the stop code are {\tt ON_NORMAL} (normal
completion as planned) or {\tt ON_ABORT} (motion was aborted).

{\tt waitForStart()} waits until the motion request associated with
the specified motion ID has started executing.
A {\it start code} that provides information about the conditions
under which the motion started may be obtained using {\tt motionStartCode()}
(q.v.). The usual value for the start code is {\tt ON_NORMAL}.

The motion ID used by the above tests is returned by the primitive
that requested the motion (e.g., {\tt move()} or {\tt stop()}).
Normally, motion IDs are assigned by the system and 
are recycled after {\tt NUM_SYSMFLAGS}
motion requests. To avoid recycling, an explicit ID may be assigned to a 
motion by calling the primitive 
{\tt setMotionFlag()} before the motion request is made.

{\tt waitForCompleted()} waits until all motion requests for a
particular manipulator have completed, and the transition concluding
the last motion has finished.

These routines are implemented as macros. If called from the planning
level, they will call {\tt rcclBlock()} before performing their
condition check.
\manSection{DIAGNOSTICS}
Because these primitives are currently implemented as macros they
do not directly return a proper error status. However, an error will cause
them to automatically abort the program if the option {\tt RCCL_ERROR_EXIT}
is set (see {\tt rcclSetOptions(3)}). They will also
place error codes and messages on the {\it errorStack} (q.v.). 

Error codes set by {\tt waitForStop()} or {\tt waitForStart()} include:

\manItem{{\tt EDescriptor} --}
The motion ID is either invalid or out of date.

No errors are currently implemented for {\tt waitForCompleted()}.
\manSection{SEE ALSO}
\rightskip=0ptplus1fil
{\tt move(3)}, {\tt stop(3)}, {\tt motionStatus(3)}, 
{\tt setMotionFlag(3)},
{\tt rcclSetOptions(3)}, {\tt errorStack(3)}.
\manEnd
\end
