This article is an extension of a previous article named "Generating Java using EGL and JSF with WebSphere Studio Site Developer V5.1.2." That article described the architecture that WebSphere® Studio Site Developer V5.1.2 uses to deploy applications written with EGL to WebSphere Application Server V5.1. Using the JavaServer Faces (JSF) as framework, we described how to generate, test, and deploy a three-tier application made up of a Web interface, WebSphere Application Server, and a server program that performs a DB2® query to access a database. That article explained how to use EGL to generate a Java™ server program.
This article will explain how to use EGL to generate a COBOL/CICS server program to run under z/OS®, and also how to configure the J2EE™ Connection Architecture (J2C or JCA Connectors) using WebSphere Application Server V5.1.
Before beginning, you may wish to load the EGL/JSF sample program referred to in the previous article into WebSphere Studio Enterprise Developer by following the download instructions found in the end of this article.
This article applies to WebSphere Studio Enterprise Developer (Enterprise Developer) Version 5.1.2 only. Other versions of Enterprise Developer (such as Versions 5.0 and version 6.0) have a different EGL syntax and wizards. However, the EGL code produced here can be imported in future releases, since a migration tool will help you moving across versions.
This article makes use of animated examples. When you see the symbol , double-click on it, and an animation sequence will demonstrate a specific development task in action.
EGL Generating COBOL for z/OS
A COBOL program can be generated to run on CICS for z/OS, either in batch mode or interactively. An EGL-generated program that runs in CICS batch mode can be used in an EGL/JSF framework. This is the model that this article will implement.
A non-interactive COBOL program also can be generated to run outside of CICS on z/OS; such a program is said to be of type z/OS batch and for instance print reports like pure COBOL batch programs. We will not cover this type of programs in this article. In addition, EGL provides a way to create Web applications that was covered in the previous article, as well as the capability to produce Web Services.
Application to be implemented
The previous article described the architecture that IBM® WebSphere Studio V5.1.2 uses to deploy EGL applications to WebSphere Application Server V5.1 using JSF technology. It showed in detail how to code, test, generate, and deploy a three-tier application consisting of a Web interface, business logic that executes on WebSphere Application Server, and a server program that performs a DB2 query to access a database. Enterprise Developer was used to generate the server program in Java code.
This article will not focus on this model and Java generation. Instead, it will describe the production process of generating COBOL to be deployed to CICS for z/OS using the JCA (also called JCA) adapters. The article will also show how to configure WebSphere Application Server V5.1 to handle JCA, a process needed during the deployment of the code to CICS.
The application architecture to be implemented in this tutorial is shown in Figure 1. At run time, Application Server contains both the view and controller components of an MVC Web application, while a third tier (which will be the COBOL) contains the model.
Figure 1. JSF and EGL architecture using COBOL and JCA
As in the previous article, we will implement a very simple application using a Web browser, but the server code to be deployed will run on z/OS CICS and uses JCA adapters. In this application:
- The user types an ID and clicks a button to invoke the server program, passing a working area.
- The server program reads a DB2 database using the ID as a key.
- If the ID is found, the server program moves the Name, Salary, and Commission to the working area and returns it.
- The returned data is sent to the Result JSP page and displayed.
- If the ID is not found, the server program moves an error message to the working area and returns it.
- The error message is sent to the Error JSP page and displayed.
The database to be used is the SAMPLE database, and the table to be used is the STAFF table.
The next steps will guide you through the creation, testing, and deployment of the application shown above. To complete this application you will need:
- IBM WebSphere Studio Enterprise Developer V5.1.2 with the EGL COBOL generation feature installed.
- IBM DB2 UDB V7 or later with the SAMPLE database created.
Although you will test, debug and generated the code under Windows, this article assumes that you do not have the z/OS available for the deployment. This article is divided into three sections:
- Section I. Import and test the EGL/JSF code provided
- Section II. Generate Java and COBOL/CICS from the EGL code
- Section III. Run the application using the generated code
Section I. Import and test the EGL/JSF code provided
In the previous article we created the EGL server program and named it
TE01A. This program is a called EGL that receives a working area named TE01W01 as parameter, does a simple DB2 inquiry to the DB2 Staff table using the SQL record
We also created the JSF client that has three JSP pages. The figure 2 below shows the flow of this application.
Figure 2. Application flow using JSF/EGL
The following tasks need to be performed to load the EGL/JSF code and have it running using Enterprise Developer:
- Set preferences for SQL database connections
- Import the provided code
- Test/Debug the application
1. Set preferences for SQL database connections
Before load the code you should prepare your workspace to access the DB2 SAMPLE database while testing the EGL in debug mode. This activity is usually done once, and is necessary since it provides the required defaults.
Using Enterprise Developer, you could start a new workspace with any desired name, this way you will be able to make changes without causing damages to your existing work. This can be easily done using the parameter -data, for example C:\ED512\wsenterprise.exe - data C:\ED512\workspace_article_Cobol.
To set the EGL preference, select Windows => Preferences => EGL => SQL Database Connections. Our example will run under Windows. As shown in Figure 3 below, the following values are specified. Note that the DB2 path could need some modification, depending where DB2 is installed in your machine.
Figure 3. EGL Preferences for SQL Database Connection
- Connection URL: type the URL used to connect to the database through JDBC. For IBM DB2 APP DRIVER for Windows, the URL is
jdbc:db2:dbName (where dbName is the database name). In our example it would be
- In the Database field, type the name of the database:
- In the User ID field, type the user ID for the connection.
- In the Password field, type the user ID password.
- In the Database vendor type field, select the database product and version that you are using for your JDBC connection. We used DB2 V8.1.
- In the JDBC driver field, select the JDBC driver that you are using for your JDBC connection. We used IBM DB2 APP DRIVER
- In the JDBC driver class field, type the driver class for the driver you selected. For IBM DB2 APP DRIVER for Windows,
the driver class is
- In the class location field, type the fully qualified filename of the *.jar or *.zip file that contains the driver class.
For IBM DB2 APP DRIVER for Windows, type the fully qualified filename to the db2java.zip file; in our example,
C:\SQLLIB\java\db2java.zip. This location depends where DB2 is installed. (Most of these entries are already filled out, and don't need to be specified.)
2. Import the provided code
The code provided by this article is the application coded in the previous article, Generating Java using EGL and JSF with WebSphere Studio Site Developer V5.1.2, but with different deployment descriptors that were used there. If you already had this application in your workspace, you must load it again here.
Starting with WebSphere Studio V5.1.2, a new nice import feature is available, the Project Interchange utility. The utility provides new import and export wizards for sharing a set of projects easily in one step. This utility:
- Preserves exact project names, structures, and classpaths.
- Computes referenced projects for both export and import.
- Allows the importing of multiple projects at one time, and will copy from the ZIP file to a workspace location or to any selected location.
You can use the Import Wizard to copy the provided files from a file system directory into the workbench:
- From the menu bar, select File => Import. The Import dialog appears.
- Under Select an import source, click Project Interchange.
- Click Next. The Import Project Interchange Contents dialog appears.
- Next to From zip file, click Browse and navigate to the directory where you downloaded the file.
- Select EGL_DEMO.zip as the target of the import and click Open.
- Click Select All.
- Click Finish. The wizard imports the project into your workspace. Be patient, this could take a while.
- Open the EGL perspective using the wizard or select from the menu bar Window => Open perspective => Other => EGL.
- From the menu bar, select Project => Rebuild All. This will force the rebuild of all workspace resources and clean possible errors.
The result of this operation can be seen in the Figure 4, using the Navigator view:
Figure 4. Projects imported
The EGL TE01A program that you loaded can be found in the project EGL_DEMO_Server. See in the Figure 5 below the program:
Figure 5. TE01A EGL Server program imported
The SQL record that maps the DB2 STAFF table can be seen in the Figure 6 below:>
Figure 6. TE01R01 SQL Record imported
Figure 7 shows the working area used to pass and receive back the data. This is the area used in the JSF client program:>
Figure 7. TE01W01 Working area used to pass and return the data
Figure 8 shows the JSP input page. Using EGL Web perspective you can find this file under the folder EGL_DEMO_Client\WebContent. When the button is clicked, the program TE01A is called, passing the TE01W01 working area:
Figure 8. JSP input page
- The code that was imported was developed in another environment than the one that you are using. Before testing the imported code you will need to change the user ID and password that r was used to connect to the database to values that reflects your system.
- In the EGL perspective and using the Project Navigator view, expand the folder EGL_DEMO_Client and edit the Web deployment Descriptor.
- Click on the Environment tab and change the variables vgj.jdbc.default.databse.user.id and vgj.jdbc.default.databse.user.password to reflect the the user ID and password that is needed to connect to the Sample database, as seen in the Figure 9 below.
Figure 9. Deployment Descriptors Environment variables
- Save and close the Deployment Descriptor.
3. Test/Debug the application
Before continuing with the COBOL generation, make sure the loaded application is working as designed. Before the debug, we need to do some setup:
- 3.1. Prepare the server for EGL Web debugging
- 3.2. Select a default Debug build descriptor
- 3.3. Add breakpoints in the EGL code
- 3.4. Test in Debug mode
3.1. Prepare the server for EGL Web debugging
To debug EGL Web programs that run in the WebSphere Application Server, you must prepare the server for EGL debug. The preparation step must be done once per server but does not need to be done again, even if the workbench is shut down.
To prepare a server for debugging:
- Using the EGL Web perspective, open the Servers view (in the bottom, Server tab).
- Make sure the server is stopped and right-click on the server EGL_Server.
- A context menu displays. Select Add EGL Debugger Jar Files.
3.2. Select a default Debug build descriptor
Since we have two EGL projects, the server does not use the J2EE specifications and the EGL Web does use J2EE, so we will need to specify two different build descriptors to be used by the EGL Debug, since that the EGL debug also needs them to run.
The EGL Server program will use the build descriptor file EGL_DEMO_Server and the EGL Web will use EGL_DEMO_Client. The steps below show how to make those build descriptors the default for the debug for each project:
- Using the EGL Web perspective, right-click on the EGL_DEMO_Client folder. From the context menu, click Properties.
- Click on EGL Default Build Descriptors and select EGL_DEMO_ClientWebBuildOptions for the Target System and the Debug build descriptor. Click OK.
- Right-click on the EGL_DEMO_Server folder and from the context menu, click Properties.
- Click on EGL Default Build Descriptors and select EGL_DEMO_ServerJavaBuildOptions for the Target System and Debug build descriptor. Click OK.
If you are developing programs for CICS, it makes more sense to have the target system build descriptor for CICS, not Java. Since you did not have a build descriptor ready for CICS, you can keep Java as the default for and change it later.
3.3. Add breakpoints in the EGL code.
A breakpoint causes the execution of a program thread to suspend at the location where the breakpoint is set. Breakpoints can be enabled and disabled via their context menus in the Breakpoints view. When a breakpoint is enabled, it will cause a thread to suspend whenever the breakpoint is reached. Enabled breakpoints are indicated with a blue circle. We will add 3 breakpoints, 2 in the EGL pageHandlers before and after calling the EGL Server and the other at the EGL Server in the first program statement. To add breakpoints:
- Using the EGL Web perspective, open the JSP file TE01_Input located under project EGL_DEMO_Client and folder WebContent.
- Click the Design tab to access the Design view, right-click in the Page Designer, then select View Page Code. Alternatively, you could open the file TE01_Input.egl located under EGLSource\pagehandlers.
- The file TE01_Input.egl will open. Position the cursor at the breakpoint line in the left margin of the Source view and double-click as shown in Figure 10.
- Open TE01A.egl and add a breakpoint in the first EGL statement.
- Close the files being edited.
Figure 10. TE01_Input.egl page handler with breakpoints
3.4. Test in Debug mode
We are ready to test the EGL in debug mode. You can see this application running in debug mode using the icon below:
- Under EGL Web perspective, right-click on TE01_Input.jsp under the folder EGL_Demo_Client/WebContent>. Then click Debug on Server.
- Be patient. The application server will start in debug mode and it could take a while. The Debug perspective will open and a step-by-step debug dialog will open. Select Skip and Disable step-by-step mode, since we want to stop only at our breakpoints. Click OK.
- Click on the Debug tab (upper left) and click on the Resume icon or select Run, Resume or just press F8.
- Use the Web browser view to enter the data. Enter a valid value such as 40 and an invalid one such as 44 to check the results.
- You also can try the debug icons located in the debug view. When it stops in the call statement, use Step Into (F5). You will
be able to debug TE01A also. Figure 11 below show the debug just after calling the TE01A Server Program and just before loading the
result JSP page. Note that data was retrieved from the DB2 table.
Figure 11. Application being debugged
So far we have tested the loaded code using the debug mode. In the next section you will see how to generate the COBOL code to be deployed in z/OS CICS.
- Stop the Server and close all opened files.
Section II. Generate Java and COBOL/CICS from EGL code
In a z/OS environment, it is possible to deploy the server program (the third tier in our Web application) using CICS. This is more realistic since most of the datasets and legacy code called by the server program will typically be located within z/OS under CICS. In this scenario, a COBOL server program will perform better than a Java one.
For our example, the following tasks must be performed in Enterprise Developer to create and test a COBOL/CICS load module:
- Create the linkage part.
- Create build descriptors for COBOL code generation.
- Create a DB2 bind control part.
- Create a new build descriptor for JSF/EGL client with the linkage part.
- Generate the COBOL/CICS server program.
- Generate the Java from EGL pagehandlers.
1. Create the linkage part
A linkage part defines how the generated Java client code should invoke a called EGL program, in this case using J2C and CICS. For a generated COBOL program, the linkage options is also required since you will use the J2C connector.
The J2C connector puts all parameters in the CICS commarea, so parmform must be set to commdata. If you do not specify a linkage part when generating the server program, parmform defaults to commptr, which would cause a problem when the calling page handler is passing the parameters in commdata. Therefore, you do need to use the linkage part when generating the server program.
Since the linkage part will be used by the client and server code, you could create it under the project that hold the client code and later the server build descriptor to be created can also be in this folder. To create the linkage part:
- Using the EGL perspective, and the Project Navigator view, open the client build descriptor EGL_DEMO_Client.eglbld located under EGL_DEMO_Client\EGLSource
- Using the EGL perspective, in the Outline view, right-click on EGL_DEMO_Client.eglbld, then select Add part... => Linkage Options.
linkageTE01A-cicsas the name and click Finish.
- Save using Ctrl+S.
- Using the Add button, add the program TE01A as remoteCall and type or select the options, as the example shown in Figure 12. Some of the options to be specified could be dependent of your z/OS system.
It is important to specify CICS J2C since you will use those connectors to connect to CICS. Also since the J2C connector puts all parameters in the CICS commarea, the parmform must be set to commdata. You do not have to use the J2C connector in the J2EE environment in V5.1.2, but if you want connection pooling, you must use the J2C connector. It is possible to use CICSECI, for example, but a new connection to the CICS region would be established for each invocation.
Figure 12. Linkage part for calling COBOL/CICS generated code
A brief description of the options specified:
|pgmName = TE01A||Name of the program part to which the CallLink element refers.|
|type = remoteCall||Indicates that the call uses EGL middleware, which adds 12 bytes to the end of the data passed, enabling the caller to receive a return value from the called program. The possible options are localCall and ejbCall.|
|conversionTable = CSOE037||Name of the conversion table used to convert data on a call. CSOE037 is the table for English or Portuguese, a different table would be used for other languages.|
|location = eis/CICSResourceAdapter||Specifies how the location of a called program is determined at run time. Because
we are using CICSJ2C as remoteComType, this refers to the JNDI name of the ConnectionFactory object that you establish for the CICS
transaction invoked by the call when setting up the J2EE server. By convention, the name of the ConnectionFactory object begins with eis/.
This name will be used in the Web Deployment Descriptor as a Resource Environment references.
|luwControl = SERVER||Indicates whether the unit of work is controlled by the caller () or the called program. SERVER means that a unit of work started by the called program is independent of any unit of work controlled by the calling program.|
|parmForm = COMMDATA||Indicates that the caller places data in the COMMAREA, rather than externally points to data. Each argument value is moved to the buffer adjoining the previous value, without regard for boundary alignment. This parameter is required when using J2C connectors.|
|remoteBind = GENERATION||Indicates that the properties used for the call are set at generation time.|
|remoteComType = CICSJ2C||Specifies the communication protocol used. WebSphere uses a J2C connector, and for J2EE implementation we must use CICSJ2C. Other possible options are CICSECI, CICSSSL, DEBUG, DIRECT, DISTINCT, JAVA400 and TCPIP.|
|remotePgmType = EGL||Specifies that the called program is a COBOL program that was generated by Enterprise Developer EGL language. The other option would be EXTERNALLYDEFINED.|
2. Create build descriptors for COBOL code generation
Since you will generate COBOL instead of Java (discussed in the previous article), you must create another EGL build descriptors to support the COBOL generation. You could create the new build descriptor in the any location. Since the new build descriptor will share the same linkage part used by the client code, you will create it in the folder were the client code is located:
- Open the EGL perspective and using the Navigator view and be sure that the build descriptor EGL_DEMO_Client.eglbld is open.
- In the Outline view, right-click on EGL_DEMO_Client.eglbld, then select Add part.
- Select Build Descriptor, type
cics-cobolfor the name and click Finish. The cics-cobol part is added to the Outline view, and the part opens ready for editing.
- Add the options shown in Figure 13. Note that some parameters can be gotten through drop down menu; you must type in the others.
Some parameters like
destPort, will depend on your mainframe. To see all the selections available for COBOL/CICS code generation, select CICS Target system (All).
- When finished, select Show only specified options to reduce the list of options displayed to only those entered.
- Save your changes using Ctrl+S.
Figure 13. cics-cobol build descriptor for COBOL/CICS generation
A brief description of the options specified:
|Bind = coboldb2||Required for DB2. Bind template identifies the bind control part for DB2 access in z/OS. You will need to create this part later.|
|cicsEntries = RDO||Optional for MVSCICS. Specifies whether to produce CICS definitions when you generate a COBOL program. This will help the CICS expert to find which entries must be added to the CICS PPT.|
|commentLevel = 1||Specifies the level of EGL comments that are included in the generated COBOL source code. This is useful for troubleshooting if you need to correspond the COBOL source code with the EGL source code.|
|destHost||Name of the machine where the target build server is running; for example, carmvs1.raleigh.ibm.com.|
|destPassword||Password corresponding to destUserID.|
|destPort||Port number of the z/OS build server; this must match the number specified in the job used to start the z/OS build server, like 9112.|
|destUserID||User ID used for processing on z/OS.|
|genDirectory||Location of the file system where Enterprise Developer places the generated output and preparation status files; for example: C:\ED512\workspace_article_Cobol\EGL_DEMO_Server.|
|prep = NO||If set to YES (default), then upon successful completion of generation (return code <= 4), preparation of the generated objects is automatically initiated. The source code will be sent to the build server for building the run time objects. We specify NO in our example because we are not connected to the mainframe. (If the default was kept, all steps would work, but an error message would appear when trying to connect to the mainframe.)|
|linkage = TE01A-cics||The build descriptor option linkage contains the name of the linkage options part that guides aspects of generation. This option is required for this generation, since J2C will be used. The J2C connector puts all parameters in the CICS commarea, so parmform must be set to commdata. If you do not specify a linkage part when generating the server program, parmform defaults to commptr.|
|projectID||High-level qualifier for z/OS partitioned data set (PDS) that will contain the generated code. Enterprise Developer will use this qualifier to locate the appropriate z/OS data sets.|
|System = ZOSCICS||Target system for the generated source code. The Server program will run under z/OS/CICS.|
|targetNLS = ENU||Target national language code used for runtime output. It is critical that the Enterprise Developer Server for the specified language has been installed, especially in countries where English is not the spoken language, since messages presented to the end user will be based on this specification. For example, in Brazil this parameter should be PTB. If set to ENU (default), the messages to the end users will be in US English.|
3. Create a DB2 bind control part
The bind control part provides a way to store information in a bind control file which, in turn, specifies what database request modules (DBRMs) are included in the DB2 plan created at preparation time. A bind control part is meaningful only if you are generating a COBOL program to run on z/OS that accesses SQL tables on DB2 (which we are). The bind control file here is equivalent to the bind control file that you would create if you accessed DB2 from a native COBOL program. In the context of EGL, the bind control file is an input to the distributed build function, which prepares the generated source for execution. To create a bind control part:
- Open the EGL Perspective and using the Navigator view and be sure that the build descriptor EGL_DEMO_Client.eglbld is open.
- Right-click on EGL_DEMO_Server, then select Add part => Bind Control.
coboldb2for the name. The coboldb2 part is added to the Outline view, and the part opens ready for editing but has no contents.
- Manually type the desired DB2 bind options. The code sample below shows one example. In fact since you will not do a "real" DB2 bind, you could skip this part
- Save and close the part created.
DB2 Bind Control Partcontents example
TSOLIB ACTIVATE DA('DSN6.DSNLOAD') ALLOC FI(DBRMLIB)SHR DA('userid.MVSCICS.DBRMLIB') DSN SYSTEM(DSN6) BIND PACKAGE(TE01A)- MEMBER(%EZEMBR%)- ACT(REP)- VALIDATE(BIND)- ISOLATION(CS)- QUALIFIER(TE01A)
4. Create new build descriptor for JSF/EGL client with linkage part
You could change the existing build descriptor that was loaded when you imported the sample code, but it is better to create a new one, so you do not interfere in the existing running code. Basically you will need a new build descriptor that has the linkage part created above. The linkage part, that is required when calling CICS generated code. Here are the steps to create the new build descriptor:
- Using the EGL perspective and Navigator view, be sure that the build descriptor EGL_DEMO_Client.eglbld located under EGL_DEMO_Client\EGLSource is opened.
- In the Outline view, right-click on EGL_DEMO_Client.eglbld then select Add part => Build descriptor.
cics-clientfor the name and click Finish. The cics-client part is added to the Outline view, and the part opens ready for editing.
- Add the options shown in Figure 14 below. To see all the selections available for Java code generation, select Java Target system (All).
- When finished, select Show only specified options to reduce the list of options displayed to only those entered.
- Save your changes using Ctrl+S.
- Close the build descriptor.
Figure 14. cics-client build descriptor
4. Generate the COBOL/CICS server program
To generate the COBOL server program:
- Using the EGL perspective, in the Projector Navigator view, right-click on TE01A.egl under EGL_DEMO_Server\EGLSource\demo\programs\ and select Generate With Wizard ....
- Click Next.
- Select Use one build descriptor for all parts and cics-cobol as build descriptor option as seen in the Figure 15.
- Click Finish.
Figure 15. Generating the server code using new build descriptor
The COBOL server program is created and in the task list a message below will be displayed:
IWN.VAL.9994.i 1/1 The part TE01A was generated using build descriptor cics-cobol from file EGL_DEMO_Client/EGLSource/EGL_DEMO_Client.eglbld. IWN.VAL.9996.i 1/1 Generation completed for TE01A with no errors.
To see the source code created and its related file, select the project EGL_DEMO_Server and using the context editor, select Refresh. The generated files will be part of the project now. Figure 16 shows the COBOL source code that has been generated.
Ignore the error in the file TE01ABuildPlan.xml. The No grammar message is produced because there is no DTD specified on the DOCTYPE tag to indicate the required grammar. EGL has no control over this. By default, Enterprise developer has the XML parser do validation automatically. For generation purpose this XML is correct, you do not need a DTD available when the distributed build component processes the build plan.
Figure 16. COBOL/CICS generated code
This tutorial will not be extended to the mainframe. You should follow the documentation to submit this to the mainframe processing. Also note that the option PREP=NO in the generation options was specified, that means that no action is taken in place to prepare this code in the z/OS.
5. Generate Java from the EGL pagehandlers
The Client part of this application will be the Java code generated from the EGL pagehandlers. During the test/debug phase, the JSP was calling the EGL server without using any linkage table,. But now you will use the newly created build descriptor named cics-client that will use a linkage part.
- Using the EGL perspective and the Navigator view, right-click on pagehandlers under EGL_DEMO_Client\EGLSource\ and select Generate With Wizard.
- Click Next.
- Select Use one build descriptor for all parts and cics-client as build descriptor option as seen in Figure 17.
- Click Finish.
Figure 17. Generating the client code using new build descriptor
The Java code generated for each pagehandler will now call the generated COBOL program using the J2C connectors as specified in the linkage part. Figure 18 below shows part of the TE01_Input.java code generated. This is the code that will call the COBOL.
Figure 18. Java code generated from pagehandler
Optionally you could set the default Target System build descriptor to the COBOL generation build descriptor. Then you user never has to use Generate with wizard. The only good reason to set the default to Java build descriptor is in a situation where a program is generated for both Java and COBOL.
To change the default build descriptor again:
- Using EGL or EGL Web perspective, right-click on the EGL_DEMO_Client folder and from the context menu, click Properties.
- Click on EGL Default Build Descriptors and select cics-client for the Target System (leave the Debug build descriptor as it is) and click OK.
- Right-click the EGL_DEMO_Server folder and from the context menu, click Properties.
- Click on EGL Default Build Descriptors and select cics-cobol for the Target System. Leave the Debug build descriptor as it is and click OK.
Now the next time that you want to generate the CICS Server and the Client Java, just use the context menu option Generate, since the defaults above will be used. Of course, you could have done that defaults before, but the objective here was to show all the possible ways to do that.
Section III. Run the application using the generated code
At this point, all the COBOL server code and Java client has been generated. The mainframe components must now be submitted to the mainframe to create the executables, and WebSphere Application Server must be properly configured to run the application with the JCA connectors that invoke the CICS COBOL program. If you have a mainframe to test this tutorial, be sure that it has the necessary code installed.
- The WebSphere Enterprise Developer Options for z/OS (5624-B67) which contains the build server code, must be installed to run the COBOL generated by Enterprise Developer. This product is free for those with a Enterprise Developer Server license.
- The Enterprise Developer Server (5655-I57) must also be installed and configured, because it provides modules that are used by the generated COBOL program. The Enterprise Developer Server is not included with the standard Enterprise Developer CDs and must be ordered separately.
The following tasks must now be performed to get the application up and running:
- Submit the generated COBOL program for mainframe preparation.
- Configure the Web Deployment Descriptor for JCA.
- Install the CICS ECI resource adapter in WebSphere Application Server.
- Create the resource adapter and configure the connection factory for WebSphere test environment.
- Test the JSP pages using the generated COBOL/CICS transactions.
1. Submit the generated COBOL program for mainframe preparation
When the COBOL program was generated, a build plan was created. The build plan is an XML file that makes the following details available at preparation time:
- What files need to be processed on the z/OS build machine.
- What build scripts are needed to process them.
- Where outputs are to be placed.
The build plan resides on the development platform and informs the build client of all the build steps. For each step a request is made of the build server.
EGL produces a build plan whenever you generate a COBOL program (unless the buildPlan option in the build descriptor is set to NO). Enterprise Developer uses this generated build plan (TE01ABuildPlan.xml in our example) as an input to the step which prepares the generated output for run time.
Since we did not expect to be connected to the mainframe at generation time, we specified prep = NO in the COBOL generation options to prevent the build plan from being launched. To invoke the build plan now, perform the following steps (not necessary if the prep option was set to YES):
- Open a command window.
- Execute the following command: java com.ibm.etools.egl.distributedbuild.BuildPlanLauncher C:\ED512\workspace_article_Cobol\EGL_DEMO_Server\TE01ABuildPlan.xml. For details, see the Enterprise Developer Help.
2. Configure the Web Deployment Descriptor for JCA
The JCA connection factory provides connections to CICS. You must specify all the information the resource adapter will need to connect to the particular CICS instance, as well as the JNDI lookup name under which the new connection factory instance would be available to components. With this lookup name, the components can quickly make a connection to CICS. At run time, a factory object can then generate a connection, locate the CICS server, and invoke the CICS program at the server.
When we defined the linkage part, we specified the location value of eis/CICSResourceAdapter in the CallLink elements. This value is a local JNDI name that we have to map to a global JNDI name. To bind the JNDI name:
- Open the EGL Web perspective.
- Using the Project Navigator view and under the project EGL_DEMO_Client, open the Web Deployment Descriptor. 3. Select the References tab (at the bottom), then the Resource Environment tab (at the top. Be careful, select Resource Environment, not the Resource tab).
- Select Add to define a new resource reference. Enter the following values:
- Resource Environment Reference:
/eis/CICSResourceAdapter. This name must match the name defined before in the linkage part.
- Click Browse, then select javax.resource.cci.ConnectionFactory. To select this class, start typing in
ConnectionFactoryto get the class list to come up. Do not type the package name, you must choose the package name from the panel in the bottom.
- JNDI Name: enter any unique name; in our example: eis/CICSERV.
- Resource Environment Reference:
- Save and close the deployment descriptor:
Figure 19. Web deployment Descriptor JCA Resource reference
3. Install the CICS ECI resource adapter in WebSphere Application Server
The CICS ECI (External Call Interface) resource adapters provide access to CICS transactions on servers. The ECI resource adapters are not automatically loaded in the Enterprise Developer during product installation. This activity needs to be performed once for each user workspace. To install the CICS ECI resource adapter follow these steps:
- Using EGL Web perspective, from the menu bar, select File => Import.... The Import wizard opens.
- Select RAR file and click Next. The Connector Import wizard opens.
- Select Browse to find the resource adapters file, cicseci.rar. The JCA resource adapters shipped with WebSphere Studio can be found in <WSED>\resource adapters\ctg510 where <WSED> is the directory where Enterprise Developer is installed.
- Select the Standalone connector project check box.
- Click Finish to complete the import. See the result in the Figure 20 below:
Figure 20. CICS ECI connectors loaded at the workspace
4. Create the resource adapter and configure the connection factory for WebSphere test environment
Application components use a connection factory to access a connection instance, not the resource adapter directly. Examples of connections include database connections, JCA, Java Message Service (JMS) connections, and SAP R/3 connections. The connection factory is really a configuration properties list holder. In addition to the arbitrary set of configuration properties defined by the vendor of the resource adapter, there are several standard configuration properties that apply to the connection factory. These standard properties are used by the JCA connection pool manager in the application server run time.
We loaded the resource adapters in the workspace. Now we have to create the resource adapter and configure the connection factory used at the run time execution. This step is similar to the data source configuration that is required to access a database.
In the following steps, you will add a connection factory to your server configuration containing the information the resource adapter needs for connecting to the particular CICS instance. You will specify the Java Naming and Directory Interface (JNDI) lookup name under which the new connection factory instance would be available to components, enabling them to quickly make a connection to CICS. At run time, a factory object will use this information to generate a connection, locate the CICS server, and invoke the CICS program at the server.
The steps required to configure the connection factory are:
- Using the EGL Web perspective and the servers view, open the server configuration (just double-click on EGL_Server)
- Select the J2C page and then select Add, as shown in Figure 21 below.
- Click OK to create the resource adapter. If the Add button is not active, it is probably because the RAR files were not correctly loaded as described before.
Figure 21. Installing J2C Resource Adapters into WebSphere Application Server
4.1 Define security for JCA usage
WebSphere Application Server V5.1 fully supports the Java Authentication and Authorization Service (JAAS) architecture and extends the access control architecture to support role-based authorization for J2EE resources. To use JAAS authentication to restrict access to the transaction, you need to add JAAS authentication entries to the server configuration:
- Assuming that the EGL_Server is still opened, select the Security page and select Add to define a new JAAS authentication entry.
- Enter the values as required. Any value is valid for Alias name, but the User ID and Password are required and must be valid to run the CICS transaction.
- Click OK.
- Save the changes. See Figure 22 for one example:
Figure 22. Defining authentication for J2C
4.2 Create a J2C connection factory
The connection factory for the J2C must now be configured:
- Using the server J2C page, select the cicseciConnector that you just created.
- From the J2C Connection Factories window (the pane below), select Add to create a Connection Factory, as shown in Figure 23 below.
- Enter the following values:
CICSERV(CICS server name)
- JNDI name:
eis/CICSERV(this matches the Web Deployment Descriptor)
- Select EGLCICS for Component-managed authentication.
- Select OK.
Figure 23. Connection factory definition
4.3 Define the properties of the connection factory
Using the Resource Properties window, define the properties of the connection factory by changing the values for each property in the configuration dialog as follows, as shown in Figure 24 below:
CICSERV(name of the CICS server)
tcp://carmv1.raleigh.ibm.com(the z/OS machine, also defined in the destHost of the build descriptors)
- Port Number:
22002(the port of the CICS Transaction Gateway)
TE01(name of the CICS transaction that runs the DB2 plan)
Save the definitions and close the editor. You have configured the WebSphere Application Server 5.1 and are ready to test the generated code.
Figure 24. Connection factory properties
5. Test the JSP pages using the generated COBOL/CICS transactions
At this point the code has been generated, all the configurations are done and you will be able to run the sample application. Below you can see the main steps that are generally necessary for that test. Since your MVS system is probably not prepared, you will not see the code running
5.1 Prepare the z/OS for run the CICS Server program
Before testing, the following environment-related tasks must be completed, most of which are typical for any z/OS environment running CICS transactions:
- The Enterprise Developer Server (5655-I57) must be installed and configured, because it provides modules that are used by the generated COBOL program.
- As with other COBOL/CICS programs, run-time components of the generated COBOL program must be compiled, link-edited, and cataloged in z/OS, the CICS Transaction Gateway must be configured, and the CICS program tables such as PPT, and PCT must be updated.
5.2 Add required CTG and CICSECI jar classes to WebSphere Application server
The connection to the mainframe uses CICS Transaction Gateway and CICS ECI Java classes that were loaded in the workspace when the CICSECI resource adapter was loaded, but those classes are not automatically loaded in the Application Server. Lets do it now:
- Using the EGL Web perspective and the Server view, edit the server EGL_Server.
- Click the Environment tab.
- Select Class Path.
- Add the classes
cicseci.jar, cicsecitools.jar, cicsframe.jar, ctgclient.jarand
ctgserver.jarlocated in the folder <WSED>workspace_article_Cobol\cicseciConnector\connectorModule as shown in the Figure 25 below:
- Save the server.
Figure 25. Adding External CTG jar files
5.3 Remove EGL Debugger Jar Files from WebSphere Application Server
In the beginning of this tutorial, the EGL files were added for debugging purpose. Now you must remove them before running the test where the client code will call COBOL/CICS generated instead of the EGL.
- Using the Web perspective and servers view, stop the server and remove those jar files as shown in Figure 26 below.
- Save the new configuration and close the server.
Figure 26. Removing EGL Debugger Jar Files from WebSphere Application Server
5.4 Run the JSP pages
Be sure to save the server configuration and close it before running the test.
- Using the EGL Web Perspective, select TE01_Input.jsp located in EGL_DEMO_Client\WebContent\.
- From the context menu, select Run on Server. The application will be published and the WebSphere Application server will start.
- Enter a valid ID like 40 and click the button Call Server Program:
Figure 27. Running the TE01_Input.jsp page
- As expected you will have errors, since the z/OS CICS is not ready to receive this call. In the example below, the z/OS system does exist and the problem occurred since the CTG is not configured to communicate with CICS. The error message will be displayed in the console:
J2CA0056I: The Connection Manager received a fatal connection error from the Resource Adapter for resource eis/CICSERV. The exception which was received is null J2CA0092E: This is an English-only message: Event source is com.ibm.connector2.cics.ECIManagedConnection@60adb511 gatewayURL="tcp://carmv1.raleigh.ibm.com" server="CICSERV" Port=22002 Userid="NOT NULL" TranName=null TPNName=TE01 TXN State=AutoCommit/Unknown Txn Context].SystemOut O VGJ0350E An error occurred on a call to program TE01A. The error code was CSO8104E (CSO8104E An error occurred during an attempt to communicate with CICS. Exception is CTG9630E: IOException occurred in communication with CICS.).<BR>VGJ0004I The error occurred in TE01_Input, function button2Action1.
If you receive errors like the one below, it could be because you forgot to remove the EGL Debugger classes from the Application server as explained in item 5.2.
You're almost done -- the application is ready to run. Errors such as these are typically CTG or CICS configuration problems that will not require any coding changes to the EGL or generated server program components.
Congratulations. Without writing a single line of Java or COBOL code, you implemented an application that uses JSF where the connection to CICS is accomplished using the J2C Connectors. Even if this simple application were sophisticated and complex, the process to code, test, debug, and deploy would be very similar. When coding in EGL, the developer doesn't need to deal with all the plumbing; all the connectors are generated using the necessary Java classes available at generation time. EGL is an easy way for programmers to move into the J2EE world without knowing all of the skills that are necessary for complex implementations.
The author wishes to thank Henry Koch for contributing to this article, and Jorge Nagasaki and Michael Virga for reviewing it.
Tip for download files: To load the code to your workspace in any perspective, use File => Import => Project Interchange and select all the projects. When loading Solution.zip, you need to set up the workspace preferences, correct the user ID and password, install the CICS ECI resource adapter in WebSphere Application Server, and create and configure the resource adapter as explained in the article, since the resource adapter will be dependent of your workspace.
- Code to be loaded before starting this tutorial
- Complete solution. Load this if you want to see the results of this tutorial without following all of the steps.
|Demo||EGL_DEMO.zip ( HTTP | FTP )||3443 KB|
|Demo||EGL_DEMO_Solution.zip ( HTTP | FTP )||3454 KB|
- Redbook: Legacy Modernization with WebSphere Studio Enterprise Developer, Ueli Wahli, Masaaki Agatsuma, Reginaldo Barosa, Gert Hekkenberg, Bob McGoogan and Iwan Winoto - SG24-6806.
- Redbook: CICS Transaction Gateway V5 - The WebSphere Connector for CICS, Phil Wakelin, John Joro, Kevin Kinney and David Seager - SG24-6133.
- WebSphere Portal Express
- Redbook: Exploring WebSphere Studio Enterprise Developer 5.1.2 - Reginaldo Barosa, James Eberwein, Michael Virga and Henk van der Wijk - SG24-6483.
- Get involved in the developerWorks community by participating in developerWorks blogs.
- Browse for books on these and other technical topics.
- Find out more about WebSphere Studio Application Developer.