IBM Resource Adapters

A resource adapter is a system-level software driver that a Java application uses to connect to an enterprise information system (EIS).

A resource adapter plugs into an application server and provides connectivity between the EIS, the application server and the enterprise application.


CICS ECI resource adapter

The Customer Information Control System External Call Interface (CICS ECI) resource adapter lets you access programs on CICS servers. Working with the external service wizard, the CICS ECI resource adapter creates services that invoke CICS transactions on a CICS server.

The aspects you must be familiar with conceptually are how to develop the CICS import with the external service wizard and the relationship of that import with the CICS adapter at run time.


Developing the CICS import

An import is a way of letting an application developed in IBM Integration Designer invoke a transaction on a CICS server. Creating the import involves using the external service wizard, which generates the import for you after you follow a sequence of steps. In these steps, you specify configuration information such as the RAR file to be used, the host name of the server, the userid and password, and so on. You then import a COBOL file of the program you want to invoke on the CICS server. Following another set of steps, the external service wizard generates the completed service for you.

Your CICS import results in outbound processing at run time. Outbound processing means the IBM Integration Designer application using the import invokes the transaction on the CICS server; that is, the IBM Integration Designer application initiates the action.


Relationship of the CICS import with the CICS adapter at run time

Your import is within a module containing your application. At run time when the CICS transaction needs to be invoked, the CICS adapter is used to invoke the COBOL program on the CICS server.

In more detail at run time, your application uses the import and then the CICS adapter to invoke the CICS transaction at the CICS server. The resulting data is passed back to the application.


Additional information about CICS

Several information centers, books and white papers are available to know CICS in detail. The CICS Transaction Gateway overview will help you understand the relationship between the CICS transaction gateway and a CICS server.

The following IBM Redbooks provide practical, detailed information on working with the CICS transaction gateway and CICS servers:

Programming information with respect to CICS and be found in these information centers.


Related concepts:

Examining and editing the properties of a CICS, IMS, or WOLA import


Related tasks:

Create a CICS import


Create a CICS import

The process of creating a CICS import from configuring the adapter to developing and generating the service is shown in this section.

Prerequisite: You should have access to a CICS server and COBOL program. In this example, a module already existed though you could alternately create the module in the final page of this wizard.

Use the external service wizard, you will follow the steps you would need to create a CICS import; that is, an import with an EIS binding intended to be used with a CICS RAR file.

  1. Right-click the module and from the menu select New > External Service. (Alternately, you could begin by opening the assembly editor and dragging a CICS outbound icon on to the canvas.) The External Service window opens. Select Adapters > CICS from the available types and click Next.
  2. The Select an Adapter page opens. Select ECIResourceAdapter with the RAR file version you want to use and click Next. The Adapter Import page opens with a connector project name, which you can change. The RAR file has already been discovered and is listed along with the runtime environment. Click Next.
  3. The Service Configuration Properties page opens. You can use a predefined JNDI name or specify the connection properties to the CICS server at this time. Click Next.
  4. The Operations page opens where you will define the operations for the import. Click Add to define an operation. In the Add Operation wizard, specify an operation name, an input type and, optionally, an output type. An input type can be an available one or a new one. In our case, we selected New. This opens the External Data Discovery window to the Business Object Mapping Details page.

    The different types of mappings available are listed as follows:

    • C to business object
    • C to business object (CICS Channel)
    • COBOL to business object
    • COBOL to business object (CICS Channel)
    • PL/I to business object
    • PL/I to business object (CICS Channel)

    Note that each language (C, COBOL or PL/I) has two choices for an input mapping. For an output mapping, there are three choices. The differences in these selections are as follows:

    • A language which will have one output value at run time
    • A language with CICS channel support. Traditionally, CICS programs have used communication areas (COMMAREAs) to exchange data. Channels and containers provide an improved method for transferring data between programs, in amounts that exceed the 32KB limit that applies to COMMAREAs. A container is a named block of data used to pass information between programs (it can be thought of as a named COMMAREA). Any number of containers can be passed between programs through the use of a channel.

    • For an output mapping only, there can be a language with multiple outputs, which means at run time one of the outputs will be selected to return a value.

    In our example, we chose COBOL to Business Object (CICS Channel). Then we clicked New and navigated to a COBOL file.

    Click Next.

  5. The Select Data Structures page opens. Platform and code page are already completed for you, but you can change them. The platform and properties specified here must be those of the target platform where the CICS transaction is running (z/OS , Windows, and so on). The defaults shown are taken from the preferences set for the COBOL importer in the preferences page. To see these preferences, from the menu select Window > Preferences > Importer > COBOL.

    Clicking Advanced reveals other fields you can change such as the floating-point format. Click Find beside the Data structures pane. The wizard returns the data structures in the COBOL file. Select the one you want. Click Finish.

  6. You are returned to the Business Object Mapping Details page. Our selection was in the Containers pane as we had selected CICS channel support. Click Next.
  7. The Generate Business Objects page opens. You can choose to change or create a new module at this point. The name of the generated business object will be the data structure name if you do not change it. Specifying a folder is recommended since otherwise all generated files will be in the root module folder, which will make them difficult to manage. Generation style, which in this case you will see if you select the container name, lets you choose several options that can shorten the length of the generated file names. A CICS channel name and container name must be specified. Click Finish to complete the generation of your business objects.
  8. The Operation page will let you add an output type at this point or let you choose to use the input type for output. In the case of a CICS channel selection like ours, the input and output must be the same. Click Finish when your operations have been defined.
  9. You are about to complete your service. In the Operations page of the External Service wizard, you may add more operations. The function name must be specified. It is the name of the program that will be run on the CICS server. You may also specify a maximum length for the commarea. Clicking Advanced provides other properties for you to override such as the timeout value. Click Next.
  10. The Generate Service page opens. You are at the point where you are about to generate your service. You can add a folder to contain the generated files. You must enter a service name. To have the RAR file deployed with the module, you can select a check box to do so. However, the preferred deployment method is to configure one instance on the application server. Click Finish.
  11. Your service is generated and added to the module. If you see a message asking to overwrite changes, click Yes.


