batch_inst(1) 

NAME
     batch_inst - AIMS source-code instrumentors (batch-mode)

SYNOPSIS
     batch_inst [ -options ] filename ... 

DESCRIPTION
     An instrumentor annotates the given source files by  insert-
     ing  calls  to  the  AIMS  instrumentation library.  The new
     files are output into a directory specified by the  - output
     option  (default is ./inst ) under the same name as the ori-
     ginal file.  These annotated source files  can  be  compiled
     just  as  the originals would have been, with one exception:
     the executables need to  be  linked  with  an  AIMS  monitor
     library  (see  AIMS(1)).   The instrumented application pro-
     gram, when executed, produces a file containing a  trace  of
     events;  this  file  serves  as  an input to AIMS' tools for
     analysis (e.g. tally(1)) and animation (e.g. VK(1)).

OPTIONS
     -quiet
          Suppress output information.

     -adb  path
          Specify an input path  for  the  application  database.
          Default is ./appl_db.

     -oadb  path
          Specify an alternate path for the application database.
          Default is ./inst/APPL_DB.

     -overwrite
          Overwrite the old application database.

     -output  path
          Specify  the  directory  into  which  the  instrumented
          modules should be written.  Default is ./inst.
 
     -origin  path
          Specify the full pathname for the root directory of the
          source tree.  Default is the current working directory.

     -enable  all  |  procs  |  io
          Specify  which  constructs  should  be  annotated.   By
          default,  all  communication calls with message passing
          are instrumented.   To  instrument  user-level  sensors
          (e.g.,   routines   and  i/o  statements),  the  option
          ``procs'' and/or ``io'' can  be  used.  ``all''  is  to
          instrument all user-selectable constructs, such as rou-
          tines, loops, ifs, and i/o statements.  Currently  user
          can    not   selectively   instrument   constructs   in
          batch_inst, and should use xinstrument(1) instead.

          The -enable flag may appear several times, interspersed
          between filenames.

     -verbose
          Print each file's name as it is instrumented.

     -keep_dep
          Keep the Sage dep files.  This is needed if you want to
          use  xinstrument  to  change  profiles  later  on.  The
          default for batch_inst is to remove the dep files after
          the instrumentation is done.

     -pp_options  switches
          Switches passed to the preprocessor for  source  files.
          The  default  is the include path for PVM or MPI calls.
          This option can also be set by the environment variable
          ``AIMS_PP_OPTIONS''.

     -platform  <platform>
          Specify the platform to use.  Possible <platforms  are
          f77-pvm | c-pvm | f77-mpi | c-mpi.

          The -platform  flag  may  also  appear  several  times,
          describing different platforms for different files.

     -help
          Print helpful information about command-line options.

IMPORTANT NOTE ABOUT PREPROCESSORS
     Prior to parsing each file, it may be necessary to pass  the
     source  code through the preprocessor.  In such cases it may
     be necessary to  specify  how  the  preprocessor  should  be
     called and what switches (e.g.  -D options for defining mac-
     ros) need to be passed.

     The preprocessor command line for each file is generated  by
     concatenating the command, the options, and the file's name.
     Typically, the system is built with the correct templates as
     defaults  but  the  switches  will  vary from application to
     application.  The switches may also be specified using shell
     variable:

          AIMS_PP_OPTIONS

     In the current implementation, the preprocessor is  selected
     during the compilation (thus built-in) for C programs, while
     it is not available for  Fortran  programs.   Therefore,  if
     there  are preprocessing directives in Fortran programs, one
     needs to run them through a preprocessor (for example  ``fpp
     -P file.F > file.f'') before performing the instrumentation.

USING PROFILES TO SELECT INSTRUMENTABLE CONSTRUCTS
     The user may select the constructs to be annotated using the
      - enable  option.   This can appear anywhere in the command
     line and is in effect for all subsequent files until another
     profile  is  specified.   The  default  profile  enables all
     message-passing calls but no user-level sensors  (e.g.  rou-
     tines  and  point_marker  sensors).  However, any customized
     profile can be specified in xinstrument(1).

ENVIRONMENT VARIABLES
     AIMS_PP_OPTIONS

SEE ALSO
     AIMS(1), xinstrument(1), tracesort(1), tally(1), VK(1),
     MONITOR(3), MONITOR(5)
     
AIMS Release 3.7    Last change: 2 July 1997