Creating custom data bindings in WebSphere Process Server without coding

Create a custom data binding based on a COBOL copybook for WebSphere Process Server, without having to write code.

Share:

Marc Fasbinder, BPM Integration Solution Architect, IBM

Photo of Marc FasbinderMarc Fasbinder is an I/T Specialist at IBM with the WebSphere Technical Sales team in Southfield, Michigan.



31 October 2007

Introduction

When IBM® WebSphere® Process Server Version 6.0.2 (hereafter called Process Server) works with a message from WebSphere MQ V6.0, the message needs to be converted into a business object. This work can be done by using a default data binding, or through custom code. WebSphere Integration Developer Version 6.0.2 has a built-in feature that can automatically generate Java™ code for this, based on a COBOL copybook.

In this article, you will learn how to use this feature, so you can create custom data bindings without writing code. Intermediate-level integration developers will benefit most from this article.

Data bindings overview

Process Server and WebSphere Enterprise Service Bus (hereafter called WebSphere ESB) use Service Component Architecture (SCA) as their invocation framework. Components such as business processes have references that can be wired to the interfaces of other components. These components can be components provided by Process Server such as human tasks, business rules, or business state machines. They can also be imports and exports to communicate with external systems.

Imports

The Java programming language has a set of built-in functions. You can access other functions in a Java program by importing them, see Listing 1.

Listing 1. Java program example, partial listing
import com.ibm.etools.logging.util.*;

