EJB CICS sample application task guide: Development

sga005


EJB CICS sample application task guide

Install supplied files for EJB CICS Sample Application

We assume that you have completed all the tasks for setting up and configuring an enterprise bean server environment in which to develop and run the sample application. This task step involves installing the Java files required to work through the development of the EJB CICS sample application and the files which are used by the developed code.

The EJB CICS sample application contains three sets of files:

The z/OS files provide a database, and CICS COBOL programs to access the database, which play the role of an "existing application" in the usage scenario on which the sample is based. The sample also includes the enterprise bean JAR file and CICS connector command file that you will be coding this during the course of the following development and deployment tasks. These will provide a new front end to the existing programs, including a Web browser user interface and business logic in an enterprise bean.

Preparation for the development and deployment tasks involves:

  1. Installing the "existing application" on z/OS.
  2. Installing COBOL source code on an application development workstation.
Installation of the web components of the sample application will be described as part of the application deployment task.

Install a CICS COBOL application and related DB2 files

Role: CICS/DB2 System Programmer

These z/OS files are supplied with the EJB CICS sample application and installed with CICS TS v2.1:

OS/390 files
Filename Type Default location Comments
DFHEBBND JCL SDFHSAMP Binds the DB2 tables to the COBOL server programs for the first time. Use only when installing the sample.
DFHEBCB1 JCL SDFHSAMP Compiles and link-edits the V2ACTDB server program. (Also contains source code.)
DFHEBCB2 JCL SDFHSAMP Compiles and link-edits the V2CSTDB server program. (Also contains source code.)
DFHEBDAT JCL SDFHSAMP Inserts sample data into the DB2 data tables.
DFHEBDEF Resource definitions SDFHSAMP Contains the CICS resource definitions required by the sample application.
DFHEBGRT JCL SDFHSAMP Grants authority to the DB2 plan.
DFHEBREB JCL SDFHSAMP Re-binds the DB2 tables to the COBOL server programs. Use each time a server program is recompiled.
DFHEBTAB JCL SDFHSAMP Defines the DB2 data tables.

To install the "existing application" on z/OS:

    Compile the CICS COBOL programs

    Jobs DFHEBCB1 and DFHEBCB2 contain the source code of the COBOL server programs V2CSTDB and V2ACTDB respectively. These jobs use the DFHEBCBJ sample procedure to pre-process, compile, and link-edit the programs.
  1. Modify the destination load library in the DFHEBCB1 and DFHEBCB2 jobs.
  2. Modify the CICS, DB2, COBOL, and Language Environment library references in the DFHEBCBJ procedure.
  3. Run the DFHEBCB1 job.
  4. Run the DFHEBCB2 job.
    Authority required: Write access to the datasets whose members are being created: the load module is written to a member of a dataset in the CICS DD DFHRPL concatenation; the SQL statements in the program are written to a member in DB2's DRMLIB.DATA dataset.

    Define DB2 tables

    Define DB2 tables, table space, storage group, and indexes and populate the tables:
  5. Modify the DFHEBTAB and DFHEBDAT jobs to use your DB2 datasets and subsystem ID. The jobs contain comments which indicate which lines must be changed.
  6. Run the DFHEBTAB job. This creates DB2 definitions for the sample application.
  7. Run the DFHEBDAT job. This does the data insertions for the sample application.
    Authority required: Ability to create a DB2 database, storage group, tablespace, tables, and indices.

    Bind the DB2 tables to the COBOL server programs

    This step statically binds the SQL statements in the server programs to DB2 and grants authority to the plan. Static binding improves performance by removing the requirement for dynamic binding at execution time.
  8. Modify the DFHEBBND and DFHEBGRT jobs to point to your DB2 datasets and subsystem ID. The jobs contain comments which indicate which lines must be changed.
  9. Run the DFHEBBND job.
  10. Run the DFHEBGRT job.
    Authority required: DB2 authority to perform a BIND for this database, and write access to the CICS region.

    Create CICS resource definitions for the COBOL and DB2 parts of the sample application

    Define the programs and DB2 connections used by the sample to CICS. The required definitions are in the supplied DFHEBDEF file. You need to modify some of the definitions to suit your environment before installing them. DFHEBDEF contains comments that tell you what needs to be modified.

  11. Modify the DB2CONN definitions as indicated by the comments in the file.
  12. The PROGRAM definitions do not need to be modified.
  13. Copy the resources definitions for the "existing" application to a new group called EJBSAMPC.
  14. Install the modified resource definitions into the CICS region you have configured as a CICS EJB server. using the CICS system definition utility program, DFHCSDUP. Authority required: RACF authority to install resource definitions into the CICS region.

    Ensure that the DB2 connection status is CONNECTED

  15. Ensure that the DB2 connection status is CONNECTED by issuing the following command at the CICS system console:
    CEMT SET DB2CONN CONNECTED
    Note: If you recompile one of the server programs subsequently and intend it to access DB2, each time you recompile you must:
    1. Run the DFHEBREB (not the DFHEBBND) job.
    2. Refresh the copy of the server program on CICS by executing the following CICS command in the CICS region:
      CEMT SET PROG(program_name) NEW

Install java class files

Role: Java developer

The java class files required for sample application are also installed with CICS TS v2.1. These are:

Java files
Filename Type Default location Comments
ccf.jar JAR file HFS samples directory: see Note. VisualAge for Java common Connector Framework (CCF) Classes
eablib.jar JAR file HFS samples directory: see Note. VisualAge for Java Enterprise access builder classes
recjava.jar JAR file HFS samples directory: see Note. VisualAge for Java Record Framework classes
SampleEJB.jar Deployed JAR file HFS samples directory: see Note. Java classes, source files, deployment descriptor, plus supporting classes for the CICS enterprise bean. Doesn't need to be unpacked unless you want to modify the source code.
SampleServlet.jar JAR file HFS samples directory: see Note. The Web components of the sample application--Java servlet classes and source files; HTML and JSPs. Files must be unpacked and stored on the Web server.
Note:The default HFS samples directory is
/usr/lpp/cicsts/cicsts21/samples/ejb/bankaccount
where cicsts21 is the value of the CICS_DIRECTORY variable used by the DFHIJVMJ job during CICS installation.

To prepare to develop the enterprise bean and its associated components:

    Download CICS COBOL source files to a development workstation

    The sources for the CICS COBOL programs V2CSTDB and V2ACTDB need be accessed by VisualAge for Java to build the connector data bean.
  1. Create a working directory for storing development files on a workstation, for example:
    C:\cicsejb
    This directory can also be used as your staging directory during the deployment tasks.
  2. Use FTP to download the files DFHEBCB1 and DFHEBCB2 to the working directory on the development workstation. Set the file transfer mode toascii.
  3. Open each file in your editor and remove all the JCL lines. Keep the lines from:
    IDENTIFICATION DIVISION
    ....
    END-EXEC
    
    Ensure that you locate the last occurrance of END-EXEC before removing subsequent lines.

    Download sample application JAR files

    You will be developing the classes contained in the JAR files: so you do not need to download these to your workstation unless you want to review the contents of the files.

  4. Optionally, use FTP to download the files SampleEJB.jar and SampleServlet.jar. Do not use the working directory on the development workstation since you will be exporting your own versions of these files. Set the file transfer mode to binary.