IMS TM resource adapter

The IMS™ TM resource adapter is used by services to access IMS transactions running on host IMS systems. It can also be used for IMS transactions to access external services.

With the IMS TM resource adapter, you can build import components that run IMS transactions by using the SCA/SDO programming model. You can also imports to retrieve undelivered IMS transaction output. The aspects you must be familiar with conceptually are how to develop the IMS import with the external service wizard and the relationship of that import with the IMS TM resource adapter at run time.


Developing the IMS import

An import is a way of letting an application developed in IBM Integration Designer access enterprise information systems. Creating the import involves providing your IMS server security and connection information and specifying an existing COBOL, C, or PL/I program to invoke on the IMS server.

An IBM Integration Designer application that uses the import invokes the transaction on the IMS host system; that is, the IBM Integration Designer application initiates the action.

In addition to building import components, you can also create J2C Java™ code that accesses an IMS transaction by using the Java EE perspective and the J2C JavaBean programming model.


Relationship of the IMS import and the IMS TM resource adapter runtime component

Your IMS import is within a module that contains your application. At run time, when the application is invoked, it triggers the IMS TM resource adapter deployed on the Process Server to access and communicate with IMS transactions.


Additional information

For more information on the IMS TM resource adapter, see:


Related concepts:

Examining and editing the properties of a CICS, IMS, or WOLA import


Related tasks:

Create an IMS import


Create an IMS import

An IMS™ import is an import with an EIS binding intended to be used with an IMS TM resource adapter RAR file. The process of creating an IMS import involves configuring the adapter and generating the service.

To create an IMS import:

  1. In the Business Integration perspective, right-click the module to create an import for and select New > External Service. The New External Service window opens.

  2. Select IMS as the type of service to access and click Next.

  3. Select the version of the IMS TM resource adapter you want to use and click Next.

  4. Select IMS COBOL, PL/I or C based application, and click Next.

  5. Specify your security configuration properties setting:

    • If you choose Use predefined connection properties, the JNDI name and the J2C authentication data entry that you specified do not need to exist on the target server at this time. They can be created in a later step.

    • If you choose Specify connection properties, you must provide the TCP/IP host name and port number and the IMS data store name.

    For more information about connection properties, see IMS TM resource adapter information in the Information Management Software for z/OS Solutions Information Center.

    After you made your selection, click Next. The Add, Edit, or Remove Operations page opens. It is initially empty.

  6. Define the operations and the input and output for each operation on the Operations page. For each operation to create:

    1. Click Add to define an operation.

    2. Set the input and output types for the operation. The first time you use this page, there are no input types to choose from.

      1. Click New next to the Input type field. You are asked to provide details for the mapping.

      2. Select the mapping for the Choose mapping field based on your program.

      3. Click Browse and navigate to your program file.

      4. Click Next.

    3. In the Select Data Structures page, specify the data structure.

      1. For Platform, you must select z/OS for an import component that runs an IMS transaction.
      2. Code page is already completed for you. You can change it if your IMS data is in a code page other than US English (037).

      3. Click Advanced to reveal the default settings for the z/OS platform.

        • Most of the values can be accepted without change. However, because most IMS programs are compiled with the TRUNC(BIN) option, it is recommended that you change the value of the Trunc field to BIN.
        • The value for the Quote field might also differ, depending on your source file.

      4. In the Data Structures field, click Find. The wizard analyzes the data structures in the source program file and returns them to the pane.

      5. Select the data structure you want to work on and click Next. The Generate Business Objects page opens.

        • Specifying a folder is recommended because all generated files will be put in the specified folder rather than the root module folder. Having a specific folder makes it easier to manage the files.
        • The name for the XSD file by default is the data structure name if you do not change it.
        • Generation style lets you specify a variation of generated names, as indicated by the hover help.

      6. Click Finish to complete the specification of your operation.
      7. Repeat the steps for the other data structure, such as the output message, in this operation if necessary.

      • You can specify multiple output messages.

      • You can add more operations by repeating step 6.

  7. After an operation is created, you can view and set the interaction properties in the Operations page:

    1. Click an operation in the Operations pane. The interaction, request type, execution timeout, and commit mode properties display.

    2. Click Advanced to specify other properties. For a complete description of the properties of IMSInteractionSpec, see the IMS TM resource adapter information in the Information Management Software for z/OS Solutions Information Center.

    3. Click Next when you are finished specifying the properties. The Generate Service page opens.

  8. In the Generate Service page, you can specify a folder to contain the generated files.

    1. Enter the name of the folder.

    2. Enter a name in the Name field for the service you are creating.

    3. Click Finish.

    Your service is created and added to the module.


Integrating IMS MFS applications in BPEL processes

You use IBM Integration Designer to generate MFS-bases services and integrate them into Business Process Execution Language (BPEL) processes.

BPEL is an industry standard for specifying actions within business processes with web services. BPEL provides means to formally specify business processes and interaction protocols. A BPEL process implements a potentially long-running service through the use of more elementary services.


Operations and iterations of a conversation

For conversational IMS™ MFS applications to participate in BPEL processes, create an operation for each iteration in the conversation. The conversation ID (convID) must be passed to subsequent iterations. The last iteration must end the conversation if the conversation is not ended by the application.

