                             TESTLOCK 1.15                  8-Dec-94

   Copyright 1993-94, Burton Systems Software.  All Rights Reserved.

TESTLOKP (for OS/2 & Win-NT) and TESTLOKR (for DOS or a Windows
DOS box) are programs to test network file-sharing, locking and
related functions.  These programs were originally written to
verify network support for the functions needed by Burton Systems
Software's TLIB Version Control System.  However, they have also
proven useful to network software vendors (and their customers),
to test for correct operation of a suite of common operations on
shared (or potentially shared) files.


TESTLOKP and TESTLOKR are functionally identical, except that
TESTLOKR is a real-mode-only program for DOS, and TESTLOKP is
a 16-bit "bound" protected-mode program for OS/2 & Win-NT.
TESTLOKR.EXE is built like the real-mode (DOS) version of TLIB
(probably called TLIB.EXE), and TESTLOKP.EXE is built like the
bound, protected-mode TLIB for OS/2 and NT (called either
OS2TLIB.EXE or TLIB2.EXE).

TESTLOKP will also run in real mode, under DOS, but some networks
(like Novell Netware, if you use the netx shell) may exhibit errors
which do not occur with the real-mode-only version (TESTLOKR.EXE).

In this document, we generally use the name "TESTLOCK" for both
programs.

Usage:
     {PROGRAM} {PATH} {OPTION}
     {PROGRAM} {PATH}{FILENAME} {OPTION}

where:

  {PROGRAM} is either TESTLOKR or TESTLOKP (or TESTLOCK, if you've
     renamed TESTLOKR.EXE or TESTLOKP.EXE to TESTLOCK.EXE)

  {PATH} is NOT optional, and should generally be in one of these forms:

     d:\subdir\
     \\server\vol\subdir\

  {OPTION} is NOT optional, and must one of the following:

     AUTO    - automatic test
     AUTO2   - similar to AUTO, but uses 2 computers or sessions for a
               more complete test
     REPLACE - create file.ext anew, opening it "exclusive"
     APPEND  - reopen existing file.ext for modification, "exclusive"
     MODIFY  - reopen existing file.ext for modification, "shared/deny-none"
               ("MODIFY" also tests region-locking)
     READ    - reopen existing file.ext for input, "shared-read/deny-write"

  {FILENAME} is optional.  If you don't specify it, then "TESTLOCK.TMP"
     will be used (and in AUTO2 mode, "TESTLOCK.SEM" will also be used).

Examples (these assume that you've renamed either TESTLOKR.EXE or
TESTLOKP.EXE to TESTLOCK.EXE):

     TESTLOCK f:\ AUTO

     TESTLOCK f:\ AUTO2

     TESTLOCK \\acme1\sys\tempdir\ AUTO

     TESTLOCK \\acme1\sys\tempdir\ AUTO2

     TESTLOCK f:\temp\ REPLACE

     TESTLOCK f:\testlev\ MODIFY

     TESTLOCK f:\testlev\testlock.tmp MODIFY
     (this is exactly equivalent to the previous example)

     TESTLOCK f:\temp\testfile.xxx READ

Notes:

AUTO and AUTO2 modes cause TESTLOCK to run an automated sequence of
tests, similar to the manual tests described later in this document,
but somewhat more extensive.

There should be at least 150K of free disk space on the test drive.

REPLACE, APPEND, MODIFY and READ modes are used to perform manual tests.
For most people, there's no need to perform manual tests; the automatic
tests are sufficient.

In AUTO mode, all the tests are performed by just one copy of TESTLOCK,
running on just one computer.  While this is useful, it may not uncover
network anomolies which only affect the sharing of files accessed
simultaneously from two different computers.

In AUTO2 mode, TESTLOCK does a more thorough test by prompting you to run
a second copy of TESTLOCK from another computer on your network (or from
another Windows or OS/2 session), and then TESTLOCK cooperatively performs
some of the tests on the two computers.  (Note: if running in two Windows
3.1 sessions, be sure to select the "Background tasking" option in Settings,
so that both sessions will run.)

