2 Installing and Configuring OracleAS Adapter for Tuxedo

Hardware Requirements

The following table summarizes the hardware requirements for Oracle Connect on a UNIX platform.

Software Requirements

The following table summarizes the software requirements for Oracle Connect.

Hardware Requirements

The following table summarizes the hardware requirements for Oracle Studio and Oracle Connect when OracleAS Adapter for Tuxedo runs on a Windows platform.

Software Requirements

The following table summarizes the software requirements for Oracle Studio or Oracle Connect when OracleAS Adapter for Tuxedo runs on the Windows platform.

Configuring the Oracle Connect Environment

When Oracle Connect is installed on a UNIX platform, using FTP, copy the brand.bin file, in the binary mode, from the Oracle Connect\Tuxedo Legacy Adapter directory in the installation CD to the OracleAS Adapter for Tuxedo computer, to NAVROOT/bin.

NAVROOT is the directory where Oracle Connect is installed.

Configuring the Tuxedo Environment for Oracle Connect

Verify that the following Tuxedo environment variables are correctly set:

• TUXDIR is set to the Tuxedo root directory.

• WSNADDR is set to OracleAS Adapter for Tuxedo network address.

• Check that the shared library environment variable (LD_LIBRARY_PATH, SHLIB_PATH under HP-UX and LIBPATH under IBM AIX) includes the path to the Tuxedo lib directory, as in the following example:

  LD_LIBRARY_PATH = /disk2/users/tuxedo/tuxedo8.0/lib
  

Configuring the Oracle Connect Script

The program that manages Oracle Connect server processes (nav_server) is accessed by a symbolic link to a file for the C-shell, Bourne and Korn shells.

To set up nav_server, perform the following steps:

1. In the bin directory, under the directory where Oracle Connect is installed, delete the existing link to nav_server using the following command:

   rm nav_server
   
   

2. In the bin directory, under the directory where Oracle Connect is installed, link to the required version of nav_server as follows:

   • C-shell: ln -s nav_server.csh nav_server

   • Bourne: ln -s nav_server.sh nav_server

   • Korn: ln -s nav_server.ksh nav_server

   
   

   Note: Instead of renaming files, use a symolic link.

   
   

The Oracle Connect nav_login procedure defines the default environment when OracleAS Adapter for Tuxedo runs. If you want site-dependent variables to be included in the environment, create a file called site_nav_login and save this file in the bin directory under the Oracle Connect root directory. nav_login runs site_nav_login automatically.

nav_login must be invoked to run Oracle Connect. It can be invoked from the user login script.

The command line for invoking nav_login varies according to the shell the user is running. The following table lists the different options for invoking the command line:

In the nav_login command, root represents the root directory of the Oracle Connect installation. After running the login procedure, the environment variable NAVROOT points to this root directory.

Ensure that users have Read and Execute permissions on the Oracle Connect files. Use the chmod command to change the permissions.

Starting the Oracle Connect Daemon

The Oracle Connect daemon must run on a server for client/server access to Oracle Connect. To start the daemon with the system startup, add the following command invoking the daemon to the end of the /etc/inittab file.

nv:3:once:navroot/bin/irpcd -l ip:2552 start >/dev/console 2>&1

In this command, the symbol navroot should be replaced with the directory where Oracle Connect is installed and ip replaced by the ip address of the computer.

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 to set password access to Oracle Studio:

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 window is displayed.

3. Expand the Studio node, as shown in the following figure.

   
   Description of the illustration prefer.gif
   
   

4. Click Change master password to open the Change Master Password screen.

5. In the Change Master Password screen, leave the Enter current master password field empty and type a new master password.

6. Confirm the new password.

7. Click OK.

Specifying Users with Administrative Rights

By default, only the user who was specified as an administrator during the installation is authorized to modify settings on that computer from Oracle Studio. The administrator can authorize other users to make changes or view the definitions for a selected computer. Adding a computer to Oracle Studio is described in "Configuring OracleAS Adapter for Tuxedo in Oracle Studio".

Using Oracle Studio, perform the following steps to specify users with administrative rights:

1. From the Start menu, select Programs, Oracle and then select Studio. Oracle Studio opens, showing 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.

   
   Description of the illustration admin.gif
   
   

   The screen has three sections:

   • Administrators: Administrators can view and modify all the definitions for the selected computer in Oracle Studio. 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 selected computer in Oracle Studio. Regular users cannot modify any of the definitions.

3. Add users or groups 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.

   
   

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

   
   

Configuring Run-Time User Access to OracleAS Adapter for Tuxedo

During runtime, 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 during runtime, when anonymous access is not allowed.

Perform the following steps to configure runtime user access to OracleAS adapter for Tuxedo:

1. In the Configuration Explorer, expand the node of the computer 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, as shown in the following figure. The NAV user profile editor is displayed

4. In the User editor, click Add to open the Add Authenticator screen, as shown in the following figure.

   
   Description of the illustration adduser.gif
   
   