Each iteration in a conversation is an operation in the BPEL process mediation flow. Each operation has an input and an output. Each input or output has a specific data type. For MFS applications, the data types are generated from the message input descriptors (MIDs) and message output descriptors (MODs) in your MFS source file. You then additional data types that contain information about the conversation ID (the value of the convID property) and whether the conversation has ended (indicated by the convEnded property value).

To demonstrate the concepts, assume that you have the following MIDs (IVTCBMI1_Page1 and IVTCBMI2_Page1) and MOD (IVTCBMO2) that are generated as data type business objects from the IMS phonebook sample. Assume that you are creating a mediation flow with three iterations, each with the following input and output:

Example of the iterations in a conversation and their input and output

Iteration (operation) Input Output
First iteration IVTCBMI1_Page1 IVTCBMO2
Second iteration IVTCBMI2_Page1 IVTCBMO2
Final iteration IVTCBMI2_Page1 IVTCBMO2

To start a conversation, the useConvID property must be set to true. In order to uniquely identify the conversation in all iterations, the conversation ID (the convID property) must be made available to the business context. In addition, subsequent iterations must be able to retrieve the convID value from the context. To end a conversation, the conversation ended (convEnded) property must be set to true. The property might be set by the client application, or when the last iteration is called.

The convID and convEnded are properties in the IMS interaction specification that are used to uniquely identify the conversation and to end the conversation. The new input and output for each of the iteration now contains additional information, as shown in the following table:

Additional fields for the input and output for each iteration

Iteration (operation) Input Output
First iteration IVTCBMI1_Page1 IVTCBMO2, convID
Second iteration IVTCBMI2_Page1, convID IVTCBMO2, convID, convEnded
Final iteration IVTCBMI2_Page1, convID IVTCBMO2, convEnded

The easiest approach to pass and receive this information is to create new data types (business objects) that hold the convID or convEnded information in addition to the input and output messages. For example, in the following table:

These new business objects are then defined as the data types for the input and output of each operation:

Additional fields for the input and output for each iteration

Iteration (operation) Input Output
First iteration IVTCBMI1_Page1 PersonOut (IVTCBMO2, convID)
Second iteration PersonIn2 (IVTCBMI2_Page1, convID) PersonOut (IVTCBMO2, convID, convEnded)
Final iteration EndConv (IVTCBMI2_Page1, convID) PersonOut (IVTCBMO2, convEnded)

After these new data types are defined, use custom mediation code to set the value of the convID and convEnded fields by retrieving the information from the context.



Custom mediation and transformations

For IMS™ MFS applications, add custom mediation code and context objects to set the convID and convEnded values and to store contextual information for some of the operations.


Mediation primitives and transformations

For MFS applications, you can use custom mediation under the transformation grouping to set or get the convID and convEnded properties. This custom mediation code is added by dragging a custom mediation object on to the canvas, wiring it, and then adding the code in the Details tab. In a request flow, the custom mediation is typically used to set the convID in the message before it is sent to the service provider at the end of the request flow. Business graphs are required for MFS conversational applications in order to dynamically set and get the useConvID, convID and convEnded conversational properties. These properties are set in the properties element of the business graphs. Because these are interactionSpec properties from the IMS TM resource adapter, the pattern for the property name used when you set or get these properties is ISinteractionSpec_property_name.

In a response flow, the custom mediation is typically used to get the convID and convEnded properties before it is sent to the service requester at the end of the response flow.


Custom mediation code

For the FirstIteration operation, add the following code to your custom mediation in the request flow. Set useConvID to true to initiate the conversation. Add this code to the Details area on the Properties tab. Modify the data objects based on the MIDs in your application. End the code with the out.fire(smo); statement. 

// Retrieve the business graph data object  1 commonj.sdo.DataObject body = smo.getDataObject("body");
// Modify the following data objects based on your application commonj.sdo.DataObject IVTCBMI1_obj = body.getDataObject("IVTCBMI1");
commonj.sdo.DataObject IVTCBMI1Input_obj = IVTCBMI1_obj.getDataObject("IVTCBMI1Input");

// Create the business graph's properties element commonj.sdo.DataObject prop_obj = IVTCBMI1Input_obj.createDataObject("properties");
// Set userConvID to true  2 prop_obj.setBoolean("ISuseConvID",true);
out.fire(smo); // propagate the service message object to the primitive that is wired to the 'out' terminal

You can determine the DataObject property names to use by examining the service message object details for the primitive. When you move the mouse pointer over the custom mediation node, an interface icon is displayed. Click the interface icon, and the details of the object is available in the Service Message Object Details section.

  1. Business object instances are represented by the commonj.sdo.DataObject interface. For more information about the commonj.sdo.DataObject classes and SDO programming, see the samples on the business process management samples and tutorials site at http://publib.boulder.ibm.com/bpcsamp/index.html.
  2. The conversation ID is assigned by IMS when the useConvID property is set to true. The EIS binding in the JCA framework expects the interactionSpec property names must begin with the prefix IS, followed by the property name.

For the FirstIteration operation, add the following code to your custom mediation in the response flow in order for the conversation ID info to pass correctly. Add this code to the Details area on the Properties tab. Customize the code based on your business object names and the field names that are used to store the convID and convEnded values. End the code with the out.fire(smo); statement. 

// Get ConvID and convEnded from the transient context commonj.sdo.DataObject context_obj = smo.getDataObject("context");
commonj.sdo.DataObject tran_obj = context_obj.getDataObject("transient");
commonj.sdo.DataObject prop_obj = tran_obj.getDataObject("properties");
String conv_id = prop_obj.getString("ISconvID");
String convEnded = prop_obj.getString("ISconvEnded");

