stop(3)

NAME
stop -- RCCL stop request primitive.

USAGE
#include <rccl.h>

mid = stop (mnp, sigma)
  MANIP *mnp;
  float sigma;

ARGUMENTS

mnp --
    Manipulator reference structure.

sigma --
    Length of time the manipulator is to be stopped for (milliseconds).

mid --
    Motion ID. This is a non-negative number either assigned automatically by the system or specified explicitly using setMotionFlag() before the call to stop().

RESTRICTIONS
This routine must be called from the planning level.

DESCRIPTION
The stop primitive queues a request to stop the manipulator at the target position of the previously specified motion, for a length of time sigma. Ordinarily, the stop request call returns immediately, before the stop has actually happened. The call will block only if the motion queue for that manipulator is full (see setMotionQueueSize(3)).

If sigma is given as F_DEFAULT, then the system checks to see if an explicit motion time has been specified by setTime() since the manipulator's last motion request. If so, this value is used for the stop time. If not, then a stop time of 0 milliseconds is assumed. If sigma is given as F_UNDEF, then a stop of indefinite duration will be generated; such a stop request will have to terminated explicitly using a routine such as stopMotion(). Other values of sigma which are less than 0 will cause an error.

In RCCL, stopping is accomplished (internally) by simply issuing another motion request to the previously specified position (according to the same paradigm described in Richard Paul's book). When a manipulator is "stopped" at a target position, and that target is changing in time (as a result of its containing variable transforms or joint biases), then the manipulator will continue to track the position. Stopping at a position, therefore, does not necessarily mean that the manipulator will come to rest.

Stop requests are implemented as motion requests: the returned motion ID value can be used to obtain status information about the motion (see motionStatus(3)), terminate it (see stopMotion(3)), or wait for it to start or stop (see waitForStop(3)). Motion IDs assigned by the system are automatically invalidated and reused after NUM_SYSMFLAGS subsequent motion requests (on all manipulators). If this is undesirable, a motion ID can be explicitly set by the program with the primitive setMotionFlag().

DIAGNOSTICS
This routine returns -1 in the event of an error. It will automatically abort the program if the option RCCL_ERROR_EXIT is set (see rcclSetOptions(3)). Error codes and messages are placed on the errorStack (q.v.). The following error codes may be set:

ENoSpace --
    The motion queue does not have enough space to store the requested motion request packet.

ERange --
    The indicated stop time was negative.

The routine will abort the program if called from the control level.

SEE ALSO
rcclCreate(3), setMotionQueueSize(3), setMotionFlag(3), waitForMotion(3), motionStatus(3), stopMotion(3), setMotionHold(3), rcclSetOptions(3), errorStack(3).