copyPosition(3)

NAME
getPositionByName, getPositionByAddr, copyPosition, freePosition -- RCCL position equation support routines.

USAGE
#include <rccl.h>

POS *getPositionByName (name)
  const char *name;

POS *getPositionByAddr (addr)
  POS *addr;

POS *copyPosition (pos)
  POS *pos;

freePosition (pos)
  POS *pos;

ARGUMENTS

name --
    Name of a position equation.

addr --
    Planning level address of (i.e., pointer to) a position equation.

pos --
    Pointer to a position equation.

RESTRICTIONS
freePosition() must be called from the planning level if the position being freed was created using makePosition(). freePosition() must otherwise be called from the same CPU as the position was allocated on.

DESCRIPTION
These routines are used to locate and copy position equations from any part of an RCCL program.

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

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

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 not global, i.e., it cannot be assigned a name or accessed with the above primitives.

The main use of copyPosition() is to re-reference a position equation. If we have a local pointer to a position equation p0 which was defined by the planning level (using makePosition()), the internal structure of p0 may not be valid because the pointers are defined for the planning level context. copyPosition() will use 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:
        p0 = getPositionByName ("name");
        p1 = copyPosition (p0);

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

DIAGNOSTICS

copyPosition() returns 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.

getPositionByName() returns NULL if it doesn't find anything.

getPositionByAddr() returns NULL if it doesn't find anything.

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

SEE ALSO
makePosition(3), allocTrans(3), solveTrans(3), allocTransXyz(3), rcclSetOptions(3).