Creating an import to retrieve undelivered IMS transaction output

Using the enterprise service discovery wizard, you create an import that retrieves undelivered Commit Mode 0 output from an IMS™ transaction.

This example also shows how to specify connection information for the managed connection used by the import component at the time the import component is created. The managed connection factory used by this import component is configured to create dedicated persistent socket connections. In addition, this example shows how to specify properties for IMSConnectionSpec. In particular, you are shown how to specify the clientID, the name of the TPIPE to which the undelivered messages were queued, and userID/password for component-managed EIS sign-on.

Prerequisite: In order for this example to run successfully the IMS installation verification transaction IVTNO must be run previously in such a way that undelivered Commit Mode 0 output messages from the transaction get queued to the TPIPE named LEILEI. This can be done by modifying the PhoneBook import component created in Creating an import using IMS, which will be shown in the first part of this set of tasks.

  1. Right-click PhoneBook and select Open. The assembly editor opens with the PhoneBookService import component on the canvas.
  2. Select sample/ims/PhoneBookService in the canvas of the editor. Select the Properties view.
  3. In the Binding section of the Properties view, select the Method Bindings tab and highlight the runPhonebook method. Make the following changes to the method bindings for runPhonebook:
    1. Set Commit mode to COMMIT_THEN_SEND (0)
    2. Set Execution timeout to 10 so that IMS will not have time to deliver the output message to IMS Connect. Another way of doing this is to stop the program corresponding to transaction IVTNO, then start the program after the import component has executed.
    3. Ensure Purge asynchronous output is not checked
    4. Check Reroute.
    5. Set Reroute name to LEILEI. Save your changes
      Setting up the InteractionSpec properties
  4. Run the PhoneBook module as shown in Testing an import created with IMS.
    Note: When you run the PhoneBook import component with the IMSInteractionSpec properties set as indicated above you will not receive the output of transaction IVTNO. Instead, you will receive the following message, indicating that the output message could not be delivered and will be queued to the TPIPE with name LEILEI.

    ICO0081E: com.ibm.connector2.ims.ico.IMSTCPIPManagedConnection@7852b692.processOutputOTMAMsg(byte[], IMSInteractionSpec, int) error. Execution timeout has occurred for this interaction. The executionTimeout value specified was [10] milliseconds. The value used by IMS Connect was [10] milliseconds.

  5. Create a module for your import component. From the menu, select File > New > Other. In the Select a wizard wizard, ensure Show All Wizards is checked. Scroll up and select Module and click Next. For this example, name the module PBReceiveAsync and select Finish.
  6. You already imported the IMS resource adapter for the PhoneBook module, so you can proceed to working with the enterprise service discovery wizard. Right-click your module and from the menu select New > Enterprise Service Discovery. In the Select an Enterprise Service Resource Adapter window, select IMS Connector for Java and click Next.
  7. The Resource Adapter Connection Properties page opens. For this example, select the Use the following connection properties radio button. Click the Show Advanced button, and provide the following:
    1. Leave the J2C Authentication Data Entry field blank, since this sample will use component-managed EIS sign-on.
    2. Provide a value for TCP/IP Host name that is appropriate for your environment.
    3. Provide a value for TCP/IP Port number that is appropriate for your environment.
    4. Ensure the Commit Mode 0 dedicated check box is selected so dedicated persistent socket connections will be created for use by your import component. A dedicated connection is required for the interaction that is used to retrieve the undelivered output.
    5. Provide a value for Data store name that is appropriate for your environment.
    6. Click Next.
  8. The Add Operations page opens. Click Add to define an operation and its input and output types. The Add operation wizard opens. In our example, we are retrieving undelivered output messages from the PhoneBook transaction IVTNO, so we will call our operation receiveAsyncPB. This page also requests the input and output information for the operation. Since you created these types in the previous IMS example, you could reuse them by clicking Browse. For this example, however, we will assume that there are no existing input and output types. Click New next to the Input type field. The Data Import page opens.
  9. Interactions used to retrieve asynchronously queued output are one-way interactions in that, unlike response mode IMS transactions that require an input and output message, only an output message is returned to the import component. The IMS resource adapter provides a null input message when executing interactions used to retrieve asynchronously queued output. However, the Add operation wizard requires both input and output types.
  10. On the Data Import page, select the mapping you want for the Choose mapping field, in our case COBOL to Business Object. Click Browse beside the COBOL file field and navigate to your COBOL file. 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.
  11. 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
  12. 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.
    Input properties
  13. 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.
  14. 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.
  15. 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.
  16. 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.
    Operation added
  17. The Add Operations page opens. The single operation, receiveAsyncPB is displayed as well as the properties of IMSInteractionSpec. For this example, provide the following values for the properties of IMSInteractionSpec, then click Next:
    • Select SYNC_RECEIVE_ASYNCOUTPUT_SINGLE_NOWAIT for Interaction verb
    • Select COMMIT_THEN_SEND (0) for Commit mode
    • Accept default values for all other properties

    Saving the operation
  18. 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 PBReceiveAsyncService. 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 the artifacts
  19. Your service is created and added to the module. Now you provide values for the properties of IMSConnectionSpec so you can create a dedicated persistent socket connection with clientID LEILEI and also use component-managed EIS sign-on.
  20. Right-click PBReceiveAsync and select Open. The assembly editor opens with the component on the canvas.
    Import component
  21. Select the service sample/ims/PBReceiveAsyncService in the canvas of the editor and then select the Properties view.
  22. You can access pages Description, Details, and Binding for the properties of the service. Select Binding.
  23. Select the Connection tab and expand Connection Spec Properties and add these values:
    1. A value for clientID. For this example, use LEILEI. This is the name of TPIPE to which the undelivered Commit Mode 0 output messages were queued.
    2. Values for userName and password appropriate for your environment. These values will be used by the import component for component-managed sign-on to IMS. The password is saved in this example. However, for security purposes in a more realistic scenario, you might choose to leave the field blank and have the user of the program enter it.
  24. Expand Authentication Properties, select Show Advanced and provide the following:
    1. Change the Res Auth value from the default, Container, to Application, since this example uses component-managed EIS sign-on.
    2. A J2C authentication data entry name is not provided, since we are not using container-managed EIS sign-on.
      Setting binding properties
  25. Save your changes and close the editor.
  26. You can now follow the instructions in Testing an import created with IMS to test your import component at the module level. You do not need to set up the test environment again, as you already did so previously. You simply need to test the module (Test > Test Module). Note that you do not need to provide any values in the Initial request parameters editor. For a SYNC_RECEIVE_ASYNCOUTPUT_SINGLE_NOWAIT interaction the IMS resource adapter provides a null input message. Select Continue.
  27. The result output will be the same as the previous result from testing a module in Testing an import created with IMS.
You have created an IMS service to retrieve undelivered IMS transaction output. 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 using IMS

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