\input manualMacros.tex
\manBegin
\manPageInfo{RCI Reference Manual}{}{}
\manTitle{getRobotPosition}{3}
\manSection{NAME}
{\rightskip=0ptplus1fil
{\tt \manName{getRobotPosition}}
-- RCI database routine to get robot joint position.
}
\manSection{USAGE}
\cverbatim
getRobotPosition (angles, posName, robotName)
  float *angles;
  const char *posName;
  const char *robotName; @endcverbatim
\manSection{ARGUMENTS}
\manItem{{\tt angles} --}
Array to return the joint angles in. Angles are returned in radians.
\manItem{{\tt posName} --}
Name of the position. The name should be a string of
alphanumerics (including underscores and dollar signs) that does not begin
with a digit.
\manItem{{\tt robotName} --}
Name of the robot. The name should be a string of
alphanumerics (including underscores and dollar signs) that does not begin
with a digit.
\manSection{RESTRICTIONS}
This routine must be called from the planning level.
\manSection{DESCRIPTION}
This routines searches a database file in the directory 
{\filefont \$RCCL/conf} for a joint angle position with the
indicated name defined for the specified robot. The routine returns
the number of robot joints 
if the position was found, {\tt 0} if it was not, and {\tt -1} if an error
occured.

There is a separate position database file for each robot, with
the name {\tt <robotName>.pos}. Entries in the file
look like:
\cverbatim
pos1    90.0    90.0    0.0     0.0     45.0    28.0
pos2    90.0     0.0  -90.0     0.0     60.0  -180.0
                .               .
                .               .
@endcverbatim
The angles are described in degrees, although the routine will return them in
radians. No conversion is applied to prismatic joints.

{\tt getRobotPosition()} consults the robot's {\tt JLS} structure (q.v.)
to determine how many joints the robot has, and which (if any) are prismatic.
This means that the robot must be known to the RCI system.
\manSection{DIAGNOSTICS}
The routine returns {\tt -1} in the event of error, or will force an exit if
{\tt EXIT_ON_ERROR} has been set (see {\tt rciSetOptions(3)}).
Error information is returned on the {\it errorStack} (q.v.). Error codes can
be examined with the routine {\tt getErrorCode()}.

Error codes include:

\manItem{{\tt EEnviron} --}
The environment variable {\TT RCCL} is not set.
\manItem{{\tt EBadAccess} --}
Can't access either the position database file or the robot's
{\tt JLS} data structure.
\manItem{{\tt EBadObj} --}
Position file is malformed.
\manItem{{\tt EMemory} --}
Program is out of memory.

The routine will abort the program if called from the control level.
\manSection{SEE ALSO}
\rightskip=0ptplus1fil
{\tt JLS}, {\tt rcclSetOptions(3)}, {\tt errorStack(3)}.
\manEnd
\end

