IMS Fileshare DatabasesNext"

Chapter 1: Advanced Customization

Customization is the process of tailoring software to suit your requirements and preferences. This chapter describes some of the more advanced customization topics available in IMS Option. It is intended to be read once you are familiar with the basic operation of IMS Option as described in the online help.

There is a great deal of customization available with IMS Option, for example, choosing locking strategies for optimizing multi-user databases. However, we recommend that you do only a minimal amount of customization until you are more familiar with IMS Option.

The topics described in this chapter are:

1.1 IMS Option Settings

IMS Option settings are used mostly to indicate where groups of files will reside. They name the drive and folder and IMS Option places and reads data from that location.

To access the following IMS Option settings select Project Settings on the Project menu and then click the IMS tab.

1.1.1 Exclusive Use Databases

You need to select the drive and folder for single-user exclusive use databases in Exclusive use databases on the IMS page of the Project Settings dialog box. If you do not select a drive and folder in this field, IMS Option puts these databases in the project \data folder.

You can select multiple drives and folders in Exclusive use databases. For example:


Multiple folders provides a search path for database data files. When IMS Option tries to open the database, it looks in the first drive and folder. If IMS Option does not find the database, it searches the second drive and folder and so on, through all listed folders.

A zeroload always creates the database files in the first drive and folder listed in the Exclusive use databases field. If you want a database to be in a drive and folder listed after the first one, you must move the files to your target folder after the zeroload.

1.1.2 CONFIG Folder

IMS Option configuration files are the mfims.ini file used by the IMSDBU utility and the IMS System Configuration data. The search for mfims.ini starts in the \mfuser folder and if it is not found the search moves to the \config folder. The System Configuration data is stored in indexed files with the names of imsconfg.dat and imsconfg.idx; these are in the \mfuser folder.

The mfims.ini file is an ANSI text file which can be edited using any text editor.

1.1.3 Listing Output

All DBDGEN, PSBGEN, MFSGEN, DBD MAP, IMSPRINT, PSB Verify and IMSDBU listing output is placed in the Listing Output folder (a subfolder of the Output Libraries folder). You may navigate to this folder using the Workgroup tab.

1.1.4 Shared Read-only Databases

You set the Shared read-only databases field to indicate the drive and folder for shared read-only databases. This field must be set if you use shared read-only databases. This field does not default to the current folder if it is not set. If you do not use shared read-only databases you do not need to set this field.

The Shared read-only databases field enables sharing of databases for read-only. This means that no one sharing the database can update it. If you need to share a database which at least one person or program needs to update, you must use a Fileshare Database. Read-only sharing is a very efficient way of sharing databases as long as no one is permitted to update them. Fileshare Databases are described in the chapter IMS Fileshare Databases.

The Shared read-only databases field may list multiple drives and folders. For example, you can locate your Shared read-only database data files on different network drives and specify a concatenated path in this field, such as:


Multiple folders provides a search path for read-only database data files. When IMS Option tries to open the database, it looks in the first drive and folder. If IMS Option does not find the database, it searches the second drive and folder and so on, through all listed folders.

1.1.5 Copybooks for IMS Source Files

IMS copybooks are found using the folder list defined in the Dependency Libraries folder. You may navigate to this folder using the Workgroup tab. This folder is also used for COBOL copybooks and Assembler macros.

1.2 Concatenating Load Libraries Definitions

The Gen definitions in the Load Library folder can be concatenated with other Gen definitions in other folders. The concatenation list is maintained using the Workgrouping Load Libraries. IMS Option supports twenty five levels of concatenation.

A Load Library folder can contain one or all of the five different Gens. A Load Library folder does not have to contain all the Gen files. If a folder does not have one of the Gens, the Gen files which are present are accessed from the folder and the missing Gen files are just ignored. For example, a Load Library folder could contain DBD, PSB and MFS Gens but not have the IMSGEN or DB Catalog Gen files.

When running a Gen update utility, you must select which of the Load Library folders is updated. To do this select the Workgroup tab and deselect all the Load Library folders except the folder you want to update or place your Gen files.

If you need to limit access to these files, you can use your network product's security features or alternative packages. See the chapter Security for more details.

See the Workgrouping documentation for details on how to specify a load library.

1.2.1 Concatenation - Overview

The concatenation that results from using multiple Load Libraries is similar to specifying multiple PDS data set DD statements for a JCL DD name. For example:


Each Load Library folder corresponds to one DD statement. For example, .\LOADLIB could name a folder for a DBDGEN file containing Gens for DBDTESTA, a second Load Library folder could name a folder for a DBDGEN file containing the Gens for DBDTESTB, a third Load Library folder could name a folder for DBDTESTC and a fourth Load Library folder could name a folder for DBDPROD.

1.2.2 Concatenation - a General Description

The IMS Option Gen files contain one or more resource definitions. We'll call each of these resource definitions a member within the Gen file. You could think of each member as a record in the Gen file but it is actually a set of records. Each member within a Gen file must have a unique name. The name is the IMS Option resource being defined:

When you Gen or define a resource, the output member is stored in the corresponding Gen file. As you Gen or define more resources, they are added to or replaced in the Gen file. To select which Load Library folder is updated, select the Workgroup tab and deselect all the Load Library folders except the folder in which you want to update or place your Gen files.

Concatenation is not used when updating the Gen files, it is only used when reading from the Gen files. IMS Option reads the Gen files when running application programs and for the IMSDBU and zeroload utilities. The DBD MAP and PSB Verify also read from the Gen files: they search all the concatenated Load Libraries until the required member is found.

To find a Gen member using concatenation, the Load Library folders are searched in sequence. The first matching member name in a Gen file is the member definition used. That is, if the member name exists in the Gen file in .\LOADLIB, it is used. If not in .\LOADLIB, the member name comes from the second Load Library folder. If not in this folder, the member name comes from the Gen file in the third Load Library and so on.

1.3 Fileshare with Shared Read-only Databases

The shared read-only databases can be accessed using standard operating system and network software. IMS Option and Fileshare include support for many networks.

You can also use the Fileshare component to access these files. Fileshare may provide better performance in some environments. A detailed discussion of performance is provided in the chapter IMS Performance and Tuning. This section is intended to show the use of Fileshare to access these files, not to suggest that you should use it. See the chapter IMS Fileshare Databases for more information on the use of Fileshare for shared update databases.

You route the I/O for the shared read-only databases to Fileshare by changing the setting of the Shared read-only databases field. You change the setting to indicate the Fileshare Server name and an optional drive and folder.

Instead of naming a drive and folder for these settings, use a '$$' (two U.S. dollar signs) and the Fileshare Server's name. You can optionally provide a drive and folder for the files. The drive and folder is the drive and folder on the Fileshare Server machine, not the client machine accessing Fileshare.



This indicates that all I/O to shared read-only databases should be directed to the Fileshare Server named "FSSRVR" and the files are in the current folder for Fileshare. That is, the folder that the Fileshare Server was started from. The two dollar signs are not part of the name when starting Fileshare, they are only an internal convention for indicating use of Fileshare.

1.4 Sample Settings for a Network

These settings show one example of a drive and folder structure for a network environment. There is no single right way to structure your system. You need to consider your situation and structure your environment accordingly. See the chapter IMS Performance and Tuning for performance considerations when using a network.

In this example, the c: drive is on the client machine. The s: drive is a network server drive accessed through network redirection. Redirected drives are the typical server drives assigned using your network commands such as NET USE or Novell's filename mapping. The d: drive is a drive on the server machine. Since the d: drive is accessed by Fileshare, it must be a drive and folder on the Fileshare Server machine - not a drive on the client machine.

Brief description of these examples:

Databases Field
Exclusive use Names a local drive and folder for single-user exclusive use databases
Shared read-only Names a server redirected drive for shared read-only databases
Fileshare Names a Fileshare Server name for multi-user update databases. d:\server\drive names a folder on the Fileshare Server machine which contains the databases

1.5 System Exits

System exits are specific places where you can change the operation of IMS Option with your own software. There are several types of exits which are described in the following sections.

1.5.1 IMS86ENT - Initialization and Entry Point Control

IMS86ENT provides programmed customization of IMS Option initialization and termination and the calling of IMS Option applications. Some examples of uses are:

This exit is enabled by including an executable module by the name of IMS86ENT in the Workgroup Load Libraries folder. To do this add the IMS86ENT source to your project. When you compile IMS86ENT the load module is created in the Project's default Load Library folder defined in the Workgroup tab. When IMS Option initializes, it tries to locate an executable program (not just source code) by this name. If the program is found, it is called with an INIT function call. If one is not found, this exit is disabled and IMS Option continues without any messages. The INIT function can also disable any further use of this exit by setting a non-zero return code.

IMS Option pre-loads the main program for a transaction or batch program to make its entry points known to the system. When this is complete and IMS Option is ready to CALL the program, it calls IMS86ENT instead with a CALL function. IMS86ENT is passed the list of PCBs and some other information about the PCB list. It can perform any processing it requires and then must CALL the application. When the application issues its GOBACK, control is returned to IMS86ENT. IMS86ENT can perform additional processing and must GOBACK to IMS Option.

During IMS Option termination, the IMS86ENT exit is called with a TERM function so IMS86ENT can perform termination logic. IMS Option termination occurs when a /RCL command is issued or a batch program issues a GOBACK. Termination is also invoked for abnormal application exits such as invoking the Stop Debugging or Restart Debugging or system or run-time failures.

A sample IMS86ENT exit routine is provided in the mfe\mfims\source folder when you install IMS Option. As provided, it does nothing other than to show and further describe the actual calling parameters. The sample exit program is named Ims86ent.cbl. This program can be modified, compiled and run or debugged as any other program. If used, it becomes part of the IMS Option Application Region and not part of any transaction.

1.5.2 User-written CBLTDLI Routines

Some organizations have customized the CBLTDLI routine that is provided with IMS/ESA. IMS Option also provides the ability to customize the CBLTDLI routine within it. Customizing of CBLTDLI is not required unless you have performed a customization of CBLTDLI on the mainframe. Contact your technical support staff if there is any doubt on this subject.

