3
Modeling Interactions for Oracle Application Server Integration Adapter for IMS/TM

Modeling interactions for Oracle Application Server Integration Adapter for IMS/TM involves defining Oracle Connect for IMS/TM using Oracle Studio. All the definitions specified in Oracle Studio are written to the OS/390.

This chapter contains the following sections:

• Setting Up Oracle Connect for IMS/TM

• Generating Outbound Interactions

• Generating Inbound Interactions

Setting Up Oracle Connect for IMS/TM

To work with Oracle Connect for IMS/TM, you need to set up an adapter definition on the OS/390 machine to handle the interactions to and from an IMS/TM program. You use Oracle Studio to specify these definitions.

Task: Setting Up the Adapter

1. On the machine where Oracle Studio is installed, from the Start menu, choose Start > Programs > Oracle > Studio > Studio.

2. In the Configuration Explorer, click the + next to the machine defined in "Configuring Oracle Connect for IMS/TM".

3. Click the + next to the Bindings node. The binding configurations available on this machine are listed.

4. Click the + next to the NAV binding node. The NAV binding configuration includes branches for data sources and adapters that are located on the machine.

   Caution: You must not delete the NAV binding configuration since it also contains Oracle Connect for IMS/TM system settings.

5. Right-click Adapters and choose New Adapter from the popup menu, to open the New Adapter wizard.

6. In the New window, enter a name for the backend adapter.

   Note: The name specified for the backend adapter is also the name specified setting up the delivery channel in Oracle Application Server ProcessConnect. For details see, "Setting Up the Delivery Channel".

   Note: The word event is a reserved word and cannot be used when naming an adapter.

7. Select IMS/TM as the backend adapter type from the Type drop-down list:

   

   Text description of the illustration 35a.gif

8. Check the Create event queue for the adapter checkbox.

   Note: Checking this box enables you to generate inbound interactions, as described in Generating Inbound Interactions.

9. Click Finish. The backend adapter is added to the tree and the definition opened for editing.

10. Select the Properties tab and change any of the properties for the backend adapter, as required.

    

    Text description of the illustration 35b.gif

    Property	Description
    maxSessions	The maximum number of sessions allowed. The default value is 5
    racfGroupId	The security facility group identification
    racfUserId	The security facility user identification
    tpipePrefix	The transaction pipe prefix used to associate between the transaction and the transaction pipe it is using. The default is ATTU
    xcfClient	The Cross System Coupling Facility client name
    xcfGroup	The Cross System Coupling Facility collection of XCF members to which the connection belongs. A group may consist of up to eight characters, and may span between multiple systems.
    xcfImsMember	The Cross System Coupling Facility group member

Generating Outbound Interactions

Oracle Connect for IMS/TM requires metadata describing the adapter interactions, including the structures used to pass information to and from the adapter.

Use the Metadata perspective in Oracle Studio to generate interaction metadata for the adapter.

• Task 1: Defining an Import Procedure

• Task 2: Generating Outbound Interactions

Task 1: Defining an Import Procedure

1. On the machine where Oracle Studio is installed, from the Start menu, choose Start > Programs > Oracle > Studio > Studio.

2. In the Configuration Explorer, click the + next to the machine defined in "Configuring Oracle Connect for IMS/TM".

3. Click the + next to the Bindings node. The binding configurations available on this machine are listed.

4. Click the + next to the NAV binding node.

5. Click the + next to the Adapters node.

6. Right-click the IMS/TM adapter defined in "Setting Up Oracle Connect for IMS/TM".

7. Choose Import from the popup menu, to open the Metadata Import perspective, with the IMS/TM adapter displayed under the Adapters list in the Metadata Import Explorer.

8. Right-click the IMS/TM adapter and choose New Import from the popup menu, to open the New Metadata Import wizard.

9. Enter a name for the import. The name can contain letters and numbers and the underscore character only.

10. Click Finish. The metadata import wizard opens in Oracle Studio.

    

    Text description of the illustration 17.gif

Task 2: Generating Outbound Interactions

After defining an import as described in the preceding task, the metadata import wizard opens in Oracle Studio. COBOL copybooks are used to create the metadata. The import wizard generates record structures, which are used for the input and resulting output for outbound interactions.

1. Click Add to add COBOL copybooks.

   A Select window opens. This window lists any files selected.

   

   Text description of the illustration ftp.gif

2. Click Add.

   The Add Resource window opens, which provides the option to select files from the local machine or FTP the files from another machine.

   

   Text description of the illustration 18.gif

3. If the files are on another machine, select the Import resource from remote machine option to start a file transfer process from the machine.

4. Click Next to open the File Transfer wizard.

   

   Text description of the illustration 19.gif

5. Enter the server name where the COBOL copybooks reside and, if not using anonymous access, enter a username and password to access the machine.

