Chapter 2: CICS Walkthrough

This chapter walks through the process of building a CICS application in Net Express with MSS, and deploying it under Enterprise Server.

Overview

CICS applications that used to run on the mainframe, now run under Enterprise Server. You maintain the applications in Net Express.

The process from developing through to running the application is as follows:

1. Create a Net Express project comprising all the parts of the application, such as the COBOL source and BMS mapsets.
2. Edit and compile BMS mapsets in Net Express.
3. Compile the CICS COBOL programs in Net Express.
4. Edit the CICS resource definitions if necessary.
5. Deploy the application to Enterprise Server.
6. Configure an enterprise server to run CICS applications, by adding a listener for MSS requests, setting environment variables and so on.
7. Run the application in Enterprise Server and check that it is working correctly.
8. Debug the application as necessary, in Net Express.

Demonstration Application and Prerequisites

Throughout this chapter, the demonstration application ACCT supplied with Net Express is used as an example. The ACCT application comprises several COBOL programs and two BMS maps, and uses the resource definitions in the file dfhdrdat.

To work through this chapter, you need:

• Net Express.
• Enterprise Server
• Mainframe Subsystem Support (MSS), an option within Enterprise Server

Enterprise Server is an option in Net Express, and is also available stand-alone.

Creating a Project in Net Express

To build an application in Net Express, you need to create a Net Express project. You need to add to the project all the files that comprise the application, such as the COBOL source files and any BMS files.

The files for the demonstration are in the directory, Examples\Net Express IDE\mto-bms of your Net Express installation.

Open the demonstration project in Net Express. To do this click File > Open and browse to acct.app and select it.

Notice that the project consists of:

• acct0*.cbl - COBOL source files
• acctrec.cpy - COBOL source copy file
• acctset.bms - BMS mapset source file
• acctset.cpy - BMS mapset copy file
• acctset.mod - BMS mapset load module
• dfhaid.cpy and dfhbmsca.cpy - System copy files, which are supplied in the base\source directory.

The project tree view shows acctset.cpy and acctset.mod, but these files don't exist yet. They will be created when the BMS mapset is compiled.

BMS Maps

The BMS maps need to be included in your Net Express project, so that you can edit and compile them easily. To edit them, you use the BMS Screen Painter in Net Express. To compile them, you use the Compile option in Net Express. You can compile just the BMS mapsets or the whole project.

Editing BMS Maps

You can also edit a text version of the BMS map by right-clicking the BMS macro (.bms) file in the right-hand pane of the File View and clicking Edit as Text.

How to ...

Compiling BMS Mapsets

If a transaction program uses BMS maps, the program must have a symbolic definition of the maps that it uses to send or receive data. This symbolic definition is stored in a load module, which is generated when you compile the BMS maps and mapsets.

When you compile a BMS mapset, a copyfile .cpy is, by default, generated for it in the project directory, and also a load module .mod.

The filename given to the load module is by default mapset.mod, where mapset is the name field of the BMS mapset's properties and is defined in the DFHMSD macro in the BMS source; it is not the name of the BMS mapset file itself. Any EXEC CICS SEND MAP commands must use this mapset name. You can override the default name mapset.mod and specify your own filename, in the BMS Build Settings, on the Advanced tab, in the DSECT and MAP fields.

When Enterprise Server runs the application, it needs to know where the BMS load module is. You specify its location using the TXMAPP environment variable, but more of this later.

To compile the BMS mapset for the demonstration application:

1. Check the build settings of the BMS mapset to ensure that the copyfile and load module will be generated. You can do this either for the whole project or for an individual mapset.

   How to

   By default, the settings specify that both the BMS copyfile and load module are generated. You can prevent generation of these by unchecking DSECT and MAP as needed.

2. Right click the BMS mapset acctset.bms in the project tree view on the left.
3. Click Compile.

   The acctset.cpy copyfile is generated and added to the files list on the right of the project. The acctset.mod load module is also generated.

Compiling CICS COBOL Programs

You can compile CICS COBOL programs using Net Express.

When you compile CICS, you use the CICS External Compiler Module (preprocessor or ECM). This is invoked by the CICSECM() directive, which you set when you choose EXEC CICS in the project build settings.

The type of object files created, and where they are put, depends on the build type you select. For the default build type, General Debug Build, they are .int and .idy files and they go in the debug directory.

