
\input manualMacros.tex
\manBegin
\manPageInfo{RCCL Reference Manual}{}{}
\manTitle{runMonitorFxn}{3}
\manSection{NAME}
{\rightskip=0ptplus1fil
{\tt \manName{runMonitorFxn}},
{\tt \manName{deleteMonitorFxn}},
{\tt \manName{runMotionFxn}}
-- RCCL routines for controlling monitor functions.

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

id = runMonitorFxn (mnp, fxn, arg)
  int id;
  MANIP *mnp;
  int (*fxn)();
  int arg;

deleteMonitorFxn (mnp, id)
  MANIP *mnp;
  int id;

runMotionFxn (mnp, fxn, arg)
  MANIP *mnp;
  int (*fxn)();
  int arg;
@endcverbatim
\manSection{ARGUMENTS}
\manItem{{\tt mnp} --}
Manipulator with which the function is to be associated.
\manItem{{\tt fxn} --}
Pointer to function.
\manItem{{\tt arg} --}
Application supplied argument for the function.
\manItem{{\tt id} --}
Handle for removing monitor function.
\manSection{RESTRICTIONS}
These routines must be called from the planning level.
\manSection{DESCRIPTION}
These routines control the execution of application specific 
monitor functions. A monitor function, when active, is called by the
trajectory generator once every control cycle (so the function 
executes at the same rate as the trajectory generator itself;
see {\tt rcclSetInterval(3)}). A monitor function will execute only
while the trajectory generator is running.

{\tt runMonitorFxn()} establishes a {\it permanent} monitor function 
that remains active until either it is explicitly deleted
with {\tt deleteMonitorFxn()}, or the trajectory generator
is turned off (through either a call to {\tt rcclRelease()} or
an RCI abort condition). It returns an {\tt id} which is used
by {\tt deleteMonitorFxn()}.
The associated manipulator {\tt mnp} indicates
which CPU the function should execute on;
it runs on the same CPU as the trajectory generator for 
{\tt mnp}.
The maximum number of permanent monitor functions that can be
associated with a manipulator at one time is {\tt MAX_MONITOR_FXNS}.

{\tt deleteMonitorFxn()} deletes the permanent monitor function
specified by {\tt id}.

{\tt runMotionFxn()} establishes a {\it motion} monitor function that will
be active only for the duration of the next motion
requested for the 
manipulator {\tt mnp}. It is executed on the same CPU as the trajectory
generator for {\tt mnp}.
The maximum number of motion monitors that can be run
for any given motion is {\tt MAX_MONITOR_FXNS}.

When executed, monitor functions are called by the trajectory
generator with the following arguments:

\cverbatim
        (*fxn)(arg, mnp)
        int arg;
        MANIP *mnp;
        {
        } @endcverbatim
where {\tt arg} and {\tt mnp} are the application argument and
manipulator specified by either {\tt runMonitorFxn()} or
{\tt runMotionFunction()}. Note that the actual address of {\tt mnp} may be
different from that used by the planning level.

Monitor functions must be part of the program's control segment;
i.e., they must be contained in modules specified to the right of the {\tt
CTRL} keyword in the {\tt rcc} command (q.v.) used to compile/load the
program. 
Since the functions are executed at the control level, their execution
times need to be contained within a single control cycle. They also do not
have access to the UNIX system services. Some RCI utility routines provide
such things as diagnostic printing ({\tt rciPrintf()}), memory allocation
({\tt rciMalloc()}), and sending UNIX signals to the planning task ({\tt
rciSignal()}). This is discussed in more detail in the ``Mulit-RCCL User's
Guide''. 

\manSection{DIAGNOSTICS}
These functions 
return {\tt -1} in the event of an error.
They 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.). 

Error codes set by {\tt runMonitorFxn()} include:

\manItem{{\tt ETaskActive} --}
The trajectory generator is not running.

\manItem{{\tt ETooMany} --}
The number of permanent monitors would exceed {\tt
MAX_MONITOR_FXNS}. 

Error codes set by {\tt deleteMonitorFxn()} include:

\manItem{{\tt ETaskActive} --}
The trajectory generator is not running.

Error codes set by {\tt runMotionFxn()} include:

\manItem{{\tt ETooMany} --}
The number of motion monitors for the next motion would exceed {\tt
MAX_MONITOR_FXNS}. 

These routines will abort the program if called from the control level.
\manSection{SEE ALSO}
\rightskip=0ptplus1fil
{\tt rcclCreate(3)}, {\tt rcclStart(3)}, {\tt rcclSetInterval(3)}, 
{\tt transEval(3)}, {\tt errorStack(3)}.

\manEnd
\end

