RMSCK C-1





Copyright (C) 1994-95 Conetic Software Systems, Inc. All names, products, and services mentioned are the trademarks of their respective organizations.



NAME


rmsck - check RMSfiles for consistency

SYNOPSIS


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

DESCRIPTION


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.