However, in AUTO2 mode, you cannot specify a specific filename.  You
must specify only a directory, ending in backslash, as the first parameter
to TESTLOCK.  Testlock will create and use the files TESTLOCK.TMP and
TESTLOCK.SEM in that directory to perform its tests.


===========================================================================

Our address:

    Burton Systems Software
    Box 4157, Cary, NC 27519-4157 USA
    Tel: 919-233-8128   Fax: 919-233-0716
    email: dburton@salzo.cary.nc.us


===========================================================================

Distribution:

  TESTLOKP.EXE, TESTLOKR.EXE and this file are all copyrighted by Burton
  Systems Software.

  However, this documentation file and either program (or both) can be
  freely distributed and used for any purpose, except in conjunction with
  the marketing of products that compete with Burton Systems Software's
  TLIB Version Control system, as long as no changes are made to either
  of the programs or this file, and as long as this file is distributed
  along with the programs.


Source code:

  The source code for TESTLOKP/TESTLOKR is a copyrighted, proprietary
  trade secret of Burton Systems Software.  However, we are generally
  willing to make the source code available to customers and network
  vendors who need it.

  If you need the source code to TESTLOKP.EXE/TESTLOKR.EXE, please
  contact us at the address above, explaining why you need it, and be
  prepared to sign a nondisclosure agreement (testlock.nda).


===========================================================================

Revisions:
  12/01/93 - version 1.0:  Initial creation.
  12/02/93 - version 1.01: Fixed bug in REPLACE mode (it wouldn't replace
             an existing file), and other minor changes.
  12/03/93 - version 1.02: Added the "R" (re-check file length) operation,
             and other minor changes.
  12/05/93 - version 1.03: Added critical error handler (unreleased)
  12/06/93 - version 1.04: Added AUTO and AUTO2 modes.
  12/18/93 - version 1.05: Expanded AUTO2 mode.
  12/22/93 - version 1.06: Improved error messages.
  02/09/94 - version 1.07: More rigorous file-commit tests, and better
             reporting of file-commit problems.
  05/24/94 - version 1.08: with better/clearer error messages
  05/25/94 - version 1.09: fixed garbled numbers in some error messages.
  06/04/94 - version 1.10: It seems that some networks give a sharing error
             when an "attrib" command is attempted on an open file, so
             TESTLOCK now supresses the error message in that case.  Also,
             to set users' minds at ease during test3 (in which we verify
             that two simultaneous exclusive opens are properly prohibited),
             I rephrased the messages a bit, to explicitly say that the
             reported sharing errors are normal there.
  08/16/94 - version 1.11: longer retries (like TLIB 5.01n) and better
             messages for Windows-NT file-commit and synchronization/coherency
             bugs (e.g., findfirst returns wrong size after file commit).
             Also, fixed bugs in test of duplicate-handle/close approach to
             flushing directory info.
  11/18/94 - version 1.12: Added test9 to AUTO & AUTO2 modes, to try to
             reproduce the new bugs in Windows-NT 3.5's NTFS file system,
             which causes incorrect file sizes to be reported by find-first.
  11/19/94 - version 1.13: Added tests #9 and #10, to better diagnose the
             NTFS v3.5 bug.
  11/20/94 - version 1.14: fixed a minor AUTO2 bug (incorrect message)
             that was introduced in v1.12.  Also, improved some messages,
             added an "advice" message when needed to make TLIB work around
             the NTFS 3.5 bug, and added better handling of disk-full
             errors, and changed it to not leave a useless test file
             around after running AUTO or AUTO tests.
  12/08/94 - version 1.15: better advice for NetWare users who need to add
             "true commit = on" to their net.cfg files.


