Micro Focus Enterprise Developer 3.0 for Eclipse > Programming > Mainframe Programming > IMS Support > Reference > mfims Command-line Utility > mfims IMSDBU > mfims imsdbu functions > Reorganize function

Reorganize function

Provides a simple mechanism for reorganizing a database or set of logically related databases.

The Reorganize function provides a simple mechanism for reorganizing a database or set of logically related databases. This automates the creation and running of separate Unload and Load functions. PtrUpdate steps are run automatically for any database containing logical children.

Syntax

mfims imsdbu REOR {database-name|filename}
     [[NO]CLS] 
     [ECHO(keyword,msglvl,stoplvl
     [[NO]INI(filespec)]
     [[NO]LIST(filespec)]
     [LISTOPEN(disp)]
     [[NO]LOG(filespec)]
     [PROGRESS(no-of-segments)]

Parameters

database-name

The name of a database on which the function operates.

filename

The name of a file containing a list of databases on which the function operates.

CLS

Clears the screen before starting the utility. NOCLS prevents the initial clear screen and can be helpful when you are running a series of utilities in a command file.

Default:

NOCLS

ECHO

Controls the display of and interaction with the messages displayed by IMSDBU.

Default:

ECHO(MSGS,4,8)

Sub-parameters

`keyword`	The category of information displayed. One of the following: ALL Always displays processing messages, input source or detail information and the ending message. Warning and error messages are displayed and stop for user input if the message level is equal to or greater than the `msglvl` and `stoplvl` values. MSGS Always displays processing messages and the ending message. No source or detail information is displayed. Warning and error messages are displayed and stop for user input if the message level is equal to or greater than the `msglvl` and `stoplvl` values. ERREND Always displays the utility ending message. Warning and error messages are displayed and stop for user input if the message level is equal to or greater than the `msglvl` and `stoplvl` values. ENDMSG Displays ending message only if the utility ending return code is equal to or greater than `msglvl`. A "Press any key to continue" message is displayed and stops for input if the utility ending return code is equal to or greater than the `stoplvl`. Enter a `msglvl` and/or `stoplvl` value of zero to display and/or stop on every ending message. COND Both the warning/error and ending messages are conditional on the `msglvl` and `stoplvl` values. Warning and error messages are displayed and stop for user input if the message level is equal to or greater than the `msglvl` and `stoplvl` values. The ending message is displayed if the ending return code is equal to or greater than `msglvl`. You see the message "Press any key to continue" which requires input if the utility ending return code is equal to or greater than the `stoplvl`. ERRORS You see warning and error messages which require input if the message level is equal to or greater than the `msglvl` and `stoplvl`. You do not see the ending message.
`msglvl`	A value from 4 through 20 to indicate the severity of messages to display.¹
`stoplvl`	A value from 4 through 20 to indicate the severity of messages to stop for user input. ¹

¹ Can take the following values:

Value	Category	Example Cause
4	General warning message	A minor coding error in DBD source which DBDGEN can make an assumption about and continue.
6	IMS specific warning message	A warning that a keyword or statement is not supported and is ignored - processing can continue.
8	General severe error	An incorrect coding in DBD source which cannot be compensated for, such as 'no DBD statement'.
10	IMS Option specific severe error	An unsupported feature was defined which cannot be compensated for, such as 'Exceeded some maximum'.
12	Severe error - possible temporary condition	A temporary I/O error such as a 'file locked' or 'database locked' status.
16	Severe error- permanent - likely installation problem	A permanent I/O error, such as an invalid data set name or member name, was input to a utility or an environment variable is not set correctly.
20	Severe error - permanent	An unrecoverable I/O error or some other unexpected error.

INI

Specifies the default directives file.

Default:

None

Sub-parameter

filespec

The name and location of the .INI file containing directives that override the IMSDBU programmed defaults.

Syntax Rules

filespec can include a drive and/or directory if required. If you do not specify a drive or directory, IMSDBU looks for the named .INI file in the current directory.
Directives listed in the .INI file override the IMSDBU programmed defaults.
Directives entered on the command line or interactive screen override directives in the .INI file.
Specifying NOINI prevents any .INI file from overriding the programmed defaults.
If you specify an .INI file that does not exist, the programmed default directives are used as if NOINI were specified.

General Rules

An .INI file is an ASCII text file containing a heading, [IMSDBU] on line 1, starting in column 1, followed by a list of mfims imsdbu directives; one directive per line. A line is terminated by a return or an end-of-file. Comment lines are indicated by an asterisk (*) or semi-colon (;) in column 1. For example:
```
[IMSDBU]
PROGRESS(1000)
;use local log
LOG(C:\MYDIR\MYDB.LOG)
```

LIST

Controls the location and name of the detail listing file, which includes items such as source listings, completion status, error messages and execution statistics.

Default:

LIST(*.LST)

Sub-parameter

filespec

The name and location to use for the listing file.

Syntax Rules

filespec can include a drive and/or directory if required. If you do not specify a drive or directory, IMSDBU creates the listing file in the current directory.
NOLIST suppresses the creation of the listing file.
To specify a path, you can use the convention of placing a dollar sign ($) in front of the name of an environment variable that represents a path. For example, LIST($ENVVAR\*.DOC) creates a list file of dbdname.DOC in the directory named by the ENVVAR environment variable.
Specifying LIST(*.LST) or LIST(*.RPT) causes the listing file to be created in the project listing directory.
If no path is specified, the listing file is created in the current directory.
If you specify the base name of filespec as an asterisk (*), it is replaced by the DBD name; this allows IMSDBU to provide separate reports for functions that can operate on multiple databases. It also assists in maintaining historical detailed reports by DBD name.
Specifying LIST with no filespec is equivalent to specifying LIST(*.LST).

LISTOPEN

Controls the open disposition of the detail listing file.

Default:

LISTOPEN(NEW)

Sub-parameter

disp

The disposition to use. One of:

NEW: Creates a new listing file or overwrites an existing one.
MOD: Appends the list output to an existing file or creates a new listing if one does not exist. MOD allows you to maintain a detailed historical record of database functions.

Syntax Rules

LISTOPEN is ignored when NOLIST is specified.

LOG

Specifies the IMSDBU activity log, which shows the ending message status for each function.

Default:

LOG(IMSDBU.LOG)

Sub-parameter

filespec

The name and location of the file to use as the IMSDBU activity log.

Syntax Rules

filespec can include a drive and/or directory if required. If you do not specify a drive or directory, the listing is created in the current directory.
Specifying NOLOG suppresses the log file output.

General Rules

The log file is created if it does not exist.
The log file is historical with the most recent entries written to the end of the file.
As the log file grows in size over time, it might require deletion periodically.

PROGRESS

Controls the frequency of progress reporting.

Default:

PROGRESS(200)

Sub-parameter

no-of-segments

A value between 0 and 9999 indicating the number of segments to process before displaying a progress message. 0 disables progress reporting.

Syntax Rules

We recommend that you do not reduce the number of segments specified to a value below its default of 200. Very small values measurably reduce the performance of the database function.
For relatively fast systems, setting the value higher (such as to 1000 or larger) might improve performance slightly.

General Rules

The progress message could show the number of segments processed, or the percentage complete and an estimate of the time remaining.

Input

The database name input to the Reorganize function must be a primary physical database defined using DBDGEN. This DBD name must be a type of database which is supported by the Load function. See the Load Function for the database qualifications.

The database data files are read and updated by Reorganize using the Unload, Load, and PtrUpdate functions.

Secondary index databases do not need to be available when starting reorganization. They are recreated during the Load step.

The Unload function does not require the logical parent databases when unloading its logical child database. However, Reorganize uses Makelist to create Unload steps for each related database. All of the databases that are logically related must be available before starting Reorganize.

Output

Database unload work files containing the segment data are created during this process. These files are named using the DBD name with a .org extension. They are created in the project listing directory. For reference, they are an Unload file created with the directives LAYOUT(D) and COMPRESSION(CBLDC001), and are deleted upon successful completion of the Reorganize.

A Runlist command file is created with the name DBUREORG.RUN. It contains the steps to perform the reorganization. It is always placed in the current directory and is not deleted upon successful completion. You can use this file as a model for creating your own reorganization scripts. Be sure to copy it to a new name as the next Reorganize function recreates it. You might need this file to recover from an incomplete reorganization.

Processing

When a segment is deleted, the space it occupied is reused by the next segment inserted which is not larger than the deleted segment. However, if new segments are not inserted which 'fit' this deleted space, the space is not reclaimed until you reorganize the database. Also, as a database is updated, the internal pointers can become fragmented which reduces performance. A reorganization will restore the performance to that of a newly loaded database.

The Reorganize function combines the functions of the Load, Unload, PtrUpdate, and Delete functions to perform the reorganization. It creates the required steps using an advanced feature of the Makelist function. This Makelist feature is only available when using the callable API interface to IMSDBU. The interactive and command-line interfaces for Makelist only supports creating steps for loading databases. The callable interface adds the ability to create the steps for reorganizing databases.

The reorganization for a database with no logical children is simply to unload the database to a sequential file and load it using the sequential file.

Reorganizing a database containing logical children results in reorganizing it and all of its related databases. The steps to reorganize these databases are:

Identify all of the related databases
Unload each of the databases to a sequential file
Load each of the databases from the sequential unload
Run PtrUpdate for each database with logical children definitions
Delete the sequential files created in step 2

Identifying the related databases is done by Makelist. The process Makelist uses to create this list is the same for Reorganize as it is for Load.

The sequential unload files are not deleted until all of the Load and PtrUpdate processing is complete. Although this requires more disk space than deleting them after the Load, it provides for restarting if a subsequent Load or PtrUpdate step fails. If you need to conserve disk space, you can change the DBUREORG.RUN file to re-sequence the Delete commands and use Runlist to run the commands. You could also create your own Runlist command file or run the required functions in an operating system command file.

When the detailed report filename *.LST is used, a separate list file is created for each database involved in the reorganization. For a combined listing, specify the directives LIST(file-spec) and LISTOPEN(MOD).

Recovery

The easiest way to recover from a failed Reorganize function is to restore the original database data files from a backup copy. In the event that a backup copy is not available, recovery can be performed using the files produced by the reorganization. Failures can occur for several possible reasons. One example is running out of disk space.

In the event of a failure, an error message is issued and the process is terminated. The sequential file unloads are kept. These files may be required to complete the reorganization.

The first thing step is to determine the cause of the failure and correct it. The error message issued from the reorganization is written to the detail report listing. This message should provide enough information to determine the cause of the failure. In some cases, the IMSMTO.LOG will provide additional information about the failure.

The IMSDBU activity log will indicate all of the steps which were successful and the step which failed. If the failing step was an Unload, database recovery is not necessary. Just restart the Reorganize function after correcting the cause of the failure.

Compare the functions listed in the log to the reorganization command file DBUREORG.RUN to identify which step in the command file failed. Use a text editor to modify the command file and remove or comment out all of the steps which completed successfully. A step is commented out by placing an asterisk (*) in column 1. Use Runlist with the modified command file to complete the reorganization.