\input manualMacros.tex
\manBegin
\manPageInfo{RCCL Reference Manual}{}{}
\manTitle{motionStatus}{3}
\manSection{NAME}
{\rightskip=0ptplus1fil
{\tt \manName{motionStatus}},
{\tt \manName{motionStopCode}},
{\tt \manName{motionStartCode}},
{\tt \manName{motionScale}},
{\tt \manName{getActiveMotionId}}
-- obtain status information for an RCCL motion request.

}
\manSection{USAGE}
\cverbatim
motionStatus (mid)
  int mid;

motionStopCode (mid)
  int mid;

motionStartCode (mid)
  int mid;

float motionScale (mid)
  int mid; 

getActiveMotionId (mnp)
  MANIP *mnp; @endcverbatim
\manSection{ARGUMENTS}
\manItem{{\tt mid} --}
Motion ID. This is the number returned by a motion request
(such as {\tt move()} or {\tt stop()}). This number is normally
assigned automatically by the system, but can be
specified explicitly using {\tt setMotionFlag()}.
\manItem{{\tt mnp} --}
Manipulator reference structure.
\manSection{DESCRIPTION}
These routines return information about a particular motion or stop
request. 

{\tt motionStatus()} returns the status of the motion request. The status
values, defined in {\tt <rccl.h>}, include:

\manItem{{\tt M_PENDING} --}
Request is on the queue.
\manItem{{\tt M_RUNNING} --}
Request is being serviced.
\manItem{{\tt M_PAUSED} --}
Request has been paused.
\manItem{{\tt M_FINISHED} --}
Request has finished.

{\tt motionStopCode()} returns the completion code that is set for
the motion when it finishes. System supplied completion codes,
defined in {\tt <rccl.h>}, include:

\manItem{{\tt ON_NORMAL} --}
Normal completion.
\manItem{{\tt ON_ABORT} --}
Motion was aborted while it was still on the queue.
\manItem{{\tt ON_FORCE} --}
Motion was stopped by hitting a force limit (not currently used).
\manItem{{\tt ON_DISP} --}
Motion was stopped by hitting a displacement limit (not currently
used).

{\tt UNDEF} will be returned if the motion has not yet finished.
Other codes can be specified if the motion is terminated by the application
(such as with {\tt stopMotion()}).

{\tt motionStartCode()} returns the start code that is set when a motion
begins executing. System supplied start codes,
defined in {\tt <rccl.h>}, include:

\manItem{{\tt ON_NORMAL} --}
Normal motion start.

{\tt UNDEF} will be returned if the motion has not yet started.
Other codes can be specified if the application uses {\tt startMotion()}.

{\tt motionScale()} returns a scale parameter which varies linearly
with time from 0.0 to 1.0 as the motion proceeds from start to completion.
Because of the way RCCL blends together adjacent motions,
the scale value will normally be slightly negative at the very
beginning of the motion. This is because the trajectory generator begins to
pre-evaluate the motion path {\it before} the nominal starting time.

{\tt getActiveMotionId()} returns the ID of whatever motion is
currently being executed on
a particular manipulator, or {\tt UNDEF} if the manipulator is
not currently executing any motion.

The system has {\tt NUM_SYSMFLAGS} motion flags available for automatic
assignment to motion requests. When it runs out of flags, it reuses them,
starting with the one least recently assigned.
As an alternative to this, the program can explicitly specify a
motion ID ahead of time using {\tt setMotionFlag()}. 

\manSection{DIAGNOSTICS}
These routines return {\tt MSTAT_ERROR} in the event of an error
(which is converted to a float in the case of {\tt motionScale()}).
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 stop(3)}, {\tt waitForStop(3)}, 
{\tt stopMotion(3)}, {\tt startMotion(3)}, {\tt setMotionFlag(3)},
{\tt rcclSetOptions(3)}, {\tt errorStack(3)}.
\manEnd
\end
