Chapter 11: Legacy Extension with MTO

This chapter provides information about how you can extend your legacy CICS applications with MTO.

Overview

Access to CICS Programs from Web Services and Services called from EJBs

A COBOL program running as a service in an enterprise server can call a CICS program running in the same enterprise server. The service can be either a Web service or a service called from an EJB. The service must be configured to be container-managed.

To use this facility you need to:

1. Code an EXEC CICS LINK statement in the COBOL source program.
2. Compile it using an extra Compiler directive option.
3. Deploy the program in the usual way, having carried out any interface mapping required to make the program accessible as a service to client programs.
4. Run the program as a service in an enterprise server. This involves invoking it from a suitable client.

Coding the EXEC CICS LINK Statement

The COBOL program calls the CICS program using the External CICS Interface (EXCI). To use this interface, you need to code an EXEC CICS LINK call every time the COBOL program wants to invoke a CICS program. This is similar to the EXEC CICS LINK call used in a CICS program to perform distributed program linking. However, there are some significant differences.

The format of the call is as follows:

EXEC CICS LINK
    PROGRAM(program-name)
    RETCODE(data-area-1)
    COMMAREA(data-area-2)
    .
    .
    .
    END-EXEC

where the options are as follows:

There are other options; for a full list see the IBM publication CICS External CICS Interface Guide.

The call must be immediately followed by an EXEC-END statement.

For example:

exec cics link
               program     (ws-program)
               commarea    (ws-commarea)
               retcode     (exci-exec-return-code)
end-exec

We supply a copy book, DFHXCPLO, which provides data descriptions for RETCODE and COMMAREA. You can find this copy book in $COBDIR/cpylib. The copybook has data descriptions for the parameter passed in the RETCODE field, exci-exec-return-code:

01 exci-exec-return-code.
   03 exec-resp                pic 9(8) comp.
   03 exec-resp2               pic s9(8) comp.
   03 exec-abcode              pic x(4).
   03 exec-msg-len             pic 9(8) comp.
   03 exec-msg-ptr             pointer.

Compiling the COBOL Program

You need to compile the program in Net Express or Server Express with the CICSECM(EXCI=YES) directive. Note that if you are using the Net Express GUI, you must not check EXEC CICS on the Compile tab of the Build Settings dialog box, but must type the directive in Directives.

Deploying the COBOL Program

After you have performed any interface mapping necessary to make the program available a a service, you need to deploy it. For more information on interface mapping and deploying see Part 1 and Part 2 of your COBOL development system Distributed Computing book. The program must be deployed as a container-managed service.

Running the Service in an Enterprise Server

Once the COBOL program has been deployed to the MTO-enabled enterprise server where the target CICS program runs, you need to invoke it using a suitable client. For more information about clients see the chapters COBOL Web Services with the Interface Mapping Toolkit and Mapping a Java Interface and Using Resource Adapters in your COBOL development system Distributed Computing book.

When the EXEC CICS LINK statement in the service program is executed, control is passed to the CICS program, which executes and passes the results back to the calling service program. The service program sets the return code to indicate to the container wheher or not the transaction should be rolled back.

When a service executes within an enterprise server, the COBOL program search path is restricted to the setting of Package Path within the service’s package object, set on the Edit Package page of Enterprise Server Adminstration. When an EXCI call is issued the search path is temporarily modified to include the system-wide CICS Transaction Path set on the Edit Server > Properties > MTO page.

Restrictions

The following restrictions apply to the use of the External CICS Interface:

• The COBOL service and the CICS program it calls must be running in the same enterprise server. The EXEC CICS LINK command takes the APPLID() operand, which is used to specify a remote server on which the CICS program resides, but it is ignored.
• The EXEC CICS LINK command takes the SYNCONRETURN() operand, which is used to specify that the MTO enterprise server is to take a syncpoint on successful completion of the server program. This operand is ignored. You can only use the EXCI interface from a container-managed service. The resources updated by the CICS program should not be committed or rolled back until the container-managed service is complete so that the CICS resources remain coordinated with those of the calling service.
• The CICS program should not issue explicit EXEC CICS SYNCPOINT commands. Results will be unpredictable and might leave resources in an inconsistent state.

CICS Transaction Gateway

Demonstration Programs for CTG

This chapter uses the application eci.app to demonstrate how to set up the client and server software.

To follow the examples in this chapter, you need Net Express 4.0 Professional with MTO installed, so that you can compile and run the demonstration client program. You need the following software installed:

• Net Express 4.0
• Enterprise Server
• UNIX Option (if you want to deploy to UNIX)
• All WebSync WrapPack

If you want to deploy to UNIX, you need, in addition, Server Express 4.0 Service Pack 1 with MTO with the following parts installed:

• Server Express 4.0 Service Pack 1
• MTO
• Enterprise Server

The CTG demonstration programs are supplied with Net Express in the base\demo\mto-ctg directory of your Net Express installation. They are:

Configuring the CTG Client

