Instrumentation Procedure

  1. Find main() and add either VovBegin(argc,argv); or the call VovConnect();
  2. Call VovBegin(...) before any other VOV procedures and before doing any I/Os.
    If FlowTracer is not running, VovBegin(...) has no effect. If FlowTracer is running, VovBegin(...) initiates a connection with the FlowTracer server, or inherits the connection from the parent process.

    VovConnect() is similar to VovBegin() but it does not initiate any connection with the vovserver. It can only inherit a connection from the parent process.

  3. Find where your program terminates. This is normally, but not necessarily, at the end of main(). The correct way to terminate a program is either to call exit(status) or to return from main() with return status.

  4. For most UNIX tools, a status equal to 0 normally means that the tool has terminated correctly. Now replace exit(status) with VovEnd(status).

    In principle, you can ignore any exit() called by error trapping routines, because if a tool terminates without calling VovEnd(), it is assumed to have failed. In practice, it is better to ensure that every exit() is replaced by a VovEnd(). If FlowTracer is not running, VovEnd() simply calls exit().

    If VovEnd() is called by the tool that opened the connection with the server, the connection is closed.

  5. Find all file I/Os. Use VovFopen() to replace all calls to fopen().
    If you use other methods to open or create a file, such as freopen() or rename(), you must call explicitly either:
    VovInput(char* db, char* name)
    or
    VovOutput(char* db, char* name)

    If the database in these calls is "FILE", you can also call VovInputFile(char* name) or VovOutputFile(char* name).

    For example, the call to VovFopen() in line 16 can be replaced with a call to VovOutputFile("Hello"), followed by fopen(). If FlowTracer is not running, VovFopen() is equivalent to fopen(), while VovInput() and VovOutput() do nothing.

    Ignoring the return status from VovInput() and VovOutput() does not change the behavior of your tool. (See the include file $VOVDIR/include/vil.h for more information on the return status of these procedures.)

  6. VovInput() and VovOutput() require two arguments: the name of a database and the name of an object in that database. In most cases, the database is "FILE", and the object name is the file name. This can be a full path starting with /, or a relative path. Tilde (~) and environment variables are expanded as by the shell.
    VovFopen() can replace fopen() in most cases, except where fopen() is used to test the existence of a file, or where temporary files are being created. The use of fopen() to test for file existence is a misuse of the function. stat() is more appropriate and more efficient.
  7. Include the file vil.h in all sources that you have modified. Then recompile and relink the tool. To complete the linking, you need the libvil.a, a copy of which can be found in $VOVDIR/lib/libvil.a.
    Note: Altair does not furnish a library for Python tools. However, Python's os.* and subprocess.* commands can execute other programs, including VovInput and VovOutput. These are links to the viltool library.