The DBC program allows investigation of databank files to ensure that the physical structure is not damaged. The functionality may also be used to examine the internal organization of a databank file and display statistical information on the databank.
The DBC program traverses every page of a given databank file, and the following are typical tasks that can be examined and verified:
•index and data page consistency
•free page list consistency
•page checksum
•records being in the correct order
•column value accuracy
Note:The functionality checks only the physical condition of the databank. Informational errors such as data inconsistency, invalid data format, and data outside the validation limits of domains are not detected by DBC.
DBC investigates databank files to ensure that the physical structure is not damaged.
Syntax
The overall syntax for the DBC program is:
dbc [-a] [-e -s file] [-o file] [databankfile [-f file [-f file...]]]
dbc [--all] [--extended --sysdbfile=file] [--output=file]
[databankfile [--filename=file [--filename=file...]]]
dbc [-v|--version] | [-?|--help]
|
Unix-style |
VMS-style |
Function |
|---|---|---|
|
-a --all |
/ALL |
If a databank file is not closed, the contents of large objects are by default not checked. The reason is that TRANSDB may contain large object updates which affects the databank state. When --all is specified, large objects are checked anyway. The utility can in these cases report errors that will correct themselves after restart of the system. It is therefore recommended to avoid this option. |
|
-e --extended |
/EXTENDED |
When extended is specified, the contents of each row is checked to verify that each column value conforms to the rules for the column data type. SYSDB must be present to do this type of checking. |
|
-f file --filename=file |
/FILE=file |
Additional filename for multi-file databank. All files for the databank are needed, together with the first databank file given as a separate argument (databankfile). This option is used once for each additional databank file. |
|
-o file -output=file |
/OUTPUT |
Sequential file created by DBC that contains the result of the verification. |
|
-s file --sysdbfile=file |
/SYSDBFILE |
Filename for SYSDB used by the databank to check. This filename is required if any tables are using collations. If not specified the correct sort order for such tables is unknown. |
|
-v --version |
/VERSION |
Display version information. |
|
-? --help |
/HELP |
Display usage information. |
|
databankfile |
databankfile |
File name for the databank to check. |
If the filenames are not specified on the command-line, the program prompts for the name of the databank file, a name for the result file and the name of the system databank (SYSDB) file.
If an error occurs when opening the databank file (e.g. file not found or file locked by another user), or while creating the result file, an appropriate error message is displayed.
If the SYSDB filename is not specified and it is found that tables in the databank use collations, these tables are not verified and a warning message is displayed.
If no errors are detected in the databank file, the following message is shown:
No errors found
The result file then contains statistics describing the physical databank organization. Otherwise, error descriptions (see below) are written to the result file, and the following message is displayed:
* Errors logged in result file
The result file should be examined to investigate the nature of the errors, see Database Consistency.
It should be noted that the DBC program returns an error status (or warning) to the operating system when an error (or warning) is encountered. This may be useful when running it from scripts or in batch mode.
DBC returns a status code to the environment executing the command. The status code can be examined by scripts.
|
VMS:On OpenVMS, the status codes correspond to the OpenVMS condition code severity levels. Use the $SEVERITY symbol in DCL command procedures. |
The following return codes are used:
|
Linux/Windows |
VMS |
Usage |
|---|---|---|
|
0 (success) |
1 (success) |
This code is used when the DBC command has executed all options with no problems. |
|
1 (warning) |
0 (warning) |
Other Error. |
|
2 |
2 (error) |
Databank error. |
The DBC program operates directly against the databank file, with no reference to the Mimer SQL database server. The program may not be run on a file which is currently held open (an error message is displayed in such a case). The system administrator should arrange for exclusive access to the databank file during DBC operations.
Any errors detected in the databank file are written to the result file directly after the identification record for the table affected.
The result file begins with the following information:
•Databank file name.
•Time when the DBC operation was performed.
•Version of Mimer SQL under which the databank was created (if this is not the same as the current version there will also be a ‘converted to’ message).
•A backup timestamp.
•Structure level.
•System identifier for the databank.
•Databank sequence number (0 = master databank, >0 = a shadow).
•Check flag.
•Number of bitmap pages (starting at 0).
•Root pages (starting at 1).
•Number of pages allocated.
•Number of pages used.
If the check flag indicates that the databank was not properly closed when Mimer SQL is stopped, there may be an additional message saying:
* No bitmap checking against databank!
An identification record is given for each table in the databank. The following information is shown:
|
Information |
Description |
|---|---|
|
The system identification number of the table. This is the number used to identify the table in the data dictionary. The table name is not stored directly in the databank file. |
|
|
The page number of the start page for the highest index level. If the number of levels is 1, this is the only data page. If the start page is 0, the table is empty. |
|
|
The number of levels in the table storage structure. |
|
|
The length of the primary key in bytes. |
|
|
The record length (row length) of the table. |
|
|
Any of the following values: Base table |
|
|
Type of compression |
Any of the following values: Mimer LZM compression |
|
Collation version |
Displayed if any key part of the table is using collation. |
|
Resident or Marked for delete. |
|
|
Size of the index page in bytes. |
|
|
Size of the data page in bytes. |
|
|
Indicates how many index pages were checked. |
|
|
Indicates how many data pages were checked. |
|
|
Gives an approximate measure of the space used in the data pages. This is expressed as a percentage, which may be >100% for data pages having variable-length (i.e. compressed) records because the required number of pages is calculated based on uncompressed record sizes. |
|
|
If no errors are reported, the number of records reached is equal to the total number of records (rows) stored for the table. |
DBC Sequential Table Information
The following information is shown:
|
Information |
Description |
|---|---|
|
|
Table name. |
|
Ordered identification. |
|
|
First page in the sequential file. |
|
|
Last page in the sequential file. |
|
|
Any of the following values: Sequential table |
|
|
Type of compression |
Any of the following values: Mimer LZM compression |
|
Resident or Marked for delete. |
|
|
Size of the index page in bytes. |
|
|
Size of the data page in bytes. |
|
|
Number of index pages checked. |
|
|
Number of data pages checked. |
|
|
Number of records checked. |
DBC LOGDB Backup Information
The following information is shown:
|
Information |
Description |
|---|---|
|
Timestamp page |
Describes actual timestamps for databanks included in the log. |
The following error situations are described by explicit messages in the result file:
|
Error message |
Explanation |
|---|---|
|
* Illegal number of free bits in bitmap |
The number of free bits in the bitmap is marked as a negative number or as a number greater than the permissible value. |
|
* Illegal pointer to first word with free bit in bitmap |
The pointer to the first word is either negative or greater than the number of words per page, or points outside the number of allocated pages. |
|
Error message |
Explanation |
|---|---|
|
* Illegal record length in root page |
The record length is not valid for the current version or for the site. |
|
* Pageno. outside databank: x
* Pageno. not marked as used: x |
The reference to the page number (x) is invalid. (Applies only where there is more than one root page.) |
|
Error message |
Explanation |
|---|---|
|
* Pointer to previous page invalid |
Error in page linkage. |
|
* Invalid record length |
The record length is either not the same as in the previous page or outside the page limits. |
|
* Record crosses page boundary |
A record stretches over the page limits. |
|
Error message |
Explanation |
|---|---|
|
* Error in root record |
The value for start page, levels, key length or record length is outside the legal values for the site. |
|
* Page has illegal record length: x |
The record length (x) given in the page is not the same as that given for the table. |
|
* Page has illegal last-record pointer: x |
The pointer (x) to data within a page is outside the page limits. The limits are the values of bytes/header and bytes/page. |
|
* Page has records in wrong order. Pos: x |
The records in the page are not correctly sorted. The value of x is the byte position within the page for the start of the wrong record. |
|
* Page has last-record key > index key. Pos: x |
The records within a page include key values greater than those in the index level above. The value of x is the byte position within the page for the start of the last record. |
|
* Page no. outside databank: x |
Reference is made to a page number (x) which is higher than the highest allocated page. |
|
* Page no. referenced twice |
There are at least two references to the same page number (x). One of these references should also give another error, or an error should have been notified earlier in the file. |
|
* Page no. not marked as used: x Bitmap pageno: Word: Bit: |
A page that is used is illegally marked as free. Continued insertion of data in the databank will result in a double referenced page. |
All table structure errors are followed by a listing of the page numbers passed in the B*-tree structure on the way to the error. In the example below a y-value indicates the byte position in the page (corresponding x-value) where the record holding the reference to the next level starts:
B*-tree
Page no: x1 x2 x3 .... xn
Byte pos: y1 y2 y3 .... yn
If the error occurs at an index level, the following additional message is given, and no checks are made at lower levels:
Branch is interrupted
In addition to the DBC program there is an internal databank check feature within the database server. When the database server is started, if it is noticed that the system was closed in a non-proper way, this verification will be triggered. The default check includes page consistency and checksum validation. If an error is found, the broken databank file will not be opened and the database will not be fully functional. In a situation like this a backup, or corresponding, must be used to get the system operational.
On VMS and Linux the internal databank check feature is controlled using the database server configuration parameter DBCheck, see MULTIDEFS Parameters.
On Windows the Mimer Administrator is used to control the internal databank check feature.