The CTG needs to know which machine the server program is running on.

You specify this using the CTG configuration tool. Alternatively, you can edit the CTG configuration file ctg.ini (or cicscli.ini for Universal Client) on the client machine.

To configure the CTG client for the demonstration:

1. Start the CTG configuration tool, which is available, by default, on the Windows Start menu as IBM CICS Transaction Gateway > Configuration Tool.
2. Add a new server for the client and set the following options:

   Server name	name for the enterprise server, such as myCICSserver
   Network protocol	TCP/IP
   Hostname or IP address	name of the machine running enterprise server
   Port	port number to listen on, which must be the same as the port number you specify for the Enterprise Server listener, later. The port number defaults to 1435, which is the IANA recognized port number for IBM CICS.

   Only the server name and hostname or IP address is mandatory.

3. Save the configuration and close the tool

Preparing the Client Program

You need to insert your ECI calls to the CTG in your program. In COBOL, an ECI call looks like this:

CALL "CICS_ExternalCall" USING ECI-PARMS

ECI-PARMS is the ECI parameter block, through which the program communicates with the server. The parameter control block is available as a copybook in the copybook folder within your CTG installation. It is called cicseci.cbl. You need to make this copybook available to your client program. You do this by adding the CTG copybook directory to the COBCPY environment variable.

When you compile your program to an executable, you must link it to the CTG library, cclwin32.lib.

For further information about using CICS Transaction Gateway, see the IBM manual CICS Family: Client/Server Programming (SC33-1435).

Before you run the demonstration, prepare the Net Express client as follows:

1. In Net Express, open the project eci.app, which is in the base\demo\mto-ctg directory of your Net Express installation.
2. Locate the following code in the program eci-call.cbl

   01 ECI-Client-Type. 
           03 pic x comp-x 
              *> --
              *> --Change the following value to select client type
              *> --
              value 0.
          88 ECI-MicroFocus-88 value 0.88  
          88 ECI-UniCli-88     value 1. 

   Change the above value clause to set ECI-Client-Type to 1.

3. Save the program.
4. Set the COBCPY environment variable to include the copybook directory of your CTG installation. This enables the project to locate the ECI copyfiles supplied by the CTG. To set the COBCPY environment variable edit the Project Properties
   1. Click Project > Properties
   2. Click IDE.
   3. Click Import.
   4. Select COBCPY and click OK.
   5. Double-click COBCPY.
   6. In the Value field, add a semicolon at the end, followed by the copybook directory of your CTG installation.
   7. Click Set and then OK.
5. Notice in the project properties that EXEC CICS is not enabled for the project, since the client program is not a CICS program.
6. Rebuild the program.

Compiling your CICS Server Program

When you compile CICS programs, you use the CICS External Compiler Module (ECM), which preprocesses the EXEC CICS statements. The ECM is invoked by the CICSECM() directive, which you set when you choose EXEC CICS in the project build settings. The client program passes the Program-ID of the server program to Enterprise Server, which locates the program and starts it.

To compile the demonstration CICS program:

1. In Net Express, open the project eci.app if it is not already open.
2. Check that CICS is enabled for the server program eci2oper.cbl. To do this, right click eci2oper.cbl, click Build settings and then go to the Compile tab. Ensure that EXEC CICS is checked, which sets the CICSECM directive.
3. Rebuild the project.

Configuring the Enterprise Server

To configure the enterprise server for the demonstration:

1. Enable MTO in the enterprise server ESDEMO.

   How to

2. On the MTO tab that you used in the previous step, in Transaction Path enter the location of the demonstration server program, eci2oper:

    install-dir\base\demo\mto-ctg\debug

3. Start the enterprise server ESDEMO.

   How to

4. If your CICS programs use the EBCDIC character set, you need to start ESMAC and do the following:
   • Specify the SIT to use.
   • Add a PPT entry for the server program in the resource definitions.
   • Make sure that the group to which you added the PPT entry is in the startup list.
   • Import the data conversion macros that the server program uses; see the section Data Conversion.

   How to

Adding a Listener to Enterprise Server

To enable support for CTG, you need to add an MTO listener to Enterprise Server so that it can receive and handle client requests from CTG. When you add the listener, you configure it and you specify a port for the listener to listen on.

To add a listener for the demo application:

1. Start Enterprise Server Administration.

   How to

2. In Enterprise Server Administration, in the row for ESDEMO, click Edit.
3. Click Listeners.
4. Click Add and fill in the following details for the new listener:
   • A name for the new listener, such as MyECI.
   • A port number to use, in the form *.nnnn, such as 1435. You must use the same number as you specified when you configured the CTG client.
   • The Supported Conversation Type. Set this to MTO ISC.

   Then click Add to return to the listeners page.

5. Stop and restart the enterprise server.

   How to

Running the Demonstration

To run the demonstration:

1. Start the CTG client from the Windows Start menu, which is by default in IBM CICS Transaction Gateway > Start Client. If you don't do this, the CTG client is started automatically when you run the program.
2. In Net Express, open the project eci.app and rebuild it.
3. Click Animate > Run.
4. Ensure that the executable file is debug\eci-call.
5. If Enterprise Server is not running, go to the MTO Debug tab and click Start Enterprise Server.
6. Return to the Application tab and click OK.
7. When the Application Output window appears and prompts you to enter a message to send to the console, enter your message.
8. The message is displayed in the Enterprise Server Console Daemon. To see the message within the Enterprise Server administration console:
   1. In the Current Status column for your enterprise server, click Details.
   2. At the bottom of the page, click ES Console.

Data Conversion

Within a single system using MTO, file data is always presented in the same codeset in which it was recorded. Between two systems running MTO, or between MTO and other CICS systems, data may need to be translated between EBCDIC and ANSI. The requirement and the method you use to meet it depend on which middleware you are using.

If You Use CICS Transaction Gateway

If you use IBM CICS Transaction Gateway, you can supply information that enables data to be converted in data conversion templates, which are held in an indexed file called dfhdrcnv, in the same folder as the resource definition file (by default ). Each data conversion template contains entries for resources that need translation and identifies which data fields require it. Each resource must have an entry in the resource definition file.

You cannot edit the file dfhdrcnv directly; instead you maintain it by importing mainframe-style DFHCNV macros, and by deleting templates that you no longer need.

Mainframe-style DFHCNV macros are organized into entries and templates. An entry is a set of conversion macros that apply to the same resource; the start of an entry is marked by a DFHCNV macro that begins TYPE=ENTRY and the entry continues until the next macro that begins TYPE=ENTRY, or until the END marker. An entry can contain one or several templates, depending on the type of resource it belongs to. For more information about mainframe-style DFHCNV macros, see the following IBM manuals:

• CICS Family: Communicating from CICS on System/390
• CICS Web Interface Guide CICS for MVS/ESA 4.1

Importing Data Conversion Templates

You use the command cascnvim to convert the data. For more information see the help topics cascnvim and Data Conversion.

Example Macros

The following data conversion macros apply to a file (TESTFC), which has two data constructs, and to a program (TESTPC):

TITLE 'DFHCNV MACRO IMPORT'
* --------- START OF DFHCNV MACROS ---------- *
DFHCNV TYPE=INITIAL,CLINTCP=(932, 437,XXXX)
SPACE 2
DFHCNV TYPE=ENTRY,RTYPE=FC,RNAME=TESTFC,USREXIT=NO
DFHCNV TYPE=KEY
DFHCNV TYPE=FIELD,OFFSET=0,DATATYP=CHARACTER,DATALEN=8
DFHCNV TYPE=FIELD,OFFSET=8,DATATYP=PD,DATALEN=3,LAST=YES
DFHCNV TYPE=SELECT,OPTION=COMPARE,OFFSET=11,DATA='A'
DFHCNV TYPE=FIELD,OFFSET=0,DATATYP=CHARACTER,DATALEN=8
DFHCNV TYPE=FIELD,OFFSET=8,DATATYP=PD,DATALEN=3
DFHCNV TYPE=FIELD,OFFSET=11,DATATYP=CHARACTER,DATALEN=1
DFHCNV TYPE=FIELD,OFFSET=12,DATATYP=PD,DATALEN=4
DFHCNV TYPE=FIELD,OFFSET=16,DATATYP=PD,DATALEN=4
DFHCNV TYPE=FIELD,OFFSET=20,DATATYP=BINARY,DATALEN=8
DFHCNV TYPE=FIELD,OFFSET=28,DATATYP=USERDATA,DATALEN=10, X23456789
USRTYPE=B'01010000'
DFHCNV TYPE=FIELD,OFFSET=38,DATATYP=CHARACTER,DATALEN=50, X
LAST=YES
DFHCNV TYPE=SELECT,OPTION=COMPARE,OFFSET=11,DATA='B'
DFHCNV TYPE=FIELD,OFFSET=0,DATATYP=CHARACTER,DATALEN=8
DFHCNV TYPE=FIELD,OFFSET=8,DATATYP=PD,DATALEN=3
DFHCNV TYPE=FIELD,OFFSET=11,DATATYP=CHARACTER,DATALEN=1
DFHCNV TYPE=FIELD,OFFSET=12,DATATYP=USERDATA,DATALEN=2
DFHCNV TYPE=FIELD,OFFSET=14,DATATYP=CHARACTER,DATALEN=20, X
LAST=YES
DFHCNV TYPE=ENTRY,RTYPE=PC,RNAME=TESTPC
DFHCNV TYPE=SELECT,OPTION=DEFAULT
DFHCNV TYPE=FIELD,OFFSET=0,DATATYP=BINARY,DATALEN=12
DFHCNV TYPE=FIELD,OFFSET=12,DATATYP=CHARACTER,DATALEN=96
DFHCNV TYPE=FINAL
END

Copyright © 2005 Micro Focus International Limited. All rights reserved.