public class HelloWorld {
    public static void main(String[] args) {
MsgLogger myLogger = (MsgLogger)         MsgLogger.getFactory().getLogger("My Logger");
        String product                  = "myProduct";
        String version                  = "myVersion";
        String componentName            = "myComponentName"; …

SCA uses a similar terminology. When you need to invoke something external, the external component is called an import

Figure 1. SCA terminology
SCA terminology

SCA Imports have bindings that define the communication mechanism for how the external component is to be invoked. There are several options available for these bindings in WebSphere Process Server V6.0.2.

JMS Binding
A message will be placed on an external queue, using the JMS API.
MQ Binding
A message will be placed on an external queue, using the WebSphere MQ API.
MQ JMS Binding
A message will be placed on an external queue, using the JMS API, with WebSphere MQ as the JMS provider.
SCA Binding
The external component resides in another SCA module. Module to module communication can occur through SCA.
Stateless Session Bean Binding
The external component is an EJB residing in an application server.
Web Services Binding
The external component is a service that will be invoked using SOAP/HTTP or SOAP/HTTPS

Exports

An SCA module can expose an interface, so that it can be invoked externally. Since the term for invoking an external function is called an import, the term for the exposed interface is called an export.

As with imports, exports have bindings to determine the communication mechanism. Exports have the same bindings as imports, with the exception that exports do not have a stateless session bean binding. This means that an SCA module can be invoked as a Web service, through a JMS message, or through a WebSphere MQ message for example.

Enterprise Information System (EIS) Binding

When using Java 2 Connection Architecture adapters (often termed JCA or J2C adapters), you can use one additional binding in SCA. The EIS binding is available as an import, so an SCA component can invoke a function from an external system through an adapter. For example, as you are using SAP, the component could look up data within SAP or make updates, via the WebSphere JCA adapter for SAP. Likewise, you can use an export with an EIS binding so that an event such as data being added to SAP could be the event that triggers your component to run.

Binding levels for an EIS

In Process Server and WebSphere ESB, there are three levels of bindings.

  • Interface. Describes the mapping between the enterprise information system service connection information, and the service interface that represents the service.
  • Method. Expresses the relationship between the operations of the interface, and the interaction or event information of the service.
  • Data. Defines how the service input our output data is mapped to the native data as understood by the enterprise information system.

Data bindings are the focus area for this article. Process Server and WebSphere ESB use business objects based on Service Data Objects (SDO), while external systems use XML, fixed format messages, and so on. If an SCA component was wired to an import with JMS binding, the SDO representation of the data needs to be converted to an XML document that can be used as the payload of the JMS message.

Data binding categories

WebSphere ESB and Process Server have predefined data bindings. The products also support the use of custom data bindings, created to support specific requirements.

General purpose bindings
Two general purpose data bindings are supplied with Process Server and WebSphere ESB. DataBindingImplXML can be used to convert business objects to and from XML. DataBindingImplJava converts business objects to and from Java serialized objects (java.io.serializable).
Supported data bindings
These data bindings are supplied to support various components in Process Server and WebSphere ESB, in order to meet specific requirements. WBIAdapterSDODataBindignImpl is used by WebSphere Adapters. BCGBackEndIntegrationDataBindingUtil is used by WebSphere Partner Gateway.
Custom data bindings
Developers can write their own data bindings.
Tool generated data bindings
Included with WebSphere Integration Developer are the CICS and IMS JCA adapters, which includes tooling to import a COBOL copybook that is often used to describe fixed length messages. These messages are often described through COBOL copybooks.

The scenario

Suppose that you are asked to develop a solution for WebSphere Process Server, so that a step in the WS-BPEL process can write a message to MQ. If the message was to be put in XML format, you could use the default data binding DataBindingImplXML. However, you are asked to put the message into a fixed format described by a COBOL copybook, as listing 2 shows.

Listing 2. COBOL copybook
	identification division.
       program-id. CUSTREC.
       data division.
       working-storage section.
000100 01  CUSTOMER-RECORD.
           05  CUSTOMER-NUMBER                  PIC X(06).
           05  CUSTOMER-NAME                    PIC X(35).
           05  CUSTOMER-ADDRESS-INFO.
               10  ADDRESS-LINE-1               PIC X(40).
               10  ADDRESS-LINE-2               PIC X(40).
               10  CITY                         PIC X(25).
               10  STATE                        PIC X(02).
               10  ZIP-CODE                     PIC X(05).
               10  ZIP-CODE-PLUS4               PIC X(04).
           05  CUSTOMER-DISCOUNT-CODE           PIC 9(03).

Since you understand the architecture, you realize that a custom data binding is required. You could write the code from scratch, but it would make sense to let the tool do the work for you, generating the code.

The wizard requires the identification division, program-id, data division and working-storage section at the top of the copybook file. If they are not present, the wizard will show errors. If your copybook does not have these lines, you can add them in, as in Listing 2.

Once the data bindings are done, you can use an import with WebSphere MQ binding to write out the message. For this example, write the message to a queue manager named QM1 with a queue named ADDRESSQ.

Building the solution

WebSphere Integration Developer is the tooling for Process Server. It contains the tools to create artifacts, an integrated test server, and it is used by the person with the role of integration developer to perform this work.

Installing support pac BA78

WebSphere Integration Developer Version 6.0.2 can be extended by adding in a free download support pac named BA78 - "IBM WebSphere Integration Developer - WebSphere MQ-CICS Bridge Plug-in". This support pac adds new capabilities, such as the ability to automatically generate data bindings for WebSphere MQ, without having to write any code. You can download the support pac from the BA78: IBM WebSphere Integration Developer - WebSphere MQ-CICS Bridge Plug-in page. Follow the directions to add BA78 into your installation of WebSphere Integration Developer.

Create the mediation module

The first step is to create a new module, then create the business object, and an interface.

  1. Start WebSphere Integration Developer with an empty workspace.
  2. Right-click the upper left-hand business integration pane, and click New => Project.
  3. Click MediationModule, then Next. Enter a name such as CustomDataBindings, and click Finish.

Build the data type and the interface

Data types need to be created based on the COBOL copybooks. A built-in wizard from the Enterprise Service Discovery tool enables this capability.

  1. Right-click the data types folder in your new mediation model, then select New => Enterprise Service Discovery.
  2. From the drop-down list for choose mapping, select COBOL to Business Object, then click Browse to select your copybook file. After selecting the file, click Next.
  3. On the next screen, you need to select the target platform. If you are sending the message to another platform such as z/OS, you would select that in the platform pulldown menu. For this example, you can keep the default value Win32. Click Apply. The structure of the record from the copybook appears. Click on CUSTOMER-RECORD to select it, then click Next.
    Figure 2. Selecting the platform
    Selecting the platform
  4. On the next screen, leave the Folder field blank to use the default value, then click Finish.
  5. A business object was created, based on the COBOL copybook. Expand the data types folder, then edit it by double clicking on CUSTOMERRECORD. The copybook defined a nested structure, while the generated business object is flat. The data types defined in the copybook were preserved in the business object.
    Figure 3. The generated business object
    Figure 3. The generated business objectF
  6. SCA exports have interfaces, which describes how to invoke them. A new interface is required. Right-click the Interfaces folder, and select New => Interface.
  7. Enter the name SendToMQ, then click Finish. The interface editor opens.
  8. An interface needs an operation. Click the icon for Add Request Response Operation as Figure 4 shows. The name "operation1" is selected. Type in the text sendMessage to replace it.
  9. The input and output messages have default names, as well as a default data type of string. Update the data type to the one you just created, by clicking on string, then selecting CUSTOMERRECORD from the bottom of the list as Figure 4 shows.
    Figure 4. The interface
    The interface
  10. Save the interface by typing Ctrl-S, or clicking the save icon on the toolbar. The interface is now complete.

Generating the data binding

Now that a business object and an interface both exist, the wizard from the BA78 support pac can be used to generate code for the data binding.

  1. Right-click CUSTOMERRECORD, then select Generate Data Binding Class => MQ-CICS.
    Figure 5. Generating data bindings
    Generating data bindings
  2. In the dialog box that pops up, select your module from the pull-down menu. You can update the name of the data binding to be created if you would like. Click Finish. The data binding code is generated for you.
  3. In order to see the generated code, you need to change views in the business integration perspective. Right-click your module, and select Refresh. Then right-click the module and select Show Files. If you have not previously used this view, you will be prompted that the view is for advanced users. Click OK to proceed.
    Figure 6. Physical resources view
    Physical resources view
  4. A new tab appears in the upper left-hand pane. You can click tabs to move back and forth between the normal business integration view, and the physical resources view. When viewing physical resources, you can see files that are normally hidden. Among the files, you will see the generated Java code and the class file. You can double-click CUSTOMERRECORDDataBinding.java to edit it.
Listing 3. Generated code, partial listing.
dObj.setString("customer__number", readMQCHAR(input, 6));
dObj.setString("customer__name", readMQCHAR(input, 35));
dObj.setString("address__line__1", readMQCHAR(input, 40));
dObj.setString("address__line__2", readMQCHAR(input, 40));
dObj.setString("city", readMQCHAR(input, 25));
dObj.setString("state", readMQCHAR(input, 2));
dObj.setString("zip__code", readMQCHAR(input, 5));
dObj.setString("zip__code__plus4", readMQCHAR(input, 4));
dObj.setShort("customer__discount__code", Short
				.parseShort(readMQCHAR(input, 3)));

The generated code includes a section where a data object is created, based on the COBOL copybook. Likewise, a second section creates an MQ message based on a business object.

Testing WebSphere MQ connectivity

Before attempting to use the generated code, it is a good idea to build a simple test case to prove out the WebSphere MQ connectivity, using one of the built-in data bindings. This will make it easier to isolate any problems you may encounter later.

  1. Switch back to the business integration view.
  2. Double-click Assembly Diagram to open it. You will see a default mediation component has been added for you. Click on it and select Delete. The assembly diagram will now be empty.
  3. Right-click the diagram, then select Add => Import. Click on the name to select it, and enter a more meaningful name such as SendToMQ.
  4. The import has no interface yet. Make sure your import is selected, then click the Properties tab in the bottom right pane.
  5. Click the Details sub-tab, as Figure 7 shows. Right-click Interfaces, and select Add Interface.
  6. Select SendToMQ, then click OK. The icon for SendToMQ will now show an interface on its left side.
    Figure 7. Adding an interface to the import
    Adding an interface to the import
  7. The SendToMQ export now has an interface, but it does not have a binding. Right click SendToMQ and select Generate Binding => Message Binding => MQ Binding.
    Figure 8. Adding MQ binding
    Adding MQ binding
  8. Set the parameters for the MQ Binding, as Figure 9 shows. Be sure to use the host name of the computer you are running on, as well as the names of your queue manager and local queues. The Send Destination Queue is where the message will be sent from Process Server. The Receive Destination Queue is where the reply message will come back to. Select Serialized as XML for both the request and response type. The default data binding is automatically selected for you. Click OK after the parameters have been entered.
    Figure 9. MQ binding properties
    MQ binding properties
  9. The icon for SendToMQ will now have a small icon on the left indicating that it has MQ binding.
  10. Add an export to the module. Right-click the diagram and select New => Export. Click the import and type in a meaningful name such as MQSendExport.
  11. Connect MQSendExport to SendToMQ. The interface from the existing import will automatically be added to the export. Your assembly diagram should now look as the example shown in Figure 10.
    Figure 10. Completed assembly diagram
    Completed assembly diagram
  12. Save the assembly diagram. The project will build.
  13. Click the Server tab, ensure your server is started, then click your server and select Add and Remove Project. Select your project, click Add, then click Finish. The project will be deployed to your test server.
  14. Right-click the assembly diagram and select Test Module. Enter values for all of the data fields, and click Continue to run the test. Click Finish to deploy the test to the server.
  15. If no errors appear in the console, the message has been sent. You can use a tool such as RFHUtil from support pac IH03, available for download at : IH03: WebSphere Message Broker V6-Message display, test, and performance utilities, or a command line utility such as amqsget to browse the message from ADDRESSQ.
    Listing 4. Generated message.
    <?xml version="1.0" encoding="UTF-8"?>
    <custom:Generated xmlns:custom="http://CustomDataBindings">
      <custom:customer__number>1</custom:customer__number>
      <custom:customer__name>IBM</custom:customer__name>
      <custom:address__line__1>18000 W. Nine Mile Road</custom:address__line__1>
      <custom:address__line__2>11th Floor</custom:address__line__2>
      <custom:city>Southfield</custom:city>
      <custom:state>MI</custom:state>
      <custom:zip__code>48175</custom:zip__code>
      <custom:zip__code__plus4>1234</custom:zip__code__plus4>
      <custom:customer__discount__code>12</custom:customer__discount__code>
    </custom:Generated>
  16. Write the message back to SENDERQ. Remember to copy the message ID to the correlation ID, and to set the message type to reply, as Figure 11 shows.
    Figure 11. Setting attributes for the reply message
    Setting attributes for the reply message
  17. You should see a reply message from the request in the tester.

You have now proved out communication from Process Server to WebSphere MQ. Close the module tester. Click No when prompted about saving changes. Remove the application from the server, so you can make changes then deploy again later.

Using the generated data bindings

Now that your module can communicate with WebSphere MQ, it is time to test it out with the generated data bindings, so that a fixed message is created based on the COBOL copybook, rather than the XML used as a default.

  1. In the assembly diagram editor, select the import SendToMQ, then click the properties tab.
    Figure 12. Updating the method bindings
    Updating the method bindings
  2. Click the Binding tab as Figure 12 shows. The serialization types for the input and output are set to XML, as you had indicated when you defined the MQ bindings for the import. Update the input and output data serialization types to User Supplied, then click Browse to select CUSTOMERRECORDDataBinding that you previously generated.
  3. Type Ctrl-S to save the updates.
  4. A Jar file needs to be added to the build path in order to use the generated code. Right-click the module, and select Properties.
  5. Select Java Build Path, then select the Libraries tab. Click Add external JARs to select your jar. Navigate to the directory <WID Install Root>\wstools\eclipse\plugins\com.ibm.sal.ibmcics_6.0.2, then select the file mqcicsmediation.jar.
  6. The generated code includes a section to set up header information if you are sending to CICS. In this scenario CICS is not involved. Only the default header will be used. You can comment out some of the lines of code, so you do not get error messages about the header. In the section of code starting with "public void read", comment out or delete the lines from "If (headers.isEmpty()" to the second "}" after the else section, as Listing 5 shows.
    Listing 5. Commented lines
    //if (headers.isEmpty()
    //|| ((DataObject) headers.get(0)).getInt("value/returnCode") == 0) {
    //if (headers.isEmpty()) {
    //	String programName = input.readMQCHAR8();
    //	if (logger.isLoggable(Level.FINEST)) {
    //		logger.logp(Level.FINEST, CLASS_NAME, "read", VERSION
    //			.concat(" Response received from CICS program ")
    //					.concat(programName));
    //			logger.logp(Level.FINEST, CLASS_NAME, "read", VERSION
    //					.concat(" No CIH header received."));
    //		}
    //
    // } else {
    //	if (logger.isLoggable(Level.FINEST)) {
    //		String programName = ((DataObject) headers.get(0))
    //			.getString("value/programName");
    //		logger.logp(Level.FINEST, CLASS_NAME, "read", VERSION
    //			.concat(" Response received from CICS program ")
    //					.concat(programName));
    //	}
    // }
  7. Similarly, comment out or delete the lines starting from "} else if (((DataObject) headers.get(0)).getInt" through the ending "}".
  8. In the section "public void write", commend out or delete the lines from "if (headers.isEmpty()" through the closing "}" after the else section.
  9. Select Project then Clean to rebuild. After the build completes, add the project to the server.
  10. Start the module tester.
  11. Invoke the component as you did previously, with the same values.
  12. Get the message from ADDRESSQ. If using RFHUtil, select Character for the data type on the data tab. You will now see the fixed format message as listing 6 shows.
    Listing 6. Fixed format message.
    1    IBM    18000 W. Nine Mile    11th Floor    Southfield      MI481751234012
  13. On the data tab of RFHUtil, select COBOL for the data type. You will be prompted to also select the copybook file. You will now see the data matched with the fields, as Listing 7 shows.
    Listing 7. COBOL formatted message
    Level  Ofs  Len Type  Occ Variable Name                  Value
    01     0   160           CUSTOMER-RECORD
    05     0     6 CHAR      CUSTOMER-NUMBER      		1
    05     6    35 CHAR      CUSTOMER-NAME                  IBM
    05    41   116           CUSTOMER-ADDRESS-INFO
    10    41    40 CHAR      ADDRESS-LINE-1                 18000 W. Nine Mile
    10    81    40 CHAR      ADDRESS-LINE-2                 11th Floor
    10   121    25 CHAR      CITY                           Southfield
    10   146     2 CHAR      STATE                          MI
    10   148     5 CHAR      ZIP-CODE                       48175
    10   153     4 CHAR      ZIP-CODE-PLUS4                 1234
    05   157     3 NUMB      CUSTOMER-DISCOUNT-CODE         012
    Copy book size 160, Data area size 160
  14. Copy the message ID to the correlation ID (as you did before), and set the message type to Reply. Write the message to SENDERQ.
  15. The reply message will be processed, and you will see the resulting business object in the tester.

You have now sent and received an MQ message in a fixed format.

Summary

In this article, you learned about data bindings in WebSphere Process Server. You learned how to write a message to WebSphere MQ with defaut data bindings, as well as how you can generate and use custom data bindings based on a COBOL copybook.


Download

DescriptionNameSize
Custom data bindings zip for this articlesample.zip374KB

Resources

Learn

Get products and technologies

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into WebSphere on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=WebSphere, Business process management
ArticleID=265563
ArticleTitle=Creating custom data bindings in WebSphere Process Server without coding
publish-date=10312007