2 Configuring OracleAS Adapter for IMS/TM

This chapter describes how to configure Oracle Connect using Oracle Studio.

All modeling of Oracle Connect is performed using Oracle Studio. To use Oracle Studio, you first configure it to enable access to the IBM z/OS platform where IMS/TM runs.

This chapter contains the following topics:

• Setting Up the IBM z/OS Platform in Oracle Studio

• Securing Access to Oracle Connect

• Modeling Interactions for OracleAS Adapter for IMS/TM

• Viewing the XML Schema

• Creating XML Schemas

Note:

The following tasks assume you have permission to access the IBM z/OS platform and that the Oracle Connect daemon is running on this computer.

Check with the system administrator to ensure these requirements are fulfilled.

Setting Up the IBM z/OS Platform in Oracle Studio

Perform the following steps to configure the IBM z/OS, using Oracle Studio:

1. From the Start menu, select Programs, Oracle, and then select Studio.

2. Right-click Machines in the Configuration Explorer and select Add Machine The Add Machine screen is displayed (for more information, see Figure 2-1).

3. Enter the name of the computer you want to connect to, or click Browse to select the computer from the list of computers that is displayed and which use the default port (2551).

4. Specify the user name and password of the user who was specified as the administrator when Oracle Connect was installed.

   Note:

   Selecting Anonymous connection enables anyone having access to the computer to be an administrator.

   The Add Machine screen is shown in the following figure:

   Figure 2-1 The Add Machine screen

   
   

5. Click Finish.

   The computer is displayed in the Configuration Explorer.

Securing Access to Oracle Connect

Oracle Studio includes mechanisms to secure access to Oracle Connect both during modeling and during run time.

During modeling, the following security mechanisms can be applied:

• Setting Password Access to Oracle Studio

• Specifying Users with Administrative Rights

During run-time, client access to Oracle Connect is provided by the user profile:

• Setting Up Run-time User Access to the IBM z/OS Platform

Setting Password Access to Oracle Studio

Initially, any operation performed using Oracle Studio does not require a password. You can set a password so that the first operation that involves accessing the server from Oracle Studio requires a password to be entered.

Perform the following steps:

1. From the Start menu, select Programs, Oracle and then select Studio. Oracle Studio opens.

2. Select Window from the menu bar and then select Preferences.

   The Preferences screen is displayed, as shown in the following figure:

   Figure 2-2 The Preferences screen

   
   

3. Select the Studio node.

4. Click Change master password. The Change Master Password screen is displayed, as shown in the following figure:

   Figure 2-3 The Change Master Password screen

   
   

5. Leave the Enter current master password field empty and type a new master password.

6. Confirm the password.

7. Click OK.

Specifying Users with Administrative Rights

By default, only the user who was specified during the installation as an administrator has the authorization to modify settings on that computer from Oracle Studio. This user can then authorize other users to make changes or to view the definitions for a selected computer. Adding a computer to Oracle Studio is described in "Setting Up the IBM z/OS Platform in Oracle Studio".

Note:

The default during installation is to enable all users to be administrators.

Perform the following steps to specify a user with administrative rights:

1. From the Start menu, select Programs, Oracle, and then select Studio. Oracle Studio opens, displaying the Design perspective.

2. Right-click the required computer in the Configuration Explorer and select Administration Authorization.

   The Administration Authorization screen is displayed, as shown in the following figure:

   Figure 2-4 The Administration Authorization screen

   
   

   The screen has the following sections:

   Administrators: Administrators can view and modify all the definitions in Oracle Studio for the selected computer. On initial entry to Oracle Studio, every user is defined as a system administrator.

   Designers: Designers can view all the definitions for the computer in Oracle Studio and can modify any of the definitions under the Bindings and Users nodes for the selected computer. For example, Oracle Studio database administrator can add new data sources and adapters and can change metadata definitions for a table in a data source.

   Users: Users can view all the definitions for the computer in Oracle Studio for the selected computer. Regular users cannot modify any of the definitions.

3. Add users or groups of users by clicking Add User or Add Group for the relevant sections. The user or group that is added must be recognized as a valid user or group for the computer.

   Once a name has been added to a section, only the user or group that logs on with that user name has the relevant authorization.

Setting Up Run-time User Access to the IBM z/OS Platform

During run time, client access to Oracle Connect is provided by the user profile. A user profile contains name and password pairs that are used to access a computer, data source or application at run time, when anonymous access is not allowed.

1. In the Configuration view, expand the node of the computer for which you want to set the user name and password.

2. Expand the Users node.

