XMPI_Coloron  -   LAM/MPI-specific  function  to  enable a
       color in the XMPI trace stream.


SYNOPSIS

       #include <mpi.h>
       int
       XMPI_Coloron(int red, int green, int blue)


INPUT PARAMETER

       red    - red value (integer)
       green  - green value (integer)
       blue   - blue value (integer)


NOTES

       The LAM implementation of MPI is integrated with the  XMPI
       run/debug  viewer.  It can generate tracefiles and on-the-
       fly trace streams suitable for display in XMPI.

       A new functionality in XMPI is the ability to  enable  and
       disable select colors in the trace stream.  LAM/MPI allows
       this functionality with the XMPI_Coloron and XMPI_Coloroff
       functions.

       XMPI_Coloron is called with red , green , and blue parame­
       ters.  Each value may be from 0 to 255.  The resulting RGB
       composite  will  become  activated  for  that rank at that
       point in time.  Enabling and disabling colors is  a  local
       action; the calls will return immediately.  The color will
       be activated or deactivated on the timeline  corresponding
       to  the  rank  that invoked XMPI_Coloron / XMPI_Colorff in
       the XMPI trace window.

       Only one color is active at a time.  However, XMPI_Coloron
       may  be invoked multiple times to build a stack of colors.
       XMPI_Coloroff will pop the last color off  the  stack  and
       make the previous color active.

       If this function is invoked and tracing is not active, the
       color is ignored.

       There is no profiling version of this function.

       This is a LAM/MPI-specific function and is intended mainly
       for use with XMPI.  If this function is used, it should be
       used in conjunction with the LAM_MPI C preprocessor macro

       #if LAM_MPI
       XMPI_Coloron(255, 255, 0);
       #endif

       All MPI routines in  Fortran  (except  for  MPI_WTIME  and
       MPI_WTICK ) have an additional argument ierr at the end of
       the argument list.  ierr is an integer and  has  the  same
       meaning  as the return value of the routine in C.  In For­
       tran, MPI routines are subroutines, and are  invoked  with
       the call statement.

       All  MPI  objects  (e.g., MPI_Datatype , MPI_Comm ) are of
       type INTEGER in Fortran.


ERRORS

       If an error occurs in an MPI  function,  the  current  MPI
       error  handler  is  called to handle it.  By default, this
       error handler aborts the MPI job.  The error  handler  may
       be  changed with MPI_Errhandler_set ; the predefined error
       handler MPI_ERRORS_RETURN may be used to cause error  val­
       ues  to  be returned (in C and Fortran; this error handler
       is less useful in with the C++ MPI bindings.   The  prede­
       fined error handler MPI::ERRORS_THROW_EXCEPTIONS should be
       used in C++ if the error value  needs  to  be  recovered).
       Note  that  MPI does not guarantee that an MPI program can
       continue past an error.

       All MPI routines (except MPI_Wtime and MPI_Wtick )  return
       an  error  value;  C routines as the value of the function
       and Fortran routines in the last argument.  The C++  bind­
       ings  for  MPI  do not return error values; instead, error
       values are communicated by  throwing  exceptions  of  type
       MPI::Exception  (but not by default).  Exceptions are only
       thrown if the error value is not MPI::SUCCESS .

       Note that if the MPI::ERRORS_RETURN handler is set in C++,
       while  MPI functions will return upon an error, there will
       be no way to recover what the actual error value was.
       MPI_SUCCESS
              - No error; MPI routine completed successfully.
       MPI_ERR_ARG
              - Invalid argument.  Some argument is  invalid  and
              is  not identified by a specific error class.  This
              is typically a NULL pointer or other such error.
       MPI_ERR_INTERN
              - An internal error has  been  detected.   This  is
              fatal.  Please send a bug report to the LAM mailing
              list (see http://www.lam-mpi.org/contact.php ).


SEE ALSO

       XMPI_Buoy, XMPI_Coloroff


LOCATION

       xcoloron.c


Man(1) output converted with man2html