Micro Focus Enterprise Developer 3.0 for Visual Studio 2013 > Programming > Mainframe Programming > IMS Support > Reference > mfims Command-line Utility > mfims IMSDBU > mfims imsdbu functions > Runlist function

Runlist function

Executes IMSDBU functions listed in a Runlist command file.

The Runlist function executes IMSDBU functions listed in a Runlist command file. This file can be created manually with a text editor or generated by Makelist.

Syntax

mfims imsdbu RUN {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 name of the command file containing IMSDBU functions. This is an ASCII text file with each function specified on a separate line. The format of this record is:

function dbdname [directives]

An individual command may not span multiple lines. An asterisk (*) in column 1 indicates a comment line.

All of the IMSDBU functions can be listed in a Runlist file except for Reorganize and Runlist functions. Reorganize uses Runlist to perform the reorganization and Runlist executions cannot be nested.

Output

The output is the results of the functions which were successfully executed and the IMSDBU listing and log report files.

Processing

The functions listed in the Runlist command file are processed in series. The highest error level set by an individual step is returned as the ending return code by Runlist. If a step fails with a return code of 8 or higher, all remaining steps are canceled. The ending return code is set to the return code of the failed step.

When running IMSBDU from the command line, the function-id to use for the Runlist function is RUN.

Any directives entered for Runlist are passed to the functions that Runlist is executing. When processing functions using Runlist, the sequence for processing directives is:

IMSDBU programmed defaults.
Directives in the .INI file override the programmed defaults.
When starting Runlist from the interactive screen, any directives from the Runlist entry screen override the previous directives.
When starting Runlist from the command line, any directives entered on the Runlist command line override the previous directives.
Directives specified for a function in the Runlist command file take precedence over all other directives.

The Makelist function adds directives to the function commands in its output Runlist command file. It only adds directives which are specific to a function. Any changes to the .INI file directives between the Makelist and the Runlist will not affect the function directives in the Runlist command file. Makelist does not add any common directives. For example, the LIST, LOG, and ECHO directives. The common directives used by Runlist are the ones active when starting Runlist - not when creating the command file using Makelist.

You can add common directives to the Runlist command file if you want to ensure that changes to the .INI file directives will not affect the operation of Runlist.

Recovery

In the event of a failure, an error message is issued and the Runlist is terminated. The remaining steps in the Runlist command file are not executed. You must determine the cause of the failure and correct it. The error message issued from Runlist is also written to the detail report file. This message should provide enough information to determine the cause of the failure. In some cases, the IMSMTO.LOG file will provide additional information.

The activity log indicates all of the Runlist steps which were successful and the step which failed. Use this to identify the step to restart from. Compare the functions listed in the log to the original Runlist file and identify which step failed.

Use a text editor to modify the Runlist file and remove or comment out all the steps which completed successfully. A step is commented out by placing an asterisk (*) in column 1 of that line.

Rerun Runlist with the modified Runlist command file.