3
Modeling Interactions for Oracle Application Server Integration Adapter for VSAM

Modeling interactions for Oracle Application Server Integration Adapter for VSAM involves defining the data source and an Oracle Connect for VSAM backend adapter using Oracle Studio. All the definitions specified in Oracle Studio are written to the OS/390.

This chapter contains the following sections:

• Setting Up the VSAM Data Source

• Importing Metadata for the VSAM Data Source

• Setting Up an Oracle Connect for the VSAM Backend Adapter

• Generating Outbound Interactions

• Generating Inbound Interactions

Setting Up the VSAM Data Source

Oracle Connect for VSAM requires you to specify the VSAM data source as the first step in setting up the adapter.

Task: Adding the VSAM Data Source Definition

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 VSAM".

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 VSAM system settings.

5. Right-click Data sources in the Configuration Explorer and choose New data source from the popup menu, to open the New data source wizard.

6. In the New window, enter a name for the VSAM data source. The name can contain letters and numbers and the underscore character only.

7. Change the Type field as follows:
   • If you are accessing VSAM data under CICS, select VSAM (CICS)

   • If you are accessing VSAM data directly, select VSAM

     Note: Only use the VSAM option to connect directly to the VSAM data in the following circumstances: The VSAM records are not managed by CICS The VSAM records are required for read only purposes and changes to the data buffered by CICS while reading the data are not expected.

     

     Text description of the illustration 10.gif

8. Click Next.

9. Enter the Data source connect string, as follows:

   If you chose VSAM (CICS), the following window opens:

   

   Text description of the illustration 11.gif

   where:

   CICS Application ID - The VTAM applid of the CICS target system. The default value is CICS. This parameter is used when updating VSAM data. You can determine this value by activating the CEMT transaction on the target CICS system. On the bottom right corner of the screen appears the legend APPLID=target_system.

   Transaction ID - The mirror transaction within CICS that receives control through MRO, which transfers the transaction from the Oracle Connect for VSAM environment to CICS. The default value is EXCI.

   VTAM NetName - The VTAM netname of the specific connection being used by EXCI (and MRO) to relay the program call to the CICS target system. For example, if you issue to CEMT the following command:

   CEMT INQ CONN
   
   

   you see on the display screen that the netname is BATCHCLI (this is the default connection supplied by IBM upon the installation of CICS). The default value is ATYCLIEN.

   Program Name - The UPDTRNS program that is supplied by Oracle Connect for VSAM to enable updating VSAM data.

   See Also: "VSAM Running Under CICS" for details about the adapter metadata

   Trace Queue - The name of queue for output which is defined under CICS when tracing the output of the UPDTRNS program. When not defined, the default CICS queue is used.

   If you chose VSAM, the following window opens:

   

   Text description of the illustration 12.gif

   where:

   Data HLQ - The high-level qualifier where the data files are located. If a value is not specified in this field, the data files are written to the DEF high-level qualifier where Oracle Connect for VSAM is installed.

   Disk Volume name - The high-level qualifier (volume) where the data resides.

10. Click Finish.

The data source you just defined now appears in the Configuration Explorer list.

Importing Metadata for the VSAM Data Source

Oracle Connect for VSAM requires metadata describing the VSAM data source records and the fields in these records.

Use the Import Metadata perspective in Oracle Studio to import metadata for the VSAM data source from COBOL copybooks, which describe the data. To import the metadata involves the following tasks:

• Task 1: Defining an Import Procedure

• Task 2: Generating Metadata for the VSAM Data

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 VSAM".

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 Data sources node.

6. Right-click the VSAM data source defined in "Setting Up the VSAM Data Source".

7. Choose Import from the popup menu, to open the Metadata Import perspective, with the VSAM data source displayed under the data sources list in the Metadata Import Explorer.

8. Right-click the VSAM data source 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.

   Note: The New import window is the same for both the VSAM imports (VSAM under CICS and direct), with the exception of the Import Type value.

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

    

    Text description of the illustration 17.gif

Task 2: Generating Metadata for the VSAM Data

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.

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

    The files selected are displayed in the wizard. In the Metadata Import Explorer the files used for the input and created for the output can be seen under the Input and Output nodes respectively.

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.

14. The records that are identified in the COBOL copybooks are displayed. You can select the records you want to import.

    

    Text description of the illustration 24.gif

15. Select the records to import and click Next.

    The import manager identifies the names of the records in the COBOL copybooks that will be imported as tables. If the names are unique, the following window is displayed:

    

    Text description of the illustration 25.gif

    However, if there are multiple records with the same name, the following window is displayed:

    

    Text description of the illustration 25a.gif

    In this case you have to specify a table name you want to use for each of the names displayed, according to the COBOL copybook where the record is defined.

16. Click Next.

17. The next step is different, depending on whether the VSAMCICS Import Manager or the VSAM Import Manager is used.

    If the VSAMCICS Import Manager is used, specify both physical file name and the logical file name for each record listed.

    If the VSAM Import Manager is used, specify the physical file name for each record listed, including the high-level qualifiers.

18. Click Next.

19. The OS/390 machine must be accessed to retrieve information to build metadata about the indexes.

    

    Text description of the illustration 28.gif

    If you try to build the indexes and the step fails for any reason (such as the OS/390 machine is temporarily not accessible), a warning message similar to the following message is issued and you continue to the next step.

    

    Text description of the illustration 29.gif

    Click Continue to go to the next step.

    Note: If the indexes are not generated, you can define them manually in the Metadata perspective of Oracle Studio. For details, refer to "Metadata for the VSAM Data Source".