When Enterprise Server runs the application, it needs to know where the object files are. You specify their location using the TXTRANP environment variable, but more of this later.

To compile the demonstration application:

1. Click Project > Properties.
2. Make sure that EXEC CICS is checked. Notice that this sets the directive CICSECM() in the Project Directives field.
3. In the Project Directives field, make sure that OSVS is entered before the semicolon. This sets the OSVS directive, which is required because the demonstration was written in the OS/VS COBOL dialect.
4. Build the project by clicking Project > Rebuild All.

If you used the default build type, Debug Build, the build created . int and .idy files and put them in the Examples\Net Express IDE\mto-bms\debug directory of your Net Express installation.

Deploying to Enterprise Server

To deploy to Enterprise Server, you need to:

1. Copy the application and its supporting files, such as data files and the resource definition file, to the location where you want to run the application. To be able to debug the application when it runs on Enterprise Server, you must include the dictionary (.idy) files.
2. Enable MSS in the enterprise server you are using.
3. Configure search paths.
4. Add an Enterprise Server listener for MSS requests.
5. Update the CICS resource definitions for your application, as necessary.

To do these tasks (apart from copying files), you use the Enterprise Server Administration console and Enterprise Server Monitor and Control (ESMAC). See the chapters:

• Deploying a Service in your Net Express Interface Mapping Tutorials for a tutorial using Enterprise Server administration.
• Introduction to Enterprise Server Administration in your Enterprise Server Configuration and Administration Guide for background to Enterprise Server administration.
• Administering Servers Using ESMAC in your Enterprise Server Configuration and Administration Guide for information on using ESMAC.
• Administering MSS-enabled Servers Using ESMAC in your MSS Configuration and Administration Guide for information on using ESMAC specifically for MSS-enabled enterprise servers.

Copying the Application Files

All the files for your application need to be available to the enterprise server that will run your application. You will probably want to copy the application files, for example, if you want them on the same machine as the enterprise server or if you want them in a different location from the files you are continuing to work on.

Your application comprises the following files:

• Compiled COBOL files (such as .int or .gnt)
• BMS load modules (.mod files)
• CICS resource definition file and its index file (dfhdrdat and dfhdrdat.idx)
• Data files (as appropriate)

  The acct demonstration uses a file called acctfil, which is created using a CFCR transaction when you run the application, but more of this later

Enabling MSS in Enterprise Server

You enable and disable MSS in Enterprise Server Administration on the Edit Server page for the enterprise server that will run the CICS application.

To enable MSS for the demonstration application:

1. Start Enterprise Server Administration.

   How to

2. In the row for ESDEMO, which is the enterprise server to use, click Edit.
3. Click Properties > MSS.
4. Make sure that Mainframe Subsystem Support enabled is checked.
5. Click OK. Note that you must click OK before going back, so that your changes are saved.

The enterprise server needs to be stopped and restarted for these changes to take effect, but you can do this later, because there are more changes to make first.

Configuring the CICS Search Paths in Enterprise Server

Your application files need to be in directories where Enterprise Server can find them. To ensure this, you specify the locations of the files using the Properties > MSS page for the enterprise server which runs your application.

You might need to set the following fields on the MSS page::

How to

To configure the search paths for the demonstration application:

1. In Enterprise Server Administration, in the row for ESDEMO, click Edit.
2. Click Properties > MSS.
3. In the Configuration Information field set the search paths as follows:

   Field	Set to...
   Transaction Path	examples-dir\Net Express IDE\mto-bms\debug
   VSAM File Path	examples-dir\Net Express IDE\mto-bms
   Map Path	examples-dir\Net Express IDE\mto-bms

   where examples-dir is the path to your Net Express Examples directory. You can specify a drive letter and have spaces in the path, if necessary.

4. Click OK to save your changes.
5. The enterprise server needs to be stopped and restarted for these changes to take effect, but you can do this later, because there are more changes to make first.

Adding a Listener

You need to set up a listener to listen for incoming CICS requests and to pass the requests to the enterprise server for processing.

If your CICS application includes BMS maps, you need to use a TN3270 listener, since the end user interacts with the application through a TN3270 terminal. If your CICS application has a client program that uses the External Call Interface to send requests to the IBM CICS Transaction Gateway, you use an MSS-ISC listener.

How to

To add a TN3270 listener for the demonstration application:

1. In Enterprise Server Administration, in the row for ESDEMO, click Edit.
2. Click Listeners.
3. Click Add and fill in the following details for the new listener:
   • A name for the new listener, such as TN3270.
   • A port number to use, in the form *.nnnn. You can use any number above 5000 that isn't in use.
   • The Supported Conversation Type. Set this to TN3270.

   Then click Add to return to the configuration page.

4. Stop the enterprise server if it is running and restart it. You can confirm that MSS and CICS are enabled, by checking in the Console Daemon window that there are PLT messages now.

   Note: You must stop Enterprise Server from the Enterprise Server Administration console, if you started it there. If you started it from the command line or from the IDE (either the Tools menu or the Start Debugging dialog box), you must stop from either the command line or the Tools menu. This is a security restriction.

   How to

Defining the CICS Resources

The CICS resources that your application uses include things like System Initialization Tables (SITs), startup lists, data files, transactions, programs and so on. These need to be defined and the definitions available at run time for Enterprise Server to access when running the CICS application.

The CICS resources are defined in the Resource Definition file dfhdrdat (with index dfhdrdat.idx). This is an ISAM file.

You can edit the resource definitions using ESMAC, which provides a graphical user interface. Alternatively, you can edit them using a text editor, but to do this, you first need to export the resource definition tables from the dfhdrdat file, and when you have finished editing, you need to import the tables back again.

When Enterprise Server runs the application, it needs to know where the application's dfhdrdat file is. You specify its location using the TXRDTP environment variable.

Using ESMAC to Edit Resources

You can change the CICS resources that your CICS application uses by using ESMAC.

To use ESMAC to examine the resource definitions for the demonstration application:

1. If you haven't stopped and restarted Enterprise Server after enabling MSS, do so now.
2. Click Details next to ESDEMO.
3. Click ES Monitor and Control.

   This shows summary information of the application that the server is running and its transactions.

4. In Resources, which is about half way down on the left, expand the drop-down list and select by Group and click Groups.

   Notice that the first group is DFH$ACCT for the ACCT demonstration program. If you click the Details button for this group, you display information on the demo's resources, and you can click Details again to see further details on each item.

5. Click Home when you have finished.

Editing Resources as Text

You can edit the CICS resource definitions as text, but first you need to export the resource definition tables from the Resource Definition file dfhdrdat. When you have edited the resource definition tables in a text editor, you then need to import them back into dfhdrdat.

The dfhdrdat containing the supplied resource definitions, which includes those for demonstration applications, is installed in the following location:

• base\files\sys

You use the following command line tools for importing and exporting resources:

These tools use the TXRDTP environment variable to find the directory containing the dfhdrdat. You can enter casrdtex and casrdtup at the command line to display a full list of the switches available.

To edit the resource definitions of the demonstration application:

1. Export the resources from dfhdrdat to a file of your choice, for example, myresources.rdt, as follows:

   set TXRDTP=net-express\base\files\sys 
   casrdtex /g /omyresources.rdt

   where:

   net-express	is the directory where Net Express is installed
   /g	means export all groups
   /o	indicates that the name of the output file follows. Notice that there is no space after the o.

2. Open the file myresources.rdt in a text editor and have a look at it. We don't need to edit the resources so you can close the file again.
3. If you had edited the file, you would import the resources back into dfhdrdat, as follows:

   casrdtup /fmyresources.rdt

   Where /f indicates the name of the input file follows.

Running under an Enterprise Server

When you run a CICS application under Enterprise Server, you run it in the same way as you would run it on the mainframe. If you run it from a 3270 terminal or emulator, you enter transaction IDs at the terminal.

Note that on a PC the keys assigned to act as the CICS keys depend on your TN3270 emulator. For example, in many cases the Escape key is used as the 3270 Clear key, and the right-hand Ctrl key is used as the 3270 Enter key.

To run the demonstration application:

1. Using a TN3270 terminal emulator, connect using the following settings:

   Session name	A name of your choice
   Host name	Computer running the enterprise server, for example localhost
   Port	The port number of the listener you specified in the section Adding a Listener
   Host type	CICS

2. When the CESN sign-on screen appears, press Clear.
3. Enter the transaction ID: CFCR acctfil

   The CFCR transaction creates an empty file acctfil in the directory indicated by the environment variable TXFILEP.

4. Enter the transaction ID: ACCT

