\input manualMacros.tex
\manBegin
\manPageInfo{RCI Reference Manual}{}{}
\manTitle{rciAttachRobot}{3}
\manSection{NAME}
{\rightskip=0ptplus1fil
{\tt \manName{rciAttachRobot}},
{\tt \manName{rciDetachRobot}}
-- attach a robot to an RCI task.
}
\manSection{USAGE}
\cverbatim
#include <rci.h>

num = rciAttachRobot (td, name, rdev)
   int num;
   RCI_DESC *td;
   const char *name;
   struct devAddr *rdev;

rciDetachRobot (td, num)
   RCI_DESC *td;
   int num;
@endcverbatim
\manSection{ARGUMENTS}
\manItem{{\tt td} --}
Pointer to task descriptor.
\manItem{{\tt name} --}
Name of the robot to attach to.
\manItem{{\tt rdev} --}
Optional address spec. for robot interface device.
\manItem{{\tt num} --}
Index of the robot within the task.
\manSection{RESTRICTIONS}
These routines must be called from the planning level.
\manSection{DESCRIPTION}
Robots may be attached to an RCI control task. {\it Attaching}
entails allocating the various data structures and the physical
interface required to control and interface to that robot. 
Once this is done, the control task is able to communicate with the
robot using these data structures in conjunction with the 
robot interface functions (see {\tt robotComfxns(7)}). 

{\tt rciAttachRobot()} attaches the named robot to an RCI task: 
it allocates and initializes the robot
parameter blocks ({\tt JLS} and {\tt KYN} structures, etc.) and
makes them accessible to the system; it locates the appropriate
robot interface functions, and it sets up an I/O device for the
robot. The memory for the parameter blocks is allocated on the 
CPU bearing the control task.

The argument {\TT rdev}, if not {\tt NULL}, is used to specify the
name and address of the interface device to be
used by the robot. If this argument is not present, then this information
is taken from the {\TT device} and {\TT address} keywords associated
with the named robot in
the system file {\filefont \$RCCL\-/conf\-/robots}. For a description of
the {\tt devAddr} structure, see {\tt rciAllocDevice(3)}.

If successful, the function returns a small integer
which indexes the robot within the task.
The index number can be used to obtain a pointer to the
{\tt RCI_RBT} structure (q.v.), which is the handle for all operations
concerning that robot; this is done with the macro {\tt TASKROBOT(td, num)}.
The maximum number of robots that can be attached
to an RCI task is {\tt MAX_TASKROBOTS}. The number of robots
attached at any particular time is given by the macro 
{\tt TASKNUMROBOTS(td)}.

In order for an {\tt rciAttachRobot()} to succeed, the following
conditions must be true: the robot must not be attached to any other
RCI task and must not be locked by another RCI program
(locks are implemented using lock files in the directory
{\filefont \$RCCL/lock}).
The robot
must be known to the system, which means that the system must be
able to obtain interface functions and a {\tt JLS} structure for it.
The robot must also be defined in the configuration file
{\filefont \$RCCL\-/conf\-/robots}, which must define an I/O device and address
for the robot. Optional arguments for the
device driver may also be declared in the configuration file.
The configuration file may 
also specify an interrupt device for use by tasks which run on the
arbiter CPU. If an interrupt device is specified, then it is opened and the
returned file descriptor is placed in the {\tt idev} field of the {\tt
RCI_RBT} structure (this field is otherwise set to {\tt UNDEF}).

The function {\tt rciDetachRobot()} removes the robot from the 
task and frees up the data structures for later use.

\manSection{DIAGNOSTICS}
The functions return {\tt -1} in the event of failure.
Error information is reported on the
{\it errorStack} (q.v.). Returned error codes are accessible with 
{\tt getErrorCode()}.
\medskip

Errors specific to {\tt rciAttachRobot()} include:

\manItem{{\tt ETooMany} --}
The number of robots attached to the task is already {\tt MAX_\-TASK\-ROBOTS}.
\manItem{{\tt EBusy} --}
The robot or its interface device has been allocated
by another RCI task (in the current program
or another one).
\manItem{{\tt ENotDefined} --}
Specified robot is unknown to the system, or the robot device
is not completely specified or is incorrect.
\manItem{{\tt ENoIntrDev} --}
The interrupt device specification in {\filefont \$RCCL/conf/robots}
is incorrect or incomplete.
\manItem{{\tt EBadAccess} --}
Can't open lock file, the support file {\filefont \$RCCL/conf/robots},
or the interrupt device.
\manItem{{\tt EBadObj} --}
Malformed or corrupted support file in {\filefont \$RCCL/conf/robots}.
\manItem{{\tt EBadFxn} --}
Support function used in accessing robot data base is missing.
\manItem{{\tt EMemory} --}
System is out of memory on either the planning CPU or one of the
auxiliary CPUs.

Errors specific to {\tt rciDetachRobot()} include:

\manItem{{\tt EDescriptor} --}
Specified robot not attached to task.

Errors common to both routines include:

\manItem{{\tt ETaskActive} --}
The task is currently active.
\manItem{{\tt EInternal} --}
Unexpected internal software error or loss of communication between
processors.

These routines will abort the program if called from the control level.
\manSection{SEE ALSO}
\rightskip=0ptplus1fil
{\tt robotComfxns(7)}, {\tt rciAllocDevice(3)}, {\tt TASKROBOT(3)}, {\tt
RCI_RBT(3)}. 

\manEnd
\end