// Set "convid" and "convEnded" into your business object commonj.sdo.DataObject body_obj = smo.getDataObject("body");
commonj.sdo.DataObject first_iteration_response_obj = body_obj.getDataObject("FirstIterationResponse");
commonj.sdo.DataObject output1_obj = first_iteration_response_obj.getDataObject("output1");
output1_obj.setString("convid", conv_id);
output1_obj.setString("convEnded", convEnded);
out.fire(smo); // propagate the service message object to the primitive that is wired to the 'out' terminal

See the Create a mediation flow topic for complete steps on how to mediate a MFS conversational application.


Transient context, correlation context, and shared context

The transient context, correlation context, shared context are user-provided business objects that are set at the input node of a mediation flow.



Related tasks:

convID property in the IMS interaction specification

convEnded property in the IMS interaction specification


Generating MFS SCA services

For an MFS application to be a service that business integration developer can integrate into a BPEL process in IBM Integration Designer, you must generate an MFS SCA service. To generate an SCA service for an MFS application, use the IMS™ TM resource adapter in IBM Integration Designer. The resource adapter takes an MFS source file as the input and generates the required information:

A business integration developer can create a mediation flow by using the generated output files.



Create a new external service from a conversational MFS application

You must first generate the required SCA service files from the MFS source file by creating a new external service.

  1. Select File > New > External Service. The New External Service window opens

  2. Select IMS from the list of available types.

  3. In the Select an Adapter screen, select the version of the IMS™ TM resource adapter for the environment.

  4. In the Select the Application Type screen, select IMS MFS-based application.

  5. Click Add and navigate to where your MFS conversational application is and click Next.

  6. Select the first discovered message input descriptor (MID) object, or the first operation, and add it to the selected object. In the next screen, you are asked to specify the configuration properties for the selected operation.
  7. Examine the auto-selected message output descriptor (MOD) object for the MID. Click Add to add any additional MODs.

    1. Click Add if there are multiple possible outputs.
    2. By default, the Generate business graph for conversation option is selected. For conversational MFS services, ensure that this option is selected. For non-conversational MFS services, clear this check box.

    3. Optionally, modify the namespace for generated business objects if a different namespace is preferred

    4. Click OK.

  8. Repeat the same steps for the second MID, or the second operation, until all operations are selected and generation properties are configured.

  9. Click Next when you are done selecting and configuring all MODs.

In the subsequent screens, you are asked to specify the service generation and deployment properties.

  1. Select Other under the Deployment Properties section.

    The security property is configured by using the Process Server administrative console, through the connection factory later.

  2. Clear the Join the global transaction option for the component to run in a new global transaction.

    By default, global transaction assumes two-phase commit. Because two-phase commit is not supported by MFS, always clear this option.

  3. For the connection settings field, select Use predefined connection properties.

  4. For JNDI lookup name, specify the JNDI name to match the JNDI name on the Process Server (for connections to IMS).

  5. Click Next. The Set the Location Properties page opens.

  6. In the Set the Location Properties page:

    1. Click New to create a module to contain the generated service.

    2. Specify a module name and click Next.

    3. Select the business object parsing mode and click Finish. You are back to the Set the Location Properties page.

    A default value for the name of the service is specified. This value is the name for the generated import component.

  7. Click Finish.

The service is generated.



Generated services

MFS SOA support generates business objects and corresponding business graphs from the MFS source file. Both are XML schema definition (XSD) files. Each complex type in the XSD file corresponds to a business object.

The business graph generated for each data type (or business object) has a suffix of BG. For example, the business graph for a data type called IVTCMBI1_Page1 would be IVTCMBI1_Page1BG. Both the business objects and business graphs are listed under the Data Types section.

The generated interface file is a WSDL interface file and is listed under the Interfaces section. You can see the content of the interface file by right-clicking the file and selecting Open With > Text Editor. The following sample shows the input type and output type for a generated interface called MFSEMDOutboundinterface. 