6. Click Next. The machine is accessed and the directory structure displayed, enabling you to browse to the files to be transferred.

   

   Text description of the illustration 20.gif

   You access the OS/390 machine at the high-level qualifier for the user name. To change the high-level qualifier, enter the name of the high-level qualifier in the Directory name field and click the Chg Root Dir button.

7. Navigate to the location where the files reside and select the files to be transferred and the transfer method (Text or Binary)

8. Click Next. A summary screen is displayed with details of what is going to be transferred.

9. Click Finish to start the transfer. The Select window is redisplayed with the list of transferred files.

   

   Text description of the illustration 21.gif

10. Select the files you want to use in the import and click OK.

    Note: You can import the metadata from one COBOL copybook and later add to this metadata by redoing the import using different COBOL copybooks. The format of the COBOL copybooks must be the same. That is, you cannot import a COBOL copybook that uses the first six columns with a COBOL copybook that ignores the first six columns. In this case, you must do separate imports.

    

    Text description of the illustration 22.gif

11. When you have completed adding the list of copybooks, click Next.

    

    Text description of the illustration 23.gif

12. Apply filters to the copybooks.

    The following filters are available:

    ignoreFirst6 - Ignore the first six columns in the COBOL copybook.

    ignoreFrom72 - Ignore columns 73 to 80 in the COBOL copybook.

    prefixNestedColumns - Prefix all nested columns with the previous level heading.

    In addition, you can specify a search string and the string that will replace this search string in the generated metadata, and whether the replacement is dependent on the case of the found string.

13. Click Next to apply the filter settings. The Add Interactions window opens.

    

    Text description of the illustration 24.gif

14. Click Add to add an interaction for the IMS/TM adapter.

    Interaction name - The name of the interaction.

    Mode - The interaction mode:

    • sync-receive - The interaction expects to receive a response.

    • sync-send - The interaction sends a request and does not expect to receive a response.

    • sync-send-receive - The interaction sends a request and expects to receive a response.

    Input - Identifies an input record. The input record is the data structure for the outbound interaction. The records generated from the COBOL programs specified at the beginning of the procedure are listed in a drop-down list. Select the relevant record for the interaction.

    Note: You must specify an input record for each interaction before you can click Next. If the interaction does not require an input record, the record specified here is ignored.

    Output - Identifies an output record. The output record is the data structure for the results of the outbound interaction. The records generated from the COBOL programs specified at the beginning of the procedure are listed in a drop-down list. Select the relevant record for the interaction.

    Note: You must specify an output record for the interaction if the mode is set to sync-send-receive or sync-receive, before you can click Next.

    Description - Free text describing the interaction.

    Interaction Specific Parameters - The name of the transaction that is called to execute the interaction.

    Note: You must specify a transaction name for each interaction.

15. Add as many interactions as necessary and then click Next.

    

    Text description of the illustration 25.gif

16. Click Next to generate the metadata definitions for the adapter.

    

    Text description of the illustration 26.gif

17. Specify that you want to transfer the metadata from the Windows machine to the OS/390 machine and click Finish.

The metadata is imported based on the options specified and it is stored on the OS/390 machine with the data source. An XML representation of the metadata is generated. This XML file can be viewed by expanding the Output node.

Text description of the illustration 33.gif

After performing the import, you can view the metadata in the Metadata perspective in Oracle Studio. You can also make any fine adjustments to the metadata and maintain it, as necessary.

See Also: "Interaction Metadata for the Adapter" for details about the adapter metadata

Generating Inbound Interactions

Inbound interactions are defined as events in Oracle Studio. When you defined the Oracle Connect for IMS/TM backend adapter with the Create event queue for the adapter box checked, as described in "Task: Setting Up the Adapter", an event adapter was defined automatically. The event adapter is defined with the same name as the backend adapter with the word event appended to it. The backend adapter and the event adapter are linked by Oracle Studio. You can jump from one adapter definition to the other by right-clicking the adapter or event in the Configuration Explorer list and choosing the Linked Event or Linked Adapter option respectively.

The event adapter requires metadata describing the inbound interactions, including the structures used to pass information to and from the adapter.

Use the Import Metadata perspective in Oracle Studio to generate interaction metadata for the adapter.

• Task 1: Defining an Import Procedure

• Task 2: Generating Inbound Interactions

Task 1: Defining an Import Procedure

1. On the machine where Oracle Studio is installed, from the Start menu, choose Start > Programs > Oracle > Studio > Studio.

2. In the Configuration Explorer, click the + next to the machine defined in "Configuring Oracle Connect for IMS/TM".

3. Click the + next to the Bindings node. The binding configurations available on this machine are listed.

4. Click the + next to the NAV binding node.

5. Click the + next to the Adapters node.

6. Right-click the IMS/TM adapter defined in "Setting Up Oracle Connect for IMS/TM".

7. Choose Linked Event from the popup menu, to jump to the event adapter.

