KEYDUMP

DUMPING THE KEY FILE

The dump produced by KEYDUMP consists of three columns: the first contains the key value, the second a pointer to a record number in the data file, and the third contains the key block address and the number of key values in that block. The key block address is given as the record number of the first record in any block.

For example, assume that TESTFILE contains an INTEGER type primary key whose values we want to see. Run KEYDUMP as follows:

 

   :RUN KSAMUTIL.PUB.SYS 

   >KEYDUMP TESTFILE 

The resulting dump consists essentially of three columns: one contains the key values in ascending sequence, another contains the record number (or word offset if record size is variable) of the associated record in the data file, and the third gives the record address of the key block. A sample dump is shown below:

This dump lists under the heading "KEY" 14 integer key values in ascending order from 0001 through 0014. The next column under "REC.PTR." lists the record number of the data record associated with the key value -- thus, key value 0001 is in record number 3 of the data file (the fourth record in chronological sequence), and key value 0006 is in the first record in the data file, record number 0. The third column under "KEY BLOCK ADR." shows the address of the key block in which each key value resides, The key block address is shown as the record number of the first record in the key block. (Note that KSAM key files use fixed length records each one sector long -- 128 words. Thus, the record number is also the sector number. A keyblock consists of more than one sectors -- default is 8 sectors).

Key values are organized into blocks using a B-Tree structure (refer to appendix B for details). This structure has one or more levels where the first or highest level, is known as the "root" and lower level are "leaves". This dump shows the level structure of the key file by indenting the key block addresses to correspond to levels. The highest or root level address is in the rightmost column, lower levels are listed to the left. By looking at the key block address, we see that the key block starting at record (sector) 6 is the root block, and that there are three key blocks at a lower level whose addresses start, respectively, at records 2, 18, and 24. This key file has two levels; a key file with more levels would have correspondingly more columns under the key block address heading.

The first time a key block address is listed, it is followed in parentheses by the number of key values in that block. Looking at the dump, we see that the block starting at record 2 has 4 key values, the block at record 6 has 2 values, the block at record 18 has 5 values, and the block at record 24 has 3.

With this dump, we can picture the structure of the key file associated with the file TESTDUMP:

The key values are shown within their key blocks; the dashed lines show the pointers that link key blocks in ascending sequence.

DUMPING A SUBSET OF THE KEY FILE

If you want to dump a selected number of key values rather than all the values in a key, you can use the SUBSET option of KEYDUMP. The starting key value can be located in two ways: if you know the key number of the first key value you want displayed, use the SUBSET=position format; if you know the actual key value (or a value less than the key value), then you can use the SUBSET="string" format. In either case, the second SUBSET parameter is always an integer that indicates the number of key values you want dumped.

BY KEY NUMBER

The key number is the sequential number associated with each key value in a particular key. If the KEYSEQ command has listed key numbers that are out of sequence, you may want to dump only these values. Suppose that TESTFILE has out of sequence values, the following example runs KEYSEQ first and then runs KEYDUMP to dump the key values shown as out of sequence. (ln order to see the last value in correct sequence, the key preceding the first key out of sequence is selected as the first key to dump.)

 

   >KS TESTFlLE 

   KEY VALUE # (FOR KEY VALUE OUT OF SEQUENCE) 

   6<-----------------------------|

   7                              |

   8                           values used for SUBSET= of KEYDUMP 

   9                                         |

   TOTAL # OF KEY VALUES READ 14             ↓

   # OF KEY VALUES OUT OF KEY SEQUENCE ORDER 4 -- values used for SUBSET= of KEYDUMP 

   KEY FILE STRUCTURE DAMAGED, KSAM FILE HAS TO BE RELOADED 

   >KD TESTFILE ;SUBSET=5,5 <------- number of key ualues out of sequence (Plus 1) 

                        ↑ 

                        |----- key preceding first key # out of sequence 

The following dump shows the last key value in sequence followed by the key values that are out of sequence:

 

                KEY            REC.PTR.             KEY BLOCK ADR.



1st key out    0005            3                            12(2) 

of sequence--->0008            9                    18 (5) 

               0007            4                    18 

               0009            7                    18 

               0006            0                    18 

BY KEY VALUE

The second version of SUBSET= specifies an actual key value followed by the number of key values. You need not specify the exact key value; it can be a value less than an actual Integer or Double type key value (approximate match) or only the first part of a Byte type key value (generic match). For example, suppose TESTFILE has an alternate key that contains names in alphabetic order and you want to look at the ten key values that start "GI" or the next greater value. Specify the following command:

 

     >KD TESTFILE ;SEQ=2 ;SUBSET="GI",10 

                       ↑          \____/

                       |            | 

                       |            ---------- dump 1st 10 values

                       |                       starting with or 

                       |                       greater than "GI" 

                       ------ 1st alternate key 

The dump appears as follows:

 

   KEY          REC.PTR.          KEY BLOCK ADR.


   GIBBS        3                 2 (4) 
   GILLESPIE    12                2 
   GLADSTONE    4                 2 
   HERTZ        8                 2 
   HIGGINS      0                 -     8(3) 
   JONES        7                 16(4) 
   LOOMIS       13                16 
   MORRIS       5                 16 
   MYERS        6                 16 
   NOLAN        1                 -     8 

SORTING DUMP BY RECORD POINTER

If you use the SORT option of KEYDUMP, you must also specify ENTITY =filename, where the specified file name is that of a disc file. (Note that you must not name an existing file; a new file is created for the dump.) In this case, you might also want to suppress the indention of the key block address levels. To do this, enter the following command:

 

                                 |------suppress key block address indentation 

                                 ↓ 

>KD TESTFILE;FILE =MYFILE;SUBSET=-1,500;SORT <--- sort by record pointer 

                   ↑ 

                   |---- dump is sent to MYFILE, created with default values 

The resulting dump is sent to a disc file MYFILE, created with a default block size of 10 words, one record per key entry. The key entries are sorted by the pointers to the records in the data file. Indentation of the key block address is suppressed. The key values, record pointers, and key block addresses are not converted to ASCII but are dumped to the specified file in binary format. In case of a file with 500 or fewer key values, the entire file is dumped.

The SORT option is useful if you want to look at key values in terms of the data records to which the key values point. For example, in order to determine whether any key values are missing, you can dump all the keys in a file using the SORT option, and compare the record numbers in each dump to make sure each record has the same number of key values pointing to it.