HP 3000 Manuals HP 3000 Manuals
KEYINFO
Displays information about the key file, and attempts recovery of a KSAM
file in case of system failure when the file is open.
{KEYINFO}
>{K1 } [filereference] [;OFFLINE] [;RECOVER]
KEYINFO performs two operations: it collects and displays information
about the key file, and it takes steps to recover the KSAM file in case a
system crash occurred when the file was open. The second operation is
performed only after a system crash or if the RECOVER parameter is
specified.
The key information displayed by KEYINFO consists of:
* Number of levels in key block structure:
* Number of key blocks
* Number of sectors per key block
* Number of keys in root block
* Number of keys in all blocks of the key file
* Percent of each key block used
* Largest key block address
The crash recovery performed by KEYINFO depends on the type of damage to
the file.
* If MPE end-of-file does not match end-of-file for KSAM data file,
KEYINFO resets the MPE end-of-file to match the KSAM end-of-file.
* If key file contains values that point to records past the KSAM
end-of-file, KEYINFO deletes these key values.
* If the key file end-of-file marker does not match the actual end of
the key file, KEYINFO corrects the key file end-of-file marker.
* If records in the data file do not have associated key values in the
key file, KEYINFO issues a warning that key values are missing.
PARAMETERS
filereference Actual file designator of the KSAM file; either the data
file name or the key file name may 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.
OFFLINE Directs output to the 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, output is sent to user's terminal.
RECOVER Forces KEYINFO to perform recovery procedures even
though no system crash occurred.
(Optional parameter.)
Default: If omitted, recovery performed only if system
crashed with file open.
REQUESTING KEY FILE INFORMATION
Information is displayed by KEYINFO for each key in the key file, in key
order starting with the primary key. For example, request KEYINFO for
the file DATAFIL which has three keys:
>KI DATAFIL
--------- INFO FOR KEY 1 ---------
# OF LEVELS OF B-TREE 1
# OF KEY BLOCKS 1
# OF SECTORS PER KEY BLOCK 8
# OF KEYS IN ROOT KEY BLOCK 20
# OF KEYS IN B-TREE 20
% OF KEY BLOCK UTILIZATION 38.4
THE LARGEST KEY BLOCK ADDRESS 2
--------- INFO FOR KEY 2 ---------
# OF LEVELS OF B-TREE 1
# OF KEY BLOCKS 1
# OF SECTORS PER KEY BLOCK 8
# OF KEYS IN ROOT KEY BLOCK 20
# OF KEYS IN B-TREE 20
% OF KEY BLOCK UTILTZATION 9.9
THE LARGEST KEY BLOCK ADDRESS 10
--------- INFO FOR KEY 3 ---------
# OF LEVELS OF B-TREE 1
# OF KEY BLOCKS 1
# OF SECTORS PER KEY BLOCK 8
# OF KEYS IN ROOT KEY BLOCK 20
# OF KEYS IN B-TREE 20
% OF KEY BLOCK UTILIZATION 13.8
THE LARGEST KEY BLOCK ADDPESS 18
>EXIT
# OF LEVELS OF B-TREE - Key files are organized in a structure known as a
"B-Tree". This structure may have one or more levels (for details refer
to appendix B). The file DATAFIL has only one level.
# OF KEY BLOCKS - Key values are stored in blocks; this entry gives the
total number of key blocks in the file. DATAFIL has only one key block.
# OF SECTORS PER KEY BLOCK - A key block may require one or more 128-word
sectors. DATAFIL uses eight sectors for its key block (the default
value).
# OF KEYS IN ROOT BLOCK - This specifies the number of key values stored
in the root block (in this case the only block). If this number is equal
to the key blocking factor (see KEY BF header in VERIFY output), then the
next key block split will increase the number of levels in the B-Tree by
one. DATAFIL has 20 key values in its root block, and the blocking
factor allows 52, 202, or 144 (see VERIFY printout below).
>VERIFY DATAFIL
WHICH (1=FILE INFO, 2=KSAM PARAMETERS, 3=KSAM CONTROL, 4=ALL)?2
KEY ENTITY=KEYFIL KEY FILE DEVICE=2 SIZE= 50 KEYS= 3
FLAGWORD(000000)=RANDOM PRIMARY, FIRST RECORD=0, PERMANENT
KEY TY LENGTH LOC. D KEY BF LEVEL
|
|----------- blocking factor, keys/block
1 B 30 1 Y 52 1
2 B 2 31 Y 202 1
3 B 6 33 Y 144 1
# OF KEYS IN B-TREE - This is the total number of key values in the key
file for each key. This number should be the same for each key and
should also be the same as the number of active records in the data file
(to determine this, use the FCOPY command >FROM=DATAFIL;TO=$NULL ;KEY=O.
FCOPY is described later in this section). DATAFIL has 20 key values in
each B-Tree, and this is the same number as the number of active data
records (see FCOPY output below).
:RUN FCOPY.PUB.SYS
HP32212A.3.08 FILE COPTER (C) HEWLETT-PACKARD CO. 1978
>FROM=DATAFIL;TO=$NULL;KEY=0
EOF FOUND IN FROMFILE AFTER RECORD 19 <---- records numbered from 0
20 RECORDS PROCESSED *** 0 ERRORS
% OF KEY BLOCK UTILIZATION - Average percent of use of all key blocks
(percent of use means how much of the block contains key values). Note
that the root block of a multi-level tree is omitted from this average.
For multi-level trees the percent is between 50% and 100%, for
single-level trees between 0% and 100%. The higher the percentage, the
faster the retrieval of data. But, also the higher the percentage, the
greater the chance of block splits when records are added. DATAFIL uses
38.4% for its primary hey, 9.9% and 13.8% each for its two alternate
keys.
THE LARGEST KEY BLOCK ADDRESS - This is the largest key block address
found for each key. The key file end-of-file should never be less than
the largest block address for the file plus the number of sectors per key
block. The largest block address for DATAFIL is 18 (the largest block
address for DATAFIL is 18 (the largest block address of key 3). Since
the number of sectors per block is 8, the key file end-of-file should be
at least 26 (see VERIFY output below).
WHICH (1=FILE INFO, 2=KSAM PARAMETERS, 3=KSAM CONTROL? 4=ALL)?3
DATA FILE = DATAFIL VERSION= A.2.1
KEY CREATED=292/'78 10:19: 7.4 KEY ACCESS= 107/'79 12: O: 2.9
KEY CHANGED= 93/'79 14:18: 7.6 COUNT START=292/,78 10:19:53.6
DATA RECS = 20 DATA BLOCKS= 19 END BLK WDS= 19
DATA BLK SZ= 19 DATA REC SZ= 38 ACCESSORS= 0
FOPEN 2 FREAD 0 FCLOSE 2
FREADDIR 0 FREADC 0 FREADBYKEY 0
FREMOVE 0 FSPACF 57 F'FINDBYKEY 0
FGETINFO 2 FGETKEYINFO 1 FREADLABEL 0
FWRITELABEL 0 FCHECK 0 FFTNDN 3
FWRITE 20 FUPDATF 0 FPOINT 0
FLOCK 0 FUNLOCK 0 FCONTROL 0
FSETMODE 0
KEYBLK BEAD 7 KFYBLK WROTE 0 KEYBLK SPLTT 0
KEY FILE EOF 26 FREE KEY HD 0 SYSTEM FAILURE 0
|-----------------file end-of-file for DATAFIL
MIN PRIME 11 MAX PRIME 5 RESET DATE 67/'79
DATA FIXED TRUE DATA B/F 1 TOTAL KEYS 3
FIRST PECNUM 0 MIN PECSIZE 38
RECOVERING AFTER SYSTEM FAILURE
KEYINFO only performs the recovery operations if there has been a system
failure or if you specify the RECOVER parameter.
If there has been a system failure while the KSAM file is open for
non-read access, a flag is set that prevents the file from being opened.
Whenever this occurs, KEYINFO must be used in order to reset this flag so
that the file can be opened. KEYINFO also recovers from any damage done
to the file as a result of the system failure. It resets end-of-file
markers for both the data and key files, and deletes any key values that
point to records beyond the data file end-of-file. It also stores in the
key file the user, group, account, and home group of the user who runs
KEYINFO to recover the file. (When there has been a system failure or
when KEYINFO is run with the RECOVER option, the KSAM file is opened for
exclusive access; otherwise it is opened for shared access.)
When KEYINFO is run after a system failure, the SYSTEM FAILURE count
displayed by option 3 of VERIFY is incremented by 1. If there was no
system failure but KEYINFO was run with the RECOVER option, this count is
not incremented.
When KEYINFO resets the "crash" flag, the date of this reset is saved and
can be recovered through the VERIFY command, option 3 under the heading
RESET DATE. Note that the NOCHECK option of VERIFY allows that command to
open a KSAM file for read-only access even if a system failure prevents
the file from being opened for all other access.
For example, assume a file TEST that was open when a system failure
occurred. In this case, KEYINFO must be run. Also, assume the
following:
* The data file end-of-file (at the end of the data) is beyond the MPE
end-of-file (not yet written to file when system failed).
* There are key values beyond the key file end-of-file (internal key
file EOF).
* There are data values with no associated key values.
Running KEYINFO will correct the end-of-file markers and, if any keys
point to data records beyond the data file end-of-file, it will delete
these key values. KEYINFO cannot, however, restore missing key values.
To do this, you must reload the file with FCOPY. To illustrate, KEYINFO
operates as shown below:
>KI TEST
RECOVERY BEGINS
DATA FILE EOF DAMAGED reset end-of-file
for data file
DATA FILE MPE EOF HAS BEEN RESET TO KSAM EOF
-------- INFO FOR KEY 1 ---------
# OF LEVELS OF B-TREE 2
# OF KEY BLOCKS 16
# OF SECTORS PER KEY BLOCK 8
# OF KEYS IN ROOT KEY BLOCK 14
# OF KEYS IN B-TREE 1000<------|
# OF KEY BLOCK UTILIZATION 52.1 |
THE LARGEST KEY BLOCK ADDRESS 210 |
|
--------- INFO FOR KEY 2 --------- # of keys
should match
# OF LEVELS OF B-TREE 2 |
# OF KEY BLOCKS 11 |
# OF SECTORS PER KEY BLOCK 8 |
# OF KEYS IN ROOT KEY BLOCK 9 |
# OF KEYS IN B-TREE 997<------|
# OF KEY BLOCK UTILIZATION 68.6
THE LARGEST KEY BLOCK ADDRESS 202
WARNING: THERE ARE SOME RECORD(S) WITH KEY VALUE(S) MISSING
OR KEY VALUE(S) POINTING TO DATA RECORD BEYOND EOF
KEY FILE EOF(INTERNAL) DAMAGED
reset key file end-of-file
KEY FILE (INTERNAL)EOF HAS BFEN RESET
--------- KEY SEQUENCE 1---------
# OF INVALID KEY VALUES DELETED 10 keys pointing to non-existent
data records are deleted
--------- KEY SEQUENCE 2 ---------
# OF INVALID KEY VALUES DELETED 10
RECOVERY ENDS
WARNING: THERE ARE SOME RECORD(S) WITH KEY VALUE(S) MISSING
THE KSAM FILE HAS TO BE RELOADED
In this case, the file must be reloaded in order to add the missing key
values to the key file. For a full discussion of recovery procedures in
case of system failure, including how to reload your file, refer to
appendix E.
USING RECOVER OPTION
Even if a system failure does not occur, you can run KEYINFO with the
RECOVER option in order to check the file structure.
The RECOVER option forces KEYINFO to correct any end-of-file
inconsistency, including the key file end-of-file, and to delete any
invalid key values. This option sets the RESET DATE field of the VERIFY
output to the current date, and saves your user name, account, group, and
home group, but does not increment the SYSTEM FAILURE count displayed by
VERIFY.
Note that checking each record and key in a file with a lot of data is
very time consuming. Therefore, you should not use RECOVER unless it is
necessary to reconstitute your file.
For example, use KEYINFO with RECOVER to validate file TEST:
>KI TEST;RECOVER
RECOVERY BEGINS
--------- INFO FOR KEY 1 ----------
# OF LEVELS OF B-TREE 1
# OF KEY BLOCKS 1
# OF SECTORS PER KEY BLOCK 8
# OF KEYS IN ROOT KEY BLOCK 10
# OF KEYS IN B-TREE 10
% OF KEY BLOCK UTILIZATION 4.9
THE LAPGEST KEY BLOCK ADDRESS 2
--------- KEY SEQUENCE 1 ----------
# OF INVALID KEY VALUES DELETED 0
RECOVERY ENDS
If you now run VERIFY, using option 3, you will see that the date of
recovery is displayed following the heading RESET DATE.
>V
WHICH (1=FILE INFO, 2=KSAM PARAMETERS, 3=KSAM CONTROL, 4=ALL)?3
DATA FILE = TEST VERSION= A.2.4
KEY CREATED= 86/'79 13:55:23.6 KEY ACCESS= 114/'79 14: 1:14.9
KEY CHANGED=114/'79 13:55:48.8 COUNT START= 96/'79 13:55:49.2
DATA RECS = 10 DATA BLOCKS= 9 END BLK WDS= 8
DATA BLK SZ= 8 DATA REC SZ= 16 ACCESSORS= 0
FOPEN 2 FREAD 0 FCLOSE 2
FPEADDIR 0 FPEADC 0 FREADBYKEY 0
FPEMOVE 0 FSPACE 9 FFINDBYKEY 0
FGETINFO 2 FGETKEYINFO 1 FREADLABEL 0
FWRITELABEL 0 FCHECK 0 FFINDN 1
FWRITE 10 FUPDATE 0 FPOINT 0
FLOCK 0 FUNLOCK 0 FCONTROL 0
FSETM0DE 0
KEYBLK READ 3 KEYBLK WROTE 1 KEYBLK SPLIT 0
KEY FILE EOF 10 FREE KEY HD 0 SYSTEM FAILURE 0
MIN PRIME 0 MAX PRIME 9 RESET DATE 114/'79
DATA FIXED TRUE DATA B/F 1 TOTAL KEYS 1
FIRST RECNUM 0 MIN PECSIZE 2