Name: AUTOCHK Shortest: AUTOCHK
Family: Command Category: Data Integrity
Description: Use the AUTOCHK command to check the integrity of a database.

Syntax

 AUTOCHK syntax diagram

Options

dbspec
Specifies a database other than the open database to check; otherwise, the open database is checked.

FULL
Provides detailed information about the processing being performed, and when AUTOCHK encounters an error, it continues processing.

About the AUTOCHK Command

Use the AUTOCHK command to ensure that the connected database is intact before using the PACK or RELOAD commands, or before making a backup of the database with either the BACKUP or COPY commands.

Please Note: If any user connected to the database has temporary tables or views created you may receive an abnormal amount of errors. This is expected and is a side effect of having temporary tables active during the check. For completely accurate results, have all users disconnect from the database to be checked.

AUTOCHK checks the following:

AUTOCHK does not check indexes.

When you run AUTOCHK, it systematically checks the structure file (DBNAME.RB1) of the open database, and the data files (DBNAME.RB2 and DBNAME.RB4). AUTOCHK only checks the index file (DBNAME.RB3) for the timestamp and length of the file. When opening a database, AUTOCHK ignores any user-identifier protection. AUTOCHK without the FULL option sets the R:BASE error variable to a non-zero value if errors are found.

The results of AUTOCHK with the FULL option are displayed on screen, or the current OUTPUT device. First, AUTOCHK validates the timestamps in the database files, then systematically checks the structure of each table and view in the database, providing a list of columns, constraints, and indexes for each. Any structure errors are noted after each table listing. Next, AUTOCHK checks the data for each table, listing active rows and deleted rows. Any problems with data, such as broken pointers, are listed after the respective tables. Finally, AUTOCHK provides a summary of the database structure, including the number of tables, columns, and indexes, and the actual space that the data occupies in the data file (DBNAME.RB2). AUTOCHK shows the percent of space used for the items in each list to give an idea of how much space has been used, and to indicate the need to recover space in the database files. Any numbers less than 100 percent indicate the need to pack or reload the database using the PACK or RELOAD commands. For more information about the PACK and RELOAD commands, see the "PACK" and "RELOAD" entries.

The following section contains information about using AUTOCHK in application files and capturing the error variables returned. This allows the application developer to prevent users from continuing to use a corrupted database.

SET ERROR VAR E1
WRITE 'Checking database for errors...'
AUTOCHK dbname
IF E1 > 40 THEN
  WRITE 'AUTOCHK has found errors in the database!'
  BEEP
ENDIF
If E1 > 0 and E1 < 50 THEN
  WRITE 'AUTOCHK will not run - User Abort or Out of Memory'
  BEEP
ENDIF
IF E1 = 0 THEN
  WRITE 'AUTOCHK successful - No errors found'
ENDIF
PAUSE 2
RETURN

If AUTOCHK with no option finds an error, it stops checking the database and displays one error message. If the error message (see list below) indicates that the database is damaged, you might want to start using a backup copy of the database. Alternatively, you might want to use R:SCOPE, a database repair tool available from R:BASE Technologies, Inc.

If AUTOCHK finds no errors, it displays the message "NO ERRORS FOUND." If you press any key while AUTOCHK is checking the database, the program stops and displays the message "USER ABORT." AUTOCHK automatically sets the error variable to the number corresponding to the message returned. For example, if the error "UNABLE TO OPEN DATABASE FILE 2" is returned, the error variable is set to 52.

Multi-User Databases

Use caution when running AUTOCHK in a multi-user environment. If the database being checked is currently open with MULTI set on, AUTOCHK places a database lock on the database. The database lock remains in effect until AUTOCHK stops checking the database. Database users are unable to make any changes to the data or structure of the database while this lock is in place.

If a user attempts to open a database being checked by AUTOCHK and the database does not have any other users, the user receives an error message indicating that the database is currently open in a mode that makes it unavailable. If other users have the database open with the MULTI set on and the database is being checked, the user attempting to open the database receives a message indicating the user is waiting in a lock queue. If AUTOCHK successfully completes checking the database and finds no errors, it reports that no errors were found and sets the error variable to 0.

Checking continues in multi-user mode (even if a database lock cannot be obtained) if a database is connected by another user; however, row errors in File 2 can occur because of database activity.

Error Messages

AUTOCHK displays one of the following messages when it is unable to start checking or complete checking the database or when it finds an error in the database files. AUTOCHK returns 0 No errors found if the database is okay. Some of these messages indicate that the database is damaged. Either switch to a backup copy of the database, or attempt repair of the database using R:SCOPE, R:BASE Technologies's database repair tool. If AUTOCHK is unable to open File 1 of the database, check that the path you specified to the database is correct; or, if you are trying a multi-user database, check that no other user has the database connected with MULTI set off.

Checking continues in multi-user mode (even if a database lock cannot be obtained) if a database is connected by another user; however, row errors in File 2 might occur because of database activity.

Any of these messages, except the first (code 0), indicates that the database is damaged. Either switch to a backup copy of the database, or attempt repair of the database using R:SCOPE, R:BASE Technologies's database repair tool.

AUTOCHK Error Messages
Exit Code Message
0 No errors found
1 This database is not of the correct version
2 The database filenames must all match
20 Out of memory
40 User Abort
50 Unable to open database file number 1
51 Unable to lock this database
52 Unable to open database number 2
53 Unable to open database number 3
54 Unable to open database number 4
55 Error reading the database information block
56 Error reading the timestamp information
57 Timestamp in file number 2 does not match file 1; run RBSYNC
58 Timestamp in file number 3 does not match file 1; run RBSYNC
59 Timestamp in file number 4 does not match file 1; run RBSYNC
60 Invalid number of tables
61 Invalid number of columns
62 Invalid number of indexes
63 File 1 is too small
70 Error in database structure block
80 Error reading the table list
81 Error reading the column list
82 Error reading the index list
100 Incorrect version flag
101 Error reading Case Folding and Collating tables
110 Error in DBinfo block offset
111 Error in DBinfo block length
120 Error in length of database file 2
121 Error in length of database file 3
150 A table's assumed row width is out of range
151 A table's first column is out of range
152 A table's assumed row count is out of range
153 A table's starting pointer is out of range
154 A table's ending pointer is out of range
155 Bad table or column hash value
160 A primary key was found in a table not known to have a primary key
161 A column is not contiguous
162 A column's data type is invalid
163 A column's length is invalid
164 A column's index file reference is invalid
165 A foreign key is referencing the wrong table
166 A foreign key references a deleted table
167 A foreign key references a table not known to be referenced
168 An index entry contains invalid columns
169 A foreign key was found in a table not known to be referenced
170 The total of a table's column lengths is invalid
200 Error reading the data file
210 The new location of a moved row is invalid
220 A row of data's length is too small
221 A row of data's length is too large
230 A row of data's previous pointer is out of range
231 A row of data's previous pointer is invalid
232 A row of data's next pointer is out of range
240 The last address encountered was not expected
241 The number of rows was not expected
300 Error - Out of Memory reading table information
301 Error reading column information
302 Error - database in need of transaction recovery

Example

The following is an example of how to put AUTOCHK results in a file for viewing:

DISC
OUTPUT dbname.chk
AUTOCHK dbname FULL
OUTPUT SCREEN

You can view DBNAME.CHK in the Text Editor to view the results.