===========================================================================
Commands:


  TESTLOCK path\file.ext AUTO

      Performs an automated sequence of tests.


  TESTLOCK path\ AUTO2

      Performs a more extensive automated sequence of tests, including
      some tests which utilize two copies of TESTLOCK, running on two
      different computers.


  TESTLOCK path\file.ext REPLACE

      This will create (or replace) a new, 0-length path\file.ext.
      An "attrib -r path\file.ext" is also done, so that even if the
      file is read-only, it will still be replaced.

      The file is opened for EXCLUSIVE access.  If you try to access
      the same file (by running TESTLOCK from another workstation or
      in another command window), the 2nd attempt should fail with
      a sharing error:

         Open of "path\file.ext" for REPLACE failed,
         _doserrno=32=SHARING_VIOLATION
         This is a retriable/sharing error (TLIB would display
         "awaiting access...").
         Do you wish to retry the open?  Enter "Y" to retry,
         or "N" to exit.

      Note that TESTLOCK (unlike TLIB) does not automatically retry
      sharing errors.  However, you can make TESTLOCK retry the open
      by entering "Y".

      If the file is created successfully, TESTLOCK will say:

         Open of "path\file.ext" for REPLACE was successful, handle=5

      Then it will prompt you:

         Select next operation:
           W = write 128 bytes (tests file-write and file-commit)
           C = close and exit
           R = re-check file length

      If you enter "C", then the file will be closed, and TESTLOCK
      will exit.

      If you enter "W", then the file will be extended by 128 bytes.
      After writing the 128 bytes of data, TESTLOCK uses the DOS
      "commit file" function (Int 21h, AH=68h) or OS/2's equivalent
      (DosBufReset) to flush the data to disk and force the disk
      directory to be updated to reflect the new file size.  Then
      TESTLOCK checks the file size (via find-first), to verify that
      the commit worked correctly.

      If you enter "R", then the file length will be redetermined
      via two different methods: find-first (directory look-up), and
      lseek().  If the file length has changed, then TESTLOCK will
      display a message similar to this:

         Note: another program changed the file size, from 4608 to 4736.
         Lseek-ing to new EOF (offset 4736)
         Find-first's returned file length for \test.1 is now 4736,
         rather than 4608.

      Note that REPLACE mode opens the file in an "exclusive" mode, so
      if the file-sharing support (e.g., SHARE) is loaded and working
      properly, it should be impossible for another program to open the
      file and change its size.

      At every step, TESTLOCK checks all error codes and verifies the
      file size.  If anything goes wrong, extensive error messages
      are displayed.  If everything works correctly, then status
      messages are displayed, followed by the next C/W/R prompt, e.g.:

         Wrote 128 bytes at offset 0.
         File length is now 128
         File-Commit was successful (findfirst returned correct size).
         Select next operation:
           W = write 128 bytes (tests file-write and file-commit)
           C = close and exit
           R = re-check file length

      Note that this commit/verify sequence is the same process that
      TLIB goes through when extending the length of a tracking file,
      though TLIB's error messages tend to be more terse than those
      of TESTLOCK.


  TESTLOCK path\file.ext APPEND

      This is similar to REPLACE, except that path\file.ext must
      already exist, and the file's existing contents will not be
      destroyed.

      This is the same file-open mode that TLIB uses to append to
      a TLIB library file or journal file.

      TESTLOCK will tell you the old file length:

         File-length of path\file.ext obtained via find-first is 1536

      As with REPLACE, you'll be prompted:

         Open of "path\file.ext" for APPEND was successful, handle=5
         Select next operation:
           W = write 128 bytes (tests file-write and file-commit)
           C = close and exit
           R = re-check file length

      If you enter "W", then the file will be extended by 128 bytes,
      and a "commit file" will be done, and verified, as for REPLACE.

      If you enter "C", then the file will be closed, and TESTLOCK
      will exit.


  TESTLOCK path\file.ext READ

      This opens path\file.ext for shared-read/deny-write.  That means
      that path\file.ext must already exist, and it must not already
      be open for REPLACE, APPEND or MODIFY.

      This is the method that TLIB uses to open library files when
      doing commands like "E" (extract) and "L" (list versions) which
      do not modify the library files.

      If path\file.ext is already open (e.g., by TESTLOCK from another
      workstation or in another command window), the 2nd attempt
      should fail with a sharing error:

         Open of "path\file.ext" for READ failed,
         _doserrno=32=SHARING_VIOLATION
         This is a retriable/sharing error (TLIB would display
         "awaiting access...").
         Do you wish to retry the open?  Enter "Y" to retry,
         or "N" to exit.

      However, if the path\file.ext is already open for READ access
      (e.g., because you ran "TESTLOCK path\file.ext READ" from another
      workstation or in another command window), then this open will
      still succeed, and the following prompt will be displayed, e.g.:

         File-length of path\file.ext obtained via find-first is 384
         Open of "path\file.ext" for READ was successful, handle=3
         Press ENTER to close and exit

      The file will be kept open until you press ENTER, then the file
      will be closed and TESTLOCK will exit.


  TESTLOCK path\file.ext MODIFY

      This is similar to APPEND, except that path\file.ext is opened
      in shared/deny-none mode, which means that two or more copies
      of TESTLOCK (running on different workstations or in different
      command windows) can have the same path\file.ext open for MODIFY
      at the same time.

      This is the same file-open mode that TLIB uses to access
      tracking files (tlibwork.trk).

      TESTLOCK will tell you the old file length:

         File-length of path\file.ext obtained via find-first is 384

      As with APPEND or REPLACE, you'll be prompted for the next
      operation, but in MODIFY mode you can also create a "region lock"
      for exclusive access while extending the file, just as TLIB does
      when adding records to tracking files.

      Note, that only a subset of the following operations will actually
      appear, since TESTLOCK only allows creation of one region lock
      at a time (which is all that TLIB ever needs).  So, for example,
      if you've already created a lock, then "L" won't appear:

         Open of "path\file.ext" for MODIFY was successful, handle=5
         Select next operation:
           L = Lock region (the 128 bytes past the end of the file)
           W = write 128 bytes (tests file-write and file-commit)
           U = unlock region
           C = unlock, close and exit
           R = re-check file length

      As with REPLACE or APPEND, if you enter "W", then the file will
      be extended by 128 bytes, and a "commit file" will be done and
      verified.

      Also, if you enter "C", then the file will be closed, and
      TESTLOCK will exit.

      However, you can also enter "L" to create a region lock for
      the 128-byte region immediately following the end of the file.
      (This is what TLIB does to ensure exclusive access while extending
      its tracking files.)

      If another copy of TESTLOCK has already locked this region, then
      an error message is displayed:

         ERROR: file/region lock failed.
         Err=33=LOCK_VIOLATION, ExtdErr=0=unknown
         Class=10=LOCKED, Locus=2=DISK, Action=2=DELAY_RETRY
         This is a retriable error (TLIB would display
         "awaiting access...").

      You can retry the lock attempt by selecting "L" again.

      With some networks, you may have to load SHARE on the server and/or
      the workstation to make region locking work correctly.  Otherwise,
      it may fail with this error:

         ERROR: file/region lock failed.  You may need to load SHARE.

      If the lock is successfully created, then TESTLOCK will display:

         File/region lock succeeded (offset 384, for 128 bytes).

      The sequence you should follow when testing region locking is the
      sequence which TLIB uses:

      1) "L" - lock region
      2) "W" - write to locked region
      3) "U" - unlock region

      When you select "U" to unlock the locked region, TESTLOCK will
      display one of the following messages:

         File/region unlock succeeded (offset 384, for 128 bytes).

      or perhaps:

         Note: non-zero file/region unlock return code (offset 384,
         for 128 bytes).
         Don't worry about this; it is such a common OS/network bug
         that most programs (including TLIB) just ignore it.

      If you get the second message, don't panic.  The unlock probably
      worked correctly, anyhow; see "Testing Region Locks," below, to
      find out for sure.