3. Right-click the NAV user profile and select Edit User. The User Editor pane is displayed, as shown in the following figure:

   Figure 2-5 The User Editor pane

   
   

4. In the User editor, click Add to display the Add Authenticator screen.

5. Select Remote Machine from the Resource type list, as shown in the following figure:

   Figure 2-6 The Add Authenticator screen

   
   

6. Enter the name of the IBM z/OS computer defined in Oracle Studio.

7. Enter the name and password used to access the computer and confirm the password.

8. Click OK.

Modeling Interactions for OracleAS Adapter for IMS/TM

Modeling interactions for OracleAS Adapter for IMS/TM involves defining an Oracle Connect back-end adapter using Oracle Studio. All the definitions specified in Oracle Studio are written to the IBM z/OS platform.

This section contains the following topics:

• Setting Up an Oracle Connect Adapter

• Generating Outbound Interactions

Setting Up an Oracle Connect Adapter

To work with the Oracle Connect, you must set up an adapter definition on the IBM z/OS platform to handle the interactions to and from an IMS/TM transaction. You use Oracle Studio to specify these definitions.

Perform the following steps:

1. From the Start menu, select Programs, Oracle, and then select Studio.

2. In the Configuration Explorer, expand the node of the computer defined in "Setting Up the IBM z/OS Platform in Oracle Studio".

3. Expand the Bindings folder. The binding configurations available on this computer are listed.

4. Expand the NAV binding. The NAV binding configuration includes branches for data sources and adapters that are located on the computer.

5. Right-click Adapters and select New Adapter to open the New Adapter wizard.

6. Enter a name for the back-end adapter.

   Note:

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

7. Select IMS/TM as the back-end adapter type from the Type list as shown in the following figure:

   Figure 2-7 The New Adapter screen

   
   

8. Select Create event queue for the adapter.

9. Click Finish. The back-end adapter is added to the list and the definition opens for editing.

   Note:

   Other adapters that are displayed in the Type list are not supported with the version of Oracle Connect installed at the site.

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

    The Properties tab is shown in the following figure:

    Figure 2-8 The Adapter Properties tab

    
    

    The following table lists the properties for the IMS/TM adapter:

    Table 2-1 Adapter Properties

    Property	Description
    cachLastTpipe	Cache the last transaction pipe used.
    cacheXcfConnection	Cache the XCF connection information.
    maxSessions	The maximum number of sessions allowed. The default value is 5.
    racfGroupId	The RACF facility group identification.
    racfUserId	The RACF 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 requires metadata describing the adapter interactions, including the structures used to pass information to and from the adapter.

If COBOL copybooks describing the adapter input and output structures are available, then you can import the adapter definition using the Metadata Import wizard in Oracle Studio Design perspective to generate interaction metadata. If the metadata is provided in multiple COBOL copybooks with different filter settings (such as whether the first six columns are ignored or not), then you first import the metadata from copybooks with the same settings and later import the metadata from the other copybooks.

If COBOL copybooks describing the input and output structures are not available, then you must manually define the metadata.

The following information is required during the import procedure:

• The COBOL copybooks: These are copied to the computer running Oracle Studio as part of the import procedure.

• The names of the IMS/TM transactions to be executed through the application adapter.

Use the Metadata Import procedure to generate interaction metadata, as follows:

1. In the Configuration view, right-click the IMS/TM back-end adapter defined in "Setting Up an Oracle Connect Adapter".

2. Select Show Metadata View, to display the Metadata tab, with the IMS/TM back-end adapter displayed under the Adapters list.

3. Right-click Imports and select New Import. The New Metadata Import screen is displayed.

   Figure 2-9 The New Metadata Import screen

   
   

4. In the Import name field, enter a name for the import. The name can contain letters and numbers and the underscore character only.

5. Select ImsTm Import Manager from the Import type list.

6. Click Finish. The Metadata Import wizard is displayed.

7. Click Add. The Add Resources screen is displayed, which provides the option to select files from the local computer or copy the files from another computer.

8. If the files are on another computer, then right-click My FTP Sites and select Add. Optionally, double-click Add FTP site. The Add FTP Site screen is displayed.

9. Enter the server name or IP address where the COBOL copybooks reside and enter a valid user name and password to access the computer (if anonymous access is used, then click Anonymous connection) then click OK.

   The FTP site is added to the list of available sites as shown in the following figure:

   Note:

   The selected server is accessed using the user name as the high-level qualifier, enabling you to browse and transfer files.

   Figure 2-10 The Add Resources screen

   
   

10. Right-click the computer and select Set Transfer Type. Enter the transfer type (ASCII or BINARY) and click OK.

