MONITOR(3) 

NAME
     Monitor Routines - AIMS Instrument Directives

DESCRIPTION
     In addition to automatically inserting monitor routines into
     instrumented  code,  AIMS provides the facility for the user
     to manually direct the insertion of instrumentation into the
     application  code  to be instrumented. Four types of instru-
     ment directives are provided:
          1) User Defined Code Blocks.
          2) User Defined Code Points.
          3) Trace and Data Flush Control.
          4) Topology Directives.

     All of the AIMS Instruement Directives may be placed in  the
     source  code as one would insert a call to a subroutine.  An
     Example in Fortran would be:
          CALL insert_marker('Starting loop')

     While in C the same directive would be:
          insert_marker("Starting loop");

     These calls are parsed by  the  AIMS  instrumentor  and  are
     translated  into  calls  which act as monitor sensors within
     the instrumented code.  If you insert  any  of  these  calls
     into  your source code, you will need to resolve these calls
     for the link phase of your uninstrumented  code.   The  AIMS
     distribution  provides  stub files (in both FORTRAN & C) for
     the resolution of these  directives  in  the  uninstrumented
     code.   Compilation  and  link  of the stub.c or stub.f file
     located within the misc sub-directory will resolve any unde-
     fines for the uninstrumented code.

     User Defined Code Blocks
          begin_block("Block Name")
          end_block("Block Name")

     These directives are placed at the beginning and  end  of  a
     user defined block of code.  These blocks are very useful in
     defining major phases of an application.   The  string  name
     for  this  block  will  be entered into the AIMS application
     database by xinstrument and be  recognized  by  the  VK and
     Tally.  Great care should be taken to insure that the blocks
     are properly balanced.

     User Defined Code Points
          insert_marker("Marker Name")

     This directive can be used to get timing information at  any
     specific  point  in  the  code (where you can call a subrou-
     tine).  This directive can be very  useful  in  marking  the
     execution   of   exceptions   or   in   determining  process
     synchronization.

     Trace And Data Flush Control
          begin_trace()
          end_trace()
          flush_trace()

     In some performance monitoring situations it may  be  useful
     for  the  user to manually control the trace process and the
     flushing of the trace data to disk.  These directives permit
     the user to specify points within the code where tracing may
     begin and end.  This is very useful for the user who is con-
     cerned  with  one  specific area of the code.  This user may
     focus tracing upon this node first by disabling the  tracing
     automatically set by xinstrument just after the start of the
     program and then by bracketing the  desired  area  of  study
     with begin_trace and end_trace directives.

     The flushing of data may also be  specified  for  one  point
     within  the  program  through  the  use of the flush_trace()
     directive.

     Topology Directives
          define_grid(rows,cols)
          define_grid_node(row,col)

     These directives permit the user to  define  an  algorithmic
     grid  topology,  which  may  be  displayed by the VK's Boxes
     (Grid) view.  That view displays processor node in a rows  X
     cols  two  dimensional  grid  as  defined by the define_grid
     directive.  The define_grid() directive need only be  called
     by  one  processor of the parallel application.  As the name
     implies, this directive assigns the dimensions to the topol-
     ogy.   After  the define_grid directive is called, each node
     should assign itself a position within the  two  dimensional
     topology through the define_grid_node() directive.

SEE ALSO
     AIMS(1), xinstrument(1), batch_inst(1)
     The AIMS Reference Manual

AIMS Release 3.6   Last change: 5 January 1997