| Oracle® Application Server Adapter for Tuxedo User's Guide 10g Release 2 (10.1.2) B15802-01 |
|
 Previous |
 Next |
| Oracle® Application Server Adapter for Tuxedo User's Guide 10g Release 2 (10.1.2) B15802-01 |
|
Previous |
Next |
This section describes how to install Oracle Connect and Oracle Studio from the CD-ROM, and how to configure Oracle Connect using Oracle Studio.
|
Note: In addition to the installation tasks described in this section, the J2CA 1.0 Tuxedo adapter must be installed with Oracle Application Server. Installing the J2CA 1.0 Tuxedo adapter is described in Oracle Application Server Adapter Installation Guide. |
This section includes the following topics:
Before installing OracleAS Adapter for Tuxedo, ensure that your computer meets the following requirements:
This section describes the following requirements for installing Oracle Connect on a UNIX platform:
The following table summarizes the hardware requirements for Oracle Connect on a UNIX platform.
The following table summarizes the software requirements for Oracle Connect.
Table 2-2 UNIX Software Requirements
| Software Component | Requirements |
|---|---|
|
HP Tru64 UNIX version 5.1 or higher. HP-UX version 11 or higher. Note: The operating system must run in 32-bit mode. IBM AIX version 4.33 or higher. Note: The operating system must run in 32-bit mode. Solaris Operating System (SPARC) version 2.8 or higher. Note: The operating system must run in 32-bit mode. |
|
|
BEA Tuxedo |
Version 8.0 or higher. |
|
Oracle Application Server 10g (10.1.2.0.1) |
This section describes the following requirements for installing Oracle Studio and Oracle Connect when OracleAS Adapter for Tuxedo runs on a Windows platform:
The following table summarizes the hardware requirements for Oracle Studio and Oracle Connect when OracleAS Adapter for Tuxedo runs on a Windows platform.
This section explains how to install Oracle Connect on a UNIX platform from the CD-ROM. This section includes the following:
Before starting the installation procedure, ensure that you have the following information is available:
The root directory where you want to install Oracle Connect.
|
Note: The root directory cannot be a system root directory, /var or /tmp. |
The account name where Oracle Connect will run.
Oracle Connect is present in the following operating system dependent files:
HP Tru64 UNIX: ocl1012-alphaunx.taz
HP-UX: ocl1012-hpux.taz
IBM AIX: ocl1012-ibmaix.taz
Solaris Operating System (SPARC): ocl1012-sunsol.taz
These files are provided on a CD-ROM in the Oracle_Connect\Tuxedo_Legacy_Adapter directory.
Perform the following steps to install Oracle Connect:
Using FTP, copy the relevant Oracle Connect installation file in the binary mode from the installation CD-ROM.
Rename the taz file using the following command:
mv ocl1012-sunsol.taz ocl1012-sunsol.tar.Z
Decompress the file using the following command:
uncompress ocl1012-sunsol.tar.Z
Run the tar command, as shown in the following example:
tar xvf ocl1012-sunsol.tar nav_install
The following message is displayed:
x nav_install, nnnn bytes, mmmm tape blocks
|
Note: Ensure that the directory used to run the installation files consists of Write privileges. |
Perform the following steps to install Oracle Connect:
Run the following command:
./nav_install
This command initiates the installation procedure. The installation procedure is displayed in a serie of screen prompts and responses.
Enter the full path of the disk archive (.tar) file, and press Enter.
Enter the root directory name for the installation, and press Enter. You must have a Write permission for this directory. The default directory is the users home directory.
|
Note: The root directory cannot be a system root directory or/var or /tmp directory.
Oracle Connect is installed into a fixed directory named navroot. |
Confirm the directory name in which Oracle Connect will be installed, and press Enter.
Enter the account name where you want Oracle Connect to run, and press Enter. This account name will be used for anonymous access to the server by clients. It can be changed after the installation is complete.
Confirm the account name, and press Enter.
Specify the required shell, under which Oracle Connect should run, and press Enter. The following options are displayed:
C-shell (/bin/csh).
Korn-shell (/bin/ksh)
Bourne-shell (/bin/sh)
Enter the account name for a user with administrative authorization. Optionally, press Enter to enable any user to administer Oracle Connect.
After installing Oracle Connect, perform the following postinstallation tasks:
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.
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
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:
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
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.
|
Note: It is recommended to addTUXDIR and WSNADDR environment variables to the site_nav_login file. Adding these environment variables facilitates their availability when new server processes are started to handle client requests. |
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:
| Shell | nav_login Command |
|---|---|
| CSH | source root/bin/nav_login |
| Bourne | . root/bin/nav_login.sh |
| Korn | . root/bin/nav_login.sh |
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.
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.
|
Note: To allow automatic client/server access to Oracle Connect, start the daemon at system startup time from a super user account. |
This section explains how to install Oracle Connect from the CD-ROM.
Assuming that the CD-ROM drive is D:, the installation file is located in the D:\Oracle_Connect\Tuxedo_Legacy_Adapter directory. Install Oracle Connect from the CD-ROM by running the installation batch file, OCL1012-win32.bat.
|
Note: If you are installing Oracle Connect on a Windows XP computer, you cannot specify a logical drive as the destination folder for the installation. |
This section explains how to install Oracle Studio from the CD-ROM.
|
Note: If you have Oracle Studio already installed because you are also using another legacy adapter, you do not need to reinstall it.The other legacy adapters are:
|
Assuming that the CD-ROM drive is D:, the installation file is located in the D:\Oracle_Studio directory. Install the software from the CD-ROM by running the self-extracting executable installation file, OSL904-win32.exe.
|
Note: If you are installing Oracle Connect on a Windows XP computer, you cannot specify a logical drive as the destination folder for the installation. |
You can configure Oracle Connect using Oracle Studio. To use Oracle Studio, first configure it to enable access to the platform where OracleAS Adapter for Tuxedo runs.
To configure Oracle Connect, refer to the following sections:
|
Note: The following tasks assume you have permission to access the platform where OracleAS Adapter for Tuxedo runs and that the Oracle Connect daemon is running on this computer. |
Perform the following steps to configure OracleAS adapter for Tuxedo in Oracle Studio:
From the Start menu, select Programs, Oracle, and then select Studio. Oracle Studio opens, displaying the Design perspective and the Welcome pane.
Right-click Machines in the Configuration Explorer and select Add Machine.
The Add Machine screen is displayed, as shown in thefollowing figure:
Enter the name of the computer you want to connect to, or click Browse to select the required computer and which uses the default port (2552).
Specify the username and password of the user who was specified as the administrator during Oracle Connect installation.
|
Note: Selecting Anonymous connection enables all users having access to the computer to be an administrator. |
Click Finish. The selected computer is displayed in the Configuration Explorer as shown in the following figure:
Oracle Studio includes mechanisms to secure access to Oracle Connect both during design time and runtime.
During design time, the following security mechanisms can be applied:
During runtime, client access to Oracle Connect is provided by the user profile:
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:
From the Start menu, select Programs, Oracle and then select Studio. Oracle Studio opens.
Select Window from the menu bar and then select Preferences. The Preferences window is displayed.
Expand the Studio node, as shown in the following figure.
Click Change master password to open the Change Master Password screen.
In the Change Master Password screen, leave the Enter current master password field empty and type a new master password.
Confirm the new password.
Click OK.
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".
|
Note: By default, all users should be given administrative rights during installation. |
Using Oracle Studio, perform the following steps to specify users with administrative rights:
From the Start menu, select Programs, Oracle and then select Studio. Oracle Studio opens, showing the Design perspective.
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 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.
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. |
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:
In the Configuration Explorer, expand the node of the computer which you want to set the user name and password.
Expand the Users node.
Right-click the NAV user profile and select Edit User, as shown in the following figure. The NAV user profile editor is displayed
In the User editor, click Add to open the Add Authenticator screen, as shown in the following figure.
Select the Remote Machine resource type.
Enter the name of the OracleAS Adapter for Tuxedo computer defined in Oracle Studio.
Enter the user name and password used to access the computer and confirm the password.
Click OK.
Modeling interactions for OracleAS Adapter for Tuxedo involves defining an Oracle Connect back-end adapter using Oracle Studio. All the definitions specified in Oracle Studio are written to the platform where OracleAS Adapter for Tuxedo runs.
This section contains the following:
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:
From the Start menu, select Programs, Oracle and then select Studio.
In the Configuration Explorer, expand the node of the computer defined in "Configuring OracleAS Adapter for Tuxedo in Oracle Studio".
Expand the Bindings node. The binding configurations available on this computer are listed.
Expand the NAV binding node. The NAV binding configuration includes branches for data sources and adapters that are located on the computer.
Right-click Adapters and select New Adapter to open the New Adapter wizard.
Enter a name for the back-end adapter.
|
Note: The word event is a reserved word and cannot be used to name an adapter. |
Select Tuxedo as the back-end adapter type from the Type list, as shown in the following figure:
Select Events to create an event queue for the adapter.
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 theType list are not supported with the version of Oracle Connect installed at the site. |
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:
From the Start menu, select Programs, Oracle and then select Studio.
In the Configuration Explorer, expand the node of the computer defined in "Configuring OracleAS Adapter for Tuxedo in Oracle Studio".
Expand the Bindings node. The binding configurations available on this computer are listed.
Expand the NAV binding node.
Expand the Adapters node.
Right-click the Tuxedo back-end adapter defined in "Configuring an Oracle Connect Adapter".
Select Edit Metadata to open the Metadata tab, with the Tuxedo back-end adapter displayed under the adapters list.
Right-click the Tuxedo back-end adapter and select New Import. The New Metadata Import screen is displayed.
Enter a name for the import. The name can contain letters and numbers and the underscore character only.
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:
Click Finish. The Metadata Import wizard is displayed.
Click Add. The Select screen is displayed. This screen lists any files selected for use as input for the import.
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.
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.
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:
Right-click the required computer and select Set Transfer Type. Enter the transfer type (ASCII or BINARY) and click OK.
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.
Select the required file or files and click Finish. The selected file or files are displayed in the Metadata Import wizard.
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:
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 |
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:
Figure 2-10 The Select Interactions screen
If FML or VIEW files are used, the Add Interactions screen is displayed.
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 tosync-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:
Table 2-5 Interaction-specific Parameters
| Parameter | Description |
|---|---|
|
|
The type of buffer used for the input. |
|
|
The type of the buffer to use for the results of an outbound interaction. |
|
|
Enables to run a service, regardless of transaction context. This parameter should always be checked. |
|
|
For future use. |
|
|
Avoids a FROM request submission if a blocking condition exists. |
|
|
Ignores blocking timeouts. |
The Add Interaction screen is displayed in the following figure:
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:
Figure 2-12 The Configure Tuxedo Records screen
Click Next to generate the metadata definitions for the adapter.
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.
|
See Also: Appendix A, "Advanced Tuning of the Metadata" for details about fine tuning the adapter metadata |
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.
|
Note: The generation of inbound interactions involves similar steps to the steps described to generate outbound interactions. For details, see "Generating Outbound Interactions". |
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:
In the Configuration Explorer, right-click the Tuxedo back-end adapter defined in "Configuring an Oracle Connect Adapter".
Select Linked Event to skip to the event adapter.
Right-click the event adapter and select Edit Event.
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.
To add Oracle Application Server users, expand the Routers node, right-click user, and then select Add Item, as shown in the following figure:
Figure 2-13 The Adapter Properties screen
Enter the name of the Oracle Application Server user in the Value column for the item added.
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.
Enter the name of the OS/390 user in the Value column for the item added.
Click Save to save the changes.
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.
Right-click Imports and select New Import. The New Import screen is displayed.
Enter a name for the import. The name can contain letters, numbers and the underscore character only.
Select Event Queue Import Manager Using Tuxedo View/FML Files as the import type, and then click Finish.
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.
Click Add.
The Select Resources screen is displayed, which provides the option to select files from the local computer or copy the files from another computer.
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.
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. |
Right-click the computer and select Set Transfer Type. Enter the transfer type (ASCII or BINARY) and click OK.
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.
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:
Click Next.
Click Next to analyze and convert the selected FML or VIEW files. The Add Events screen is displayed.
Click Add to add an event. The Add Events screen is displayed.
Add as many interactions as required. For each interaction, provide the required information, as listed in the following table:
Table 2-6 Interaction Parameters
| Property | Description |
|---|---|
|
Name |
The name of the interaction. You can change the default name. |
|
Mode |
The Interaction mode. |
|
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. |
Click Next to generate the metadata definitions for the adapter.
Specify that you want to transfer the data from the Windows computer to the IBM OS/390 or z/OS platform, then click Finish.
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 |
The XML schema describing the adapter interactions can be viewed in the Source tab of Oracle Studio.
The XML schemas are created automatically during the import procedure, as described in "Generating Outbound Interactions" and in "Generating Inbound Interactions". XML schemas describe the adapter interactions and the input and output records for these interactions.