11. Expand the list of the added site until you find the necessary COBOL files. To change the high-level qualifier, right-click the computer and select Change Root Directory. Enter the new high-level qualifier enclosed in quotes, and click OK.

12. Select the required COBOL copybook file or files and click Finish. The selected file or files are displayed in the Metadata Import wizard.

    Note:

    You can import the metadata from one COBOL copybook and later add to this metadata by repeating the import procedure using different COBOL copybooks.

    The format of the COBOL copybooks must be identical. 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 type of case you must repeat the import procedure.

13. Click Next. The Apply Filters screen is displayed, as shown in the following figure:

    Figure 2-11 The Apply Filters screen

    
    

14. Apply filters to the copybooks, as needed.

    The following table lists the available filters:

    Table 2-2 Available Filters

    Filter	Description
    COMP_6 switch	The MicroFocus COMP-6 compiler directive. Specify either COMP-6'1' to treat COMP-6 as a COMP data type or COMP-6'2' to treat COMP-6 as a COMP-3 data type.
    Compiler source	The compiler vendor.
    Storage mode	The MicroFocus Integer Storage Mode. Specify either NOIBMCOMP for byte storage mode or IBMCOMP is for word storage mode.
    Ignore after column 72	Ignores columns 73 to 80 in the COBOL copybook.
    IgnoreFirst6	Ignores the first six columns in the COBOL copybook.
    Replace hyphens (-) in record and field names with underscores (_)	Replaces all hyphens in either the record or field names in the metadata generated from the COBOL with underscore characters.
    Prefix nested columns	Prefix all nested columns with the previous level heading.
    Case sensitive	Specifies whether to be sensitive to the search string case.
    Find	Searches for the specified value.
    Replace with	Replaces the value specified for Find with the value specified here

    
    

15. In the import wizard, click Next. The Add Interactions screen is displayed, as shown in the following figure:

    Figure 2-12 The Add Interactions screen

    
    

16. Click Add to add an interaction for the IMS/TM adapter. Provide the information, as listed in the following table:

    Table 2-3 Interaction Parameters

    Parameter	Description
    Name	The name of the interaction. You can change the default name specified.
    Mode	The interaction mode. You can select one of the following: sync-send-receive: The interaction sends a request and expects to receive a response. This is the default 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.
    Input	Identifies an input record. The input record is the data structure for the interaction. The records generated from the COBOL files specified at the beginning of the procedure are listed. 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, then the record specified here is ignored.
    Output	Identifies an output record. The output record is the data structure for the results of the interaction. The records generated from the files specified at the beginning of the procedure are listed. 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	IMS/TM specific parameters: c: The interaction commit mode. maxSegmentSize: The maximum size of the segment. The default value is 32768 (bytes). transaction: The name of the transaction that is executed when the interaction is executed. You must specify a transaction name for each interaction. The maxSegmentSize parameter enables dynamically splitting large messages into smaller segments. Although the default value can be changed, the logic of IMS/TM transaction must correspond accordingly. The transaction must perform a GU call followed by a series of GN calls to compile the entire input message. A transaction output message, larger than 32K, is handled by the OTMS C/I interface which performs the task of assembling the output segments into a single buffer.

    
    

17. Add as many interactions as necessary and click Next to go to the Mark first data field step.

    The Mark first data field page is displayed.

    Figure 2-13 Mark First Data Field

    
    

18. The COBOL copybooks for IMS transactions always begin with three fields that are provided by IMS. These fields should not be part of the metadata and they must be skipped in the import.

    In this step, you select the method for choosing first data field used for inputs and outputs. You can select one of the following:

    • Enter the number for the first input and output data fields: Select this and enter a line number for both the First input field and the First output field. The data at that line number is the first data used for the input or output.

    • Manually mark the first data field of the transaction following the LL ,ZZ and TRANSNAME fields: When you select this option, select the first line to use for the imports and outputs from the field below.

19. Click Next to open the Import Metadata step. For Do you want to transfer the medadata to the server?, click Yes to transfer the metadata from the Windows computer to the IBM z/OS computer and click Finish.

The metadata is imported based on the options specified and it is stored on the IBM z/OS platform. An XML representation of the metadata is also generated.

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

See Also:

Appendix A, "Advanced Tuning of the Metadata" for details about fine tuning the adapter metadata

Viewing the XML Schema

The XML schema describing the adapter interactions can be viewed by selecting the Source tab when you view the metadata as XML. For more information, see Appendix E, "Editing XML Files in Oracle Studio".

Creating XML Schemas

The XML schema describing the adapter interactions and the input and output records for these interactions are created automatically during the import procedure, as described in "Generating Outbound Interactions" .