RMSCK

NAME

rmsck - check RMSfiles for consistency

SYNOPSIS

rmsck[ -afeynsqxk ] [-b dbname] [-v n] [-t n] file [file...]

Rmsck examines C/Base RMSfiles and checks their contents for consistency. Rmsck makes a detailed examination of the data stored in the RMSfiles, and will repair (if given permission) any errors it finds.

The following flags are recognized by rmsck:

-y Answer Yes to all questions.

-n Answer No to all questions.

-s Answer Skip to all questions.

-q Answer Quit to all questions.

If rmsck finds an error, it describes the error and then asks for the action to be taken. For example, if there were a record that was in the RMSfile, but for some reason the record keys were not in the RMS index file, rmsck would announce:

NUMBER OF KEYS IN INDEX 0 NOT EQUAL TO

NUMBER OF ACTIVE RECORDS

REBUILD THIS INDEX?

When asked a question, you may respond Yes, No, Skip, or Quit. Answering Yes performs the action; answering No does not, and continues processing the RMS-file; answering Skip stops processing the current RMSfile and starts checking the next RMSfile; and answering Quit terminates rmsck. You may specify the answer to all questions in advance by using the -y, -n, -s, or -q command line flag. For example, -n will check all the RMSfiles, but not make any changes.

-b dbname

Check all RMSfiles in database dbname.

-a Check all RMSfiles in database catalog.

These two command line flags simplify the selection of RMSfiles. The -b flag lets you name a database to be checked; all the RMSfiles in that database are checked by rmsck. The -a flag checks all RMSfiles in all databases. These two flags use the database catalog to find the RMSfiles to be scanned. Rmsck first checks the database catalog itself for consistency when these two flags are used.

-e Test only that RMSfiles exist. This flag is used in conjunction with the -b or -a flag to confirm that the RMSfiles named in the database catalog actually exist without being required to also check the contents of each RMSfile for consistency.

-v n Set message level to n (0-3). Rmsck issues status messages while it is running. You can modify the message level and thus change the number of status messages that are given. When rmsck starts, the message level is 1, and each RMSfile name is printed while it is processed. A message level of 0 prints no status messages. Message levels 2 and 3 give more description of the progress of rmsck.

-t n Use n byte table when rebuilding index. See the description of this flag in the OPERATION section below.

-x Rebuild index using external sort. See the description of this flag in the OPERATION section below.

-k Confirm that index key values match record contents. See the description of this flag in the OPERATION section below.

OPERATION

Rmsck makes several passes over each RMSfile. To understand the process rmsck follows, a detailed understanding of the structure of RMSfiles is needed. See Section 4.2,

"Data File Organization", in the C/Base Utilities manual for a discussion of the internal RMSfile organization. The following discussion is not necessary to successfully run rmsck, but will let the curious reader understand its operation.

Pass 1 examines the status of each data record and builds a map of all the active, deleted, and unused records.

Pass 2 examines the deleted record list and confirms that the list points to only deleted records and that all deleted records are included in the list. This pass rebuilds the deleted record list if necessary.

Pass 3 examines the RMS index file. It scans each index in the RMS index file and checks that the index keys are in ascending order, that each active record is represented in the index exactly once, and that the index page connectivity is correct. If the -k flag is used, rmsck will read the record referenced by each index entry, and confirm that the key values in the index entry are also in the fetched record. Since this will significantly slow the operation of rmsck, this procedure is optional. Rmsck remembers which indexes, if any, are in error, and they are corrected in pass 5.

Pass 4 checks the list of deleted index pages and rebuilds the list if necessary.

Pass 5 is only run if there were errors in the RMS index file. This pass rebuilds either the entire RMS index file, or if only a single index in the file is corrupted, it will rebuild just that index.

When rebuilding an index, rmsck reads each data record, and builds a table in memory to hold the key values. When the table is filled, it is sorted, and then the keys are written (in order) to the RMS index file. If all the record keys will not fit in the table in memory, then

this process is repeated until all the records have been read.

Filling the table and writing its sorted contents into the index is called a batch. Rmsck uses a custom version of RMS that efficiently adds record keys when they are in ascending order, and there are not other record keys already in the index. Rmsck may run slower if many batches are necessary to process one index, as each batch must be merged into the batches already contained in the index.

