This chapter describes the following topics:
These sample files are distributed with IMS Option. They are located in the mfe\mfims\source folder unless customized during installation.
|Mainframe IMS/ESA DB extract - IMSDBUV.CBL||Can be used on your mainframe to extract an IMS/ESA database into a variable length sequential file for downloading and subsequent loading by the IMSDBU utility. IMSDBUV creates a formatted file specifically for use by IMSDBU on the PC. It can optionally compress the segment data to reduce disk space and transfer time.|
|Mainframe IMS DB extract JCL - IMSDBUV.JCL||Sample JCL for use with the IMSDBUV|
|Mainframe IMS DB extract compression - IMSDBUC.CBL||Compression program for IMSDBUV|
|Alternative IMS DB extract - DBUTILV.CBL and DBUTILF.CBL||These programs can also extract an IMS/ESA database. It creates a 'generic' extract file which can be used by either IMSDBUV or DBUTIL utilities. DBUTIL was the primary database load utility before IMSDBU was introduced with version 3.1. DBUTILV creates a variable length output file suitable for downloading. DBUTILF creates a fixed length output file.|
|Alternative IMS DB extract JCL - DBUTILV.JCL and DBUTILF.JCL||Sample JCL for use with DBUTILV and DBUTILF|
|Dynamic DB attach interface - DDBA.CBL and DDBA.TXT||The Dynamic DB Attach interface is a flexible way to 'connect' to IMS Option for issuing database calls. DDBA.TXT describes the detailed specifications for this API. DDBA.CBL is a sample program to demonstrate its use. An MFIMSCOB.DLL is provided with the IMS Option installation to allow other language programs to call the dynamic attach interface. See the MFIMSCOB.TXT file for details.|
|Gen file access - IMS86GIO.TXT and CALLGIO.CBL||CALLGIO demonstrates using the IMS86GIO call interface to retrieve and update the Trancode, Printer, DBD, PSB and MFS Gen, DB Catalog and System Configuration. The IMS86GIO.TXT file provides a complete description of the parameters and use of these APIs.|
|Utility call interface - CALLUTIL.CBL||Demonstrates and documents the callable interface for running the IMS Option utilities.|
|IMSDBU call interface - DBUDEMO.CBL||Demonstrates the use of the direct call interface to IMSDBU for advanced DB administration|
|MFS color/attributes - MFSATTRS.MFS||Shows how the 3270 attribute and extended attributes will appear in your environment. The color and high-lighting appearance may vary based on your operating system and your terminal configuration.|
|Default MFS format source -DFHMO2.MFS||Allows manual Gen of the default MOD that is used by IMS Option|
|Remote IMS Requester configuration file - RMTIMS.INI||Example configuration file for the Remote IMS Requester|
|TSO CLIST - USERIMS.TSO||Sample TSO CLIST for IMS Option Application Region. Provides customization of IMS Option initialization and termination.|
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.
|Animating DBUTIL calls - DBUTIL2.CBL||Allows you to debug DL/I calls issued by the DBUTIL utility so that you can use the power of Debugger to modify or view the DL/I calls issued.|
|IMSDBU Load and Unload exits - DBUPARMS.CPY||IMSDBU provides two exits during Load, Add and Unload processing. One allows for selecting and changing segments. The other provides for compression/decompression of the input and output sequential files.|
|COBOL MFS MFLD exit - DFSME000.CBL||A COBOL implementation of the DFSME000 Assembler MFS field edit exit routine provided with the IMS/ESA product.|
|COBOL MFS MFLD exit - DFSME127.CBL||A COBOL implementations of the DFSME127 Assembler MFS segment edit exit routine provided with the IMS/ESA product.|
|IMS2ASM for MF370 MVS mode - IMS2ASM.MLC||A 'glue' module between IMS Option and Assembler Option for support of Assembler IMS system exits.|
|Custom SQL syncpoint exit - IMS2SQL.CBL||Allows integration of SQL products into the IMS Option syncpoint coordinator. Can also be used to replace the built-in SQL support for additional security, database selection, or other purposes.|
|DC CHNG call exit - IMS86ALT.CBL||Can programmatically add printer definitions and change transaction definition information during application execution. This exit is invoked each time an application issues a CHNG call.|
|User entry point management - IMS86ENT.CBL||Provides for programmed customization of IMS Option initialization and termination and invocation of IMS applications.|
|MFS display exit - MFSDISP.TXT and MFSDISP.CBL||Enables you to replace the terminal handling built-in to IMS Option to re-map the 3270 MFS screens into a different format (such as a GUI) or to send the screens from/to other systems.|
|MFSGEN preprocessor exit - MFSPREPR.CBL||Allows programmed modification of MFS source input to the MFSGEN utility.|
|COBOL DB sparse routine - SPARSRTN.CBL||A COBOL example for implementing Database Secondary Index sparse routines in COBOL.|
|User DB handler exit - USERDB.TXT and USERDB.CBL||Provides for programmatic control of the DB Catalog setting for a database instead of using the defined DB Catalog. Also, this exit can process DL/I calls completely, for example, to map DL/I calls into VSAM I/O requests.|
|User written CBLTDLI - USRTDLI.CBL||Provides for programmed customization of the CBLTDLI interface or to provide alternate DL/I interfaces.|
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:
|CALLGIO2.CBL||CALLGIO2.CBL combines IMS86GIO with other features to reorganize the Gen files from a command line and other sample uses|
|CALLUTIL.CBL||Demonstrates use of the callable interface for the utilities|
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.
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:
|Process statement||Identifies major steps in a utility. For example, 'MFSGEN starting'|
|Source statements or detail information||The input source statements for DBD, PSB and MFS Gen or other detailed information for other utilities. For example, with the PSBGEN Verify utility, this would be the display of the verification results of each PCB instead of just the final result.|
|Warning and Error messages||Messages which result from the utility|
|Ending message||The final result of the utility. For example, DBDGEN for MYDBD successful RC=04.|
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:
|4 and 6||'W' suffix meaning Warning|
|8 and 10||'E' suffix meaning Error|
|12||'S' suffix meaning Severe|
|16 and 20||'U' suffix meaning Unrecoverable|
The directive used to control the interaction with the utilities is ECHO. You can specify three values for this directive which instruct:
It is specified as:
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:
|IMS Option v 2.5
|ECHO(ON)||Converts to ECHO(ALL)|
|ECHO(OFF)||Ignored since it matches the new ECHO default settings|
The table below describes the ECHO values:
|ECHO(ALL,msglevel,stoplevel)||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 msglevel and stoplevel values.|
|ECHO(MSGS,msglevel,stoplevel)||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 msglevel and stoplevel values.|
|ECHO(ERREND,msglevel,stoplevel)||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 msglevel and stoplevel values.|
|ECHO(ENDMSG,msglevel,stoplevel)||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 stoplevel. Enter a msglevel and/or stoplevel value of zero to display and/or stop on every ending message.|
|ECHO(COND,msglevel,stoplevel)||Both the warning/error and
ending messages are conditional on the msglevel and stoplevel
values. Warning and error messages are displayed and stop for user input
if the message level is equal to or greater than the msglevel
and stoplevel values. The ending message is displayed if the
ending return code is equal to or greater than msglevel. You see
|ECHO(ERRORS,msglevel,stoplevel)||You see warning and error messages which require input if the message level is equal to or greater than the msglevel and stoplevel. You do not see the ending message.|
|NOECHO||Disables all display and stopping for user input. Setting NOECHO also sets the NOCLS directive to prevent the screen from clearing. For the MFSGEN utility, it also forces the NO/FOR directive. The NOECHO directive provides a video and keyboard 'quiet' mode of operation.|
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
apply. A stoplevelof 50 disables all stopping for user input.
|ECHO(ALL)||Valid - same as ECHO(ALL,4,8)|
|ECHO(ENDMSG)||Valid - same as ECHO(ENDMSG,4,8)|
|ECHO(ALL,6)||Error - defaults to ECHO(ENDMSGS,4,8)|
|ECHO(MSGS,,6)||Error - defaults to ECHO(MSGS,4,8)|
|ECHO(MSGS,8,4)||Error - defaults to ECHO(MSGS,4,8)|
|ECHO(BAD,6,10)||Error - defaults to ECHO(MSGS,4,8)|
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:
|Warning messages||Continue, Quit, Zoom (suppress pausing) and Up Lvl (quit pausing at this message level)|
|Severe errors||Generally just Quit but some utilites offer Continue, Zoom and Up Lvl. For example, PSBGEN Verify can continue verifying the remaining PCBs even if one PCB has an error.|
||Category of data is:
|Echolvl||Controlled by msglevel and stoplevel settings|
|Keyword||Source/detail||Process messages||Warn/Err messages||Ending message|
Displays process, warning, error and ending messages. Any error causes the utility to stop for input from the user.
Same as ECHO(MSGS,4,8) but adds the display of source statements or other detail information depending on the utility.
Displays IMS Option specific errors and the ending message. Severe errors cause the utility to stop for input from the user.
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.
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.
Displays error message and stops for input from the user.
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.
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.
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.
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'.
You can restrict developers' access to the DBDGEN and PSBGEN utilities by deleting the library (.lbr) file containing the respective utility:
If you try to use DBDGEN or PSBGEN after deleting the library, you see the error message "Utility not installed".
Note: You must retain at least one copy of the library files for your DBD and PSB Gens to run.
Copyright © 2001 Micro Focus International Limited. All rights reserved.
This document and the proprietary marks and names used herein are protected by international law.