ANALYZE command

Summary

Privileges

File manager

Function

Analyze an Ordered Index, validate and output index and page information

Syntax

ANALYZE {fieldname | * }

Where: fieldname is a valid field with the ORDERED attribute. If an asterisk (*) is provided in the place of a field name, all entries in the root node of the ordered index are analyzed. The information is collected based on field codes instead of field names.

Purpose

The ANALYZE command provides sufficient information about Ordered Index fields so that you can assess an Ordered Index, a prerequisite in debugging an Ordered Index and related problems. A file manager can use the ANALYZE command to diagnose those fields that are experiencing Ordered Index related problems and verify the possibility of an Ordered Index inefficiency.

In addition to providing information about inefficiencies, the ANALYZE command gives you insights on how Model 204 manages fields and values.

Because the analysis process is identical to that of the Ordered Index retrieval, this command can trigger a bug macro when a corrupted Ordered Index is encountered, thus providing a simplified and yet reproducible environment.

This command examines the settings of Ordered Index spacing parameters, LRESERVE, NRESERVE, SPLITPCT, and IMMED, while creating or reorganizing a given Model 204 file in order to achieve the optimized results.

The ANALYZE command can analyze any Model 204 file, going back to those of Version 8.1.

Usage

For each Ordered Index field in the ANALYZE command, the analysis begins at the corresponding entry in the root node and then processes downward to the individual pages in the leaf nodes. Each page is analyzed in terms of its disk space usage. The usage information is then accumulated at the each node level.

If the file to be analyzed has its FISTAT reset from Physically Broken, the following message and prompt are displayed:

FIWHO DVTEST TERMINAL ID THAT RESET FISTAT *** M204.1076: DO YOU REALLY WANT TO CONTINUE?

Note:
If someone resets the FISTAT parameter from Physically Broken, the Ordered Index might be broken and the ANALYZE command might not work.
Enter Y to proceed.
However, if the field name is not an Ordered Index, the following message is displayed:

*** 1 M204.1265: NO SUCH FIELD NAME. FIELD = FOO *** M204.0003: ANALYZE DONE

Example

In the following example the ANALYZE command is diagnosing the CLIENT CODE field in the CLIENT file. The example continues with the screen display of the results, followed by a table explaining the output for each column.

Commands entered

OPEN CLIENT ANALYZE CLIENT CODE

Sample result

ANALYZE CLIENT CODE FIWHO TERMINAL ID THAT RESET FISTAT *** M204.1076: DO YOU REALLY WANT TO CONTINUE Y ROOT NODE VERSION NUMBER = 434975 *** M204.0005: ANALYZE FIELDNAME = CLIENT CODE AVG.NO. OFFSET COMPRES KEY PAGE AVG. PAGES ENTRIES AREA KEYSIZE AREA USAGE% UNUSED ROOT 1 7 34 61 1 6049 I-NODE 1 276 572 3080 59 2492 LEAF 4 173 366 2 4244 75 1532 MRIB: IMMEDIATE LIST BITMAP TOTAL ENTRIES 402 1859 4 2265 RECORDS 574 48664 16432 65670 PAGES 1603 4 1607 SRIB: 96 *** M204.0003: ANALYZE DONE

The table below lists the column headings from the previous example's output with an explanation of what the information represents.

Notes on the results of an ANALYZE command

Result column	Explanation
ROOT NODE VERSION NUMBER	A version number recorded in the Root node.
ROOT	The entire page information, same for all ordered fields.
LEAF	The average page information of the selected ordered field.
PAGES	Number of pages in the node.
AVG. ENTRY	Average (Index) entries per page.
OFFSET AREA	Average number of bytes per page for the offsets.
COMP. SIZE	Average number of bytes for the compression key.
KEY AREA	Average number of bytes for the (Index) key.
PAGE USAGE%	(Offset area + Key area + Compress size) / (Page size - Header - Trailer).
Record Information	Contained in the entries in the leaf node.
SRIB #	Single Record Information Block number.
MRIB #	The categories of MRIB are: IMMEDIATE LIST BITMAP
TOTAL	Sum of all MRIB categories.
ENTRIES	Total entry count in the category/
RECORDS	Total records covered by each MRIB category/
PAGES	Total Table D pages encountered in retrieving the respective MRIB category. Note: This count might be greater than the actual number of pages for the MRIB category.

Fatal errors

During the execution of the ANALYZE command, some errors might occur, triggering a bug macro. However, the ANALYZE detects most errors before calling existing routines. In such cases, the following type of error message is displayed:

*** M204.0005: ANALYZE FIELDNAME = FOO SEGMENT POINTER EXCEEDS NEXT CLUSTER POINTER ON PAGE X'04000002' *** M204.0623: FILE DATA MAY BE LOGICALLY INCONSISTENT *** M204.1076: DO YOU REALLY WANT TO CONTINUE?

Enter Y to continue the diagnosis.

Other messages are:

SEGMENT POINTER EXCEEDS NEXT CLUSTER POINTER ON PAGE X'04000002' CLUSTER POINTER EXCEEDS RANGE OF MRIB POINTER ON PAGE X'04000002' SEGMENT POINTER IS NOT IN THE RANGE OF MRIB POINTER ON PAGE X'04000002' INVALID BIBSIT VALUE ON PAGE X'04000002' POINTER TO IMMEDIATE IS NOT AN EVEN OFFSET ON PAGE X'04000002' TABLE D LIST POINTER IS NOT AN EVEN OFFSET ON PAGE X'04000002'

Rocket Software strongly recommends that you record the page number shown in the message and report this problem by sending the file to Rocket Software Technical Support for further analysis, whenever possible.

Nonfatal errors

Nonfatal errors are shown in the following format:

RETURN CODE FROM %C WAS %C'

The FROM clause can be one of the following names:

BXFIND BXNEXT BXNEXT2

The table below lists each return code with an explanation of its meaning.

Nonfatal error return codes

Code	Explanation
X'1'	Attempt to find an equal key failed, no position exists.
X'2'	Attempt to refind a position failed, no position exists.
X'4'	Result of BX call is OFFEND position, either OFFENDL or OFFENDR - find which by checking CIA flags BXCFOFLE and BXCFOFRI
X'8'	Result of BX calls OFFEND of tree, for example, OFFENDR or OFFENDL, no next or previous node.
X'10'	Empty tree - Position is OFFENDL
X'20'	Insert would illegally duplicate key
X'40'	BXINSE or BXCHNG would result in entry, which is illegally large
X'100'	Next entry in given direction does not satisfy given RELCODE
X'200'	Position has ceased to exist, as when a call to BXDELE frees the current node and there is no right sibling