5. Select the Remote Machine resource type.

6. Enter the name of the OracleAS Adapter for Tuxedo computer defined in Oracle Studio.

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

8. Click OK.

Configuring an Oracle Connect Adapter

To work with Oracle Connect, you need to configure the adapter definition on the platform where OracleAS Adapter for Tuxedo runs to handle the interactions to and from a Tuxedo service.

Perform the following steps using Oracle Studio to specify these definitions:

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 "Configuring OracleAS Adapter for Tuxedo in Oracle Studio".

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

4. Expand the NAV binding node. 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 to name an adapter.

   
   

7. Select Tuxedo as the back-end adapter type from the Type list, as shown in the following figure:

   
   Description of the illustration addtux.gif
   
   

8. Select Events to create an event queue for the adapter.

9. Click Finish. The back-end adapter is added to the adapters list and its 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.

   
   

Generating Outbound Interactions

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

If either BEA JOLT bulk loader file or Tuxedo configuration and FML or VIEW source files describing the adapter are available, you can import them using the Metadata Import wizard in Oracle Studio Design perspective to generate interaction metadata. If either BEA JOLT bulk loader file or Tuxedo configuration and FML or VIEW source files describing the input and output structures are not available, you need to manually define the metadata. For details of the metadata definition refer to Appendix A, "Advanced Tuning of the Metadata".

The following information is required during the import procedure:

BEA JOLT bulk loader file or Tuxedo configuration and FML or VIEW source files. These are copied to the computer running Oracle Studio as part of the import procedure.

Using Oracle Studio, complete the Metadata Import steps to generate interaction metadata, as follows:

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 "Configuring OracleAS Adapter for Tuxedo in Oracle Studio".

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

4. Expand the NAV binding node.

5. Expand the Adapters node.

6. Right-click the Tuxedo back-end adapter defined in "Configuring an Oracle Connect Adapter".

7. Select Edit Metadata to open the Metadata tab, with the Tuxedo back-end adapter displayed under the adapters list.

8. Right-click the Tuxedo back-end adapter and select New Import. The New Metadata Import screen is displayed.

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

10. Select the metadata import type. You can import the metadata either from a BEA JOLT file or from Tuxedo record definition files (FML or VIEW files).

    
    

    Note: A JOLT file consists of definitions of Tuxedo services along with the metadata, using the BEA JOLT Bulk Loader. FML and VIEW files are metadata files used by Tuxedo in conjunction with a configuration file that includes the Tuxedo services.

    
    

    For a JOLT file, select Tuxedo Import Manager Using Jolt Bulk Loader File. For FML or VIEW files, select Import Manager Using VIEW Files as shown in the following figure.

    
    Description of the illustration import1.gif
    
    

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

12. Click Add. The Select screen is displayed. This screen lists any files selected for use as input for the import.

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

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

15. Enter the name or IP address of the server where the JOLT bulk loader file or the FML or VIEW files reside and enter a valid username and password to access the computer (if anonymous connection is used, select Annonymous connection), then click OK.

    The FTP site is added to the list of available sites. The computer is accessed enabling you to browse and transfer files required to generate the metadata, as shown in the following figure.

    
    Description of the illustration import3.gif
    
    

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

17. Click the node of the added site and locate the necessary file. To change the root directory, right-click the computer and select Change Root Directory. Enter the root directory and click OK.

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

19. Click Next. The next step of the procedure depends on whether a JOLT file or FML or VIEW files are used for the import. If a JOLT file is used, the Apply Filters screen is displayed.

    If FML or VIEW files are used, the Get Tuxedo Records screen is displayed, as shown in the following figure.

    
    Description of the illustration import5.gif
    
    

    Use this screen to add additional simple record definitions that are not included in the FML or VIEW files used for the import. You can include information stored in the following Tuxedo buffer types:

    • XML data

    • String data

    • Carrays

    Specify the name of the record and select the buffer type from the list in the Field Type field.

    Unstructured message buffers are wrapped within a record as follows:

    • A message buffer of type STRING is wrapped within a record containing a single field of type string.

    • A message buffer of type CARRAY is wrapped within a record containing a single field of type binary with a fixed size.

    • A message buffer of type XML is wrapped within a record containing a single field of type XML.

    
    

    See Also: Appendix B, "OracleAS Adapter for Tuxedo Message Buffer Support and Data Type Support" for details about support for Tuxedo message buffers and data types

    
    

20. Click Next. The next step in the procedure depends on whether a JOLT file, an FML or VIEW files are used for the import.

    If a JOLT file is used, the Select Interactions screen is displayed, as shown in the following figure. The screen lists the services from the input JOLT file as interactions, along with the input and output structures to use with each interaction. Select the interactions to implement from the list, and then click Next.

    The Select Interactions screen is shown in the following figure:

    
    Description of the illustration import6.gif
    
    

    If FML or VIEW files are used, the Add Interactions screen is displayed.

