Summary of Tests for the Jam/Unjam Utility
July 28, 2004

Tests for 'Jam'

Case 1:  add a user block to an HDF5 file with no ub, output to new HDF5 file

The output file is the same HDF5 file with the user block at the front, padded as needed. The input file is unchanged.

Example invocation:  jam -u ub.txt -i ifile.h5 -o ofile.h5

Correct Result:
  1. user block of new file (ofile) should be the same as the input user block file (plus padding).
    Test: extract (size of ub.txt) bytes from ofile.h5, compare to ub.txt
  2. The output file should be the same HDF5 file as the input file
    Test:  
    1. h5dump ifile,
    2.  h5dump ofile, 
    3. compare dump output.
Table 1. Tests for Case 1

Case
Test
small input user block file (10 bytes)
./jam -u ub10.txt -i tall.h5 -o ta.h5
input near the alignment
./jam -u ub511.txt -i tall.h5 -o ta.h5
input exactly fills the user block
./jam -u ub512.txt -i tall.h5 -o ta.h5
input over the alignment boundary, must fill to next alignment
./jam -u ub513.txt -i tall.h5 -o ta.h5


Table 2. Correct results for tests
New user block
Output File User Block
10 bytes
512 bytes:   10 input bytes+pad to 512
511bytes
512 bytes;   511input bytes+pad to 512
512bytes
512 bytes:   512 input bytes
513bytes
1024 bytes: 513 input bytes+ pad to 1024



Case 2: Add user block to HDF file with no ub (rewrite the existing file)

Add the user block to the front of the input file.  Same as Case 1, except the original file is rewritten.

Example invocation:  jam -u ub.txt -i ifile.h5

Correct Result:
  1. user block of input file (ifile) should be the same as the input user block file (plus padding).
    Test: extract (size of ub.txt) bytes from ifile.h5, compare to ub.txt
  2. The input file should be the same HDF5 file as the original input file
    Test:
    1. save copy of original file,
    2. h5dump original file, 
    3. h5dump ifile (after jam), 
    4. compare dump output.
Table 3. Tests for Case 2
Cases
Test
small input user block file (10 bytes)
cp tall.h5 ta.h5; ./jam -u ub10.txt -i ta.h5
input near the alignment
cp tall.h5 ta.h5; ./jam -u ub511.txt -i ta.h5
input exactly fills the user block
cp tall.h5 ta.h5; ./jam -u ub512.txt -i ta.h5
input over the alignment boundary, must fill to next alignment
cp tall.h5 ta.h5; ./jam -u ub513.txt -i ta.h5


Table 4. Correct output (in the original file)

New user block
Output File User Block
10 bytes
512 bytes:  10 input bytes+pad to 512
511bytes
512 bytes:  511input bytes+pad to 512
512bytes
512 bytes:  512 input bytes
513bytes
1024 bytes: 513 input bytes+ pad to 1024



Case 3: Add user block to HDF file with a ub, output to new file

Same as Case 1, except the input file already has a user block. The input user block is added to the end of the existing user block.

Example invocation:  jam -u ub.txt -i ifilewithub.h5 -o ofile.h5

