atom_object_management(5)					File Formats Manual					 atom_object_management(5)

NAME

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

SYNOPSIS

       #include <cmplrs/atom.inst.h>

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

DESCRIPTION

       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

       These routines return values as described above.

FILES

       Header file containing external definitions of Atom routines

SEE ALSO

       Commands: atom(1)

       AtomTools: hiprof(5), pixie(5), third(5)

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

       Programmer's Guide

															 atom_object_management(5)