<?xml version="1.0" encoding="UTF-8"?>
<wsdl:definitions name="MFSEMDOutboundinterface" targetNamespace="http://ConvPB/MFSEMDOutboundinterface"
 xmlns:bons1="http://www.ibm.com/xmlns/prod/ims/mfs/sca/IVTCBMI1_Page1BG"
 xmlns:bons2="http://www.ibm.com/xmlns/prod/ims/mfs/sca/IVTCBMO2BG"
 xmlns:bons3="http://www.ibm.com/xmlns/prod/ims/mfs/sca/IVTCBMI2_Page1BG"
 xmlns:tns="http://ConvPB/MFSEMDOutboundinterface"
 xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
 xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <wsdl:types>
    <xsd:schema elementFormDefault="qualified" targetNamespace="http://ConvPB/MFSEMDOutboundinterface">
      <xsd:import namespace="http://www.ibm.com/xmlns/prod/ims/mfs/sca/IVTCBMI2_Page1BG" schemaLocation="IVTCBMI2BG.xsd"/>
      <xsd:import namespace="http://www.ibm.com/xmlns/prod/ims/mfs/sca/IVTCBMI1_Page1BG" schemaLocation="IVTCBMI1BG.xsd"/>
      <xsd:import namespace="http://www.ibm.com/xmlns/prod/ims/mfs/sca/IVTCBMO2BG" schemaLocation="IVTCBMO2BG.xsd"/>
      <xsd:element name="IVTCBMI1">
        <xsd:complexType>
          <xsd:sequence>
 1             <xsd:element name="IVTCBMI1Input" type="bons1:IVTCBMI1_Page1BG"/>
          </xsd:sequence>
        </xsd:complexType>
      </xsd:element>
      <xsd:element name="IVTCBMI1Response">
        <xsd:complexType>
          <xsd:sequence>
 2             <xsd:element name="IVTCBMI1Output" type="bons2:IVTCBMO2BG"/>
          </xsd:sequence>
        </xsd:complexType>
      </xsd:element>
      <xsd:element name="IVTCBMI2">
        <xsd:complexType>
          <xsd:sequence>
 3             <xsd:element name="IVTCBMI2Input" type="bons3:IVTCBMI2_Page1BG"/>
          </xsd:sequence>
        </xsd:complexType>
      </xsd:element>
      <xsd:element name="IVTCBMI2Response">
        <xsd:complexType>
          <xsd:sequence>
 4             <xsd:element name="IVTCBMI2Output" type="bons2:IVTCBMO2BG"/>
          </xsd:sequence>
        </xsd:complexType>
      </xsd:element>
    </xsd:schema>
  </wsdl:types>
  <wsdl:message name="IVTCBMI1RequestMsg">
    <wsdl:part element="tns:IVTCBMI1" name="IVTCBMI1Parameters"/>
  </wsdl:message>
  <wsdl:message name="IVTCBMI1ResponseMsg">
    <wsdl:part element="tns:IVTCBMI1Response" name="IVTCBMI1Result"/>
  </wsdl:message>
  <wsdl:message name="IVTCBMI2RequestMsg">
    <wsdl:part element="tns:IVTCBMI2" name="IVTCBMI2Parameters"/>
  </wsdl:message>
  <wsdl:message name="IVTCBMI2ResponseMsg">
    <wsdl:part element="tns:IVTCBMI2Response" name="IVTCBMI2Result"/>
  </wsdl:message>
  <wsdl:portType name="MFSEMDOutboundinterface">
    <wsdl:operation name="IVTCBMI1">
      <wsdl:input message="tns:IVTCBMI1RequestMsg" name="IVTCBMI1Request"/>
      <wsdl:output message="tns:IVTCBMI1ResponseMsg" name="IVTCBMI1Response"/>
    </wsdl:operation>
    <wsdl:operation name="IVTCBMI2">
      <wsdl:input message="tns:IVTCBMI2RequestMsg" name="IVTCBMI2Request"/>
      <wsdl:output message="tns:IVTCBMI2ResponseMsg" name="IVTCBMI2Response"/>
    </wsdl:operation>
  </wsdl:portType>
</wsdl:definitions>



Examining the files in Java EE view

You can examine the data bindings, XSD files, and import files from the Java™ EE view.

Business objects and business graphs are derived from a set of XSD files. There is not a one-to-one relationship between the number of XSD files and the number of business objects or business graphs.

  1. Switch to the Java EE view by selecting Window > Open Perspective > Other > Java EE.
  2. Double-click the service name ( ConvPB) and select gen/src > com.ibm.ims.mfs.emd.databinding.

    • The data binding Java files are location in this folder. These files are based on the SCA framework.
    • The XSD files are what define the business objects in the business integration perspective.
    • The import file is a file that has information about EIS system (such as IMS™) and connection information. This file contains the resource adapter name and the connection information. The resource adapter name must match the name of the IMS TM resource adapter that is installed through the Process Server administrative console. 
      <esbBinding xsi:type="EIS:EISImportBinding" dataBindingType="com.ibm.ims.mfs.emd.databinding.generator.MFSDataBindingGenerator">
 1    <resourceAdapter name="IMS TM Resource Adapter" type="com.ibm.connector2.ims.ico.IMSResourceAdapter" version="11.3.0">
      <properties/>
    </resourceAdapter>
 2    <connection target="<JNDI lookup>" type="com.ibm.connector2.ims.ico.IMSManagedConnectionFactory" interactionType="com.ibm.connector2.ims.ico.IMSInteractionSpec">
      <properties/>
    </connection>



Create a mediation flow

To create a mediation flow, create an operation for each iteration in the conversation. Include the convID and convEnded information in the input and output for each operation, and add custom mediation code to retrieve the convID and convEnded information from the context.

The following discussion provides the high-level description of the key steps to create a mediation flow for a conversational MFS application with multiple iterations of a conversation. For a detailed step-by-step sample, see Sample: Creating a mediation flow for a business process in the IBM Information Management Software for z/OS Solutions information center. This sample uses the conversational phone book application (the dfsivf34.mfs sample application that is shipped with IMS) to demonstrate the creation of mediation flow.

  1. Use the convID property to identify the conversation from iteration to iteration.

  2. Use the convEnded property to identify if the conversation has ended by the IMS™ application before the last iteration.
  3. To include convID or convEnded information with the input or output, create new data types (business objects) from the data types that were generated for this MFS service, with added fields to hold the convID or convEnded information.

  4. Create an operation for each iteration in your conversation. These operations must implement the interface you created for the mediation flow, with the input and output mapped to the appropriate data types that you created to hold the convID or convEnded information.

  5. Select the Operation Map as the mediation flow template.

  6. Use Transient Context to store information in a request and response flow of an iteration, such as the business graph information.

  7. Use Correlation Context to store information across a request and response flow of an interation, such as the convID.

  8. Add custom mediation code to retrieve the convID or convEnded information from the context, based on the JCA interactions specification.

  9. Add custom mediation code to end the conversation in the last iteration by setting the interaction verb to 3 (SYNC_END_CONVERSATION).



Related concepts:

Operations and iterations of a conversation

Custom mediation and transformations


WOLA resource adapter