---------------------------------------------------------------------------

Test Strategies (summary):

  Using TESTLOCK, you can verify that your network correctly supports
  (and you have the necessary network access permissions for) all of
  the common file operations which TLIB needs:

  #1. Creating and modifying files.

  #2. Examining and modifying file attributes (esp. the "read-only"
      attribute), like the DOS "attrib" command.

      If you have "READONLY Y", "ROLOCKS Y", or "READONLYB Y" configured
      in TLIB.CFG (as do most users), then TLIB must be able to modify
      the read-only attribute of various files.  Also, the AATTR
      configuration parameter controls how TLIB sets your source files'
      "archive" attribute.

      You can also test this by using the DOS "attrib" command to change
      and display the attributes of a file on your network server.

  #3. Enforced exclusive access to files, with correct "sharing error"
      return codes, so that TLIB's "awaiting access..." logic can
      properly retry and recover.

      This is required so that TLIB operations which modify library,
      lock and/or journal files can be serialized to avoid malfunction.

  #4. Shared "read" access to files.

      This lets multiple TLIB users do "read-only" operations, like
      extracting and listing versions, simultaneously, from the same
      TLIB libraries, without interfering with one another.

  #5. Shared "modify" access to files.

      TLIB requires this for access to tracking files (tlibwork.trk).

  #6. File commit, which updates directory information (esp., the file
      size) for an open file.

      This function was introduced in DOS 3.3, and should be supported
      on all modern networks.

      TLIB uses this when creating or lengthening tracking files.
      However, if this doesn't work on your network, TLIB can use a
      slower, alternative method (i.e., simply close and reopen the
      file).

  #7. File region locking, to enforce exclusive access to a portion of
      a file, with proper "lock error" return codes, so that TLIB's
      "awaiting access..." logic can properly retry and recover.

      TLIB uses this when creating or lengthening tracking files.

  #8. Multiple, adjacent region locks, and lock/write conflicts.

      TLIB does not actually do this, but it is a good "combination"
      test of region locking and file commits under your network OS.


