\input manualMacros.tex
\manBegin
\manPageInfo{RCCL Reference Manual}{}{}
\manTitle{makePosition}{3}
\manSection{NAME}
{\rightskip=0ptplus1fil
{\tt \manName{makePosition}}
-- RCCL routine to define position equations.
}
\manSection{USAGE}
\cverbatim
#include <rccl.h>

POS *makePosition (name, L1 [, Lm] ... , `EQ',
                   R1 [, Rn] ... [, `TL', tl] , NULL)
  const char *name;
  TRSF *L1, ... *Lm, *R1, ... *Rn, *tl; @endcverbatim
\manSection{ARGUMENTS}
\manItem{{\tt name} --}
Name of the position. This argument is optional, and may be
given as {\tt NULL}.
\manItem{{\tt L1} \dots {\tt Lm} --}
Transforms comprising the left-hand (clockwise) side of the equation.
\manItem{{\tt R1} \dots {\tt Rm} --}
Transforms comprising the right-hand (counterclockwise) side of the equation.
\manItem{{\tt EQ} --}
Keyword denoting the ``equal'' sign in the equation.
\manItem{{\tt T6}, {\tt TRANS} --}
Keywords denoting a manipulator T6 transform. This
is the
transform that must be solved for when this position is used
to specify the target of a manipulator motion. This keyword is optional.
\manItem{{\tt TL} --}
Keyword denoting the TOOL frame of the equation, applicable only to positions
which contain a T6 transform. This keyword is
optional; if omitted, the TOOL frame will be set equal to the T6 frame.
\manSection{RESTRICTIONS}
This routine must be called from the planning level.
\manSection{DESCRIPTION}
{\tt makePosition()} builds a position equation out of a
set of transforms. It allocates space
for, and returns a pointer to, a structure describing the 
transform equation specified by the argument list. This
equation is of the form 
\manIfTeX
$$
{\rm L}\sb 1 \ldots {\rm L}\sb m = {\rm R}\sb 1 \ldots {\rm R}\sb n
$$
\manElse
\cverbatim
     L_1 ... L_m = R_1 ... R_n
@endcverbatim
\manFi
where ${\rm L}\sb i$ are the transformations on the left-hand side, and
${\rm R}\sb i$ are the transformations on the right-hand side.
The position of the equal sign is denoted by placing the
predefined keyword {\tt EQ} in the argument list at the
appropriate point, and the argument list is terminated
with a {\tt NULL} pointer. If the resulting equation is represented as
a directed circular graph, then the transforms on the left-hand side 
are assumed to be directed {\it clockwise\/} and those on the
right-hand side are directed {\it counterclockwise\/}.

The first argument to {\tt makePosition()} may be used to give the
position equation a name. This can be used, in conjunction with the routine
{\tt getPostionByName()}, to get a pointer to the position from another
part of the program.

All of the transforms which comprise the position equation must be allocated
using one of the {\tt allocTrans()} routines. There is no real limit
on the number of terms that an equation may contain, although a 
``sanity check'' limit of 100 is currently imposed.

If a position equation is used to specify the target of a motion request,
then it must also contain a T6 transform. This can
be specified by placing either of the two synomymous
keywords {\tt T6} or {\tt TRANS} at the appropriate place in the argument
list.

When used to specified the target of a manipulator motion, the
trajectory generator will resolve the position equation into the
following canonical form:
\manIfTeX
$$
{\rm T6} \; {\rm TOOL} \;=\; {\rm COORD}
$$
\manElse
\cverbatim
     T6 TOOL = COORD
@endcverbatim
\manFi
TOOL defines the transform (or set of transforms) that 
lie between T6 and the manipulator TOOL frame. 
This is the frame, which, among other things,
the trajectory generator uses when computing a Cartesian
straight line motion to the target.

By default, {\tt makePosition()} sets the TOOL frame to be the same
as the T6 frame (i.e., it assumes that ${\rm TOOL} = {\rm I}$).
Specifying a different TOOL frame can be done by placing 
two more arguments at the end of the routine call: the
special argument {\tt TL}, followed by a pointer to whichever transform
(already listed in the equation definition) immediately preceeds
the TOOL frame.
The TOOL component of the equation is then taken to be the
product of this transform, plus all others leading back
to the T6 transform. If the transform indicated by
{\tt TL} occurs more than once in the equation definition, then the
one closest to T6 defines the TOOL frame.
If {\tt TL} is followed by the special argument {\tt T6}, then
the TOOL frame is assumed to be equivalent to the T6 frame, as in
the default case.

When a call to {\tt makePosition()} contains a {\tt TL} tool specification
at the end, the final {\tt NULL} argument may be omitted.

A position equation allocated with {\tt makePosition()} is a global
memory object and can be accessed from any part of the RCCL program using
{\tt getPositionByName()} or {\tt getPositionByAddr()}.
If referenced from a different CPU, it will generally be necessary
to build a local copy of it (using {\tt copyPosition()}) before it
can be used with other routines.
It is possible to solve for
individual transforms or components of a position equation
by using the routines {\tt solveTrans()}, {\tt solveChain()},
and {\tt solveInvChain()}.

\manSection{DIAGNOSTICS}
This routine returns {\tt NULL} 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 ESyntax} --}
Syntax error in the position specification.
\manItem{{\tt EDuplicate} --}
Another position equation already exists with the same name.
\manItem{{\tt EMemory} --}
Out of program memory.
\manItem{{\tt ETooMany} --}
Too many transforms specified in the equation. This limit is defined by the
parameter {\tt MAX_TERMS} in the source file for {\tt makePosition()}; at the
time of this writing, {\tt MAX_TERMS} is set to 100. The reason for putting
this limit on is to trap cases where delimiter keywords are
accidentally omitted.
\manItem{{\tt EDescriptor} --}
One of the specified transforms was not allocated using
one of the {\tt allocTrans()} routines.
This error can also occur when the function 
call is not properly terminated with a
{\tt NULL} or {\tt TL} sequence.

The routine will abort the program if called from the control level.
\manSection{BUGS}
The format for the loop equation is not very general. It might be
nice to be able to specify ``special'' frames (like the TOOL frame)
more easily.
\manSection{SEE ALSO}
\rightskip=0ptplus1fil
{\tt copyPosition(3)}, {\tt solveTrans(3)},
{\tt allocTrans(3)}, {\tt allocTransXyz(3)}, {\tt rcclSetOptions(3)}, 
{\tt errorStack(3)}.
\manEnd
\end
