IMS Installation Verification

Chapter 14: IMS Option Administration Information

This chapter describes the following topics:

• Sample files

• System exits

• Call interface

• The ECHO system

• The IMS system log

• Restricting access to DBDGEN and PSBGEN

14.1 Sample Files

These sample files are distributed with IMS Option. They are located in the mfe\mfims\source folder unless customized during installation.

14.2 System Exits

These programs are distributed with IMS Option. They are located in the mfe\mfims\source folder unless customized during installation. Refer to these sample programs and the chapter Advanced Customization in the IMS Option Technical Guide for details.

14.3 Call Interface

The call interface is used to run the IMS Option utilities directly from a COBOL program by issuing a CALL and passing a command line. It is intended for specialized situations where you need to provide a highly integrated or automated environment.

A sample program named CALLUTIL.CBL is provided in the mfe\mfims\source folder to demonstrate its use. This sample also provides the technical specifications for this interface.

The call interface provides for specialized integration between the utilities and other routines and it requires you to develop a COBOL program to CALL the utilities. The COBOL return-code special register contains the utility's ending return code. For example, you could develop a program which uses the IMS86GIO routine to get a list of the Genned DBDs. You could then call the IMSDBU utility to reorganize all of the databases.

The following files are provided in the mfe\mfims\source folder to further document and demonstrate this interface:

14.4 ECHO System

The ECHO system is a simple but powerful mechanism for controlling the display and interaction of the IMS Option utilities. It is driven by two basic factors - what to display and when to stop (or prompt) for instructions. The subsections below describe the Echo system. The section IMSGEN Directives in the chapter Developing IMS Applications in your User's Guide describes the specific features of Echo that the DBD, PSB and MFS utilities supports. Most of the utilities support all of the features listed in this section.

This ECHO system provides flexible control of the IMS Option utilities. Optimal settings for your environment may not be obvious. However, the default ECHO settings result in a reasonable behavior for many uses and one which is compatible with previous versions of IMS Option. It may require that you do some experimentation to develop the settings to suit your preferences. You may find you prefer different settings for different utilities.

14.4.1 Categories of Output and Messages

The ECHO system works by grouping the displayed data into four categories, expanding the groupings of the error messages into seven groups and providing control of these groups by use of a single utility directive. The categories for the displayed data are:

Categories for the Warning and Error messages are:

4 - General warning message

For example, a minor coding error in DBD source which DBDGEN can make an assumption about and continue.

6 - IMS Option specific warning message

For example, a warning that a keyword or statement is not supported and is ignored - processing can continue.

8 - General severe error

For example, an incorrect coding in DBD source which cannot be compensated for such as 'no DBD statement'.

10 - IMS Option specific severe error

For example, an unsupported feature was defined which cannot be compensated for such as 'Exceeded some maximum'.

12 - Severe error - possible temporary condition

Generally an I/O error. For example, a 'file locked' or 'database locked' status.

16 - Severe error - permanent - likely installation problem

Generally an I/O error. For example, 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.

In Mainframe Express these error message categories have the following mapping:

14.4.2 ECHO Directive Details

The directive used to control the interaction with the utilities is ECHO. You can specify three values for this directive which instruct:

• Which categories of information are to be displayed

• The severity of messages to display

• The severity of messages which stop for user input

It is specified as:

ECHO(keyword,msglevel,stoplevel)

The default setting is ECHO(MSGS,4,8) which results in you seeing the processing steps, all warning and error messages, stopping for error messages and display of an ending message.

The msglevel and stoplevel values are 4 through 20 to indicate the message categories described earlier. There is also special purpose settings of zero and 50. You do not have to specify msglevel and stoplevel values with an Echo Keyword, but, if you specify one level you must specify the other.

If the older ECHO(ON) or ECHO(OFF) directive from version 2.5 of IMS Option is used for MFSGEN, it is converted as follows:

The table below describes the ECHO values:

Interaction details - stoplevel

The stoplevel can be equal to or higher than the msglevel. A stoplevel less than the msglevel results in using the default ECHO settings. Specifying a msglevel with no stoplevel also defaults the ECHO settings. If an ECHO keyword only is specified, the msglevel and stoplevel defaults of 4,8 apply. A stoplevelof 50 disables all stopping for user input.

Example inputs:

stoplevel only indicates which messages are paused awaiting input from the user. It does not override the normal error handling of the utility. For example, DBD, PSB and MFS Gen utilities cannot continue once an error message level 8 or above is encountered. If stoplevel exceeds 8, these utilities do not stop on those errors and immediately display the ending message indicating a failure.

In association with these options, additional actions are allowed when a warning or error message is paused. The actions that are offered depends on the utility being run, but, in general, the following actions apply:

14.4.3 Expert Quick Lookup

14.4.4 Example ECHO Uses

ECHO(MSGS,4,8)

Displays process, warning, error and ending messages. Any error causes the utility to stop for input from the user.

ECHO(ALL,4,8)

Same as ECHO(MSGS,4,8) but adds the display of source statements or other detail information depending on the utility.

ECHO(ERREND,10,12)

Displays IMS Option specific errors and the ending message. Severe errors cause the utility to stop for input from the user.

ECHO(ENDMSG,0,6)

Displays every ending message since the utility ending return codes will all be equal to or greater than zero. The ending message will stop for input from the user if the ending return code is 6 or higher indicating an IMS Option specific warning message or higher.

ECHO(ENDMSG,0,50)

Displays every ending message since the utility ending return codes will all be equal to or greater than zero. The ending message does not stop for input from the user because no ending return code can exceed 50.

ECHO(ERRORS,8,8)

Displays error message and stops for input from the user.

ECHO(COND,8,8)

Same as ECHO(ERRORS,8,8) but the ending message is also displayed if the ending return code is 8 or higher; the ending message also stops and waits for input from the user.

14.5 IMS System Log

The IMS System Log is a general-purpose log file. It is used to provide descriptive information for serious problems encountered when debugging, running or using the IMS Option utilities. It consists of the Mainframe Express IDE's IMS Log tab and the imsmto.log file in the Listing folder.

• The Mainframe Express IDE's IMS Log tab:

  This contains messages produced during the current execution of the IDE. When you start the IDE, the IMS Log tab is disabled until a message is produced. You can clear the IMS Log tab at any time during an IDE session.

• The IMSMTO.LOG file in the Listing directory:

  This is a historical log file. The most recent log entries are added to the end of an existing imsmto.log file. It is an ASCII text file and is created the first time a message needs logging. You may need to delete this file periodically as it could grow quite large. The 'mto' in imsmto stands for 'Master Terminal Operator'.

Note: You must retain at least one copy of the library files for your DBD and PSB Gens to run.

IMS Installation Verification