There are two solutions available for this. By default, rmsck allocates a table less than 32K bytes. The -t flag lets you set a much larger table size, thus reducing the number of batches necessary. Because of processor restrictions, you cannot increase the batch size on Intel 8086 and 80286 processors.

The second solution is to use the -x flag. This does not use the internal memory table, but instead creates a text file containing the record keys, uses an external sort program to sort all the keys simultaneously, and then adds all the record keys in one batch.

Neither of these command line flags is required. Rmsck will always work properly without them. In fact, rmsck will automatically select the -x flag if more than 10 batches are necessary to rebuild an index. Using these flags will speed up rmsck when dealing with very large RMSfiles.

When rmsck has completed examining all the RMSfiles, it displays a total of the number of files with errors. If there are any files with errors, the program also exits with a non-zero status.

SEE ALSO

rbldidx(C-1).

DATA FILE ERROR MESSAGES

DATA RECORD n HAS INVALID STATUS

This error normally only occurs when an RMSfile and an RMS data dictionary are out of sync; for example, by copying the dictionary of one RMSfile on top of the dictionary for a different file. Before fixing records, check that the file and dictionary belong together.

ERROR READING DATA RECORD n

This error is displayed when there is an I/O error reading an RMSfile.

ERROR WRITING DATA RECORD n

This error is displayed when there is an I/O error writing an RMSfile.

PREMATURE END OF FILE, RECORD n

While reading the records sequentially, the end of the RMSfile was reached before all the records (according to the dictionary) were read.

FILE LONGER THAN EXPECTED

While reading the records sequentially, the end of the RMSfile was NOT reached after reading the last record (according to the dictionary).

NUMBER OF DELETED RECORDS NOT EQUAL TO NUMBER OF RECORDS IN DELETED RECORD LIST

The deleted record list is incorrect and must be rebuilt.

ACTIVE OR UNUSED RECORD IN DELETED RECORD LIST

The deleted record list includes a record that has not been deleted. The deleted record list must be rebuilt.

FILE IS READ ONLY AND CANNOT BE FIXED

You do not have write permission for either the RMSfile or the RMS index file. No changes can be made. You can continue to scan this RMSfile for errors, but no errors can be corrected.

CANNOT LOCK DATA FILE; FILE SKIPPED

Someone else is using the RMSfile, so it is unsafe to modify the file. The RMSfile is checked only when it is possible to modify it.

INDEX FILE ERROR MESSAGES

ERROR WRITING INDEX PAGE n

This error is displayed when there is an I/O error writing the RMS index file.

KEYS OUT OF ORDER

This message is displayed, along with the incorrect values, when the keys in the index are not in ascending order. The index must be rebuilt.

NUMBER OF KEYS IN INDEX n NOT EQUAL TO NUMBER OF ACTIVE RECORDS

There are either too many or too few index entries in an index. The index must be rebuilt.

INDEX FILE HAS INVALID LENGTH

The RMS index file is not an exact multiple of the size of an index page. The RMS index file must be rebuilt.

INVALID PAGE NUMBER n IN INDEX

Each index page has pointers to other index pages in the index. An out of range index page number has been found. The index must be rebuilt.

INDEX HAS CROSS LINKS; PAGE n

An index page is referenced by two or more other index pages. Each index page should be referenced exactly once. The index must be rebuilt.

NUMBER OF DELETED INDEX PAGES NOT EQUAL TO NUMBER OF PAGES IN DELETED INDEX PAGE LIST

The deleted index page list is incorrect and must be rebuilt.

STRANGE INDEX PAGE FORMAT

Rmsck cannot decipher the contents of an index page. The index must be rebuilt.

INVALID RECORD NUMBER n IN INDEX

Each key value in an index contains a record number. Some key contains an illegal record number. The index must be rebuilt.

INCORRECT KEY VALUE FOR RECORD NUMBER n IN INDEX

The -k flag has been used, and the record contents does not match the key value in the index. The index must be rebuilt.

INDEX ENTRY POINTS TO DELETED RECORD NUMBER n

An index key value contains the record number of a deleted record. The index must be rebuilt.

TWO INDEX ENTRIES POINT TO RECORD NUMBER n

A data record is referenced by two different key values in the same index. The index must be rebuilt.