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.1
stoplvl A value from 4 through 20 to indicate the severity of messages to stop for user input. 1
1 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
  1. 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.
  2. Directives listed in the .INI file override the IMSDBU programmed defaults.
  3. Directives entered on the command line or interactive screen override directives in the .INI file.
  4. Specifying NOINI prevents any .INI file from overriding the programmed defaults.
  5. If you specify an .INI file that does not exist, the programmed default directives are used as if NOINI were specified.
General Rules
  1. 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
  1. 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.
  2. NOLIST suppresses the creation of the listing file.
  3. 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.
  4. Specifying LIST(*.LST) or LIST(*.RPT) causes the listing file to be created in the project listing directory.
  5. If no path is specified, the listing file is created in the current directory.
  6. 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.
  7. 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
  1. 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
  1. 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.
  2. Specifying NOLOG suppresses the log file output.
General Rules
  1. The log file is created if it does not exist.
  2. The log file is historical with the most recent entries written to the end of the file.
  3. 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
  1. 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.
  2. For relatively fast systems, setting the value higher (such as to 1000 or larger) might improve performance slightly.
General Rules
  1. 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:

  1. IMSDBU programmed defaults.
  2. Directives in the .INI file override the programmed defaults.
  3. When starting Runlist from the interactive screen, any directives from the Runlist entry screen override the previous directives.
  4. When starting Runlist from the command line, any directives entered on the Runlist command line override the previous directives.
  5. 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.

Parent topic: mfims imsdbu functions