The am_check purpose function

If a user executes the oncheck utility for a virtual index, the database server calls am_check.

Syntax

mi_integer am_check(MI_AM_TABLE_DESC *tableDesc,
   mi_integer option)

tableDesc: Points to the table descriptor of the index that the current oncheck command specifies.
option: Contains an encoded version of the current command-line option string for the oncheck utility.

Usage

A user, generally a system administrator or operator, runs the oncheck utility to verify physical data structures. The options that follow the oncheck command indicate the kind of checking to perform. The additional -y or -n option specifies that the user wants oncheck to repair any damage to an index. For

In response to an oncheck command, the database server calls the am_check purpose function, which checks the internal consistency of the index and returns a success or failure indicator. If appropriate, am_check can call the am_open and am_close purpose functions.

Interpreting options

To determine the exact contents of the command line, pass the option argument to the following Virtual-Index Interface (VII) macros. Each macro returns a value of MI_TRUE if the option includes the particular -c or -p qualifier that the following table shows.


Macro	Option	oncheck action
`MI_CHECK_DATA() MI_DISPLAY_DATA()`	-cd -pd	Checks and displays data rows, but not simple or smart large objects
`MI_CHECK_DATA_BLOBS() MI_DISPLAY_DATA_BLOBS()`	-cD -pD	Checks and displays data rows, simple large objects, and smart-large-object metadata
`MI_CHECK_EXTENTS() MI_DISPLAY_EXTENTS()`	-ce -pe	Checks and displays chunks and extents, including sbspaces
`MI_DISPLAY_TPAGES()`	-pp	Checks and displays pages by table or fragment
`MI_DISPLAY_CPAGES()`	-pP	Checks and displays pages by chunk
`MI_DISPLAY_SPACE()`	-pt	Checks and displays space usage
`MI_CHECK_IDXKEYS() MI_DISPLAY_IDXKEYS()`	-ci -pk	Check and display index key values
`MI_CHECK_IDXKEYS_ROWIDS() MI_DISPLAY_IDXKEYS_ROWIDS()`	-cI -pK	Check and display index keys and rowids
`MI_DISPLAY_IDXKEYLEAVES()`	-pl	Check and display leaf key values
`MI_DISPLAY_IDXKEYLEAVES_ROWIDS()`	-pL	Check and display leaf key values and row identifiers
`MI_DISPLAY_IDXSPACE()`	-pT	Check and display index space usage
`MI_CHECK_NO_TO_ALL`	-n	Do not attempt to repair inconsistencies
`MI_CHECK_YES_TO_ALL`	-y	Automatically repair an index

The am_check purpose function executes each macro that it needs until one of them returns MI_TRUE. For example, the following syntax tests for oncheck option -cD demonstrate:

if (MI_CHECK_EXTENTS(option) == MI_TRUE)
{
   /* Check rows and smart-large-object metadata 
    * If problem exists, issue message.      */
}

Check and display table state

The access method can call accessor function mi_tab_spacetype() to determine whether the specified index is in an sbspace or extspace. If the data is in an sbspace, the am_check purpose function can duplicate the expected behavior of the oncheck utility.

For an extspace, such as a file that the operating system manages, am_check performs tasks that correspond to the command-line option.

To provide detailed information about the state of the index, am_check can call the mi_tab_check_msg() function.

Handling index problems

An access method can contain the logic to repair an index and execute additional macros to determine whether it should repair a problem that am_check detects. The following table shows the oncheck options that enable or disable repair and the am_check macro that detects each option.


Option	Meaning	Macro
-y	Automatically repair any problem.	MI_CHECK_YES_TO_ALL
-n	Do not repair any problem.	MI_CHECK_NO_TO_ALL

If a user does not specify -y or -n with an oncheck command, the database server displays a prompt that asks whether the user wants the index repaired. Similarly, when both MI_CHECK_YES_TO_ALL() and MI_CHECK_NO_TO_ALL() return MI_FALSE, am_check can call accessor function mi_tab_check_set_ask(), which causes the database server to ask if the user wants the index repaired. If the user answers yes or y, the database server adds -y to the option argument and executes am_check a second time.

Tip: Store any information that am_check needs to repair the index in PER_STATEMENT memory. Call mi_tab_check_is_recheck() to determine if the am_check can use previous PER_STATEMENT information that it stored in the preceding execution. If mi_tab_check_is_recheck() returns MI_TRUE, call mi_tab_userdata() to access the problem description.

If either the MI_CHECK_YES_TO_ALL macro or mi_tab_check_is_recheck() accessor function returns MI_TRUE, am_check should attempt to repair an index.

Important: Indicate in the access-method user guide whether the access method supports index repair. Issue an exception if the user specifies a repair that am_check cannot make.

Return values

MI_OK: Validates the table structure as error free.
MI_ERROR: Indicates the access method could not validate the table structure as error free.