Databank Check Functionality

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 - Databank Check

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]

Command-line Arguments

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.

Exit Codes

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.

Authorization

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.

Result File Contents

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!

DBC B*-tree Table Information

An identification record is given for each table in the databank. The following information is shown:

Information

Description

Tabid

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.

Startp

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.

Levels

The number of levels in the table storage structure.

Keylen

The length of the primary key in bytes.

Reclen

The record length (row length) of the table.

Type of table

Any of the following values:

Base table
Secondary index table
Collation description table
LOB directory table
.

Type of compression

Any of the following values:

Mimer LZM compression
Mimer LZU compression
Mimer RLE compression
none.

Collation version

Displayed if any key part of the table is using collation.

Status of table

Resident or Marked for delete.

Index page size

Size of the index page in bytes.

Data page size

Size of the data page in bytes.

Number of index pages

Indicates how many index pages were checked.

Number of data pages

Indicates how many data pages were checked.

Required/Allocated datapages

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.

Reached no of records

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.

Tabid

Ordered identification.

Startpage

First page in the sequential file.

Endpage

Last page in the sequential file.

Type of table

Any of the following values:

Sequential table
Collation description table
LOB directory table
.

Type of compression

Any of the following values:

Mimer LZM compression
Mimer LZU compression
Mimer RLE compression
none.

Status of table

Resident or Marked for delete.

Index Page size

Size of the index page in bytes.

Data Page size

Size of the data page in bytes.

No. of index pages read

Number of index pages checked.

No. of data pages read

Number of data pages checked.

No. of records read

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.

Error Messages

The following error situations are described by explicit messages in the result file:

Bitmap Errors

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.

Root Page Errors

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.)

Sequential Structure Errors

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.

Table Structure Errors

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

Internal Databank Check

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.