HP 3000 Manuals HP 3000 Manuals
KEYDUMP
Provides formatted, structural dump of key file.
{KEYDUMP}
>{KD } [filereference] [;SEQ=keysequence]
[;SUBSET= {[-]position "string"} [,number]]
[;FILE =formaldesignator] [;OFFLINE] [;SORT]
The key file dump consists of three items of information for each key
value:
1. Key Value The actual value of each key in ascending order
2. Record Pointer The record number (fixed-length files) or word offset
(variable-length files) of the data record to which
the associated key value points.
3. Key Block Relative record number of the first record in the key
Address block containing the associated key value, followed
within parentheses by the number of key values in the
block. The addresses of key blocks at different
levels are indented.
This dump is very useful for examining the contents of any key file.
Since key blocks are physically scattered throughout the key file, linked
by pointers, it is difficult to follow an unstructured dump of a key
file. The KEYDUMP display shows the contents of the key file, not as
they are actually stored, but in a way that makes it much simpler to read
than a dump of the actual file.
One key at a time is dumped by KEYDUMP. If there is more than a primary
key, you must run KEYDUMP for each key in order to dump the entire key
file.
Note that you can use CNTL/Y (the CNTL key held down while pressing the Y
key) to stop display of this dump at any time. This is particularly
useful if you display the dump at the terminal. Usually, however, you
will use the OFFLINE option to list the dump on a line printer (see
Parameter description, below).
You can choose to dump a subset of the key file contents based on the key
number or a key value. You can send the dump to a particular file and,
if so, you can sort the key file contents by the record number in the
data file rather than by key value. You can also send the dump to a line
printer.
PARAMETERS
filereference Actual file designator identifying the KSAM file whose
key file is to be dumped; either the data file name or
the key file name can be specified. The filereference
can be a back reference to a file named in an MPE :FILE
command.
(Optional parameter if no parameters are specified.)
Default: If omitted, the last file referenced is
assumed.
SEQ= Specify a particular key whose contents are to be
keysequence dumped. The primary key, whatever its location in the
data record, is always key number 1 (SEQ=1). Alternate
keys are numbered according to the order in which they
are specified in the BUILD command (or in ksamparam at
FOPEN). The first alternate key is specified as SEQ=2,
the next alternate key as SEQ=3, and so forth.
(Optional parameter.)
Default: If omitted, the primary key is selected.
SUBSET= Select a portion of the key file to dump, based on the
numeric position of the key or the key value, and the
number of key values.
[-]position Start dump with key whose number is specified. This
number is the same as the key number issued by KEYSEQ.
It corresponds to the position of the key value in the
file in ascending sequence. Thus the first key value is
position 1, the second is position 2, and so forth.
The optional minus sign suppresses the normal
indentation by key levels of the key block address
display.
"string" Start dump with first key value greater than or equal to
the specified string.
,number Indicates the number of key values to be dumped starting
with the key at the indicated position or whose value is
indicated by "string".
(Optional parameter.)
Default: If omitted, all the key ualues for selected
keys are dumped.
FILE =filename Direct key file dump to specified disc file. A disc
file (filename) will be created with a record size equal
to the size of a key entry, that is keylength (rounded
up to full words) + four words.
The four words are needed for the record pointer (2
words) plus the key block address (2 words). Note that
a new file is always created, so do not name an existing
file.
The file has a default block size of 1K words. Any of
the file characteristics except the record size can be
changed by a :FILE statement. For example:
>:FlLE FILEDUMP ;REC=,100 ;DEV=TAPE
>KEYDUMP MYFILE ;ENTITY =*FILEDUMP
These commands dump the primary key sequence to a tape
with 100 records per block.
(Optional parameter.)
Default: If omitted, key dump is sent to terminal.
OFFLINE Direct output to a line printer. An MPE :FILE command
can be used to indicate a different output device or a
particular line printer.
(Optional parameter.)
Default: If omitted, the dump is sent to the user's
terminal.
SORT Sort dump by record pointers rather than key values.
The record pointers indicate the record number of the
records in a data file with fixed length records or the
word offset of the records in a data file with
variable-length records.
Note that this option can be used only when the dump is
directed to a specific file with the ENTITY = option.
(Optional parameter.)
Default: If omitted, key dump is in ascending sequence
by key value.
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:
![[]](../../pic3k/M010088/F0201G3c50.gif)
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:
![[]](../../pic3k/M010088/F0201H3c50.gif)
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.