Correct Result:
  1. user block of new file (ofile) should be the concatination of the original user block (including padding, then the new user blocksamem then padding.
    Test: extract (sizeof old ub) bytest from original file, concatinate input (ub.txt). Extract (size of old ub + size of ub.txt)  bytes from the output file. Compare the extracted bytes with the concatinated files.
  2. The input file should be the same HDF5 file as the original input file
    Test:
    1.  save copy of original, 
    2. h5dump original file, 
    3. h5dump ifile, 
    4. compare dump output.
Table 5. Test Cases for Case 3
Cases
Test
small input file (10 bytes), H5 file has small ub (10 bytes + pad)
./jam -u ub10.txt -i twithub.h5 -o ta.h5
input near the alignment, H5 file has small ub (10 bytes + pad)
./jam -u ub511.txt -i twithub.h5 -o ta.h5
input exactly fills the user block, H5 file has small ub (10 bytes + pad)
./jam -u ub512.txt -i twithub.h5 -o ta.h5
input over the alignment boundary, must fill to next alignment,  H5 file has small ub (10 bytes +data)
./jam -u ub513.txt -i twithub.h5 -o ta.h5
small input file (10 bytes), H5 file has ub >513
./jam -u ub10.txt -i twithub513.h5 -o ta.h5
input near the alignment, H5 file has ub >513
./jam -u ub511.txt -i twithub513.h5 -o ta.h5
input exactly fills the user block, H5 file has small ub (10 bytes + pad)
./jam -u ub512.txt -i twithub513.h5 -o ta.h5
input over the alignment boundary, must fill to next alignment,  H5 file has small ub (10 bytes +data)
./jam -u ub513.txt -i twithub513.h5 -o ta.h5


Table 6. Correct Results


Input HDF5 file user block:

New user block
10 original bytes + pad
513 original bytes+pad
10 bytes
1024 bytes :  10 original bytes+pad to 512+10 input bytes+ pad to 1024
2048 bytes: 513 original bytes+pad to 1024+10 input bytes + pad to 2048
511 bytes
1024 bytes:  10 original bytes+pad to 512+511 input bytes+ pad to 1024
2048 bytes: 513 original bytes+pad to 1024+511 input bytes + pad to 2048
512 bytes
1024 bytes:  10 original bytes+pad to 512+512 input bytes
2048 bytes: 513 original bytes+pad to 1024+512 input bytes + pad to 2048
513 bytes
2048 bytes: 10 original bytes+pad to 512+513 input bytes + pad to 2048
2048 bytes: 513 original bytes+pad to 1024+513 input bytes + pad to 2048


Case 4: Add user block to HDF file with existing ub, replace the ub, write to a new file

Same as Case 2, except the original HDF5  file already has a user block. The input user block replaces the original user block.

Example invocation:  jam -u ub.txt -i ifilewithub.h5 -o ofile.h5 --clobber

Correct Result:
  1. user block of new file (ofile) should be the the same as the input user block file (plus padding).
    Test: extract (size of ub.txt) bytes from ofile.h5, compare to ub.txt
  2. The input file should be the same HDF5 file as the original input file
    Test:
    1.  h5dump ifile,
    2.  h5dump ofile, 
    3. compare dump output.
Table 7. Test Cases
Cases
Test
small input file (10 bytes), H5 ile has small ub (10 bytes + pad)
./jam -u ub10.txt -i twithub.h5 -o ta.h5 --clobber
input near the alignment, H5 file has small ub (10 bytes + pad)
./jam -u ub511.txt -i twithub.h5 -o ta.h5 --clobber
input exactly fills the user block, H5 file has small ub (10 bytes + pad)
./jam -u ub512.txt -i twithub.h5 -o ta.h5 --clobber
input over the alignment boundary, must fill to next alignment,  H5 file has small ub (10 bytes +data)
./jam -u ub513.txt -i twithub.h5 -o ta.h5 --clobber
small input file (10 bytes), H5 file has ub >513
./jam -u ub10.txt -i twithub513.h5 -o ta.h5 --clobber
input near the alignment, H5 file has ub >513
./jam -u ub511.txt -i twithub513.h5 -o ta.h5 --clobber
input exactly fills the user block, H5 file has small ub (10 bytes + pad)
./jam -u ub512.txt -i twithub513.h5 -o ta.h5 --clobber
input over the alignment boundary, must fill to next alignment,  file has small ub (10 bytes +data)
./jam -u ub513.txt -i twithub513.h5 -o ta.h5 --clobber


Table 8. Correct results

Input HDF5 file user block:

New user block
10 original bytes + pad to 512
513 original bytes+pad to 1024 bytes
10 input bytes
512 bytes:  10 input bytes+pad to 512
512 bytes: 10 input bytes+pad to 512 (file shrinks)
511 input ytes
512 bytes:   511 input bytes+pad to 512
512 bytes:  511input  bytes+pad to 512 (file shrinks)
512 input bytes
512 bytes:   512 input  bytes (no pad)
512 bytes:  512 input  bytes (no pad) (file shrinks)
513input bytes
1024 bytes:  513 input bytes+pad to 1024
1024 bytes:  513 input bytes+pad to 1024


Case 5: Add user block to HDF file with existing ub, replace the ub, write to same file

Same as Case 4, except the original file is rewritten.  The input user block replaces the original user block.

Example invocation:  jam -u ub.txt -i ifilewithub.h5  --clobber

Correct Result:
  1. user block of input file (ofile) should be the the same as the input user block file (plus padding).
    Test: extract (size of ub.txt) bytes from ofile.h5, compare to ub.txt
  2. The input file should be the same HDF5 file as the original input file
    Test: 
    1. h5dump ifile, 
    2. h5dump ofile, 
    3. compare dump output.
  3. The input file ub should be no larger than needed by the input. (?? not sure how to implement)

Table 9. Test Cases
Cases
Test
small input file (10 bytes), H5 file has small ub (10 bytes + pad)
cp twithub.h5 ta.h5; ./jam -u ub10.txt -i ta.h5 --clobber
input near the alignment, H5 file has small ub (10 bytes + pad)
.cp twithub.h5 ta.h5; ./jam -u ub511.txt -i ta.h5 --clobber
input exactly fills the user block, H5 file has small ub (10 bytes + pad)
cp twithub.h5 ta.h5; ./jam -u ub512.txt -i ta.h5 --clobber
input over the alignment boundary, must fill to next alignment, H5 file has small ub (10 bytes +data)
cp twithub.h5 ta.h5; ./jam -u ub513.txt -i ta.h5 --clobber
small input file (10 bytes), H5file has ub >513
cp twithub513.h5 ta.h5; ./jam -u ub10.txt -i ta.h5 --clobber
input near the alignment, H5 file has ub >513
cp twithub513.h5 ta.h5; ./jam -u ub511.txt -i ta.h5 --clobber
input exactly fills the user block, H5 file has ub >513
cp twithub513.h5 ta.h5; ./jam -u ub512.txt -i ta.h5 --clobber
input over the alignment boundary, must fill to next alignment,  H5 file has ub >513
cp twithub513.h5 ta.h5; ./jam -u ub513.txt -i ta.h5 --clobber


Table 10. Correct Results

Input HDF5 file user block:

New user block
10 original bytes + pad to 512
513 original bytes+pad to 1024
10 input bytes
512 bytes :  10 input bytes+pad to 512
51 bytes: 10 input bytes+pad to 512 (file shrinks)
511 input bytes
512 bytes:  511 input bytes+pad to 512
512 bytes:  511 input bytes+pad to 512 (file shrinks)
512 input bytes
512 bytes:  512 input bytes (no pad)
512 bytes:  512 input bytes (no pad) (file shrinks)
513 input bytes
1024 bytes:  513 input bytes+pad to 1024
1024 bytes:  513 input bytes+pad to 1024


Tests for 'Unjam'

Case 1:  remove a user block from an HDF5 file, output to new HDF5 file
and user block file

The output file is the same HDF5 file with the user block removed.  The user block (including padding) is written to the designated file. The input file is unchanged.

Example invocation:  unjam -i ifile.h5 -o ofile.h5 -u ubout.txt

Correct Result:
  1. The output file (ofile) should have no user block.
    Test: H5Fget_user_blocksize should be 0.
  2. The output file should be the same HDF5 file as the input file
    Test:  
    1. h5dump ifile,
    2.  h5dump ofile, 
    3. compare dump output
  3. The output user block file should be the same as the original user block, including padding.
    Test:
    1. get H5Fget_user_blocksize from original
    2. compare (original user block) with ubout.txt
Table 11. Tests for Case 1

Case
Test
Input H5 file has small user block  (10 bytes)
cp withub10.h5 ta.h5; ./unjam -i ta.h5 -o tao.h5 -u ub10.txt
Input H5 file has user block  (513  bytes)
cp withub513.h5 ta.h5; ./unjam -i ta.h5 -o tao.h5 -u ub513.txt


Table 2. Correct results for tests
input HDF5 file with user block
Output HDF5 File
Output File User Block
512 bytes:   10 input bytes+pad to 512
0 bytes (no user block)
512 bytes:   10 input bytes+pad to 512
1024 bytes: 513 input bytes+ pad to 1024
0 bytes (no user block)
1024 bytes: 513 input bytes+ pad to 1024


Case 2:  remove a user block from an HDF5 file, rewrite the HDF5 file and write user block to file

The HDF5 file is rewritten without the user block removed.  The user block (including padding) is written to the designated file.

Example invocation:  unjam -i ifile.h5 -u ubout.txt

Correct Result:
  1. The input file (ofile) should have no user block.
    Test: H5Fget_user_blocksize should be 0.
  2. The input file should be the same HDF5 file as the original file
    Test:  
    1. h5dump ifile,
    2.  h5dump original 
    3. compare dump output
  3. The output user block file should be the same as the original user block, including padding.
    Test:
    1. get H5Fget_user_blocksize from original
    2. compare (original user block) with ubout.txt
Table 13. Tests for Case 2

Case
Test
Input H5 file has small user block  (10 bytes)
cp withub10.h5 ta.h5; ./unjam -i ta.h5 -u ub10.txt
Input H5 file has user block  (513  bytes)
cp withub513.h5 ta.h5; ./unjam -i ta.h5 -u ub513.txt


Table 2. Correct results for tests
Input HDF5 file with user block
HDF5 File after test
Output File User Block
512 bytes:   10 input bytes+pad to 512
0 bytes (no user block)
512 bytes:   10 input bytes+pad to 512
1024 bytes: 513 input bytes+ pad to 1024
0 bytes (no user block)
1024 bytes: 513 input bytes+ pad to 1024

Case 3:  remove a user block from an HDF5 file, rewrite the HDF5 file; don't write user block.

The HDF5 file is rewritten without the user block removed.  The user block (including padding) is siacarded.

Example invocation:  unjam -i ifile.h5 -u ubout.txt --delete

Correct Result:
  1. The input file (ifile) should have no user block.
    Test: H5Fget_user_blocksize should be 0.
  2. The input file should be the same HDF5 file as the original file
    Test:  
    1. h5dump ifile,
    2.  h5dump original 
    3. compare dump output
Table 13. Tests for Case 2

Case
Test
Input H5 file has small user block  (10 bytes)
cp withub10.h5 ta.h5; ./unjam -i ta.h5 -o ofile.h5  --delete
Input H5 file has user block  (513  bytes)
cp withub513.h5 ta.h5; ./unjam -i ta.h5 -o ofile.h5  --delete


Table 2. Correct results for tests
Input HDF5 file with user block
HDF5 File after test
Output File User Block
512 bytes:   10 input bytes+pad to 512
0 bytes (no user block)
not written
1024 bytes: 513 input bytes+ pad to 1024
0 bytes (no user block)
not written



Other Tests (Not Yet Implemented)

Test similar cases for different HDF5 files, especially:
  1. Small file, large user block
  2. Large HDF5 file
  3. File with  data after the end of HDF5
  4. File with external storage
  5. File with mounted file(?)
  6. Mount file with user block(?)
  7. File with object references (make sure object ref's are correct after adding/removing user block)
Test similar cases with binary data in the user block (instead of ASCII)