===========================================================================


Recommendation:

  We recommend that, rather than wading through the manaul tests
  described below, you simply run TESTLOCK in one of its two automatic
  modes.

  AUTO2 is a better test than AUTO, but for AUTO2 mode you'll need to
  use two computers on your network (or, at least, two Windows or OS/2
  sessions).  AUTO mode has the advantage that you can run it from a
  single session.

  Then, if AUTO2 mode turns up errors, you can experiment with the
  manual modes to better determine precisely what causes the problems.


===========================================================================

Test Strategies (detailed):

      Test                                                     line
      ------------------------------------------------------   ----
   1) Creating and modifying files.                            542

   2) Examining and modifying file attributes.                 563

   3) Enforced exclusive access to files, with correct         601
      "sharing error" return codes.

   4) Shared "read" access to files.                           655

   5) Shared "modify" access to files.                         690

   6) File commit.                                             733

   7) File region locking, with correct "lock error"           778
      return codes.

   8) Multiple, adjacent region locks, and lock/write          861
      conflicts.


 - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

#1. Creating and modifying files.

    Run:

      TESTLOCK f:\path\file.ext REPLACE

    where:

      f: is a drive (probably a network drive), which you wish to test
         for compatibility with TLIB.

      path is an existing directory on f:

      f:\path\file.ext need not already exist (and can even be read-only).

    Use the "W" command to write data to the file, and the "C" command to
    close the file and exist TESTLOCK.


 - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

