\input manualMacros.tex
\manBegin
\manPageInfo{RCCL Reference Manual}{}{}
\manTitle{copyPosition}{3}
\manSection{NAME}
{\rightskip=0ptplus1fil
{\tt \manName{getPositionByName}},
{\tt \manName{getPositionByAddr}},
{\tt \manName{copyPosition}},
{\tt \manName{freePosition}}
-- RCCL position equation support routines.

}
\manSection{USAGE}
\cverbatim
#include <rccl.h>

POS *getPositionByName (name)
  const char *name;

POS *getPositionByAddr (addr)
  POS *addr;

POS *copyPosition (pos)
  POS *pos;

freePosition (pos)
  POS *pos;  @endcverbatim
\manSection{ARGUMENTS}
\manItem{{\tt name} --}
Name of a position equation.
\manItem{{\tt addr} --}
Planning level address of (i.e., pointer to) a position equation.
\manItem{{\tt pos} --}
Pointer to a position equation.
\manSection{RESTRICTIONS}
{\tt freePosition()} must be called from the planning level if
the position being freed was created using {\tt makePosition()}.
{\tt freePosition()} must otherwise be called from the same CPU
as the position was allocated on.
\manSection{DESCRIPTION}
These routines are used to locate and copy position equations from
any part of an RCCL program.

{\tt getPositionByName()} finds the local pointer for 
a global position equation, using its
{\tt name} as a key. 
Global positions are those created using
{\tt makePosition()} in the planning CPU. 
Before using
this position, it may be necessary
to use {\tt copyPosition()} to make a local copy
whose internal structure is valid for the current
CPU (see below).

{\tt getPositionByAddr()} finds the local pointer for 
a global position equation, using its
planning level pointer value {\tt addr} as a key. 
Global positions are those created using
{\tt makePosition()} in the planning CPU.
Before using
this position, it may be necessary
to use {\tt copyPosition()} to make a local copy
whose internal structure is valid for the current
CPU (see below).

{\tt copyPosition()} creates a local copy of a position equation.
Only the equation structure and the term pointers are copied; the transforms
themselves are not. This position equation is {\bf not} global, {\it i.e.},
it cannot be assigned a name or
accessed with the above primitives.

The main use of {\tt copyPosition()} is to {\it re-reference} a position
equation. If we have a local pointer to a position equation
{\tt p0} which was defined by the planning level (using {\tt makePosition()}),
the internal structure of {\tt p0} may not
be valid  because the pointers are defined for
the planning level context. {\tt copyPosition()} will use {\tt p0} to
create a private copy of the equation where the internal structure
is correct. A typical way of getting and using a position equation
from the control level could look like:
\cverbatim
        p0 = getPositionByName ("name");
        p1 = copyPosition (p0); 
@endcverbatim

{\tt freePosition()} deletes a position equation created by
either {\tt makePosition()} or {\tt copyPosition()}, 
and frees the associated memory. The transforms referenced by
the position equation are {\bf not} deleted. {\tt freePosition()}
should be called from the same CPU as the one which created
the position, and if the position was created using {\tt makePosition()},
then it may be called from the planning task only. 

\manSection{DIAGNOSTICS}

{\tt copyPosition()} returns {\tt NULL} if no memory is available
to build the equation. 
It will abort the program if it cannot reference the transforms contained in
the original equation. 

{\tt getPositionByName()} returns {\tt NULL} if it doesn't find anything.

{\tt getPositionByAddr()} returns {\tt NULL} if it doesn't find anything.

{\tt freePosition()} {\it tries} to return {\tt -1} if the indicated position
is not valid or cannot be freed because it was allocated somewhere else.

\manSection{SEE ALSO}
\rightskip=0ptplus1fil
{\tt makePosition(3)}, 
{\tt allocTrans(3)}, {\tt solveTrans(3)}, 
{\tt allocTransXyz(3)}, {\tt rcclSetOptions(3)}.
\manEnd
\end
