Chapter 37: Developing IMS Applications

This chapter describes the IMS-specific aspects of developing applications with Mainframe Express. For information about using the Mainframe Express IDE, creating projects and compiling and debugging applications see the chapters The Mainframe Express Interface, Developing Applications with Mainframe Express and Workgrouping in this User's Guide.

Creating an IMS Project

You must specify that the project uses IMS when you use the Create new project wizard.

You must then add the source files for your applications to the newly created project. These files are the program source files, DBD files (.dbd), MFS files (.mfs) and PSB files (.psb) that your applications use.

For information about creating an IMS project and adding files to it, see the chapter IMS Applications in your Getting Started manual.

Creating and Editing Source Code

You create and edit the source code for the application programs in your project in the same way as any other Mainframe Express project. See the chapter Editing Programs for more information.

Compiling an IMS Project

You compile the program source code for an IMS project when you build an IMS project.

See the chapter IMS Applications in your Getting Started for information on building an IMS project.

Creating Gens

You create the DBD, PSB and MFS gens when you compile the .dbd, .psb and .mfs source files. You can compile these files as a group when you build your project or individually.

You can find information on compiling individual .dbd, .psb and .mfs files in the DBD, PSB and MFS topics of the online help: click Help Topics on the Mainframe Express Help menu, then on the Contents tab click IMS Option, then choose one of Working with DBD Files, Working with MFS Files or Working with PSB Files.

To view the gen files that have been created:

Select the IMS tab in the Project window
Select DBD Gens, PSB Gens or MFS Gens on the left-hand pane of the project window.
You see the corresponding gen members listed on the right-hand pane.

IMSGEN Directives

IMSGEN directives consist of DBDGEN, PSBGEN and MFSGEN directives. The specification of these directives is not required and if you do not set these directives the default directive settings apply.

For information on how to set these directives, see the online help: click Help Topics on the Mainframe Express Help menu, then on the Contents tab click IMS Option, then one of Working with DBD Files, Working with MFS Files and Working with PSB Files, then Project Management, then one of How to specify DBDGEN build settings, How to specify MFSGEN build settings and How to specify PSBGEN build settings. In addition, any valid DBDGEN, PSBGEN and MFSGEN directive value can be specified as an additional directive. See Enter additional DBD directives, Enter additional MFS directives and Enter additional PSB directives in the IMS Option online help.

The table below lists the valid DBDGEN, PSBGEN and MFSGEN directives. For further information see the online help: click Help Topics on the Mainframe Express Help menu, then on the Contents tab click Reference, IMS Option, then one of DBDGEN Directives, MFSGEN Directives and PSBGEN Directives.

DBDGEN Directives	PSBGEN Directives	MFSGEN Directives
CLS COPYEXT() DEFAULTEXT(ext) ECHO EXCLUPDT IMSLIBNO(x) LIST MAP	CLS COPYEXT() DEFAULTEXT(ext) ECHO EXCLUPDT IMSLIBNO(x) LIST VERIFY	CLS COPYEXT(ext) DEFAULTEXT(ext) ECHO EXCLUPDT /FOR IMSLIBNO(x) LIST MODEL() PREPROCESS() STACK

Transactions

Usually, a transaction definition must exist for any program you want to run. There are two ways of creating transaction definitions:

You can import them from the mainframe
You can define transactions individually

However, you can run a batch program (DLI or BMP program) directly from the command line or an application region without a predefined transaction. For further information see the online help: click Help Topics on the Mainframe Express Help menu, then on the Contents tab click IMS Option, then Managing and Running IMS Applications, How to run your programs.

Importing Transactions

The transaction import facility enables you to extract IMS transactions from an IMS stage 1 file downloaded from the mainframe, and automatically add the transactions to your IMS project. Importing transactions is a process with two steps:

The stage 1 file is read and all the transaction definitions are extracted into another file, known as a transaction file. It is likely that an administrator would perform this step. Note that the stage 1 file never contains any transaction definitions for DLI programs as these are batch programs that run outside the IMS region.
The transaction file from the first step is read and transaction definitions are added to the current IMS project. You can choose whether to import only new transactions or all transactions. There is also an option to delete all the existing transaction definitions in the project before any are imported.

How to...

This two-step process has two advantages:

It provides the opportunity for an administrator to perform further processing on the transaction file before any transactions are added to IMS projects. For example, the single transaction file output from step 1 could be split into a number of transaction files, each containing a subset consisting of transactions required by a specific IMS project.
It means that you can create a transaction file for use with an IMS application developed (or extended) in Mainframe Express. For example, if a team of developers are working on a new application, one developer could create a transaction file containing all the new transactions, then everyone on the team could import the transactions into their IMS project. This would be much quicker than everyone creating the transactions individually.

A transaction file is a standard .dat file. It must use the EBCDIC character set. The record length is 42 characters and the format is as follows:

Field	Format	Comments
Program type	X(3)	Must be one of BMP , MPP , NRMP, QBMP
Transaction code	X(8)	Not required for BMP
PSB name	X(8)
Program name	X(8)
Process limit count	9(4)	Not required for BMP
Scratch pad area size	9(5)	Not required for BMP or QBMP
Number of message segments	9(5)	Not required for BMP

Defining Transactions

For information on how to define a transaction see the IMS Option online help: click Help Topics on the Mainframe Express Help menu, then on the Contents tab click IMS Option, then Defining Resources, Defining Transactions, How to add a transaction code definition.