You can now use this application. You add entries in the second half of the screen, giving them a Reason of "N" and other fields to suit yourself. You search for entries in the top half of the screen.

Debugging a CICS Application

You can start debugging by using:

• The Enterprise Server Dynamic Debugging facility, which enables you to debug a service on a local or remote enterprise server.
• The INITCALL directive, which starts the debugger when you start a specific application
• The cassi /a command, which starts the debugger when any application is started in a specific enterprise server

Using Enterprise Server Dynamic Debugging

This requires no changes to your program code. It does, however, require that you associate your project with the enterprise server on which your CICS application will run. You must also ensure that the enterprise server is configured to enable dynamic debugging.

1. Connect to Enterprise Server Administration.

   How to

2. In the row for ESDEMO, which is the enterprise server to use, click Edit.
3. Check Allow Dynamic Debugging.
4. You must now stop and restart the enterprise server.

   How to

5. In the Net Express IDE, make sure that the project for your CICS application is open.
6. Click Project > Properties.
7. Check Project uses an enterprise server, then click Browse and choose ESDEMO as the server to use.

   Note: When you browse for enterprise servers, Net Express will check on each of the machines specified in the mfclient.dat file. This is located in the base\bin directory of your Micro Focus software installation.

8. Click Debug > Start Debugging from the IDE menus.

   The dialog displayed enables you to specify the details of the application that you want to debug.

9. Click the CICS tab.

   You use this tab to specify the details of the application that you want to debug. Enterprise server uses this information to inform your IDE when the application is started.

10. Specify ACCT in the transaction field, and click OK.

    Net Express now passes the service details to the enterprise server and waits for the application to start.

    Each time a CICS application is started, the enterprise server will check to see if it matches the details that you provided. If it does, the enterprise server attaches the Net Express debugger to the application.

11. Run the acct application as before, by entering ACCT in a 3270 session.
12. You can step through the CICS application in the usual manner.
13. When debugging reaches the exit program statement and no line is highlighted, the application has exited.

    The IDE debugger now waits for the application to start again.

14. When you have finished debugging, click Debug > Stop from the IDE menus. Click No on the message that comes after a few seconds asking if you want to continue waiting.

INITCALL Directive

To have the debugger start when you start a particular application, specify the INITCALL Compiler directive with the CBL_DEBUGBREAK switch, when you compile the application.

1. Recompile the project with the INITCALL"CBL_DEBUGBREAK" directive. To do this:
   1. Open the acct.app project in Net Express.
   2. Click Project > Properties.
   3. In the Project Directives field, insert INITCALL"CBL_DEBUGBREAK" before the semicolon.
   4. Rebuild the project.
2. Start Enterprise Server. You can do this from the Enterprise Server Administration console, from the Tools menu or with the command:

   casstart /rESDEMO

3. Run the acct application as before, by entering ACCT in a 3270 session.
4. When you are asked if you want to start the debugger, click Yes.

   A new instance of the Net Express IDE starts, with the source of ACCT00 ready to debug.

5. When you have finished debugging, remember to remove the directive and rebuild the project.

cassi /a Command

To have the debugger start when any application is started in a particular enterprise server, use the command cassi with the /a switch. This command works only if you started the enterprise server from the command line, using the casstart command.

With both these commands, you use the /r switch to specify the enterprise server. There must be no space between the r and its value, for example: casstart /rESDEMO. If you omit this parameter, it defaults to ESDEMO.

See the reference help topics casstart and cassi for details.

1. If you started ESDEMO from the Enterprise Server Administration console, go to the console and stop it from there. If you get a message saying that it cannot start because a region is already running, use the Windows Task Manager to ensure that casmgr.exe is not running, and then try again.

   If you started ESDEMO from the Net Express IDE, you don't need to stop it.

2. If ESDEMO is stopped, start it, either from the Net Express IDE or with the command:

   casstart /rESDEMO

3. Start a service execution process for ESDEMO by entering the command:

   cassi /a /rESDEMO

4. Run the ACCT application as before, by entering ACCT in a 3270 session.

   The source of the file acct00.cbl opens in Net Express ready for you to debug.

5. When you have finished debugging, click Debug > Stop Debugging.
6. To stop ESDEMO enter:

   casstop /rESDEMO

Compiler Directives

Copyright © 2008 Micro Focus (IP) Ltd. All rights reserved.