Developing CICS Applications

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

Once you have created a CICS project you must add the project files to it. This includes the CICS application source files and the BMS macro files. You must then set up the CICS environment by defining the resources used by the project.

Having set up the project and defined the CICS environment, you can then build the project by compiling the BMS mapsets and application source files. Once built, you can run and debug the applications in the project in a single-tasking or multi-tasking CICS environment.

Creating a CICS Project

You must specify that the project uses CICS when you use the Create new project wizard. You will then have to specify or confirm the location of the CICS resource definition file, the name of the CICS region to be used, and the name of the system initialization table (SIT) to be used. Your CICS system administrator will have created a resource definition file that contains a base SIT for your project and can give you this information.

You must then add the source files for your applications to the newly created project. These files are the program source files and the BMS macro files (.bms files) for any BMS mapsets that your applications use.

You can create a CICS-specific entry name map file for your project. For more information see the section CICS-specific Entry Name Map Files in the chapter Compatibility with the Mainframe Environment.

For information about creating a CICS project and adding files to it see the chapter CICS Applications in your Getting Started.

Setting Up the CICS Environment

You must define the resources your applications use to enable the CICS environment to be created in which you can run and debug your applications. Your CICS system administrator will have defined some of these resources in the resource definition file for your project. These resources are:

Changing System Settings and SIT Parameters

You can change CICS system settings and override some SIT parameters that are relevant to application development from the IDE. From the CICS View of the project (click the CICS tab to see this) right-click CICS System at the top of the tree view in the left-hand pane and click Properties on the popup menu. This displays the Properties dialog box shown in Figure 34-1 and Figure 34-2.

You can see a description of each field in this dialog box by clicking the ? icon on the right of the title bar, dragging the mouse pointer (now a question mark) to the field and clicking.

It is unlikely that you will need to change the project details on the Settings tab page of the Properties dialog box but you can do this by clicking the Change button if you need to. You may need to set some of the fields on the Overrides tab page. For instance you might change the initial transaction ID to be the transaction used by your project so that it is initiated at terminal startup.

You can also add a new SIT and maintain existing SITs in the resource definition file from the IDE. If yours is a large installation with a team of developers working on the same project and sharing a resource definition file, it is likely that a system administrator would do this for you. For details of how to add and maintain SITs, see the section Maintaining System Initialization Tables in the chapter CICS Resource Definitions in your Administrator's Guide.

Changing the Startup List

The startup list is a copy of the Resource Definition File (RDF) startup list and is saved with the project. If you have several resource groups defined for your project you might want to change the order in which they are used in the startup list or add them to or remove them from the startup list. From the CICS View of the project (click the CICS tab to see this) right-click CICS System at the top of the tree view in the left-hand pane and click Startup List. This displays the Startup List Configuration dialog box shown in Figure 34-3.

You can add a group to or remove a group from the startup list by selecting the group name and clicking Add or Remove as appropriate. You can change the position of a group in the startup list by selecting the group name and clicking Up or Down.

Creating a Resource Group

You can create a new resource group for your project from the Startup List Configuration dialog box (described above) by clicking New Group, or when you define the first program or file for your project. In both cases you see the Add New Group dialog box shown in Figure 34-4.

Specify the name for the new group and its description in this dialog box, make sure both the In current startup list and Viewable check boxes are selected and click OK. The new group is then created with the highest precedence in the startup list.

Defining Programs and Files

You must now define the programs and files that are used by your project to CICS. You define transactions in the program control table (PCT), files in the file control table (FCT) and programs in the processing program table (PPT).

Note: You can choose to hold some information about your files in the catalog and some in the FCT entry, or hold it all in the FCT entry. Having catalog entries makes it easier for CICS and batch programs to use the same files.

Adding a PCT Entry

To add an entry to the PCT, display the PCT in the right-hand pane of the CICS View in the IDE, right-click in the right-hand pane and click Add new entry. This displays the PCT Properties dialog box shown in Figure 34-5.

You can, at this stage, create a new resource group by clicking the down arrow on the Group field and clicking <Add New Group>.

Descriptions of the other fields are available through the popup help - click the ? icon in the title bar and click the field.

Adding an FCT Entry

