openfoam/applications/test/ensightFoamReader

udr_checker
-----------

udr_checker.c is a routine that can be used to debug EnSight User-defined
readers.   It exists because of the difficulty of debugging dynamic shared
libraries when you don't have the source for the calling program (EnSight).

If udr_checker.c is compiled and linked with your reader source code (including
access to any libraries needed, and the global_extern.h file), it will exercise
most options of you reader, giving feedback as it goes.  The resulting
executable can be debugged using your favorite debugger.  And if you have
memory/bounds checking software (such as purify), you can (and should) run it
with this executable to make sure that you are not overwriting things.  Readers
that bash memory will cause problems when run with EnSight!

You will note that the Makefile provided with the readers in the EnSight
distribution have a "checker" object.  If you do a "make checker" instead of
just a "make", the "checker"executable will be produced.   You may need to
modify these makefiles slightly if the locations of your reader files are
different than the normal.


--------------------------------------
Once the "checker" executable exists, you can run the checker program by simply
invoking it:

> checker

And you will be prompted for the type of information that you provide in the
EnSight Data Reader dialog, namely:

The path
filename_1
[filename_2]           Only if your reader uses two fields
swapbytes flag
<toggle flags>         Only if your reader implements extra GUI
<pulldown flags>        one flag value per line
<field contents>        one field string per line

There are certain command line options that you can use to control some aspects
of the checker program.  One of the more useful is the ability to provide the
input just described in a file.  This is done in this fashion:

> checker -p <playfile>

And <playfile> would be a simple ascii file with 3 [0r 4] lines:
line 1:         the path
line 2:         filename_1
line 3:        [filename_2]   (if two_fields is TRUE)
line 3 or 4:    0 or 1, for swapbytes  (0 is FALSE, 1 is TRUE)
remaining lines 0 or 1 for toggle disable enabled
                       one line for each toggle
                0 - num_pulldown_values for pulldown choice
                       one line for each pulldown
                strings 
                       one line for each field

example playfile for an EnSight Gold reader casefile (entitled cube.play)
could look something like the following:  (Note: two_fields is FALSE)
-------------------

/usr/local/bin/data/ens
cube.case
0


And you would invoke checker as:

> checker -p check.play

Another example playfile 
with swapbytes 0, 
two enabled toggles, 
three pulldowns with the value 0 chosen 
and a single field "sample field value"

could look something like the following::
----------------------

/mydirectory/subdir/
myfile
0
1
1
0
0
0
sample field value


Other command line arguments are:
---------------------------------
-server_number       For checking server number routines.  If you use this
                     option, you will be prompted for the total number of
                     servers and the current server number.  These will then be
                     used in the calls to the server number routines.

-gts #               For specifying the geometry timestep to test.  The default
                     is step 0.
                     The # is the (zero based) time step to read for geometry.

-vts #               For specifying the variable timestep to test.  The default
                     is step 0.
                     The # is the (zero based) time step to read for variables.



Testing optional routines using #defines
-----------------------------------------
For optional routines, such as the extra_gui, or var_extract_gui routines, you
must uncomment the proper #define in udr_checker.c

Currently the ones available are:

#define _EGS          for extra gui routines
#define _VES          for var extract gui routines