NAME    [Toc]    [Back]

       atom_object_management,  BuildObj,  IsObjBuilt,  WriteObj,
       ReleaseObj - Allows an Atom tool's  InstrumentAll  routine
       to build, release, and write objects

SYNOPSIS    [Toc]    [Back]

       #include <cmplrs/atom.inst.h>

       unsigned BuildObj(
               Obj * ); unsigned IsObjBuilt(
               Obj * ); void WriteObj(
               Obj * ); void ReleaseObj(
               Obj * );

DESCRIPTION    [Toc]    [Back]

       Atom's  object  management  routines  allow an Atom tool's
       InstrumentAll  routine  to  build,  write,   and   release
       objects.

       You  can  use  these  routines  only  from  an Atom tool's
       instrumentation file. See atom(1)  for  a  description  of
       Atom.

       An  InstrumentAll  routine  must call the BuildObj routine
       before calling AddCallObj to add analysis routine calls to
       the  object  and  before  traversing the procedures in the
       object.  BuildObj builds the internal data structures Atom
       uses  to  manipulate  the object. After the Atom tool traverses
 and instruments the object, the InstrumentAll  routine
  must  call  the  WriteObj  routine  to write out the
       instrumented version of the object.  For example:

       unsigned InstrumentAll(int iargc, char **iargv) {
           Obj *  obj;

           AddCallProto("Startup()");
           AddCallProto("Finish()");
           AddCallProto("foo(int, REGV)");

           AddCallProgram(ProgramBefore, "Startup");
           AddCallProgram(ProgramAfter, "Finish");

           for  (obj  =  GetFirstObj();   obj;   obj  =   GetNextObj(obj))

           {
               if (BuildObj(obj))
                   return(1);

                   /* instrument obj */

               WriteObj(obj);
            }
           return(0); }

       The  WriteObj  routine  writes the instrumented version of
       the  specified  object,  deallocating  the  internal  data
       structures BuildObj previously created.

       Note  that BuildObj may return an error code. It returns a
       nonzero value (and issues an appropriate error message) if
       it  encounters  an  error  in  the executable file for the
       Obj0. You should propagate this error value back  to  Atom
       by returning 1 from InstrumentAll.

       The  ReleaseObj  routine  deallocates  the  internal  data
       structures for the given object, but does  not  write  out
       the  instrumented  version the object. You should not call
       ReleaseObj if you have added any analysis routine calls to
       the object.

       The  IsObjBuilt  routine  returns  a  nonzero value if the
       specified object has been built with BuildObj, but not yet
       written with WriteObj or unbuilt with ReleaseObj.

       Whenever  possible,  tools should build and write out each
       object only once.  Some  tools,  however,  may  build  and
       release  an  object  several times, ultimately writing out
       its instrumented version. This can be very  time-consuming
       for a tool with very large objects.

       Similarly,  tools should normally build only one object at
       a time. Certain tools  may  simultaneously  build  several
       objects,  instrument  each  one,  and then write each out.
       This has advantages for tools that  call  ResolveNamedProc
       or  ResolveTargetProc. However, having more than one large
       object built at a single  time  will  cause  Atom  to  run
       slowly and to consume a large amount of memory.

RETURN VALUES    [Toc]    [Back]

       These routines return values as described above.

FILES    [Toc]    [Back]

       Header  file  containing external definitions of Atom routines

SEE ALSO    [Toc]    [Back]

       Commands: atom(1)

       Functions:            atom_application_instrumentation(5),
       atom_application_navigation(5), atom_application_query(5),
       atom_application_symbols(5),     atom_description_file(5),
       atom_instrumentation_routines(5),         AnalHeapBase(5),
       Thread(5), Xlate(5)

       Programmer's Guide



                                        atom_object_management(5)