Use the WebSphere optimized local adapter (WOLA), you can create and access services to exchange information with COBOL, PL/I, C, and C++ programs that run on Customer Information Control System (CICS ), IBM Information Management System (IMS™) transaction systems, and batch programs on z/OS .

From the New External Service wizard, you can use WOLA to create services that can make outbound calls from Process Server for z/OS to programs that run in an external address space on the same z/OS system.

WOLA provides high-performance interactions between business processes in Process Server for z/OS and the COBOL, PL/I, C, and C++ applications in external address spaces that run on the same z/OS system. These interactions are achieved using the shared memory between the processes and applications. Use WOLA when you target CICS, IMS, or batch programs that are local to the Process Server for z/OS.


Developing a WOLA import

Use an import, Process Server for z/OS invokes a service that is external to a business or mediation module. Using a WOLA import, Process Server for z/OS invokes a local CICS, IMS, or batch program that runs in an external address space using one of the native WOLA APIs Host Service or Receive Request.

Use the New External Service wizard in IBM Integration Designer, you can generate a WOLA import. Specify information such as the resource adapter to be used, security and connection properties, operations with input and output types and interaction properties, and the name and location for WOLA import service.


Use WOLA at run time

A WOLA import is created in an Integration Designer module. At run time, Process Server for z/OS uses the import and WOLA to invoke the local COBOL, PL/I, C, and C++ program. The resulting response data is returned.

Remember: WOLA must be installed on the server for use at run time. Embedding the resource adapter in an application is not supported.

IBM Redbooks article on WOLA

Washington System Center White Papers

developerWorks article

Plan to use optimized local adapters for z/OS

Use optimized local adapters for outbound support


Outbound calling using WOLA

The WebSphere optimized local adapter (WOLA) uses high-performance communication services called Local Comm to enable cross-memory transfers between the Process Server for z/OS and external address space programs.

A REGISTER API call registers the external address space with the Process Server for z/OS. During this call, the external application that runs in CICS or IMS, or as a batch server indicates the cell, node, and server the external application communicates with. The external application also provides a register name and information about the maximum number of established connections.

For outbound requests, the external address space applications must first use one of the native WOLA APIs Host Service or Receive Request and be identified as target services. On the connection factory, specify the register name and on the interaction specification, specify the service name. Process Server for z/OS uses these specifications to call the target service.

Use WOLA, business processes and services on Process Server for z/OS can call CICS or IMS transactions, or batch programs on z/OS.


Transactions, security, and connection properties for a CICS system

Use WOLA, business processes and services on Process Server for z/OS can call CICS programs.


CICS outbound calling

WOLA is implemented in CICS as a task-related user exit (TRUE) that provides the low-level connection code to cross-memory services. There are two ways of making outbound calls to applications in CICS:


Global transactions using WOLA

The WebSphere optimized local adapter (WOLA) supports global transactions in a two-phase commit process for Process Server for z/OS to CICS program invocations.

When calling into a CICS transaction from Process Server for z/OS using WOLA, an XA-capable transaction context is passed from Process Server for z/OS to CICS.

The WOLA CICS link server that runs in CICS must be started with the TXN=Y parameter so the link server can read the XA transaction context and create a unit of work to run the specified native language program. When Process Server for z/OS reaches a sync point or a commit point, XA protocol messages are exchanged between Process Server for z/OS and the WOLA link server. The link server drives the appropriate functions in the CICS OTS (OT) domain to complete the unit of work.

To use the global transaction capability when calling into a CICS transaction from Process Server for z/OS, use CICS Transaction Server for z/OS V4.1 or later. How WOLA propagates a transaction context is based on the settings of the WOLA CICS link server that runs inside CICS and the transaction attributes of the process application that runs inside Process Server for z/OS.


CICS security propagation

In CICS transactions, you can propagate the thread level user ID from Process Server for z/OS to CICS using the WOLA CICS link server, but you must start the link server with SEC=Y. When running in this mode, WOLA propagates the identity of the user on the current thread to CICS and the link server invokes a link invocation task using EXEC CICS START TRANSID('BBO#') USER(<userid>).

You must ensure the CICS SURROGAT SAF class is active and the user ID under which the link server runs has authority to issue START TRANSID for the propagated user ID. Alternatively, when the WOLA CICS link server runs with SEC=NO, all requests that are received in CICS from Process Server for z/OS run under the identity of the link server task, which is the ID of the user that started the link server.

In Process Server for z/OS, you may choose to use the security credentials that are already set on the thread, which by default is the user ID running the server, or you can set the credentials using a JAAS alias.


CICS connection properties

When creating the WOLA import and service, you must define the connection properties for the target CICS system.

In the New External Service wizard, on the Security and Configuration Properties page, specify the JNDI name of the connection factory defined on Process Server for z/OS or specify the connection properties for the CICS server to connect to. If you choose to specify the connection properties, then the managed connection factory is created during deployment with the specified properties. In both the cases, a connection property that must be specified for CICS is the target register name.

Define the connection factory on the server for easy changes by the administrator. You can share or reuse the same connection factory among many external services.

If the target program on the CICS system uses CICS containers and can be accessed using WOLA, then in the Security and Configuration Properties page under the CICS connection properties area, you must select CICS connection properties and select Use CICS containers to use CICS containers to communicate with the CICS link server. CICS programs that use containers can pass data that is larger than 32 KB.

To communicate with a COBOL, PL/I, C, or C++ program on a CICS system when using CICS containers, you must set the following properties:

Link invocation task transaction ID - Specifies the CICS transaction ID used to run the program link invocation task. The default transaction ID is BBO#. If the default transaction ID is changed, the CICS system programmer must ensure the transaction ID is defined properly in the target CICS regions. The transaction ID must be defined with the name of the WOLA CICS link invocation program, which is BBOACLNK.

