DOCUMENT #713
=======================================================================
CHECKING DATABASE INTEGRITY
=======================================================================
PRODUCT: R:BASE VERSION: 3.1 or Higher
=======================================================================
CATALOG: Data Integrity AREA : Pointers
=======================================================================
You should always check your database for errors before making a
backup. After all, a corrupt backup isn't a good backup. And errors
accessing data such as, "Disk problems. Please check disk and files"
should be investigated for possible database damage.
Microrim provides three different ways to check your database
structure and data pointers: AUTOCHK, RBCHECK, and R:SCOPE. Both
AUTOCHK and RBCHECK are included with R:BASE 3.x and 4.x. R:SCOPE is
a separate product that can be purchased from our Sales Department
(800-628-6990).
AUTOCHK is a small program that can be easily incorporated into an
application and called with ZIP (see README.TXT for examples using
AUTOCHK). AUTOCHK returns a value to the R:BASE error variable. An
AUTOCHK value other than 0 indicates damage to the database. AUTOCHK
does not check the entire database, it stops checking as soon as it
encounters an error. To get a complete picture of the possible damage
in the database you need to use either RBCHECK or R:SCOPE.
R:SCOPE is the most complete of the three database checking tools; it
checks database structure, data pointers and indexes. It also
incorporates database correction features. The R:SCOPE documentation
includes detailed information about R:BASE database file structure
and data storage. But you may not have R:SCOPE and you'd like to know
the possible damage right away. Even having R:SCOPE sent overnight
may not be quick enough.
RBCHECK is an undocumented utility designed for use by Technical
Support to help diagnose database problems. When you call Technical
Support and it sounds like you might have database damage, we'll
suggest that you run RBCHECK. RBCHECK checks the structure file
(1.RBF) and the pointers in the data file (2.RBF), it does not check
the index file (3.RBF). RBCHECK does not correct damaged databases,
it only indicate if there is damage.
Note: R:BASE 4.5 names the database files dbname.rb1, dbname.rb2 and
dbname.rb3. To check a 4.5 database you need the 4.5 version of
R:SCOPE or AUTOCHK. The 4.5 version of AUTOCHK incorporates the full
database checking features of RBCHECK.
Using RBCHECK
=============
RBCHECK is executed at the operating system prompt, not from within
R:BASE. You can run RBCHECK from the directory where the database is
located, or from the RBFILES directory indicating the drive and
directory location of the database. When running RBCHECK, you must
direct the output to see all the results. RBCHECK requires the
database owner password if one has been defined.
RBCHECK stops checking data in a table when it hits an error. It may
not report all the errors in a table. After correcting the reported
errors, run RBCHECK again.
You cannot run RBCHECK against a database that is currently being
used. Everyone using a database must be disconnected from the database
or exited from R:BASE in order to check the database.
Be sure to use the correct version of RBCHECK. Don't use the version
of RBCHECK that came with R:BASE 3.1A to check a database that you are
now working on with R:BASE 4.0. A current version of RBCHECK is
included with each version of R:BASE. If checking databases used with
R:BASE prior to 3.x, be aware that many names may be reported as errors
in the structure check. RBCHECK checks for legal names based on the 3.x,
4.x rules. The R:TOOLS version of RBCHECK (RBCHECK2.EXE) is available on
the BBS as well as the 4.x version. Use the R:TOOLS version to check
databases from earlier versions of R:BASE (R:BASE for DOS, 2.11, or
System V).
Examples of RBCHECK syntax, checking the sample database Concomp:
RBCHECK concomp
---------------
Results scroll across the screen without pausing. If there is an owner
password defined, RBCHECK stops and prompts for the password. Use this
syntax for a quick check, total errors are reported at the end of the
output.
RBCHECK concomp |more
---------------------
The check results pause on the screen page by page, you can read them
but once they've gone by you must redo the command to see them again.
More is a DOS utility that displays output a page at a time. The
output is not displayed until the check has completed. Because the
output is redirected (to the program More), you don't see the password
prompt if your database has an owner password defined. The program
simply waits for keyboard entry. After the copyright message displays,
type in your owner password.
RBCHECK concomp >check.dat
--------------------------
This is the recommended syntax. The check results are directed to a
file called check.dat. You can replace check.dat with a filename of
your choosing. View the output file at the DOS prompt by entering TYPE
CHECK.DAT |MORE, the file displays page by page. In R:BASE, the
command TYPE CHECK.DAT at an R> prompt also displays the file page
by page. You can load the file into a word processor, use the R:BASE
editor, or print the file. Because the output has been redirected (to
the file check.dat), you do not see the password prompt if your
database has an owner password defined. The program simply waits for
keyboard entry. After the copyright message displays, type in your
owner password.
RBCHECK -Upassword concomp >check.dat
-------------------------------------
The check results are directed to a file called check.dat. The -U
option tells RBCHECK that the letters immediately following are the
owner password for the database.
It is recommended to direct the RBCHECK results to a file. The results
can be easily viewed or printed.
Interpreting the results and correcting errors
====================================================
RBCHECK error messages are cryptic and intended for internal use. The
first step is understanding the error messages, second is figuring out
what to do about the error. The most common errors are described below.
If you get an error that's not listed below, call Technical Support.
RBCHECK checks and reports errors in two groups: file 1 (structure)
and file 2 (data). File 1 is further broken down into database
parameters and relation & column tables. RBCHECK reports the name of
the table it's checking and any errors are reported immediately
following the table (or column) name.
The number and type of errors indicate what to do in response to the
errors. Some errors can be ignored, some can't be easily fixed.
Generally you want to evaluate the time and effort needed to correct
the errors versus restoring a backup copy and reentering data. The
article "Understanding Data Pointers" in this Exchange has additional
information on correcting database errors.
Correcting the errors again depends on what the errors are. Sometimes
an error is easily corrected if it is the only one you have, but in
combination with other errors can be difficult to correct. Some errors
are corrected in R:BASE, others with R:SCOPE, still other errors
require restoring the database backup.
In general, if the only reported errors are in the structure file
(1.RBF), and you can view all the data in the tables with errors,
the errors can be corrected by using the R:BASE BACKUP/RESTORE or
UNLOAD/INPUT commands. For further information on UNLOAD/INPUT you
can download document #637 from Microrim's automated fax server at
(206) 649-2789. To correct structure errors, you need to recreate the
structure file in R:BASE and then load the data. Do not attempt to
correct structure errors in R:SCOPE; and do not try to replace the
structure file with an older copy of the file. Structure errors are
often best corrected by restoring the backup copy of your database.
If you have errors in the data file (2.RBF), you can use RSCOPE to
fix the errors. Some tables can be corrected in R:BASE using the
PROJECT method with an indexed column.
If you are unsure of how to proceed to correct the errors, call
Technical Support. Have the RBCHECK output handy, we'll want to know
what the exact errors are.
Always be sure you have a current backup copy of the database made
using the DOS COPY or BACKUP commands or a third party backup utility
before proceeding with any steps to correct the errors.
File 1 (database structure) errors
=======================================
R5KVER is mmm, should be nnn.
-----------------------------
The database was not properly exited. When a database is closed this
value must be either -201 or -214. The -214 indicates that the database
is a 4.x extended database, it has more than 80 tables or 800 columns
and can only be connected by 4.x. All other databases should have a
value of -201. For example, a value of -204 indicates that the database
was left in a COMPATIBILITY OFF mode. To correct the error, simply
connect the database in the correct mode and then disconnect and exit
normally from R:BASE.
F2SIZE is mmmmmm, should be nnnnnn.
-----------------------------------
The size of the 2.RBF file (data file) is incorrect. The actual size
on the hard disk is mmmmmm, but the 1.RBF file indicates that the size
should be nnnnnn. This error can occur if R:BASE is not exited normally.
Expect to also see errors in the data file check. This error indicates
that data is physically missing from the data file. There is no way to
recover the missing data. A PACK or RELOAD will correct the database
errors and the missing data can be reentered. When checking a 4.x
database with an earlier version of RBCHECK you will see this error but
there is not a problem with the database. R:BASE 4.x pre-extends the
size of file 2 to alleviate full disk problems.
F3SIZE is mmmmmm, should be nnnnnn.
-----------------------------------
The size of the 3.RBF file (data file) is incorrect. The actual size
on the hard disk is mmmmmm, but the 1.RBF file indicates that the size
should be nnnnnn. This error can occur if R:BASE is not exited normally.
It indicates that data is physically missing from the index file. There
is no way to recover the missing indexes. A PACK or RELOAD will rebuild
all the indexes and correct the errors. When checking a 4.x database
with an earlier version of RBCHECK you will see this error but there
is not a problem with the database. R:BASE 4.x pre-extends the size of
file 3 to alleviate full disk problems.
RNAME invalid.
--------------
RNAME comes from Relation NAME. The term RELATION means TABLE. The
table name (RNAME) shown after the word checking is an illegal name
in R:BASE 3.x or 4.x or RBCHECK has seen control codes or extended
ASCII characters in the name or the name is blank. If there are not
other errors in the database, it may be possible to correct with
R:SCOPE. Usually this error means restore the database backup.
ANAME invalid.
--------------
ANAME comes from Attribute NAME. The term ATTRIBUTE means COLUMN.
The column name (ANAME) shown is an illegal name in R:BASE 3.x or
4.x or RBCHECK has seen control codes or extended ASCII characters
in the name or the name is blank. If there are not other errors in
the database, it may be possible to correct with R:SCOPE. Usually
this error means restore the database backup.
NCOL invalid.
------------
NCOL is (nn), should be (mm).
The row length stored for a table is not correct. The row length for
the table is either less than two (minimum row length) or greater
than 2,048 (maximum row length) and there are no NOTE fields in the
table. If you receive this message you can expect a corresponding SIZE
LESS THAN MINIMUM or SIZE GREATER THAN MAXIMUM error in the 2.RBF file.
Usually this error means restore the database backup. It is rare for
this to be the only error in file 1.
IDATT is mm, should be nn.
--------------------------
This is one of the most common errors you'll see when using RBCHECK.
It is a harmless error, and has no effect on the operation of your
database. R:BASE stores all the columns in a numbered list, each table
references a beginning location in that list. The first table in the
database starts at one. The second table in the database starts at one
plus the number of columns in table1. The third table starts at the
beginning location for table2 plus the number of columns in table2 etc.
RBCHECK calculates the expected reference value using this formula.
If the beginning location referenced by a table is not the same as the
calculated number RBCHECK reports an error. Once you have this error
on one table in a database, all succeeding tables should report the
same error. You often have a NUMATT error reported also. This error
happens when columns are left in the column list but are no longer
associated with a table. It occurs most often in converted databases.
These errors cannot be corrected with R:SCOPE. You must recreate the
database using the R:BASE BACKUP/RESTORE or UNLOAD/INPUT commands. If
these are the only errors, they can also be corrected with the
RBPACKF1.EXE program from the Microrim Bulletin Board
(1-206-649-9836).
ATTCOL invalid (nn).
ATTCOL is (mm), should be (nn).
-------------------------------
This is the location of the data within a row. It is calculated
similar to the IDATT. The first column in a table must have an ATTCOL
of one. The second column's ATTCOL is one plus the length of the first
column in words ( one word = two bytes or characters). If you get this
error, you probably also get an ATTYPE and ATTLEN error. Usually this
error means restore the database backup.
ATTYPE invalid (nn).
--------------------
R:BASE stores the data type of a column as a number. If the number
stored for the column is invalid you will receive this message. If
you get this error, you probably also get an ATTCOL and ATTLEN error.
Usually this error means restore the database backup.
ATTLEN invalid (nn).
ATTLEN is (mmm), should be (nnn).
---------------------------------
All data types are stored with a length of 1 except TEXT and NOTE.
TEXT data types are stored with their actual lengths. Therefore, TEXT
30 is stored as 30. NOTE fields are stored with a length of 4. You get
this error if the stored length does not match the datatype. If you get
this error, you probably also get an ATTCOL and ATTYPE error. Usually
this error means restore the database backup.
NUMATT is (nn), should be (mm).
-------------------------------
The number of columns in the column list of the database does not
match the sum of the number of columns stored for each table. If you
have IDATT errors, you usually have this error also. This error cannot
be corrected with R:SCOPE. You must recreate the database using the
R:BASE BACKUP/RESTORE or UNLOAD/INPUT commands.
ATTKEY invalid (nn).
--------------------
The value of ATTKEY is the starting location of the index information
in file 3. This error means that the value is either less than zero or
ATTKEY times 512 is greater than the size of file 3 (F3SIZE). Generally,
ATTKEY errors can be corrected by rebuilding indexes with a PACK,
RELOAD or CREATE INDEX command.
File 2 (database data) errors
=============================
Read error at id = nnnn.
------------------------
RBCHECK could no longer read data from the file. The address (ID) shown
is often either negative or beyond the end of file 2. The database may
also report an F2SIZE error when checking database parameters. There is
no way to recover the missing data. A PACK or RELOAD will usually
correct the error and the missing data can be reentered.
Id = nnn, NEXT out of range (mm).
---------------------------------
This is a common error and indicates the table has what is called a
"broken pointer". You usually get this error when you can't find all
the data in a table. The error means that at the address nnn, the
value that identifies the location of the NEXT row of data, mm, is not
valid. It is not an address within the size of file 2. When you have
this error, you can also expect to see a row count error. The row
count error will tell you where in the table the "broken pointer" is
and how many rows of data are missing. This error can be corrected
with R:SCOPE, using a PROJECT method within R:BASE (see article
"Understanding Data Pointers") or by doing a PACK or RELOAD (if only
a few rows would be lost).
Id = nnn, PREV invalid (mm).
----------------------------
This is similar to the NEXT out of range error. At the address nnn,
the previous row pointer, mm, is not correct. This error does not
necessarily mean that you can't find data in the table. The table
should be checked in R:SCOPE or in R:BASE. To check the data pointers
in R:BASE use the command: COMPUTE ALL (1) FROM tablename. The rows
and count of the result should be the same. If they are different then
there are other errors in the table and you should proceed as if you
have a broken pointer (NEXT out of range). When you have a PREV
invalid error, you can also expect to see a row count error.
Id = nnn, move id invalid (mm).
-------------------------------
The only rows that should be moved in the data file are rows from
tables that have NOTE fields. When data is added to a NOTE field it
no longer can fit in the same space in file 2 so R:BASE moves it to
a new location. When the row is moved the size is changed to 0 and
the new row address is noted. This error means the row at address nnn
is marked as moved (SIZE equal to zero) but the address, mm, of where
it is moved to is invalid (less than zero or beyond the end of file 2).
Fixing this error depends on whether or not the table has NOTE fields
and on the other errors in file 2.
Id = nnn, SIZE (mm) less than minimum.
--------------------------------------
File 1 stores a row size (NCOL) for each table. There is also a row
size stored with the data in file 2. This error means that the size
of this row stored in file 2 is less than the value stored in file 1.
This error may occur for every row in a table, or only for some of the
rows. It is not corrected with R:SCOPE, but through doing an R:BASE
BACKUP/RESTORE or UNLOAD/INPUT of the table.
Id = nnn, SIZE (mm) greater than maximum.
-----------------------------------------
File 1 stores a row size (NCOL) for each table. There is also a row
size stored with the data in file 2. This error means that the size
of this row stored in file 2 is larger than the value stored in file 1.
This error may occur for every row in a table, or only for some of the
rows. It is not corrected with R:SCOPE, but through doing an R:BASE
BACKUP/RESTORE or UNLOAD/INPUT of the table.
IDEND is mmm, should be nnn.
----------------------------
The address, mmm, of the last row of data found in file 2 for the
particular table does not match the value for the last row as stored
in file 1, nnn. This error usually is reported along with NEXT out of
range and PREV invalid errors. The error can be corrected in R:SCOPE
or by doing a PACK or RELOAD of the database.
Row count is nn, should be mm.
------------------------------
The number of rows for the table as stored in file 1 does not match
the actual number of active rows counted as the data was checked.
You usually get this error in addition to other file 2 errors. The
error can be corrected in R:SCOPE or by doing a PACK or RELOAD of
the database.
After correcting file 2 errors the database must be PACKed, RELOADed,
or rebuilt using BACKUP/RESTORE or UNLOAD/INPUT. This will correct
IDEND and row count errors as well as rebuilding all indexes. Indexes
must be rebuilt after making file 2 corrections.
RBCHECK Example using Concomp
=============================
Database: concomp Name of the database given to RBCHECK
----- Checking File 1 -----
Checking Database Parameters
Errors in file size or database
0 errors. mode reported here
Checking Relation & Column Tables Beginning structure check of each
table
Checking SYSCOMP Table name (RNAME) followed by list
Column SYSREL of column names (ANAME) defined for
Column SYSATT the table. This information is repeated
Column SYSTYP repeated for each table in the
Column SYSPOL database.
Column SYSTBL All tables are listed, R:BASE system
Column SYSTBL tables (including hidden tables)
Column SYSALG and data tables.
0 errors.
Checking SYSINFO
Column SYSSNAME
Column SYSCNAME
Column SYSDESCR
Column SYSINC
Column SYSFMT
Column SYSNEXT
Column SYSLONG
0 errors.
Checking SYSREP
Column SYSRNAME
Column SYSRDATA
Column SYSRSEQ
0 errors.
Checking customer
Column custid
Column company
Column custaddr
Column custcity
Column custstat
Column custzip
Column custphon
0 errors.
Checking transdet Only the first 8 characters of table
Column transid and column names are displayed.
Column detailnu
Column model
Column units
Column price
Column extprice
0 errors.
Checking transmas
Column transid
Column custid
Column empid
Column transdat
Column netamoun
Column freight
Column tax
Column invoicet
0 errors.
Checking prodview, This is a 3.x view.
Views are not checked, they are
listed and identified as views.
----- 0 errors for File 1 ----- Reporting of total errors in database
structure
----- Checking File 2 ----- Beginning data check of each table
Checking data for SYSCOMP
6 active rows, 0 deleted rows, 0 errors.
Checking data for SYSINFO
73 active rows, 0 deleted rows, 0 errors.
Checking data for SYSREP
100 rows Rows are counted by hundreds.
200 rows
300 rows
400 rows
454 active rows, 0 deleted rows, 0 errors.
Checking data for customer
9 active rows, 0 deleted rows, 0 errors.
Checking data for transdet Only first 8 characters of table name
41 active rows, 0 deleted rows, 0 errors. are displayed.
Checking data for transmas
19 active rows, 0 deleted rows, 0 errors.
Checking data for prodview
View
----- 0 errors for File 2 ----- Report of total errors in database
data
Total errors: 0 Report of total errors, structure
and data