# @(#)README.win32	8.4 (Sleepycat) 6/2/98

These notes are for build/running/changing dbtest on Win32 platforms
(only!).  At this point, I've only really tried Win/NT.  And because I
really want to test/debug DB, I've taken the path of least resistance in
fixing the dbtest environment.  Hopefully, these hacks can be fixed over
time, via changes to the scripts or whatever.

================
BUILDING dbtest.

1) Open the build.win32/Berkeley_DB.dsw workspace,
2) Set the active configuration to dbtest - Debug.
3) Build.  That should create a build.win32/dbtest.exe file.

Unlike the other executables made via this workspace, dbtest.exe is not
put in the debug subdirectory, but directly in build.win32.  This is
needed because the tcl scripts expect subordinate dbtest processes to be
run via "./dbtest args..." .

================
RUNNING dbtest.

You will need a set of UNIX-like utilities to even think of running these
tests.  Currently, it requires: cp, diff, kill, ls, mkdir, mv, rm, sed,
sleep, sort and tr.  I'm using the MKS/NT package, which mostly works.
If you use this package, see MKS/NT notes below.  I'd bet the GNU
utilities would work better.  Before starting the tests, you need to:

1) cd build.win32
2) Edit the ./include.tcl file, changing the command entries to point to
   your executables.  For example, the line:

	set DIFF c:/tools/diff.exe

   in my case is changed to:

	set DIFF c:/mksnt/diff.exe

3) Copy debug/dbrecover.exe dbrecover.exe .	(Needed for recd test.)
4) Make the source CHANGES discussed below.
5) ./dbtest              (You should get a '%' prompt.)
6) % run_all             (This will take hours, producing an ALL.OUT file.)

================
RUNNING individual tests.

Instead of step 6) above, you can run individual tests, e.g.

	% r btree

or:
	% test001 hash

See test/README for details.  Note, you will probably want to run:

	./dbtest -debug

so that any traps stop in the debugger.

================
FAILURES

Places where the tests still fail:

1) memp003 (first time)
   memp_unlink:./TESTDIR: expected 0, got memp_unlink: Error 0

   I guess that someone still has the db open at the time of the unlink,
   similar to the common/db_region.c/runlink() CHANGE above, but I don't
   see where or how this happens.

2) memp003 (second time? after dbtest ../test/mpoolscript.tcl ... -shmem name)
   get_verify/RO: expected absenteesabsentees, got absentees

3) Rsrc001.a: Read file, rewrite last record; write it out and diff
   getlast: expected This is record 3 This is record 3 This is record 3, got This is record 3 This is record 3 This is record 3

   Maybe CR/NL issue?

4) Recd005.1.d:
   About to run recovery ... Recovery error: db_recover: appinit failed: Permission denied.

================
DEVELOPER NOTES

The dbtest program *cannot* current be linked with the DLL version of
libdb.  This is because of the use of function pointers across dll
boundaries.  The __db_jump structure (see os_func.h, os_map.c) stores
function pointers in a global structure.  Unfortunately the address of
these functions apparently cannot be used to jump to the functions outside
of the DLL (presumably a way to store a "global-accessible" function
pointer is available with a pragma, dunno how MS does this).  For now,
most of these issues are dealt with by linking static.  Of course, this
may introduce other issues since we are linking against a DLL version of
Tcl, so we get multiple versions of malloc linked into our application.
Sigh.  Fortunately that doesn't cause too much trouble, we merely need to
comment out a free call at the end of list_to_numarray() in test/utils.c
.  That's the only known place where Tcl mallocs memory that we try to
free.  (Linking with the DLL version of libdb doesn't fix this either!).

Also due to shared library issues, you may see errors reported as:

	memp_unlink:./TESTDIR: expected 0, got memp_unlink: Error 0

Rather than a more meaningful error:

	... got memp_unlink: no such file or directory

This has been isolated to a shared lib in using the Tcl_PosixError()
function.  Setting errno = n; in one shared library does not necessarily
make it visible in another shared library.  Thank you, MS.

================
MKSNT notes:

If you are using MKS NT, you will find that there are a few tests that
don't work out of the box, because there are some tests that produce
input/output data that has very long (> 2048 char) lines that are longer
than the MKS default limit.  The 'diff' and 'sort' commands both break on
these long lines.  The 'diff' problem can be more or less solved by
setting:

	set DIFF c:/mksnt/diff.exe

since you only care in this case whether outputs are different, not so
much the actual differences.

The 'sort' problem can be fixed by changing the maximum record length on
the command line, adding a '-z16384' option does the trick.  You can
change the .tcl script or hack up a replacement for sort.exe that calls
the real sort.exe with the extra options.  Unfortunately changing
include.tcl to have the extra option doesn't work (I'm a neophyte to tcl,
maybe there's an easy way to do this).