\input manualMacros.tex
\manBegin
\manPageInfo{RCCL Reference Manual}{}{}
\manTitle{rcclCreate}{3}
\manSection{NAME}
{\rightskip=0ptplus1fil
{\tt \manName{rcclCreate}},
{\tt \manName{rcclDelete}}
-- RCCL routines for attaching and detaching manipulators.
}
\manSection{USAGE}
\cverbatim
#include <rccl.h>

MANIP *rcclCreate(name, cpuMask)
  const char *name;
  unsigned long cpuMask;

rcclDelete (mnp)
  MANIP *mnp; @endcverbatim
\manSection{ARGUMENTS}
\manItem{{\tt name} --}
Name of the manipulator to be attached. 
\manItem{{\tt cpuMask} --}
A bitmask describing which CPUs the system may use in selecting a
CPU to run the manipulator's trajectory generator. If this
argument is {\tt 0}, then the system will choose the CPU itself.
\manItem{{\tt mnp} --}
Pointer to the {\tt MANIP} structure returned by {\tt rcclCreate()}.
\manSection{RESTRICTIONS}
These routines must be called from the planning level, and the 
trajectory generator must not be running.
\manSection{DESCRIPTION}
These routines create and delete manipulator objects within
an RCCL program.

{\tt rcclCreate()} creates a manipulator object for the named
robot, and establishes a trajectory generator for it
on one of the CPUs specified by {\tt cpuMask}. If {\tt cpuMask} is 0,
then the CPU is chosen arbitrarily by the system, using the set of
available CPUs.
The set of available CPUs is given by the {\tt RCCL} parameter 
{\tt cpus} in the {\tt .rciparams} file (see {\tt RCCL_params(5)}).
If {\tt cpuMask} is not {\tt 0}, then it is logically ``anded'' with the 
set of available CPUs to determine those that the system may choose from.
{\tt rcclCreate()} returns a pointer to a manipulator structure 
(see {\tt MANIP(3)}).
Subsequent commands issued to
the manipulator will use this pointer for reference.

If the {\tt name} given to {\tt rcclCreate()} does not match the name of a
robot configured into the RCI system, then a {\it virtual
manipulator} is created. This is
a coordinate frame in space, with no robot attached,
that is controlled by the trajectory
generator and can be moved around
with RCCL motion primitives. The trajectory generator simply skips the
robot kinematic and communication steps. Because a
virtual manipulator has no
joint-level 
interpretation, some motion commands are undefined with respect to it
(such as {\tt setMod()} or {\tt movej()}).

A manipulator may be deleted with the command {\tt rcclDelete()}.

{\tt rcclCreate()} and {\tt rcclDelete()} cannot be called
while the trajectory generator is active.
The trajectory generator is activated with the command {\tt rcclStart()},
and is deactivated with the command {\tt rcclRelease()}. 

\manSection{DIAGNOSTICS}
{\tt rcclCreate()} returns {\tt NULL}, and
{\tt rcclDelete()} returns {\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 ETaskActive} --}
RCCL trajectory generator is running.
\manItem{{\tt EInternal} --}
Unexpected internal software or communication failure.

{\tt rcclCreate()} may also set the following (warning:
this list may be incomplete):

\manItem{{\tt EDuplicate} --}
A manipulator with the same name already exists.
\manItem{{\tt EAuxHalted} --}
One of the auxiliary CPUs is in a halted state; probably in console mode.
\manItem{{\tt ENotAvail} --}
None of the requested CPUs are available.
\manItem{{\tt EEnviron} --}
Environment variable {\tt RCCL} not set.
\manItem{{\tt EMemory} --}
System is out of memory, on either the arbiter CPU or on one of the
auxiliaries.

These routines will abort the program if called from the control level.
\manSection{SEE ALSO}
\rightskip=0ptplus1fil
{\tt MANIP(3)}, {\tt rcclStart(3)}, {\tt rcclSetInterval(3)}, 
{\tt RCCL_params(5)}.
\manEnd
\end
