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

KEYINFO

Technical documentation

» Table of Contents

PARAMETERS

REQUESTING KEY FILE INFORMATION

RECOVERING AFTER SYSTEM FAILURE