\input manualMacros.tex
\manBegin
\manPageInfo{RCCL Reference Manual}{}{}
\manTitle{maintain}{3}
\manSection{NAME}
{\rightskip=0ptplus1fil
{\tt \manName{maintain}}
-- RCCL routine to ``place'' a virtual manipulator.
} 
\manSection{USAGE}
\cverbatim
mid = maintain (mnp, pos)
  MANIP *mnp;
  POS *pos;
@endcverbatim
\manSection{ARGUMENTS}
\manItem{{\tt mnp} --}
Manipulator reference structure.
\manItem{{\tt pos} --}
Target position to be maintained.
\manItem{{\tt mid} --}
Motion ID, used to control the maintain request or query its status.
\manSection{RESTRICTIONS}
This routine must be called from the planning level, and may be used
for virtual manipulators only.
\manSection{DESCRIPTION}
This routine ``puts'' a virtual manipulator {\it at} the specified target
position immediately, and keeps it there (tracking the target position)
until some other motion request is made on the manipulator. 
{\tt maintain()} does not ``drive'' the manipulator to
the target position the way {\tt move()} does.

The transition time associated with a {\tt maintain()} request is
normally set to 0, unless previously set with {\tt setTime()}.

A {\it maintain} request is a motion request like any other:
the returned motion ID value can be used to obtain status information
about the motion (see {\tt motionStatus(3)}), or terminate it
(see {\tt stopMotion(3)}). A motion ID can be explicitly
set ahead of time 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 ENotDefined} --}
{\tt maintain()} was called on a real robot.
\manItem{{\tt ENoSpace} --}
The motion queue does not have enough space to store the requested motion
request (NOTE: this can occur idependently of the motion queue size,
which is the number of requests that can be put on the queue at any one
time. That is because the size of a motion request is not fixed).

The routine will abort the program if called from the control level.
\manSection{SEE ALSO}
\rightskip=0ptplus1fil
{\tt rcclCreate(3)}, {\tt makePosition(3)}, {\tt stop(3)},
{\tt setMotionFlag(3)}, {\tt setTime(3)},
{\tt waitForMotion(3)}, {\tt motionStatus(3)}, {\tt stopMotion(3)}, 
{\tt setMotionQueueSize(3)}, {\tt rcclSetOptions(3)}, {\tt setMotionHold(3)},
{\tt errorStack(3)}.
\manEnd
\end
