Creating an import using IMS

Using the enterprise service discovery wizard, you create an import based on an IMS™ application. You are taken step by step through the generation of the import as well as shown how to test the import using the integration test client.

Prerequisite: This example uses IVTNO, one of the transactions used in IMS installation verification. Most IMS systems will include this transaction. If this transaction is not installed on your IMS system, and you wish to test the import component you create, contact your IMS system administrator and have it installed. In this example, a module already existed called PhoneBook though you could alternately create the module in the final page of the wizard.

You will follow the pattern you see in these steps when you create an import component for IMS. You can find a similar step-by-step example but with multiple outputs in the samples section.

For more information on the IMS resource adapter, see What is the IMS resource adapter?. However, remember that you are looking at this information from the Rational® Application Developer perspective. While in the WebSphere® Integration Developer, you are using different tools. Nevertheless, for reference material on IMS, the Rational Application Developer material can be helpful.

  1. Right-click the PhoneBook module and from the pop-up menu select New > Enterprise Service Discovery. The enterprise service discovery wizard opens. If you have not added the IMS resource adapter,
    1. Click Import Resource Adapter. The Connector Import wizard opens.
    2. Browse to the appropriate resource adapter from the file system and path. All resource adapters that come with the product are found in this path: <installdir>\Resource Adapters. In the case of IMS, only the JCA 1.5 IMS resource adapter is supported for use in the creation of import components, so you must select the RAR file in <installdir>\Resource Adapters\ims15.
    3. At this time, you may also select a particular name for the connector project, a specific target server, and specify that your selection be added to a particular EAR project. Deploying or not deploying the resource adapter in the module discusses why you might want to add and later deploy your resource adapter with a module. For this example, do not select Add module to an EAR project. Click Finish. If asked to change perspectives, select No.
      Importing the IMS resource adapter
  2. With your resource adapter added, return to the Select an Enterprise Service Resource Adapter page, select your resource adapter and click Next. You may occasionally need to wait a minute as your workspace is rebuilding in the background following the import. If you do not see your resource adapter, close the wizard, wait until the workspace has rebuilt, and then return to the enterprise service discovery wizard.
    Selecting the resource adapter
  3. The Resource Adapter Connection Properties page opens. You can choose between two types of managed connections. The differences are discussed in Using connection properties specified on a server or specifying them. For this example, select the Use connection properties specified on server radio button and specify eis/imsTarget for the JNDI Lookup Name and widNode/myAlias for the J2C Authentication Data Entry (the JAAS alias name). The connection factory with JNDI lookup name eis/imsTarget and the J2C authentication data entry with name widNode/myAlias may or may not exist on the target server at this time. For this example, they will be created in a later step.
    Specifying connection properties
    If you select Use the following connection properties, then you will need to provide, at a minimum, the TCP/IP Host name and Port Number and the IMS Data store name. This option is illustrated in Creating an import to retrieve undelivered IMS transaction output.
    Descriptions of these IMS connection properties can be found in Connection properties. As mentioned previously, remember that you are looking at this information from the Rational Application Developer perspective. Complete the information and click Next.
  4. The Add Operations page opens. It is initially empty.
    Add operations page
  5. Click Add to define an operation and its input and output types. The Add operation wizard opens. In our example, we are creating an import component for the IMS transaction, IVTNO. This transaction processes an IMS database containing phone book data using commands DISPLAY, ADD, DELETE, and UPDATE. For this example we will define a single operation called runPhoneBook, which contains the command to be executed as part of its input message. You will need to specify an input and an output for your operation.
    Adding an operation
    This page also requests the input and output types for the operation. The first time you use this page, there will not be any input types to choose from. Click New next to the Input type field. The Data Import page opens.
  6. The Data Import wizard requests the type of mapping you want and the source file. Select the mapping you want for the Choose mapping field, in our case COBOL To Business Object.
    Importing the source file
    Click Browse beside the COBOL file field and navigate to your COBOL file. Click Next.
    We used the following COBOL code for our particular example:
    01  INPUT-MSG.
                02  IN-LL          PICTURE S9(3) COMP.
                02  IN-ZZ          PICTURE S9(3) COMP.
                02  IN-TRCD        PICTURE X(10).
                02  IN-CMD         PICTURE X(8).
                02  IN-NAME1       PICTURE X(10).
                02  IN-NAME2       PICTURE X(10).
                02  IN-EXTN        PICTURE X(10).
                02  IN-ZIP         PICTURE X(7).
            01  OUTPUT-MSG.
                02  OUT-LL       PICTURE S9(3) COMP VALUE +0.
                02  OUT-ZZ       PICTURE S9(3) COMP VALUE +0.
                02  OUT-MSG      PICTURE X(40) VALUE SPACES.
                02  OUT-CMD      PICTURE X(8) VALUE SPACES.
                02  OUT-NAME1    PICTURE X(10) VALUE SPACES.
                02  OUT-NAME2    PICTURE X(10) VALUE SPACES.
                02  OUT-EXTN     PICTURE X(10) VALUE SPACES.
                02  OUT-ZIP      PICTURE X(7) VALUE SPACES.
                02  OUT-SEGNO    PICTURE X(4) VALUE SPACES.
    Click Next
  7. The Importer page opens where you specify the data structure you will use. Platform and code page are already completed for you, but you can change them. For an import component that runs an IMS transaction, you must select z/OS® from the Platform drop-down list. Click Show 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 from STD to BIN. Other values might differ for your environment. For example, you might need to specify a different value for the Code page field if your IMS data is in a code page other than U.S. English (037). The value for the Quote field might also differ, depending on your COBOL source. Click Apply beside the Data structures field. The wizard analyzes the data structures in the COBOL file and returns them to the pane. Select the one you want. In our example, we selected INPUT-MSG for the input. Click Next
    Selecting input data structure
  8. The Saving Properties page opens specifying the names, styles and folder for the properties. Note that you can choose to change or create a new module at this point. Remember, at this point nothing has been generated. The name will be the data structure name if you do not change it, which in our case is INPUTMSG. Specifying a folder is recommended since otherwise all generated files will be put in the root module folder and it will be difficult to manage them. In this sample, use sample/ims. Generation style lets you specify a variation of generated names, as indicated by the hover help. Click Finish to complete the specification of your operation.
    Saving the operation's properties
  9. The wizard returns to the Add operation window. In this IMS example we will add an output type by selecting Specify an output type radio button and clicking New. We return to the Import page. Select the COBOL to Business Object mapping for the Choose mapping field. Click Browse beside the COBOL file field and navigate to the same COBOL file used above for the input message. Note that for output type multiple outputs are possible. Click Next.
    Importing the source file
  10. The Importer page opens. Select z/OS from the Platform drop-down list. Optionally, provide advanced properties. Click Apply beside the Data structures pane, then select OUTPUT-MSG and click Next.
    Selecting the output data structure
  11. The Saving Properties page opens specifying the names, styles and folder for the properties. Provide the same values for Module, Folder, and Generation Style as you provided for the input message. Click Finish to complete the specification of your operation.
    Saving the operation's properties
  12. The wizard returns to the Add operation wizard page. At this point you could add more output types but for the IMS transaction IVTNO one input and one output is sufficient. Click Finish.
    Complete operation specified
  13. The Add Operations page opens. You could at this point add some more operations. For this example, we will only use one operation, runPhoneBook. The InteractionSpec class is shown as well as the InteractionSpec properties. Clicking Show Advanced provides other properties you may want to specify.
    Saving your operation
    For a complete description of the properties of IMSInteractionSpec, see IMSInteractionSpec properties. As mentioned previously, remember that you are looking at this information from the Rational Application Developer perspective. For this example, we will accept all the default values. Click Next.
    Note: Depending on the maintenance level of the IMS resource adapter you are using you may have difficulty in entering values for the properties: Reroute name, LTERM name, and Map name. Ensure that you remove the blanks from these fields before entering your values.
  14. The Generate Artifacts page opens. You can specify a folder to contain the generated files, in our case sample/ims. You must enter a name in the Name field. In our case, enter PhoneBookService. At this point you can deploy the resource adapter with the module if you wish. Deploying or not deploying the resource adapter in the module discusses why you might want to deploy your resource adapter. In our case, do not deploy the IMS resource adapter with this module. Click Finish.
    Saving properties for the import component
  15. Your service is created and added to the module. Select your business object beneath Data Types. The relationship of this business object to others appears in the references view. Right-click a business object. From the pop-up menu select Open With > Business Object Editor. It opens in the editor. Selecting an item from the business object results in seeing lower level information in the properties view. Business objects from data structures provides more details on the properties view of business objects created by the wizard.
  16. Right-click your interface beneath Interfaces. From the pop-up menu, select Open With > Interface Editor. The interface opens in the interface editor. The relationship between the interface and the service is shown in the references view.
  17. Right-click the name of service you created, PhoneBookService, from the pop-up menu select Open. The assembly editor opens with an import component icon. EIS indicates that it is created from an application on an EIS system.
    Import component in assembly editor
  18. Select the import component. In the properties view, more details are provided. You can add or change the names and description provided. Select Details. More details are specified including the interface name, preferred interaction style - synchronous, asynchronous, or any - and the operations. Qualifiers tab may let you add a qualifier to the interface. A qualifier is a quality of service (QoS) addition you may be able to add to the interface; for example, a security level. However, it is determined by the creation of the service whether one or more are present and if you are permitted to add any yourself. The Event Monitor tab lets you monitor events at run time using the Common Event Infrastructure (CEI) property. For example, you might want to monitor how many times a transaction involving this service occurred. Event monitoring can be helpful in fine tuning an application. For example, if you monitored the transactions occurring it might point to a bottleneck at run time.
    Import component properties
  19. Select the Binding tab. The type of binding, the resource adapter, the managed connection factory class, data type and binding description are listed. Since a JNDI lookup name was specified in this example, the Connection section is empty as the server will contain the connection values. If the JNDI name was not specified then this example would contain the managed connection factory class and its properties, the Connection Spec class and its properties, the authentication and administration properties. The Resource Adapter section contains the resource adapter name and type. The Method Bindings section contains the interaction information. You can set IMSInteractionSpec values such as IMS request type and commit mode. Binding information fields are discussed in detail in Data bindings, function selector and generated properties.
  20. If you wish to test your component using the WebSphere test environment, see WebSphere test environment setup.
You have created an IMS service as an import component. You can find a similar step-by-step example but with multiple outputs in the samples section. Compare it with creating an import component using a PeopleSoft system.
Related concepts
Relationship of imports and exports to inbound and outbound events
Related tasks
Creating an import using PeopleSoft
Creating an export using PeopleSoft
Creating an import using CICS
Creating an import to retrieve undelivered IMS transaction output

Feedback
(C) Copyright IBM Corporation 2005, 2006. All Rights Reserved.