#2. Examining and modifying file attributes (esp. the "read-only"
    attribute), like the DOS "attrib" command.

    Run:

      ATTRIB +R f:\path\file.ext
      ATTRIB f:\path\file.ext
      TESTLOCK f:\path\file.ext APPEND

    where:

      f:\path\file.ext is the file you created in test #1.

    The second ATTRIB command will display the file attributes.  It
    should show the file as being read-only:

       A    R   f:\path\file.ext

    This is what would be displayed if the file were NOT read-only:

       A        f:\path\file.ext

    If the "R" is not displayed, then the file is not read-only.  If that
    is the case, then the "ATTRIB +R f:\path\file.ext" command was unable
    to set the file attributes.  This probably means that your network
    user ID does not have the needed authorization to run TLIB; your
    network administrator can solve this problem.

    After verifying that the ATTRIB command can change the file to read-
    only, run "TESTLOCK f:\path\file.ext APPEND" and use the "W" command
    to write additional data to the file.

    After you exit TESTLOCK, the file will no longer be read-only;
    TESTLOCK has removed the read-only attribute.


 - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

#3. Enforced exclusive access to files, with correct "sharing error"
    return codes.

    From computer #1, run:

      TESTLOCK f:\path\file.ext REPLACE

    You should see:

      Open of "f:\path\file.ext" for REPLACE was successful, handle=5
      Select next operation:
        W = write 128 bytes (tests file-write and file-commit)
        C = close and exit
        R = re-check file length

    Enter "W" to write some data to the file.
    Do not close and exit.

    From computer #2, run each of these commands:

      TESTLOCK f:\path\file.ext REPLACE
      TESTLOCK f:\path\file.ext APPEND
      TESTLOCK f:\path\file.ext MODIFY
      TESTLOCK f:\path\file.ext READ

    Each time you should see a "sharing error", similar to this one,
    on computer #2:

      Open of "path\file.ext" for _______ failed,
      _doserrno=32=SHARING_VIOLATION
      This is a retriable/sharing error (TLIB would display
      "awaiting access...").
      Do you wish to retry the open?  Enter "Y" to retry,
      or "N" to exit.

    (The important part is "This is a retriable/sharing error".)

    The first three times, answer "N" (to exit) on computer #2.
    The last time, however, do not answer the prompt.

    Instead, go back to computer #1 and enter "C" to close and exit.

    Then, from computer #2 enter "Y" to retry the open.  This time,
    the open should succeed:

      File-length of path\file.ext obtained via find-first is 128
      Open of "path\file.ext" for READ was successful, handle=3
      Press ENTER to close and exit

    Press ENTER to close the file and exit.


 - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