To add an entry to the FCT, display the FCT in the right-hand pane of the CICS View in the IDE, right-click in the right-hand pane and click Add new entry. This displays the FCT Properties dialog box shown in Figure 34-6.

If you want to use the catalog to store some file information, check Use catalog. As soon as you do this, all the fields for information that is stored in the catalog are disabled. The catalog entry must exist already. You can create it either by running JCL that calls the Micro Focus utility MFJAMS, or by using Interactive AMS > Define Cluster on the Tools menu.

If you want to use the FCT entry to store all file information, uncheck Use catalog. If there is an entry in the catalog for the file, CICS Option populates the corresponding fields with values from the catalog entry and enables them; if there is no corresponding entry, CICS Option displays default values.

The following details are required only for keyed files if you uncheck Use catalog:

Descriptions of the other fields are available through the popup help - click the ? icon in the title bar and click the field.

Adding a PPT Entry

PPT entries for COBOL and Assembler programs that are invoked by transaction or other programs may be required by older versions of CICS/ESA.

To add an entry to the PPT, display the PPT in the right-hand pane of the CICS View in the IDE, right-click in the right-hand pane and click Add new entry. This displays the PPT Properties dialog box shown in Figure 34-7.

Descriptions of the fields are available through the popup help - click the ? icon in the title bar and click the field.

Note: The CICS View does not show entries in the Processing Program Table that relate to Mainframe Express Options that you have not installed or are not using in this project. For this reason you may receive an error message telling you that a record already exists with the Program ID you entered, even though the table appears to contain no entries.

For information about creating a resource group and adding program and file definitions see the chapter CICS Applications in your Getting Started.

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 information on how to do this.

CICS Option supports a large subset of the CICS/ESA application programming interface (API) and system programming interface (SPI). See the online help for details of the supported CICS API.

Dynamically Converting Data

CICS Option runs with an EBCDIC character set, which means that you do not have to convert data when communicating with mainframe CICS. For communication with CICS on platforms that use an ANSI character set you do need to convert data. Standard conversion is done by defining and assembling the conversion table, DFHCNV.

Creating and Editing BMS Mapsets

As well as preparing the program source code, you must also prepare any BMS mapsets that are used by your applications. CICS Option provides a BMS screen painter that lets you create and edit BMS maps. The painter also lets you import BMS macro files that already exist, for instance, BMS macro files created by the IBM Screen Definition Facility (SDF II). For information about preparing BMS mapsets see the chapter CICS BMS Screen Painter.

You can also edit the BMS macro file source directly by right-clicking the BMS macro (.bms) file in the right-hand pane of the File View and clicking Edit as Text. This displays the BMS macro source in the IDE editor.

Compiling a CICS Project

You compile the program source code for a CICS project in the same way as for any other Mainframe Express project. However, you must also generate the copybook and load module for any BMS mapset that is part of the project. You must do this before compiling the source code so that the BMS copybook is available during source compilation.

Building the project (by clicking Build or Rebuild All on the Build menu), automatically generates any BMS mapsets before compiling any program source code.

See the chapter CICS Applications in your Getting Started for information on building a CICS project.

Generating BMS Mapsets

If a transaction program uses any of the BMS maps in a mapset, the program must have a symbolic definition of the maps that it uses to send or receive data (a copybook). You can generate these copybooks from the IDE.

The copybook generated for a mapset is written to a file called mapset.cpy. in the project's copylib directory.

When you have produced the copybook, you then need to assemble the mapsets, so that transaction programs can refer to them at run time. The assembled mapset is written to a file mapset.mod in the project's loadlib directory.

The name of the mapset file is taken from the name field in the DFHMSD macro in the BMS macro source, not the name of the BMS macro source file itself.

Any EXEC CICS SEND MAP commands must use the MAPSET name as specified in the DFHMSD operand.

Before generating the BMS mapset copybook and load module you must set the build settings for BMS. You can do this either for the whole project:

This displays the BMS tab page in the Build Settings dialog box shown in Figure 34-8.

By default, both the BMS copybook and load module are generated. You can deselect the MAP or DSECT check box to prevent generation of the load module (MAP)or copybook (DSECT).

Descriptions of the other fields are available through the popup help - click the ? icon in the title bar and click the field.

Compiling from the IDE