Most customizations of CBLTDLI result in a new program being written which is called by the application program instead of calling CBLTDLI, example, CALL 'ABCTDLI' USING GU DBPCB etc. IMS Option provides for this by providing a program, UsrtDLI.cbl, which is installed in themfe\mfims\source folder with IMS Option. UsrtDLI.cbl is renamed to the name of the program which the application calls. In the example just given, you rename UsrtDLI.cbl to AbctDLI.cbl. You would also change the PROGRAM-ID name in the program. USRTDLI is a source program which can then be modified to perform the processing required by the alternate CBLTDLI module. After modification, USRTDLI may be compiled and run as any other program under IMS Option. Comments included in the UsrtDLI.cbl source program describe the use of the program in more detail, the compiler directives required and so forth.

Another type of customization to CBLTDLI results in actually changing the CBLTDLI module in IMS/ESA by replacing it with a separate one. This results in the application program continuing to call CBLTDLI, however, the CBLTDLI module would act differently compared to the CBLTDLI module as documented by IBM. This type of customization is also provided for but there are several techniques to replace the CBLTDLI module built-in to IMS Option. Which technique is appropriate depends on too many factors to be explained here. Please contact your technical representative for implementation assistance.

1.5.3 User-written DLITCBL Routines

It is possible to customize the DLITCBL routine provided with IMS/ESA. Customizing of DLITCBL in IMS Option is not required unless you have performed a customization of DLITCBL on your mainframe. Contact your technical support staff if there is any doubt on this subject. As with CBLTDLI, this is most often implemented as a new routine which the application program 'links in' and then uses an ENTRY 'ABCTCBL' USING PCB1 PCB2, etc., instead of ENTRY 'DLITCBL' USING PCB1 PCB2, etc.

IMS Option provides for this capability with the use of the IMS86ENT system exit explained in this chapter. In general, the implementation of a customized DLITCBL routine would also require a customized CBLTDLI routine. Although this customization is fairly straightforward in IMS Option, the customization of linkage conventions and the DL/I interface can become complex. The details of all possibilities is much too lengthy to describe here. If your organization requires these features, please contact your technical representative for assistance with your particular environment.

1.5.4 IMS86GIO - Read and Update Gen Files

IMS86GIO is a routine which can be called by a stand-alone program or by an online IMS Option program. As a note, the IMS configuration panels use IMS86GIO to perform all of their functions. IMS86GIO provides for:

The called routine is named IMS86GIO. IMS86GIO is built-in to the IMS Option system software. A sample program named CALLGIO.CBL is provided in the \mfims\source folder for IMS Option. It shows sample uses of the IMS86GIO interface. An ims86gio.txt file is also supplied in the \mfims\source folder. It provides a detailed explanation of all the functions available with this interface.

1.5.5 MFS Field Exits

MFS MFLD exits are supported in Assembler and COBOL languages. A complete explanation of MFS field exits is provided in the chapter For the TM/MFS Expert.

1.5.6 Secondary Index Sparse Routines

Secondary Index external sparse routines are supported for both Assembler and COBOL language programs. A complete explanation of these routines is provided in the chapter For the Database Administrator (DBA).

1.5.7 User Program Database Exit

This exit serves two different purposes:

This exit is documented in files provided in the mfe\mfims\source folder. One of the files is userdb.cbl showing the call parameters and the other is userdb.txt which describes the exit in more detail.

1.5.8 IMS86ALT DC CHNG Call Exit

This exit is used to add printer definitions dynamically and change transaction definition information during application program execution. This exit is invoked when a DL/I CHNG call is issued. There is a sample program, Ims86alt.cbl in the mfe\mfims\source folder where IMS Option is installed. It contains a more detailed description of this and the call parameters.

To enable this exit, you must:

1.5.9 Dynamic Database Attach - DDBA

DDBA provides a dynamic call interface for initialization, control and access of IMS Option Databases. This API is intended as a flexible mechanism for vendors or customers wanting to provide a specialized interface to the IMS Option Database subsystem. This interface enables access to IMS Option databases without having to adhere to the normal rules for a batch or online program. That is, you do not have to run under the control of an IMS Option Application Region or the CICS Option. You could think of this as being your own TP monitor - your program handles the screen displays and the syncpointing according to your own requirements. An example of this would be to get access to IMS Option databases from a native GUI application.

There are two on-disk files installed in the mfe\mfims\source component of IMS Option: the ddba.txt file, which describes this interface, and the ddba.cbl program, which demonstrates the use of these APIs.

It is important to note that ddba.cbl cannot be compiled with the AMODE directive. To disable this directive:

  1. Click the Files tab

  2. Select the Cobol folder on the left-hand pane of the project window

  3. Right-click on ddba.cbl in the right-hand pane and select Build Settings for ddba.cbl in the popup menu

  4. Enter NOAMODE in the Additional directives entry field on the General page

  5. Click OK

Copyright © 1999 MERANT International Limited. All rights reserved.
This document and the proprietary marks and names used herein are protected by international law.

IMS Fileshare DatabasesNext"