8. Right-click the event adapter and choose Edit Event from the popup menu.

9. Select the Properties tab to add the names of Oracle Application Server ProcessConnect users who can retrieve inbound interactions and OS/390 users who can send inbound interactions.

10. To add Oracle Application Server ProcessConnect users, click the + next to the routers node and right click the users property to add the user.

    

    Text description of the illustration 50a.gif

11. Enter the name of the Oracle Application Server ProcessConnect user in the Value column for the item added.

12. To add OS/390 users, click the + next to the senders node and right click the users property to add the user.

13. Enter the name of the OS/390 user in the Value column for the item added.

14. Click the Save Editor Contents button to save the changes.

15. Right-click the event adapter in the Configuration Explorer and choose Import from the popup menu, to open the Metadata Import perspective, with the event adapter displayed under the Events list.

16. Right-click the event adapter and choose New Import from the popup menu, to open the New Metadata Import wizard.

17. Enter a name for the import. The name can contain letters and numbers and the underscore character only.

18. Select Event Queue Import Manager Using Cobol COPYBOOK Input Files for the Import Type.

    

    Text description of the illustration 51.gif

19. Click Finish. The metadata import wizard opens in Oracle Studio.

    

    Text description of the illustration 52.gif

Task 2: Generating Inbound Interactions

After defining an import as described in the preceding task, the metadata import wizard opens in Oracle Studio. COBOL copybooks are used to create the metadata. The import wizard generates record structures, which are used for the record structures for inbound interactions.

Note: The generation of inbound interactions involves similar steps to the steps described to generate outbound interactions. For details, see "Task 2: Generating Outbound Interactions".

1. Click Add to add COBOL copybooks.

   A Select window opens. This window lists any files selected.

2. Click Add.

   The Add Resource window opens, which provides the option to select files from the local machine or FTP the files from another machine.

3. If the files are on another machine, select the Import resource from remote machine option to start a file transfer process from the machine.

4. Click Next to open the File Transfer wizard.

5. Enter the server name where the COBOL copybooks reside and, if not using anonymous access, enter a username and password to access the machine.

6. Click Next. The machine is accessed and the directory structure displayed, enabling you to browse to the files to be transferred.

   You access the OS/390 machine at the high-level qualifier for the user name. To change the high-level qualifier, enter the name of the high-level qualifier in the Directory name field and click the arrow button.

7. Navigate to the location where the files reside and select the files to be transferred and the transfer method (Text or Binary)

8. Click Next. A summary screen is displayed with details of what is going to be transferred.

9. Click Finish to start the transfer. The Select window is redisplayed with the list of transferred files.

10. Select the files you want to use in the import and click OK.

    Note: You can import the metadata from one COBOL copybook and later add to this metadata by redoing the import using different COBOL copybooks. The format of the COBOL copybooks must be the same. That is, you cannot import a COBOL copybook that uses the first six columns with a COBOL copybook that ignores the first six columns. In this case, you must do separate imports.

    

    Text description of the illustration 53.gif

11. In the metadata import wizard, click Next after you have completed adding the list of copybooks.

    

    Text description of the illustration 23.gif

12. Apply filters to the copybooks.

    The following filters are available:

    ignoreFirst6 - Ignore the first six columns in the COBOL copybook.

    ignoreFrom72 - Ignore columns 73 to 80 in the COBOL copybook.

    prefixNestedColumns - Prefix all nested columns with the previous level heading.

    In addition, you can specify a search string and the string that will replace this search string in the generated metadata, and whether the replacement is dependent on the case of the found string.

13. Click Next to apply the filter settings. The Add Events window opens.

    

    Text description of the illustration 54.gif

14. Click Add to add an interaction for the IMS/TM adapter.

    Interaction name - The name of the interaction.

    Mode - The interaction mode:

    async-send - The inbound interaction sends a request and does not expect to receive a response.

    Input - Identifies an input record. The input record is the data structure for the inbound interaction. The records generated from the COBOL programs specified at the beginning of the procedure are listed in a drop-down list. Select the relevant record for the interaction.

    Note: You must specify an input record for each interaction before you can click Next.

    Output - For internal use. You cannot specify a value for this field.

    Description - Free text describing the interaction.

15. Add as many interactions as necessary and then click Next.

    

    Text description of the illustration 25.gif

16. Click Next to generate the metadata definitions for the adapter.

    

    Text description of the illustration 26.gif

17. Specify that you want to transfer the metadata from the Windows machine to the OS/390 machine and click Finish.

The metadata is imported based on the options specified and it is stored on the OS/390 machine. An XML representation of the metadata is generated. This XML file can be viewed by expanding the Output node.

After performing the import, you can view the metadata in the Metadata perspective in Oracle Studio. You can also make any fine adjustments to the metadata and maintain it, as necessary.

See Also: "Interaction Metadata for the Adapter" for details about the adapter metadata