To compile a source program that uses CICS, from the IDE, you must first enable the CICS preprocessor. You can enable the CICS preprocessor either for all programs written in a particular language or on a program-by-program basis.

To enable the CICS preprocessor for all programs written in a particular language:

The other fields on the Build Settings dialog box are used in the same way as for any other Mainframe Express project. See the chapter Using Projects in this User's Guide.

Descriptions for each of the fields on these pages are available through the popup help - click the ? icon in the title bar and click the field.

Debugging a CICS Project

You can debug the applications in a CICS project in either a single-tasking or a multi-tasking CICS environment.

Once you have established the CICS environment the debugger operates in the same way as for any other Mainframe Express project.

Debugging In a Single-tasking Environment

To start debugging, click Start Debugging on the Debug menu. This displays the Start debugging dialog box shown in Figure 34-9. Make sure that the CICS page is displayed by clicking the CICS tab.

If you want to override the initial transaction ID that you entered in the Initial Transaction ID field on the Overrides page of the Properties dialog box, do so using the Initial Tran Id field and click OK.

Note: If you don't specify an initial transaction ID using either the Properties dialog box or the Start debugging dialog box, clicking OK starts a single-tasking CICS region and an associated 3270 terminal emulation without running a transaction.

This initiates a single-tasking CICS region and an associated 3270 terminal emulation. You can see the progress of the region initiation in the CICS log tab of the Output window at the bottom of the IDE. The 3270 terminal emulation appears in the Application Output window of the IDE and you may need to undock and move this window to be able to see the whole of the 3270 terminal screen. The program source appears in a debug window and you can step through the program and use the other functions of the debugger in the normal way.

The 3270 terminal emulation includes an emulation of the 3270 keyboard and when entering input to the 3270 terminal emulation screen you must use the right-hand Ctrl key of the PC keyboard as the 3270 Enter key. If you get no response use either the Enter key on the numerical keypad or press Ctrl + Return.

When you have finished debugging you must shut down the 3270 terminal and the region. On the 3270 terminal emulation screen, press Esc to clear the screen, then enter the transaction ID CQIT and press Enter.

Debugging In a Multi-tasking Environment

To debug in a multi-tasking environment you must first set up the environment by starting a CICS region and then starting a 3270 terminal emulation.

To start the CICS region, click CICS on the Tools menu of the IDE and then click Start Region.

This initiates a multi-tasking CICS region. You can see the progress of the region initiation in the Console tab of the Output window at the bottom of the IDE. Wait for the "Server initialization completed successfully" and "PLTPI Phase 2" messages to appear to indicate that the region has started.

Now start the 3270 terminal emulation. Click CICS on the Tools menu of the IDE and then click Start 3270 Terminal.

This opens a new 3270 Terminal emulator window. If the CESN sign-on transaction screen appears, press Esc to clear the screen.

The 3270 emulator window loses focus whenever you perform actions on the IDE and you must switch to it when you need to see it.

Now you can start debugging. Click Start Debugging on the Debug menu. This displays the Start debugging dialog box shown in Figure 34-10. Make sure that the CICS page is displayed by clicking the CICS tab.

The multi-tasking debug options are now available on the CICS page. With Generic selected (the default), click OK. This starts a debug server and more messages appear in the Console tab of the Output window. Again, wait for the "PLTPI Phase 2" message.

Now, on the 3270 Terminal emulator screen enter the transaction ID of the application you want to debug and press Enter (that is, the 3270 Enter key - the right-hand Ctrl key on the PC keyboard). The program source appears in a debug window and you can step through the program and use the other functions of the debugger in the normal way.

When you have finished debugging you must shut down the debug server, the 3270 terminal, and the region. On the 3270 terminal emulation screen, press Esc to clear the screen, then enter the transaction ID CQIT and press Enter.

Transaction ID:	The four-character name of your transaction
Program Name:	The name of the program to be invoked by the transaction

Type:	The file type (KSDS=Key sequenced, ESDS=Entry sequenced, RRDS=Relative record, ALT=Alternate index or Undefined=Remote file)
Min LRECL:	The minimum record length for the file
Max LRECL:	The maximum record length for the file

Key position:	Position of the key in the data set
Key length:	Length of the key in your data set