#4. Shared "read" access to files.

    From computer #1, run:

      TESTLOCK f:\path\file.ext READ

    Where f:\path\file.ext already exists (it can be the file you created
    in test #3).

    The open should succeed:

      File-length of path\file.ext obtained via find-first is 128
      Open of "path\file.ext" for READ was successful, handle=3
      Press ENTER to close and exit

    Do not press ENTER.

    From computer #2, run the same command:

      TESTLOCK f:\path\file.ext READ

    This open should also succeed:

      File-length of path\file.ext obtained via find-first is 128
      Open of "path\file.ext" for READ was successful, handle=3
      Press ENTER to close and exit

    At this point, the file is open for shared, read-only access on
    both computers.

    Press ENTER on both computers, to close the file.


 - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

#5. Shared "modify" access to files.

    From computer #1, run:

      TESTLOCK f:\path\file.ext MODIFY

    Where f:\path\file.ext already exists (it can be the file you
    used in tests #3 and #4).

    The open should succeed:

      File-length of path\file.ext obtained via find-first is 128
      Open of "path\file.ext" for MODIFY was successful, handle=5
      Select next operation:
        L = Lock region (the 128 bytes past the end of the file)
        W = write 128 bytes (tests file-write and file-commit)
        C = close and exit
        R = re-check file length

    Do not enter anything yet.

    From computer #2, run the same command:

      TESTLOCK f:\path\file.ext MODIFY

    This open should also succeed:

      File-length of path\file.ext obtained via find-first is 128
      Open of "path\file.ext" for MODIFY was successful, handle=5
      Select next operation:
        L = Lock region (the 128 bytes past the end of the file)
        W = write 128 bytes (tests file-write and file-commit)
        C = close and exit
        R = re-check file length

    At this point, the file is open for shared, read/write access on
    both computers.

    Proceed to test #6.


 - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

#6. File commit.

    Note: f:\path\file.ext should already be open for MODIFY access
    from both computers, as left by test #5.

    From computer #1, press "W" to write data to the file.  The write
    and file-commit should both succeed:

      Wrote 128 bytes at offset 128.
      File length is now 256
      File-Commit was successful (findfirst returned correct size).
      Select next operation:
        L = Lock region (the 128 bytes past the end of the file)
        W = write 128 bytes (tests file-write and file-commit)
        C = close and exit
        R = re-check file length

    Then, from computer #2, do the same thing - press "W" to write data
    to the file.  The copy of TESTLOCK running on computer #2 should
    detect that computer #1 changed the length of the file:

      Note: another program changed the file size, from 128 to 256.
      lseek-ing to new EOF (offset 256)
      Find-first's returned file length for \test.1 is now 256, rather
      than 128.

    It is the fact that computer #2 detected the change in file size
    which proves that File-Commit is working on your system.

    The write and file-commit should succeed also succeed on computer #2:

      Wrote 128 bytes at offset 256.
      File length is now 384
      File-Commit was successful (findfirst returned correct size).
      Select next operation:
        L = Lock region (the 128 bytes past the end of the file)
        W = write 128 bytes (tests file-write and file-commit)
        C = close and exit
        R = re-check file length

    Enter "C" to close the file on both computers.


 - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

#7. File region locking, with correct "lock error" return codes.

    On both computers, run:

      TESTLOCK f:\path\file.ext MODIFY

    where f:\path\file.ext is an already existing file, perhaps the same
    one used in tests #3-6.

    Both opens should succeed:

      File-length of path\file.ext obtained via find-first is 384
      Open of "path\file.ext" for MODIFY was successful, handle=5
      Select next operation:
        L = Lock region (the 128 bytes past the end of the file)
        W = write 128 bytes (tests file-write and file-commit)
        C = close and exit
        R = re-check file length

    On computer #1, enter "L" to lock a region.  The operation should
    succeed:

      File/region lock succeeded (offset 384, for 128 bytes).
      Select next operation:
        W = write 128 bytes (tests file-write and file-commit)
        U = unlock region
        C = unlock, close and exit
        R = re-check file length

    On computer #2, enter "L" to try to lock the same region.  The
    attempt should fail, with a "lock error":

      ERROR: file/region lock failed.
      Err=33=LOCK_VIOLATION, ExtdErr=0=unknown
      Class=10=LOCKED, Locus=2=DISK, Action=2=DELAY_RETRY
      This is a retriable error (TLIB would display "awaiting access...").
      Select next operation:
        L = Lock region (the 128 bytes past the end of the file)
        W = write 128 bytes (tests file-write and file-commit)
        C = close and exit
        R = re-check file length

    An important part of that error message is, "This is a retriable
    error".  If that is not displayed, then file/region locking is
    not working correctly on your network.

    Now, return to computer #1, and enter "U" to unlock the region.
    That operation should succeed:

      File/region unlock succeeded (offset 384, for 128 bytes).
      Select next operation:
        L = Lock region (the 128 bytes past the end of the file)
        W = write 128 bytes (tests file-write and file-commit)
        C = close and exit
        R = re-check file length

    Note: a common OS/network bug may cause the "unlock" to apparently
    fail, even when it actually worked correctly:

      Note: non-zero file/region unlock return code (offset 384,
      for 128 bytes).
      Don't worry about this; it is such a common OS/network bug
      that most programs (including TLIB) just ignore it.

    If this happens to you, do not worry.  Your network or OS does,
    indeed, have a bug, but as long as the next step works correctly
    the bug will not affect TLIB.

    Now, return to computer #2, and retry the lock attempt, by
    entering "L" again.

    This time the lock operation on computer #2 should succeed:

      File/region lock succeeded (offset 384, for 128 bytes).
      Select next operation:
        W = write 128 bytes (tests file-write and file-commit)
        U = unlock region
        C = unlock, close and exit
        R = re-check file length


 - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

#8. Multiple, adjacent region locks, and lock/write conflicts.

    Note: This functionality is not actually necessary for TLIB to work
    reliably, but a properly working network OS will pass this test.

    On both computers, run:

      TESTLOCK f:\path\file.ext MODIFY

    where f:\path\file.ext is an already existing file, perhaps the same
    one used in tests #3-6.

    Both opens should succeed:

      File-length of path\file.ext obtained via find-first is 384
      Open of "path\file.ext" for MODIFY was successful, handle=5
      Select next operation:
        L = Lock region (the 128 bytes past the end of the file)
        W = write 128 bytes (tests file-write and file-commit)
        C = close and exit
        R = re-check file length

    On computer #1, enter "L" to lock a region.  The operation should
    succeed:

      File/region lock succeeded (offset 384, for 128 bytes).
      Select next operation:
        W = write 128 bytes (tests file-write and file-commit)
        U = unlock region
        C = unlock, close and exit
        R = re-check file length

    On computer #2, enter "W" to attempt a write.  The operation should
    fail, because the write is to a region locked by computer #1:

      ERROR: only 0 of 128 bytes were written.
      ExtdErr=33=LOCK_VIOLATION
      Class=10=LOCKED, Locus=2=DISK, Action=2=DELAY_RETRY
      Select next operation:
        L = Lock region (the 128 bytes past the end of the file)
        W = write 128 bytes (tests file-write and file-commit)
        C = close and exit
        R = re-check file length

    (Note: on OS/2, ExtdErr=0=unknown, but the class, locus and action
    should still be correct.)

    Now, on computer #1, enter "W" to write to the locked region.  The
    operation should succeed:

      Wrote 128 bytes at offset 384.
      File length is now 512
      File-Commit was successful (findfirst returned correct size).
      Select next operation:
        W = write 128 bytes (tests file-write and file-commit)
        U = unlock region
        C = unlock, close and exit
        R = re-check file length

     Now, on computer #2, enter "L" to lock a region immediately following
     the region which computer #1 still has locked.  The operation should
     succeed, and computer #2 should display:

       Note: another program changed the file size, from 384 to 512.
       lseek-ing to new EOF (offset 512)
       Find-first's returned file length for \test.1 is now 512,
       rather than 384.
       File/region lock succeeded (offset 512, for 128 bytes).
       Select next operation:
         W = write 128 bytes (tests file-write and file-commit)
         U = unlock region
         C = unlock, close and exit
         R = re-check file length

     At this point, both computer #1 and computer #2 have region locks
     on (non-overlapping) portions of the file.

     Now, try another write on computer #1.  This time, the write should
     fail, since computer #2 has the region locked to which computer #1
     is trying to write (even though computer #1 still has a different
     region locked):

       ERROR: only 0 of 128 bytes were written.
       ExtdErr=0=unknown
       Class=10=LOCKED, Locus=2=DISK, Action=2=DELAY_RETRY
       Select next operation:
         W = write 128 bytes (tests file-write and file-commit)
         U = unlock region
         C = unlock, close and exit
         R = re-check file length

     Now, on each computer enter "C" to unlock and close the file.  On
     each computer a message should be displayed indicating what region
     was unlocked (they are not the same), and then TESTLOCK should exit:

       File/region unlock succeeded (offset 384, for 128 bytes).

     and:

       File/region unlock succeeded (offset 512, for 128 bytes).


 - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