For CICS programs, you must specify the name of the CICS program to invoke in the InteractionSpec Service name property for the selected operation in the New External Service wizard.


Transactions, security, and connection properties for an IMS system

Use WOLA, business processes and services on Process Server for z/OS can call IMS programs.


IMS outbound calling

For IMS (similar to CICS), you can call IMS transactions that use the WOLA link server using the native WOLA APIs (Host Service and Receive Request). Using the IMS Open Transaction Manager Access (OTMA) interface through WOLA, you can also call IMS transactions and drive them in IMS message processing regions or fast-path dependent regions. When you target IMS transactions using OTMA, you do not specify a register name in the connection properties.

WOLA does not support local or global transactions when invoking applications in IMS. All requests sent to IMS applications over WOLA run with Commit Mode 1 and Send-then-Commit. With this, OTMA defers the commit till the response message is sent.


IMS security propagation

For security propagation and assertion between the Process Server for z/OS and an IMS system, use WOLA over the OTMA interface. The Process Server for z/OS must be configured to run with the SyncToThread option enabled. Also, the IMS OTMA parameter OTMASE=FULL must be set. With these settings, the user ID under which the Process Server for z/OS application runs is propagated and asserted in the IMS message processing or fast-path dependent region where the transaction is dispatched. The security propagation and assertion between the Process Server for z/OS and the IMS system does not apply to IMS batch message processing regions.

In Process Server for z/OS, you may choose to use the security credentials that are already set on the thread, which by default is the user ID running the server, or you can set the credentials using a JAAS alias.


IMS connection properties

When creating the WOLA import and service, you must define the connection properties for the target IMS system.

In the New External Service wizard, on the Security and Configuration Properties page, specify the JNDI name of the connection factory defined on Process Server for z/OS or specify the connection properties for the IMS server in the binding. If you choose to specify the connection properties, then the managed connection factory is created during deployment with the specified properties.

Define the connection factory on the server for easy changes by the administrator. You can share or reuse the same connection factory among many external services.

When targeting an IMS transaction via OTMA then you must set the appropriate OTMA properties in the connection factory. In the binding, these are found under the IMS OTMA connection properties area in the Security and Configuration Properties page, where you must select IMS OTMA connection properties and select Use OTMA to set OTMA properties to call IMS transactions instead of using the native WOLA APIs.

To communicate with a COBOL, PL/I, C, or C++ program on a IMS system, you must set the following properties:

The value of the properties Request prefix style and Response prefix style should be LLZZ when targeting a COBOL, C, or C++ program. For a PL/I program, the value can be set to either LLZZ or LLLL.

For IMS transactions, when using WOLA over OTMA, the target transaction is embedded in the inbound message. You do not need to specify the InteractionSpec properties at the operation level.


Transactions, security, and connection properties for batch programs on z/OS

Use WOLA, business processes and services on Process Server for z/OS can call batch programs on z/OS.


Batch outbound calling

Outbound interactions with batch programs on z/OS are achieved using the native WOLA APIs (Host Service and Receive Request). WOLA does not support transactions for batch programs.


Batch security and connection properties

For outbound calls to batch server programs, the user ID of the batch job is used for requests from Process Server for z/OS. There is no identity propagation in this scenario.

In the New External Service wizard, on the Security and Configuration Properties page, specify the JNDI name of the connection factory defined on Process Server for z/OS or specify the connection properties for the batch program in the binding. If you choose to specify the connection properties, then the managed connection factory is created during deployment with the specified properties.

Define the connection factory on the server for easy changes by the administrator. You can share or reuse the same connection factory among many external services.

For batch programs on z/OS, you must specify the following information in the New External Service wizard:


Testing WOLA-enabled applications on a remote server

When creating the WOLA import and service using the New External Service wizard and when you call WOLA-enabled applications from a remote Process Server for z/OS , you must set the appropriate remote connection properties in your connection factory. This allows your WOLA import service on a distributed Process Server or on a non local Process Server for z/OS to remotely invoke a service. A remote EJB call is used from WOLA resource adapter on the remote server to a WOLA proxy EJB on the Process Server for z/OS. The WOLA proxy then invokes the target external service, accepts the response and returns it to the WOLA-enabled application on the remote server.

Set the remote connection properties in the connection factory specified by the JNDI name, or in the New External Service wizard, on the Security and Configuration Properties page under the Remote connection properties area, you must select Remote connection properties and select Use remote to perform remote testing.

To communicate with a COBOL, PL/I, C, or C++ program on the target system (CICS or IMS) from a remote Process Server for z/OS, you must set the appropriate connections properties in addition to the following remote properties:

Remember: For a remote connection, if you test your WOLA-enabled applications on a WebSphere Application Server for z/OS instead of Process Server for z/OS, then ensure that you are running both the distributed WebSphere Application Server for z/OS and the OLA proxy server for WebSphere Application Server for z/OS at version 8.0.0.3 or higher.

For more information about the remote properties, see Configure optimized local adapters in development mode on the local node.

For a successful remote connection, you may need to perform the following security administrative steps:

  1. Ensure the JNDI realm name is defined in the local application server the WOLA proxy EJB runs on. To set the JNDI name:

    1. Log on to the administrative console.

    2. Select Security > Global Security > CSIv2 Outbound Communications > Add external realm.

  2. Connect to the application server that runs the WOLA proxy EJB over an SSL-enabled connection, ensuring the local application server has retrieved and stored a valid signature certificate from the application server on z/OS.

    1. Log on to the administrative console for the proxy application server and select Security > SSL certificate and key management > Key stores and certificates > NodeDefaultTrustStore > Signer certificates, and then select retrieve from port.
    2. Provide the host name of the proxy server and the port number for an SSL-enabled port.