21. Click Add to add an interaction for the Tuxedo adapter. Add as many interactions as required. Provide the following information for each interaction:

    • Interaction name: The name of the interaction. You can change the default name.

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

    • Output: Identifies an output record. The output record is the data structure for the results of the interaction. The records generated from the input 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.

      
      

    • Input: Identifies an input record. The input record is the data structure for the interaction. The records generated from the input 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, the record specified here is ignored.

      
      

    • Description: Free text describing the interaction.

    • Interaction-Specific Parameters: Tuxedo specific parameters, as listed in the following table:

      Parameter	Description
      Input Buffer Type	The type of buffer used for the input.
      Output Buffer Type	The type of the buffer to use for the results of an outbound interaction.
      No Transaction	Enables to run a service, regardless of transaction context. This parameter should always be checked.
      No Reply Expected	For future use.
      No Blocking Request	Avoids a FROM request submission if a blocking condition exists.
      No Timeouts	Ignores blocking timeouts.

      
      

    The Add Interaction screen is displayed in the following figure:

    
    Description of the illustration import6a.gif
    
    

22. Click Next. The Configure Tuxedo Records screen is displayed. It is used to specify how the Tuxedo records should be configured, as shown in the following figure.

    
    Description of the illustration import7.gif
    
    

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

24. Specify that you want to transfer the metadata from the Windows computer to the OracleAS Adapter for Tuxedo computer and click Finish.

The metadata is imported based on the options specified and it is stored on the computer where OracleAS Adapter for Tuxedo runs. An XML representation of the metadata is 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.

Generating Inbound Interactions

Inbound interactions are defined as events in Oracle Studio. An event adapter is defined automatically when you selected the Tuxedo back-end adapter with Create event queue for the adapter selected, as described in "Configuring an Oracle Connect Adapter". The event adapter is defined with the same name as the back-end adapter with the word event appended to it.

The back-end adapter and the event adapter are linked by Oracle Studio. You can skip from the adapter definition to the event definition by right-clicking the adapter, or event, in the Configuration explorer, and selecting Linked Event or Linked Adapter, respectively.

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

During the import procedure, the BEA JOLT bulk loader file or Tuxedo configuration and FML or VIEW source files. These are copied to the computer running Oracle Studio as part of the import procedure.

Perform the Metadata Import steps to generate inbound interaction metadata, as follows:

1. In the Configuration Explorer, right-click the Tuxedo back-end adapter defined in "Configuring an Oracle Connect Adapter".

2. Select Linked Event to skip to the event adapter.

3. Right-click the event adapter and select Edit Event.

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

5. To add Oracle Application Server users, expand the Routers node, right-click user, and then select Add Item, as shown in the following figure. A new entry is added under the User node.

   
   Description of the illustration new_eveadapprop.gif
   
   

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

7. To add OS/390 users, expand the Senders node, right-click Users, and then select Add item. A new entry is added under the User node.

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

9. Click Save to save the changes.

10. Right-click the event adapter in the Configuration Explorer and select Edit metadata to display the Metadata tab with the event adapter displayed under the Events list.

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

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

13. Select Event Queue Import Manager Using Tuxedo View/FML Files as the import type, as displayed in the following figure, and then click Finish.

14. After defining an import type, the Metadata Import wizard opens in Oracle Studio. FML or VIEW files are used to create the metadata. The Import wizard generates record structures, which are used for the record structures for inbound interactions.

15. Click Add.

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

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

18. Enter the server name or IP address where the FML or VIEW files reside and enter a valid username and password to access the computer (if anonymous access is used, select Anonymous connection), then click OK. The FTP site is added to the list of available sites.

    
    

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

    
    
    
    Description of the illustration import3.gif
    
    

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

20. Expand the node of the added site and locate the necessary FML or VIEW 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.

21. Select the required FML or VIEW file or files and click Finish. The selected file or files are displayed in the Metadata Import wizard, as shown in the following figure:

    
    Description of the illustration import1_in.gif
    
    

22. Click Next.

23. Click Next to analyze and convert the selected FML or VIEW files. The Add Events screen is displayed.

24. Click Add to add an event. The Add Events screen is displayed.

25. Add as many interactions as required. For each interaction, provide the required information, as listed in the following table:

    Property	Description
    Name	The name of the interaction. You can change the default name.
    Mode	The Interaction mode. You can select the following:
    async-send	The interaction sends a request and does not expects to receive a response.
    Input	Identifies an input record. The input record is the data structure for the interaction. The records generated from the FML or VIEW files specified are listed. Select the relevant record for the interaction. Note: You must specify an input record for each interaction before you can click Next
    Description	Free text describing the interaction.

    
    

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

27. Specify that you want to transfer the data from the Windows computer to the IBM OS/390 or z/OS platform, then click Finish.

28. The metadata is imported based on the options specified and it is stored on the IBM OS/390 or 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