\input manualMacros.tex
\manBegin
\manPageInfo{RCCL Reference Manual}{}{}
\manTitle{rcclPause}{3}
\manSection{NAME}
{\rightskip=0ptplus1fil
{\tt \manName{rcclPause}},
{\tt \manName{rcclResume}},
{\tt \manName{rcclIsPaused}},
{\tt \manName{rcclWasPaused}}
-- pause and resume RCCL motions.

}
\manSection{USAGE}
\cverbatim
rcclPause (atime, ptime)
  float atime, ptime;

rcclResume()

rcclIsPaused()

rcclWasPaused()
@endcverbatim
\manSection{ARGUMENTS}
\manItem{{\tt ptime} --}
Length of time motions are to be paused for (in milliseconds).
Specifying this as {\tt F_UNDEF} causes a pause of indefinite duration.
\manItem{{\tt atime} --}
Length of time allocated for slowing motions down and starting
them up again. Specifying this as {\tt F_DEFAULT} causes
the default acceleration times to be used.
\manSection{DESCRIPTION}
These routines allow RCCL manipulator motions to be
suspended and resumed. 

{\tt rcclPause()} suspends all current RCCL manipulator motions, for
{\tt ptime} milliseconds.
If {\tt ptime} is equal to {\tt F_UNDEF}, then
the motions will pause indefinitely until {\tt rcclResume()} is
called. Other negative values of 
{\tt ptime} will cause an error.
The deceleration/acceleration times for slowing down the manipulators
and starting them up again can be specified with
{\tt atime}. 
If {\tt atime} is equal to {\tt F_DEFAULT},
then the default motion transition times
will be used.

{\tt rcclResume()} causes the RCCL motions to start up again, regardless of
whether or not the time limit (if any) specified by {\tt ptime} has
expired. This routine has no effect if the system is not paused.

When the system is paused, the RCCL system time (returned by
{\tt rcclSysTime()}) is frozen. Monitor or transform
functions explicitly associated with a motion are also suspended
(i.e., those established using {\tt runMotionFxn()} or
{\tt transMotionEval()}). Other monitor or transform functions
will continue to execute (i.e., those established with
{\tt runMonitorFxn()} or {\tt transEval()}). Care should be taken
to implement such functions so that they
do not continue to modify manipulator setpoints while the system
is paused,
since this may cause the robot to jump when resumed.
The following predicate functions are intended to help facilitate
this:

{\tt rcclIsPaused()} returns true if the system is currently paused.

{\tt rcclWasPaused()} returns true if the system was in a paused
state during the last control cycle.

\manSection{DIAGNOSTICS}
{\tt rcclPause()} 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 EBusy} --}
The system is already paused.
\manItem{{\tt ERange} --}
An illegal pause or transition time value was given.

No errors are currently implemented for {\tt rcclResume()}, 
{\tt rcclIsPaused()}, or {\tt rcclWasPaused()}.
\manSection{SEE ALSO}
\rightskip=0ptplus1fil
{\tt stopCurrentMotion(3)}, {\tt flushMotions(3)},
{\tt rcclSetOptions(3)}, {\tt errorStack(3)}.
\manEnd
\end