When you define a transaction you must choose a Program type from the list available on the Transaction Properties dialog box. BMP and DLI are batch programs; MPP, NRMP and QBMP are online programs. Whether or not the remaining fields on this dialog box require a value depends on the program type you select. See the example table below:

Program type	BMP	DLI	MPP	NRMP	QBMP
Trancode name			DEMO1	DEMO2	DEMO3
PSB name	DEMOPSB	DEMO002T	DEMO003T	DEMO004T	DEMO005T
Program name	DEMOPGM	DEMO002T	DEMO003T	DEMO004T	DEMO005T
SPA size			1,000	1,000
Process limit count			99	99	6
Maximum seg no			9	999	0

Conversational MPP and NRMP programs must have a Scratch Pad Area (SPA) greater than zero.

For information on these program types, see the following topics in the online help index: BMP programs, DLI programs, MPP or NRMP programs and QBMP programs.

Debugging Programs

For information on debugging IMS programs see the online help: click Help Topics on the Mainframe Express Help menu, then on the Contents tab click IMS Option, then Managing and Running IMS Applications, How to debug a program.

Defining Printers

You need to define those printers that are sent messages by the applications you intend to run. For more information see the online help: click Help Topics on the Mainframe Express Help menu, then on the Contents tab click IMS Option, then Defining Resources, Defining Printers, How to add a printer definition.

Defining DB Catalog Entries

DB Catalog definitions override the DB Catalog defaults which you can set on the DB Catalog defaults page of the IMS System Properties dialog box.

For information on how to view the DB Catalog default settings or add a DB Catalog definition see the IMS Option online help: click Help Topics on the Mainframe Express Help menu, then on the Contents tab click IMS Option, then Defining Resources, Defining a Database Catalog.

Using Databases

You can specify IMS Option databases as:

Single-user exclusive use databases
Shared read-only databases
Shared update databases
User databases or remote databases

For information on these database types see the chapters Advanced Customization and IMS Fileshare Databases in your IMS Option Technical Guide.

For information on how to set the path to these databases see the online help: click Help Topics on the Mainframe Express Help menu, then on the Contents tab click IMS Option, then Defining Resources, Defining Databases.

IMSDBU - Database Management

You can use the IMSDBU utility to perform a number of database management operations; for example, loading a database.

To access IMSDBU, click IMS > Database Utility on the Tools menu. You see the IMSDBU interactive screen.

Below is an example of how to load a database using the IMSDBU utility. Loading initializes a database and then loads information from an input data file. The input data can be a .dbu file that has been downloaded from the mainframe on to your PC. Before you load a database you need to add the database definition file (.dbd) that is associated with this input data file to the project and then compile this .dbd file.

To load a database:

Type L (for Load) on the IMSDBU screen
Enter the name of the database you want to load, for example DEMO03DD and press Enter
or

Press F2 to obtain a database listing. Type S (for select) next to the database you want to load and press Enter. You return to the IMSDBU main screen. Press Enter to continue.
Specify an Input DSN or a path to an Input DSN on the next screen. For example, DEMO03DD.DBU.
Select the input file layout. For example, G for generic file layout.
Press Enter to execute the load.
A message indicates when the load has finished.
Press Enter to return to the main screen and press Esc to exit the Database Utility.
Loading produces a .dat file in the project's data folder.

Editing Databases

This section describes two methods for editing databases:

Interactive DL/I calls with DBUTIL
Using the Mainframe Express IDE to add data dynamically

Mainframe Express also provides a graphical interface for editing IMS databases. For more information, see the chapter Editing IMS Databases that describes the IMS Database Editor.

Issuing DL/I Calls with DBUTIL

You can use the IMS Option's DBUTIL utility to retrieve, change, insert or delete segments interactively. Combined with its DBUTIL2 companion program and the IDE, you can make changes to database data with relative ease. For information on accessing and using the DBUTIL utility, see the chapter DBUTIL - Interactive DB Calls in your IMS Option Technical Guide.

Using the IDE to Add Data Dynamically

You can use the Mainframe Express IDE's 'Skip to Cursor' and 'Examine' operations to create or update data. You can use:

Examine to enter data
Skip to Cursor to re-execute DL/I calls to insert this data

to dynamically create segments during a debugging session. This technique provides a simple way to add segments to a database.

For example, imagine that you are debugging a program and receive a GE status code (not found) when trying to retrieve a root segment. You can insert the root segment dynamically without exiting the Mainframe Express IDE. The following steps are an example of using this technique with the IDE:

Position the cursor to the letter 'C' in the CALL verb. Select Skip to Cursor on the Debug menu to reset the Cursor position.
Select Examine
On the Examine dialog box, specify the data item whose value you want to examine or select one from the list
Click OK
You see the Examine List dialog box which shows the data item and its current value.
Click Change to change the value.
The Change value of: DATA ITEM dialog box appears. Change the value, for example replace GHU with ISRT.
Click Apply to apply this change to the value of the data item.
You return to the Examine List dialog box.
Click Close to close this dialog box
Click Step to step through the call. The PCB processing options must allow insert calls for this insert operation to succeed.
Repeat steps 2 through 8 to restore the function code to GHU
Repeat step 1 and click Step to step through the call

If you have done this correctly, the GHU results in a 'blank' status code.

For information on debugging in the Mainframe Express IDE, see the chapter Debugging COBOL in your Getting Started.

Problem Determination

See the chapter IMS Problem Determination in your IMS Option Technical Guide.