Makelist function

Generates a Runlist command file.

Loading logically related databases involves multiple steps that must be performed in a fixed sequence. The Makelist function simplifies the process of creating these steps. Makelist generates a Runlist command file containing the steps required to load a set of logically related databases. You perform Runlist to execute the steps in the generated command file.

Syntax

mfims imsdbu MAKE {database-name|filename}
     [[NO]CLS] 
     [ECHO(keyword,msglvl,stoplvl
     [[NO]INI(filespec)]
     [[NO]LIST(filespec)]
     [LISTOPEN(disp)]
     [[NO]LOG(filespec)]
     [MAKELISTDSN(output-dsn)]
     [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.

MAKELISTDSN

Specifies the dataset name of the output file for the IMSDBU commands.

Default:

MAKELISTDSN(MAKELIST.RUN)

Sub-parameter

output-dsn

The dataset name of the output file for the IMSDBU commands.

General Rules

This output file is written to the current directory if no drive or directory is provided.

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 input is the starting physical DBD name defined using DBDGEN. From this DBD, logical relationships are followed to create the set of logically related databases. The DBDGEN files are the input to Makelist.

Output

The output is a Runlist command file. Its name and location are controlled by the MAKELISTDSN directive. It is an ASCII text file. Any text editor can be used to modify this file for changing directives or file names.

Logically Related Databases

Makelist begins by creating a list of logically related databases. The DBDGEN definitions are used to determine the relationships. Once the set is determined, it creates the required load and logical pointer update steps to load the databases.

Makelist builds the list by starting with a single DBD name. The databases referenced by logical children in the input DBD are added to the list. These newly-added DBDs are scanned and databases referenced by their logical children are also added to the list. This continues until all of the relationships are located. Makelist requires that all of the physical DBDs have been genned. If a DBD referenced by a logical child is not found, an error message is issued and Makelist terminates. The error message includes the required DBD name. You should gen the DBD and re-run Makelist.

Databases referenced by logical children also need to be genned and at least zeroloaded. That is, if you need access to a database with a logical child, you must also gen the logical parent database and at least zeroload it.

However, if you need a database that contains only a logical parent for a unidirectional relationship, the database containing the logical child is not required. Thus, you may get different results from Makelist depending on the DBD name you start with.

You should review the output of Makelist for databases that define unidirectional logical relationships. You could also run Makelist multiple times with different initial DBD names and merge the output Runlist files. Database load steps can also be added by editing the Runlist command file manually. This is an ASCII text file and can be edited in any text editor. For any required logical child database which was not located, add a Load step at the top of the file and a PtrUpdate step at the bottom. All PtrUpdate steps should follow the Load steps.

The following uni-direction examples consider three logically related databases - 'A', 'B', and 'C'. Database A contains a logical child segment which defines a uni-directional logical relationship to database B. Database B contains the logical parent for database A's logical child. A second uni-directional logical relationship is defined between databases B and C. Database B contains a logical child segment which points to the logical parent in database C. In other words, database A points to database B and database B points to database C. A is related to B and B is related to C by uni-directional relationships.

Example 1

If database A is used as the starting DBD name, databases B and C are both included. Database C contains no logical child segments and does not require a pointer update step. The sequence of the load steps is:

LOAD A DSN(...
LOAD B DSN(...
LOAD C DSN(...
PTRUPDATE A ...
PTRUPDATE B ...

Example 2

If database B is used as the starting DBD name, only database C is included. Database C contains no logical child segments and does not require a pointer update step. The sequence of the load steps is:

LOAD B DSN(...
LOAD C DSN(...
PTRUPDATE B ...

If your application requires the use of database A, a Load and PtrUpdate step must be added manually. MFIMS does not require database A if you only access databases B and C. The Load step for A must be placed prior to the first PtrUpdate step. The PtrUpdate step can be placed anywhere after the last Load step.

Example 3

If database C is used as the starting DBD name, databases A and B are not included. The load step is simply:

LOAD C DSN(...

If your application requires the use of database A and B, the Load and PtrUpdate step must be added manually. You do not need databases A or B if you only need access to database C. The steps to load all three databases is shown in Example 1.