20. The next step (Assign Index File Names) applies only if the VSAM under CICS Import Manager is used.

    

    Text description of the illustration 30.gif

    For each table listed, specify next to the alternate indexes for the table the logical file name for the index.

21. Click Next.

    

    Text description of the illustration 31.gif

22. Click Next to generate the metadata.

    

    Text description of the illustration 32.gif

23. 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: "Metadata for the VSAM Data Source" for details about the data source metadata

Setting Up an Oracle Connect for the VSAM Backend Adapter

To work with Oracle Connect for VSAM, you need to set up an adapter definition on the OS/390 machine to handle the interactions to and from VSAM. 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 VSAM".

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.

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 adapter.

   Note: The name specified for the 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 the Database 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 Adapter is added to the tree and the definition opened for editing.

10. Select the Properties tab.

    

    Text description of the illustration 35b.gif

11. Set the following properties for the adapter:

    Property	Value	Description
    connectString	-	For internal use only
    defaultDatasource	ds_name For example, VSAM_DATA	The name of a data source in the binding configuration defined in "Setting Up the VSAM Data Source"
    multipleResults	true	For internal use only

    Note: You must specify the VSAM data source name for the defaultDatasoure property.

Generating Outbound Interactions

Oracle Connect for VSAM 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: Setting Up the Metadata Perspective

• Task 2: Generating Outbound Interactions

• Task 3: Modifying the Generated Outbound Interactions

Task 1: Setting Up the Metadata Perspective

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 VSAM".

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 Oracle Connect for VSAM backend adapter defined in "Setting Up an Oracle Connect for the VSAM Backend Adapter".

7. Choose Edit metadata from the popup menu, to open the Metadata perspective, with the VSAM adapter displayed under the adapters list.

Task 2: Generating Outbound Interactions

1. In the Metadata perspective, right-click the Interactions node and choose New from the popup menu, to open the New Interaction wizard.

   The New Interaction wizard opens with two options displayed, to create interactions:

   • Automatic - Four interactions are generated for each VSAM table enabling the following SQL to be executed:

     SELECT

     INSERT

     UPDATE

     DELETE

   • Manual - One interaction is generated, based on the type of SQL selected: Database Query (a SELECT statement) or Database Modification (an INSERT, UPDATE or DELETE statement).

     Note: VSAM does not support the stored procedure option.

   It is recommended that you choose the automatic mode to create interactions.

   

   Text description of the illustration 39.gif

2. Click Next. The Select Tables window opens, enabling you to add tables from the VSAM data source that you want to access with the interaction.

   

   Text description of the illustration 43.gif

3. Click Add to add tables.

   The data sources that have been defined and all the tables, for each data source, that have had metadata defined for them are displayed.

   Select the tables that you want to access with the interaction and click the right arrow to move these tables into the right pane.

   

   Text description of the illustration 44.gif

4. Click Finish. The selected tables are displayed.

   

   Text description of the illustration 45.gif

5. Click Finish. Four interactions are generated for each table selected, together with the record structures to support the interactions and the responses from the VSAM data source.

   

   Text description of the illustration 46.gif

6. Click Yes to complete the task. The interactions and the record structures that relate to the interactions are displayed in the Metadata perspective.

   

   Text description of the illustration 47.gif

The SQL used in the interactions can be modified to the exact application requirements using the Metadata perspective, as described in "Task 3: Modifying the Generated Outbound Interactions".

Task 3: Modifying the Generated Outbound Interactions

You can modify the interaction definitions to the exact requirements of the application in the Metadata perspective. The following example uses the DELETE interaction generated in the previous task to describe how the interactions can be modified.

1. In the Metadata perspective, right-click the interaction to modify and choose Edit Metadata from the popup menu.

   

   Text description of the illustration 48.gif

   The adapter metadata editor opens, displaying the Interaction General tab.

   

   Text description of the illustration 49.gif

   The Interaction General tab displays general information about the way the interaction is executed. You can add a description of the interaction and define the mode of operation for the interaction. The following modes are available:

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

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

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

   The information for a request is passed in the input record. The information for the response from the VSAM data source is passed in the output record.

2. Click the Interaction Advanced tab to display specific information about the interaction.

   

   Text description of the illustration 49a.gif

   As, required, change the SQL and the parameters associated with the SQL.

   Parameters are specified in a SET clause or in a WHERE clause with the following format:

   :parameter_name
   
   

3. Dependent on the changes made to the SQL, when you close the editor, or click the Save button, the Context Selection window opens.

   

   Text description of the illustration 49b.gif

   Specify the adapter from the list and check the Update interaction-related records checkbox. Any changes that need making to the record structures in the schema part of the metadata are done automatically.

   Note: The interaction records are built based on all the fields in the table and cannot be changed manually, even if you change the SQL so that less fields are involved.

   Note: Modifying interactions is the same as described above, which uses a DELETE SQL statement, for all types of SQL statements (INSERT, UPDATE, etc.).

   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 VSAM 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 VSAM".

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 VSAM adapter defined in "Setting Up an Oracle Connect for the VSAM Backend Adapter".

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 in "Task 2: Generating Metadata for the VSAM Data".

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 53a.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 VSAM 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 enter a value in this field.

    Description - Free text describing the interaction.

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

    

    Text description of the illustration 55.gif

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

    

    Text description of the illustration 56.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