Defining operations for a WOLA service

You define the operations for a WOLA service in the Operations page in the New External Service wizard. When defining a set of operations for your service, group related programs. For each operation, specify the appropriate input and output types. If the output type can be one of several output data structures, then you can use the multiple possible outputs option while creating the output business object.

To create an operation, specify the appropriate mapping details for the business objects to be created in the New Business Object From External Data page. Select one of the following available mappings:

For example, if you select COBOL to Business Object, you must specify a COBOL program.

In the Select Data Structures page of the New External Service wizard, the properties available are according to the target platform (z/OS or non-z/OS) where the target program runs. By default for WOLA, the target Platform is set to z/OS. For a COBOL program, the default properties are according to the preferences set for the COBOL importer in the preferences page in IBM Integration Designer. To see these preferences, select Window > Preferences > Importer > COBOL. You can modify the default properties in the Select Data Structures page.

The Code page in the Select Data Structures page is set to IBM-037 by default. While setting the CICS connection properties if you set the Request container type property to CHAR, then the Code page must be set to UTF-8.

The name of the generated business object is the name of the data structure from the target program if you do not change it. Changing this name to be more meaningful would prevent conflicts when importing other business objects.

For CICS programs, you must specify the name of the CICS program to invoke in the InteractionSpec Service name property for the selected operation. For batch programs, you must specify the name of the batch program you want to invoke in the InteractionSpec Service name property.


Related concepts:

Configure the PL/I importer for a PL/I program on an IMS system


Configure the PL/I importer for a PL/I program on an IMS system

Depending on the prefix style the target PL/I program uses on an IMS transaction system, configure the PL/I importer.

The message prefix style used by PL/I programs can either be LLZZ (4 bytes in all) or LLLL (4 bytes) followed by ZZ (2 bytes). All other IMS programs such as COBOL, C, or C++ use a two-byte LL field. For the field lengths applicable for the various IMS programs, see IMS Input Message formats and contents.

To enable IMS support, configure the PL/I importer under IBM Integration Designer and convert the LLLL (4 bytes) field into LL (2 bytes). You must select the Enable IMS support option when working with the IMS TM resource adapter, but this selection is optional when working with WOLA.

When exchanging information between a WOLA external service and the target PL/I IMS program, you must specify the format for the message prefix style. For example, if you enabled IMS support for the PL/I program, use the LLZZ prefix style. However, if you did not enable the IMS support, use the LLLL prefix style with the appropriate field length so that WOLA correctly parses the message at run time and delivers it accordingly to IMS OTMA. The IMS Transaction Manager (TM) ensures that correct LLLL size is used when delivering the message to the PL/I IMS program.

When creating the WOLA import using the New External Service wizard, you can set the values for the request and response prefix styles under the IMS OTMA connection properties area which is under Advanced.

To configure the PL/I importer, choose one of the following methods:


Create a WOLA import and service

To invoke a local CICS , IMS™, or batch program that runs in an external address space from Process Server for z/OS , you must define a WOLA import and service. A WOLA import is an import with an EIS binding that is intended to be used with WOLA.

You must have access to the CICS, IMS, or batch server. You must also know the version of the RAR file used, the security and connection properties to be set depending on the transaction type, and the COBOL, PL/I, C or C++ program to be imported.

To create a WOLA import and service:

  1. Select File > New > External Service. Alternatively, you could open the Assembly editor and drag a WOLA import component onto the canvas. The New External Service wizard opens.

  2. From the available types, select Optimized Local Adapter for z/OS and click Next. The Select an Adapter page opens.

  3. Select WebSphere Optimized Local Adapter. When you select WebSphere Optimized Local Adapter, the minimum version of the RAR file, version 2, is also selected. This RAR file comes from WebSphere Application Server for z/OS 8.0.0.3.
  4. Continue through the wizard.


Related concepts:

Transactions, security, and connection properties for a CICS system

Transactions, security, and connection properties for an IMS system

Transactions, security, and connection properties for batch programs on z/OS

Testing WOLA-enabled applications on a remote server

Defining operations for a WOLA service

Examining and editing the properties of a CICS, IMS, or WOLA import


Examining and editing the properties of a CICS, IMS, or WOLA import

After a CICS, IMS, or WOLA import has generated its binding, you can examine and modify its properties. You can examine the created business objects and modify the properties of the import in various views and editors in the Business Integration perspective in Integration Designer.

Remember: You must have created a CICS, IMS, or WOLA import using the New External Service wizard in an Integration Designer module.

To examine the relationship of the business object to others, select the business object under Data under Assembly Diagram. The relationship of this business object with others appears in the References view. If the References view is not open, then right click the business object and select Show References in References view.

To examine the business object using the Business Object Editor, right click the business object and select Open With > Business Object Editor. The object opens in the editor. Selecting an item from the business object results in seeing lower level information in the Properties view.

To examine the interface, right click your interface under Interfaces and select Open With > Interface Editor. The relationship between the interface and the service is shown in the References view.

To examine or edit the binding properties, under Assembly Diagram, right click the created import and select Open. The import component appears in the assembly editor. Select the import and select the Properties view.

To add, update or remove operations in the import, under Assembly Diagram, right click the created CICS, IMS, or WOLA import and select Edit binding. Alternatively, you could select the import component from the Assembly editor canvas, right click and select Edit binding. The Operations page from the New External Service wizard opens. You can add new operations for the import, or edit or remove existing operations.


+

Search Tips   |   Advanced Search