EJB CICS sample application task guide: Development

sga010


The EJB CICS sample application task guide

Develop command beans using VisualAge for Java

This section describes the task steps to create the command beans that the EJB CICS sample application will use to access the existing Cobol - DB2 application on your CICS Server. We assume that you have now completed all the tasks for setting up and configuring an enterprise bean environment in which to develop and run the sample application. In addition we assume that you have installed the sample COBOL programs, DB2 components and CICS definitions that play the part of "existing" CICS COBOL applications in your system.

In Java, fields and methods are grouped into classes, and classes are grouped into packages. VisualAge for Java allows you to group packages into Projects. The tasks involved in creating the command beans through which the enterprise bean interacts with the existing CICS COBOL-DB2 application are:

  1. Start up Visual Age for Java
  2. Add a Project for the sample application command bean
  3. Add a Package for the sample application command beans
  4. Create command beans to access the CICS application
  5. Add a data type class to the package

    Start up Visual Age for Java

    Start Visual Age for Java:
    1. Click on Start Button->Programs->IBM VisualAge for Java for Windows V3.5->IBM VisualAge for Java.
    2. If necessary, click on the Workbench tab to bring it into view in the main Visual Age for Java window.

    Add a Project for the command beans

    1. Click on Selected->Add->Project to start the Add Project SmartGuide.
    2. Enter a name for the new project: CICSEJBSample.

      Add project SmartGuide panel

    3. Click on the Finish button.

      The new project CICSEJBSample is now shown in the list of projects available in the Workbench.

    Add a Package for the command bean classes

    1. Select your project in the project list. Sample: CICSEJBSample.
    2. Click on Selected->Add->Package... to start the Add Package SmartGuide.
    3. Ensure that the correct Project is identified in the top field. If the project name is incorrect, click on the Browse button, then select your project.
    4. Select the radio button labelled: Create a new package named:.
    5. Enter a name for the new package: cics.sample.

      Add package smartguide panel

    6. Click Finish

    Create command beans to access the CICS applications

    You need command beans for each CICS program with which an application will interact. The sample programs are: The classes required to work with each COBOL program are:
    1. Dynamic record type class to import the COBOL customer records in an appropriate format.
    2. Record classes to hold the data from the COBOL customer records.
    3. Command classes V2CSTDBCommand and V2ACTDBCommand to retrieve the customer information.
    These classes will be used to construct an input command bean and an output command bean for each of the two CICS COBOL programs in the sample application.

    Create classes to access the COBOL customer records using V2CSTDB

    Create a dynamic record type class for COBOL customer records

    Use the Enterprise Access Builder of VisualAge for Java to create a dynamic record class to import a COBOL file in the appropriate format for use in the customer account enterprise bean.

    In the Workbench

    1. Right-click the cics.sample package.
    2. From the menu for the package, select Tools -> Enterprise Access Builder -> Import COBOL to Record Type to start the Import SmartGuide.
    3. In the Import COBOL to Record Type window, click Browse.
    4. Navigate to the directory in which you installed the downloaded Sample Application COBOL files, and import V2CSTDB.ccp.

    5. Select the A CICS Transaction radio button:

      Import COBOL smartguide panel: Select COBOL file

    6. Click Next.
    7. Ensure that the Use Bigdecimal option is not selected:

      Import COBOL smartguide panel: Select COMMAREA

    8. Click Next.
    9. In the Class Name field, type sample: V2CSTDBRecordType:

      Import COBOL smartguide panel: Specify package

    10. Click Finish .
    The Create Record from Record Type SmartGuide will open.

    Create a record class for COBOL customer records

    The Create Record from Record Type SmartGuide constructs the record class needed to hold the customer information imported from the COBOL file.
    1. In the Class Name field type the name of the commarea from which the data will be imported:V2CSTDBCommarea.
    2. Set the Access Method to Direct. This option allows direct, or flattened, access to the record fields.
    3. Set the Record Style to Custom Records. This option generates the offset information directly into the code, so that the fields are accessed more quickly at run time.
    4. Do not select any of the Additional Options.

      Create Record smartguide panel: Specify package

    5. Click Next.
    6. Specify the following values for the CICS server properties:

      Property Value
      Floating Point Format IBM
      Endian Big Endian
      Remote Integer Endian Little Endian
      Code Page 037
      Machine Type MVS

    7. Click Finish.

    Three new classes are generated into the specified package: cics.sample :
    V2CSTDBRecordType
    V2CSTDBCommarea
    V2CSTDBCommAreaBeanInfo
    You can see these by expanding the project tree on the left hand side of the Workbench.

    Create a command class to access customer records

    Constructing a Command class for handling the input to, and output from the CICS COBOL V2CSTDB program entails:
    1. Creating the command class, sample: V2CSTDBCommand
    2. Defining connection and interaction specifications
    3. Creating input and output beans

    In the Workbench:

      Create the V2CSTDBCommand class

    1. Locate the cics.sample package in the workbench project tree and right-click on it.
    2. From the menu for the package, select Tools -> Enterprise Access Builder -> Create Command... to start the Create Command SmartGuide.
    3. In the Create Command window, type V2CSTDBCommand in the Class Name field.

      Create the connection and interaction specifications

    4. Click Browse beside the Connection Spec class name field.
    5. From the class selection box, select CICSConnectionSpec and click OK.
    6. Click Browse beside the Interaction Spec class name field.
    7. From the class selection box, select ECIInteractionSpec and click OK.

       Command editor panel: Specify connection bean properties

    8. Click Next.

      Prepare to create the input and output beans

    9. Ensure that the Implements IByteBuffer check box is selected.
    10. Click the Browse button beside the Input Record Bean class name field.
    11. From the class selection box, select V2CSTDBCommarea in the cics.sample package, and click OK.
    12. Click Use input bean type as output bean type to use an output record bean the same as the input record bean.

      Create Command smartguide panel: Specify beans

    13. Click Finish. The Command Editor window will open.

      Customize the connections for your server

    14. In the Command Editor window, select the Connector folder in the top left pane, and then select the CICSConnectionSpec bean in the top right pane.
    15. In the properties table for the connection spec, in the bottom pane, ensure that the following property values are set:

      Property Value
      URL Local
      CICSServer  

      The window should look similar to this:

       Command editor panel: Specify connection spec properties

    16. Select the ECIInteractionSpec bean in the top right pane.
    17. In the properties table for the interaction spec in the bottom pane, ensure that the the following property values are set:

      Property Value
      ProgramName V2CSTDB
      TPNTransactionName true
      TransactionName  
      The window should look similar to this:

       Command editor panel: Specify interaction spec properties

      Create the input command bean

      The CICS EJB Sample application uses default settings for the input command bean so no changes are required.

      Create the output command bean

      The CICS EJB Sample application uses default settings for the output command bean so no changes are required.

    18. Click Command -> Save to save your changes.
    19. Click Command menu -> Exit Editor to close the Command Editor.

    Create classes to access the COBOL account records using V2ACTDB

    The command bean construction procedure is repeated to create input and output beans to access account data via the CICS COBOL program V2ACTDB.

    Create a dynamic record type class for COBOL account records

    Use the Enterprise Access Builder of VisualAge for Java to create a dynamic record class to import a COBOL file in the appropriate format for use in the customer account enterprise bean.

    In the Workbench

    1. Right-click the cics.sample package.
    2. From the menu for the package, select Tools -> Enterprise Access Builder -> Import COBOL to Record Type to start the Import SmartGuide
    3. In the Import COBOL to Record Type window, click Browse.
    4. Navigate to the directory in which you installed the downloaded Sample Application COBOL files, and import V2ACTDB.ccp.

    5. Select the A CICS Transaction radio button:

      Import COBOL smartguide panel: Select COBOL file

    6. Click Next.
    7. Ensure that the Use Bigdecimal option is not selected:

      Import COBOL smartguide panel: Select COMMAREA

    8. Click Next.
    9. In the Class Name field, type sample: V2ACTDBRecordType:

      Import COBOL smartguide panel: Specify package

    10. Click Finish.
    The Create Record from Record Type SmartGuide will open.

    Create a record class for COBOL account records

    The Create Record from Record Type SmartGuide constructs the record class needed to hold the account information imported from the COBOL file.
    1. In the Class Name field type the name of the commarea from which the data will be imported:V2ACTDBCommarea.
    2. Set the Access Method to Direct. This option allows direct, or flattened, access to the record fields.
    3. Set the Record Style to Custom Records. This option generates the offset information directly into the code, so that the fields are accessed more quickly at run time.
    4. Do not select any of the Additional Options.

      Create Record smartguide panel: Specify package

    5. Click Next.
    6. Specify the following values for the CICS server properties:

      Property Value
      Floating Point Format IBM
      Endian Big Endian
      Remote Integer Endian Little Endian
      Code Page 037
      Machine Type MVS

    7. Click Finish.

    Three new classes are generated into the specified package: cics.sample :
    V2ACTDBRecordType.
    V2ACTDBCommarea
    V2ACTDBCommAreaBeanInfo
    You can see these by expanding the project tree on the left hand side of the Workbench.

    Create a command class to access account records

    Constructing a Command class for handling the input to, and output from the CICS COBOL V2ACTDB program entails:
    1. Creating the command class, sample: V2ACTDBCommand
    2. Defining connection and interaction specifications
    3. Creating input and output beans

    In the Workbench:

      Create the V2ACTDBCommand class

    1. Locate the cics.sample package in the workbench project tree and right-click on it.
    2. From the menu for the package, select Tools -> Enterprise Access Builder -> Create Command... to start the Create Command SmartGuide.
    3. In the Create Command window, type V2ACTDBCommand in the Class Name field.

      Create the connection and interaction specifications

    4. Click Browse beside the Connection Spec class name field.
    5. From the class selection box, select CICSConnectionSpec and click OK.
    6. Click Browse beside the Interaction Spec class name field.
    7. From the class selection box, select ECIInteractionSpec and click OK.

       Command editor panel: Specify connection bean properties

    8. Click Next.

      Prepare to create the input and output beans

    9. Make sure that the Implements IByteBuffer check box is selected.
    10. Click the Browse button beside the Input Record Bean class name field.
    11. From the class selection box, select V2ACTDBCommarea in the cics.sample package, and click OK.
    12. Click Use input bean type as output bean type to use an output record bean the same as the input record bean.

      Create Command smartguide panel: Specify beans

    13. Click Finish. The Command Editor window will open.

      Customize the connections for your server

    14. In the Command Editor window, select the Connector folder in the top left pane, and then select the CICSConnectionSpec bean in the top right pane.
    15. In the properties table for the connection spec, in the bottom pane, ensure that the following property values are set:

      Property Value
      URL Local
      CICSServer  

      The window should look similar to this:

       Command editor panel: Specify connection spec properties

    16. Select the ECIInteractionSpec bean in the top right pane.
    17. In the properties table for the interaction spec in the bottom pane, ensure that the the following property values are set:

      Property Value
      ProgramName V2ACTDB
      TPNTransactionName true
      TransactionName  
      The window should look similar to this:

       Command editor panel: Specify interaction spec properties

      Create the input command bean

      The CICS EJB Sample application uses default settings for the input command bean so no changes are required.

      Create the output command bean

      The CICS EJB Sample application uses default settings for the output command bean so no changes are required.

    18. Click Command -> Save to save your changes.
    19. Click Command menu -> Exit Editor to close the Command Editor.

    The command beans are now complete.

    Add data type class

    The data type class combines the customer data and account data into a sinlge, serializable data type, to be accessed by the enterprise bean business logic. The steps involved in adding a data type class are:
    1. Create data type class
    2. Add required field definitions to the class

    In the workbench:

      Create a data type class

    1. Right click the package to which the class is to be added. Sample: cics.sample.
    2. From the menu for the package, select Add-> Class... to open the Create Class window in the Create Class smart guide.
    3. In the Class name field enter the name for the data type class. Sample: CustomerData.
    4. Ensure that the Superclass field is blank.

       Create class smartguide panel: Specify class name

    5. Click Next to open the Attributes window of the smartguide.
    6. Next to the Interfaces list, click Add to open the Add Interfaces panel.
    7. In the Choose and interface type field enter: java.io.serializable
    8. Click Add.
    9. Click Close.

       Create class smartguide panel: Specify class attributes

    10. Click Finish.
      The class is generated and added to the package.

      Add data fields to the class

    11. Right click on the new class CustomerData.
    12. From the menu for the class select Add -> Field...to start the Create Field smartguide.
    13. In the Field name field enter a name for the new field. Sample: AcctNo.
    14. Set the field properties:

      Property Value
      Field type int
      Access modifiers Private

    15. Check Access with getter and setter methods.
    16. Set the method attributes:

      Attribute Value
      Getter public
      Setter Public

       Create field smartguide panel

    17. Click Finish.

      The field and its getter and setter methods are added to the class.

    18. Repeat this procedure to add the remaining fields to the class:

      Field Data type
      CustNo int
      Balance double
      LastName
      FirstName
      Address
      City
      State
      Country
      string
    This completes the creation of classes and command beans used by the enterprise bean to communicate with the CICS COBOL programs in the CICS EJB Sample Application.