This chapter includes the following topics:
You can configure Oracle Connect using Oracle Studio. To use Oracle Studio, first configure it to enable access to the platform where OracleAS Adapters for Tuxedo run.
Before configuring Oracle Connect, ensure the following requirements are fulfilled:
You have permission to access the platform where OracleAS Adapters for Tuxedo runs.
Oracle Connect daemon is running on this computer.
The following requirements are for the Tuxedo Q Adapter only:
Tuxedo queue space and a queue are defined.
The TMQUEUE server is set to handle Q-space.
The EventBroker
server process is set. Either TMUSREVT
for application events, or TMSYSEVT
for system events.
Note:
For further information on BEA Tuxedo, see BEA Tuxedo documentation.Perform the following steps to configure OracleAS Adapters 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 the following figure:
Enter the name of the computer you want to connect to, or click Browse to select the required computer that uses the default port (2551).
Specify the OracleAS Adapter and password of the user who was entered 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.
Oracle Studio includes mechanisms to secure access to Oracle Connect both during design time and run time.
During design time, the following security mechanisms can be applied:
During run time, 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.
Click Studio, 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.
Note:
By default, all users should be given administrative rights during installation.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-3 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 Bindings and Users 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 that logs on with that user name has the relevant authorization.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 during run time, when anonymous access is not allowed.
Perform the following steps to configure run-time user access to OracleAS Adapters for Tuxedo:
In the Configuration Explorer, expand the machine to set the user name and password.
Expand the Users.
Right-click the user profile and select Open. The 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.
This section contains the following topics:
This section describes some parts of the configuration process that you should be aware of before you start.
Workspace Server: You should ensure that the workspace server mode is set to reusable
or single client
. It is recommended to use the reusable
mode. For more information on setting the workspace server mode, see Configuring the Server Mode.
Maximum number of servers: Esure that this property is set to a number that is large enough to handle your system requirements. The default value of 3
may not provide enough servers. For more information on how to set the maximum number of servers, see Configuring the Server Mode.
Environment properties: Ensure that you set the environment properties required by the Tuxedo adapter to work with tuxedo, such as TUXDIR.
Setting the environment properties in UNIX may be done by editing the nav_login
script to set up all of the required environment variables.
In Windows, enter the information in the Windows Environment Variables dialog box. To open the Environment Variables dialog box, right-click My Computer on the Windows desktop and select Properties. Click the Advanced tab, then click Environment Variables.
Modeling interactions for OracleAS Adapter for Tuxedo involves defining an Oracle Connect adapter using Oracle Studio.
All the definitions specified in Oracle Studio are written to the platform where OracleAS Adapters for Tuxedo run.
This section contains the following:
Getting Tuxedo Records for Tuxedo Adapter (FML and View Files)
Generating Interactions for Tuxedo Adapter (FML and View Files)
To work with Oracle Connect, you must configure the adapter definition on the platform where OracleAS Adapters for Tuxedo run 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 machine defined in Configuring OracleAS Adapters for Tuxedo in Oracle Studio.
Expand the Bindings. The binding configurations available on this computer are listed.
Expand the binding where you want to define the adapter. The binding configuration includes branches for data sources and adapters that are located on the machine.
Right-click Adapters and select New Adapter to open the New Adapter wizard.
Enter a name for the adapter.
Note:
The word event is a reserved word and cannot be used to name an adapter.Select Tuxedo as the adapter type from the Type list, as shown in the following figure:
Select Create event queue for the adapter to create an event queue for the adapter.
Click Finish. The 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 must manually define the metadata. For more information of the metadata definition, see 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 machine where you are using the Tuxedo adapter defined in Configuring OracleAS Adapters for Tuxedo in Oracle Studio.
Expand Bindings. The binding configurations available on this computer are listed.
Expand the binding with the adapter you are using.
Expand the Adapters.
Right-click the Tuxedo adapter defined in Configuring a Tuxedo OracleAS Adapter.
Select Show Metadata View to open the Metadata tab, with the Tuxedo adapter displayed under the adapters list.
Right-click the Tuxedo 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 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.
If JOLT files are used, see Getting a JOLT Input File for Tuxedo Adapter and follow the instructions.
If FML or VIEW files are used, see Getting an FML or VIEW Import File for Tuxedo Adapter.
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 the import is complete, 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:
Advanced Tuning of the Metadata for details about fine tuning the adapter metadataIf you selected the Tuxedo Import Manager using JOLT Bulk Loader File, the first step is Get Input Files.
In this step you must select the JOLT file where you are importing the metadata. Do the following to select a JOLT file.
In the Get Input File step that is displayed in the Editor, click Browse. The Select From 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 or 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 OracleAS Adapter and password to access the computer (if anonymous connection is used, select Anonymous connection), then click OK.
Right-click the required computer and select Set Transfer Type. Enter the transfer type (ASCII or BINARY) and click OK.
Click 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 Get Input File step.
Click Next to for Applying Filters for Tuxedo Adapter (JOLT).
In the Applying Filters step the filters are applied automatically as shown in the figure below.
Click Next to analyze and convert the source file. The next step is for Generating Interactions (JOLT).
The Select Interactions step is used to select the interactions to be used. This step is displayed below. The screen lists the services from the input JOLT file as interactions, along with the input and output structures to use with each interaction.
Figure 2-9 The Select Interactions screen
Select the interactions to implement from the list, and click Next. The next step for Configuring Tuxedo Records for Tuxedo Adapter.
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-10 The Configure Tuxedo Records screen
Click Next for Importing the Metadata Definitions for Tuxedo Adapter.
In the Import Metadata step, select Yes to transfer the metadata from the Windows computer to the computer where the Tuxedo Gateway adapter runs, and then 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:
Advanced Tuning of the Metadata for details about fine tuning the adapter metadataIn this step you can add Tuxedo configuration files and Tuxedo record definition files (FML or VIEW). The step is displayed in the Editor as shown below.
This step is optional for both types of files. To get the import files, do the following.
In the Get Input Files step that is displayed in the Editor, click Add for either type of file. The Add button is at the top and bottom of the 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 or 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 OracleAS Adapter and password to access the computer (if anonymous connection is used, select Anonymous connection), then click OK.
Right-click the required computer and select Set Transfer Type. Enter the transfer type (ASCII or BINARY) and click OK.
Click 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 Get Input File step.
Note:
Each file should be of equal size.Click Next for Adding FML Records for Tuxedo Adapter (FML and View).
The Add FML records step is displayed in the Editor as shown below.
In this step, add FML records by selecting fields from the files imported in the first step. If you did not import any files, you can skip this step and add records in the Getting Tuxedo Records for Tuxedo Adapter (FML and View Files) step.
In the Records column, enter a name for the record.
Notes:
Use an expression to filter the records displayed in the list.
User the + and - buttons to change the record order in the list.
From the Available Fields section, select a field or multiple fields to add to the record.
Click the Use Selected Button to add the selected fields to the record. The Use Selected button is a blue triangle that points up.
Note:
To use all of the fields, click the Use All button (the button with the double triangle pointing up).Click Next for Getting Tuxedo Records for Tuxedo Adapter (FML and View Files).
To remove fields from an FML record
Select a record from the Records column.
From the Selected Fields section, select a field or multiple fields to remove from the record.
Click the Remove Selected button to remove the selected fields. The Remove Selected button is a blue triangle that points down.
Note:
To remove all of the fields, click the Remove All button (the button with the double triangle pointing down).The Get Tuxedo Records step is displayed in the Editor as shown below.
In this step, add additional simple record definitions that are not included in the FML or VIEW files used for the import.
Enter the name of the record and select the buffer type from the list in the Field Type field.
Select one of the following message buffer types:
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.
Click Next for Generating Interactions for Tuxedo Adapter (FML and View Files).
In the Add Interaction step, you can add interactions to the Tuxedo Gateway adapter. The Add Interaction screen is displayed in the following figure.
Click Add to add as many interactions as required. Provide the following information for each 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.
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.
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.
The records include those generated from the input files, and those defined in the previous step
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.Description: Free text describing the interaction.
Interaction-Specific Parameters: Tuxedo specific parameters, as listed in the following table:
Table 2-1 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. |
Signal Restart: When selected, if a signal interrupts any underlying system calls, the interrupted system call is reissued.
Interaction Type: Your options are:
SERVICE: Sends a request and synchronously awaits its reply. This is the default setting.
ENQUEUE: Places a message in the queue.
If you select this option, you must also fill in the fields Queue Space Name and Queue Name with the relevant values to assign the queue where the message is to be placed.
POST: Places a message into one or more queues, according to rules and filters predefined according to events that have been subscribed to.
If you select this option, you must also fill in the field Event Name.
Click Next for Configuring Tuxedo Records for Tuxedo Adapter.
Inbound interactions are defined as events in Oracle Studio. An event adapter is defined automatically when you selected the Tuxedo adapter with Create event queue for the adapter selected, as described in Configuring a Tuxedo OracleAS Adapter. The event adapter is defined with the same name as the adapter with the word event appended to it.
The 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 the information.
Note:
The generation of inbound interactions involves similar steps to the steps described to generate outbound interactions. For more information, see Starting Outbound Interactions Metadata Import.During the import procedure, the BEA JOLT bulk loader file or Tuxedo configuration and FML or VIEW source files are used. 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 adapter defined in Configuring a Tuxedo OracleAS Adapter.
Select Linked Event to skip to the event adapter.
Right-click the event adapter and select Open.
Click the Properties tab to add the names of Oracle Application Server users who can retrieve inbound interactions and users who can send inbound interactions.
To add Oracle Application Server users, expand the Routers, right-click user, and then select Add Item, to open the following screen:
Figure 2-15 The Adapter Properties screen
Enter the name of the Oracle Application Server user in the Value column for the item added.
To add users, expand the Senders, right-click Users, and then select Add item. A new entry is added under User.
Enter the name of the 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 Show Metadata View 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.
In the Get Input Files step that is displayed in the Editor, click Add for either type of file. The Add button is at the top and bottom of the 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 or 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 OracleAS Adapter 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 OracleAS Adapter 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 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-2 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.
For Do you want to transfer the metadata to the server, select Yes to transfer the data from the Windows computer to the target platform, then click Finish.
The metadata is imported based on the options specified. 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:
Advanced Tuning of the Metadata for details about fine tuning the adapter metadataThe Tuxedo adapter is configured using Oracle Studio.
This section contains the following topic:
Modeling interactions for OracleAS Adapter for Tuxedo Queue involves defining an Oracle Connect queue adapter using Oracle Studio.
All the definitions specified in Oracle Studio are written to the platform where OracleAS Adapter for Tuxedo Queue runs.
This section contains the following:
To work with Oracle Connect, you must configure the queue adapter definitions on the platform where OracleAS Adapter for Tuxedo Queue runs to handle the events from a Tuxedo Queue.
Perform the following steps to specify these definitions:
From the Start menu, select Programs, Oracle and then select Studio.
In the Configuration Explorer, expand the computer defined in Configuring OracleAS Adapters for Tuxedo in Oracle Studio.
Expand the Bindings. The binding configurations available on this computer are listed.
Expand the binding where you want to define the adapter. The binding configuration includes branches for data sources and adapters that are located on the computer.
Right-click Events and select New Event.
The New Event wizard is displayed.
Enter a name for the event queue.
Note:
The word event is a reserved word and cannot be used to name an event.Select Tuxedo Queue as the event type from the Type list, as shown in the following figure:
Click Finish.
The queue adapter requires metadata describing the inbound interaction, including its structure.
During the import procedure, Tuxedo FML
or VIEW
configuration source files are copied to the computer running Oracle Studio as part of the import procedure. Alternatively, this procedure enables you to manually define the queue adapter metadata.
Before generating the interactions, note the following:
All the events described in a single Tuxedo Queue adapter, should have the same Tuxedo buffer type.
In case that FML/FML32 buffer type is used, a common field with the same FBName
must be included in all events. This field should contain the record/event name.
The interaction is of async-send
type (it does not expect to receive a response).
Perform the following steps to generate inbound interaction metadata:
In the Configuration Explorer, select the Tuxedo Queue adapter defined in Configuring the Tuxedo Queue Adapter.
Right-click the queue adapter in the Configuration Explorer and select Show Metadata View.
The Metadata tab is displayed, with the queue adapter displayed under the Adapters 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 the import type from the Import Type list. You have the following options:
Tuxedo Queue Import Manager for XML/STRING/CARRAY Buffers: This option does not require importing any files. It enables you to manually define the required Tuxedo record.
Tuxedo Queue Import Manager for VIEW/VIEW32 Buffers:
Tuxedo Queue Import Manager for FML/FML32 Buffers:
Click Finish.
The next step depends on the selected import type. If either the VIEW/VIEW32 Buffers
or the FML/FML32 Buffers
options is selected, then the Metadata Import wizard opens, in which case, proceed to the following step. If the XML/STRING/CARRAY Buffers
option is selected, proceed now to Defining the Tuxedo Queue Unstructured Records.
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 required reside and enter a valid OracleAS Adapter 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.
Right-click the computer and select Set Transfer Type. Enter the appropriate transfer type, and click OK.
Expand the added site and locate the files. To change the directory, right-click the computer and select Change Root Directory. Enter the new directory name, and click OK.
Select the required 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.
The Configure Tuxedo Records screen is displayed, as shown in the following figure:
Figure 2-20 The Configure Tuxedo Queue Records screen
Ensure that the settings are correct for the following properties:
Buffer type
: Indicates the buffer type, as read from the FML
/VIEW
file. This property should not be modified.
Get Tuxedo Queue header field in the output record
: Indicates that the header field of each record is read. The default setting is true
.
Read strings from buffer as null terminated
: Indicates that strings are handled as null terminated. The default setting is true
.
Specify the FBName
of the field that contains the event name. This field is common to all incoming events and it should include the record name. This property is required only for FML
/FML32
files.
Click Next to generate the metadata definitions for the queue adapter.
Specify if you want to transfer the data to the server, then click Finish.
The Import wizard generates record structures, which are used for the record structures for the inbound interactions, and the metadata is imported based on the options specified and it is stored on the target 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, under the Imports for the Queue adapter. You can also make any fine adjustments to the metadata.
See Also:
Advanced Tuning of the Metadata for details about fine tuning the adapter metadata.You can manually define the required Tuxedo records when all the events in the Tuxedo queue are of the same type and are unstructured. Only one record is defined.
Perform the following steps to manually define the required Tuxedo records, as follows:
In the Configuration Explorer, select the Tuxedo Queue adapter defined in Configuring the Tuxedo Queue Adapter.
Right-click the Tuxedo Queue adapter and select Show Metadata View.
The Metadata tab is displayed, with the queue adapter displayed under the Adapters 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 Tuxedo Queue Import Manager for XML/STRING/CARRAY Buffers from the Import Type list.
Click Finish.
The Get Tuxedo Records screen is displayed, as shown in the following figure:
Figure 2-21 The Get Tuxedo Records screen
Click Add Record. A new record entry is added to the records list, with a default type.
Select the field type from the Field Type list. Your options are:
STRING
(the default)
CARRAY
XML
X_OCTET
Specify the maximum buffer size in the Size column. This is not required if XML was selected as the field type.
Click Next.
Specify if you want to transfer the data to the target platform, then click Finish.
The record structure is generated, and the metadata is imported to and stored on the target 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, under the Imports for the Queue adapter. You can also make any fine adjustments to the metadata.
See Also:
Advanced Tuning of the Metadata for details about fine tuning the adapter metadata.The Tuxedo Gateway adapter is configured using Oracle Studio. When you set up the adapter, a new Binding and Workspace with the same name as the new Tuxedo Gateway adapter are automatically created. The adapter is added to the new binding. You also import metadata to the adapter with the Oracle Studio import manager.
Note:
In the Workspace property sections, ensure not to change the values for the following:Server type: This must be left to its default setting of external
. For more information, see General.
Workspace server mode: This must be left to its default setting of multiClient
. For more information, see Server Mode.
When you create interactions in Oracle Studio, each interaction defined on the gateway, represents a service exposed by the Gateway as tuxedo server service.
Before you start setting up the Tuxedo Gateway adapter, ensure that the daemon is running.
To set up the Tuxedo Gateway adapter, you should:
Use Oracle Studio to configure the OracleAS Tuxedo Gateway.
The following topics describe how to configure the interactions (services):
Generating Inbound Synchronous Interactions for Tuxedo Gateway Adapter (JOLT)
Importing the Metadata Definitions for Tuxedo Gateway Adapter
Getting an FML or VIEW Import File for Tuxedo Gateway Adapter
Adding FML Records for Tuxedo Gateway Adapter (FML and View)
Getting Tuxedo Records for Tuxedo Gateway Adapter (FML and View Files)
Generating Inbound Synchronous Interactions for Tuxedo Gateway Adapter (FML and View Files)
This section provides details on how to use the Oracle Studio to create an Oracle Tuxedo Gateway adapter.
To work with Oracle Connect, you must configure the adapter definition on the platform where OracleAS Adapters for Tuxedo run to handle the interactions to and from a Tuxedo service.
Perform the following steps using Oracle Studio:
From the Start menu, select Programs, Oracle and then select Studio.
In the Configuration Explorer, right-click the machine and select New and then Tuxedo Gateway. The following is displayed.
Figure 2-22 Tuxedo Gateway Adapter Configuration
Enter the following information:
Name: Enter a name for the new adapter. When you finish this process a new adapter, binding, and workspace are created. The binding and workspace have the same name as the adapter. Do not use a name that is in use as a binding or workspace on your machine.
Machine: Select a machine where you want to configure the new adapter. By default, the machine you selected to open the dialog box is selected.
Daemon: Select the daemon where you want to create the adapter's workspace.
Click Finish to create the new adapter, workspace, and binding.
To edit the Tuxedo Gateway adapter properties, open the Oracle Studio Design perspective and find the binding for the Tuxedo Gateway adapter. The binding has the same name you gave to the Tuxedo Gateway adapter. For information on how to create a Tuxedo Gateway adapter, see Configuring the Tuxedo Gateway Adapter in Oracle Studio.
Do the following to edit the Tuxedo Gateway adapter properties.
From the Start menu, select, Programs, Oracle, and then select Studio.
Expand the Machines folder.
Expand the server machine that you are working with.
Expand the Bindings folder, and then expand the binding the name of Tuxedo Gateway adapter that you are working with.
Expand the Adapter folder.
Right-click the adapter and select Open.
The adapter configuration editor opens in the editor, which displays the properties for the adapter.
Edit the adapter parameters as required.
logLevel
: To set the logging level for the Tuxedo Gateway adapter select from the following log levels. The log levels are listed in order of completeness (None means that no logs are produced, and Debug produces logs with all possible information).
None
API
Info
Debug
Note:
The Tuxedo Gateway adapter logging goes to the Tuxedo log.timeout
: Sets the service request timeout in the Oracle Tuxedo Gateway Server. Enter a time in seconds.
tmsConnectTimeout
: Sets the connection timeout in the Oracle Tuxedo Gateway TMS. If the transaction level is 0PC
, this property is not relevant. The default value is 30 seconds. For information on setting this property, see Starting the Tuxedo Gateway Transaction Group.
transactionLevelSupport
: Enter the transaction type supported. The options are:
0PC
: Does not support transactions
2PC
: Supports XA transactions.
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 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 must manually define 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 machine where you are using the Tuxedo Gateway adapter. For more information, see Configuring OracleAS Adapters for Tuxedo in Oracle Studio.
Expand Bindings. The available binding configurations are listed.
Expand the binding that was created when you created the adapter. This binding has the same name as the Tuxedo Gateway adapter.
Expand the Adapters.
Right-click the Tuxedo Gateway adapter defined in Configuring the Tuxedo Gateway Adapter in Oracle Studio.
Select Show Metadata View to open the Metadata tab, with the Tuxedo Gateway adapter displayed under the adapters list.
Right-click the Tuxedo Gateway 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 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/FML Files as shown in the following figure:
Click Finish. The Metadata Import wizard is displayed.
If JOLT files are used, see Getting a JOLT Input File for Tuxedo Adapter and follow the instructions.
If FML or VIEW files are used, see Getting an FML or VIEW Import File for Tuxedo Adapter.
If you selected the Tuxedo Import Manager using JOLT Bulk Loader File, the first step is Get Input Files.
In this step you must select the JOLT file where you are importing the metadata. Do the following to select a JOLT file.
In the Get Input File step that is displayed in the Editor, click Browse. 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 or 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 OracleAS Adapter and password to access the computer (if anonymous connection is used, select Anonymous connection), then click OK.
Right-click the required computer and select Set Transfer Type. Enter the transfer type (ASCII or BINARY) and click OK.
Click 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 Get Input File step.
Click Next to for Applying Filters for Tuxedo Adapter (JOLT).
In the Applying Filters step the filters are done automatically as shown in the figure below.
Click Next to analyze and convert the source file. The next step is for Generating Interactions (JOLT).
The Select Interactions step is used to select the interactions to be used. This step is displayed below. The screen lists the services from the input JOLT file as interactions, along with the input and output structures to use with each interaction.
Note:
Interactions in Oracle Connect are the Tuxedo Services that you are using.Figure 2-26 The Select Interactions screen
Select the interactions to implement from the list, and click Next. The next step for Configuring Tuxedo Records for Tuxedo Adapter.
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-27 The Configure Tuxedo Records screen
Click Next for Importing the Metadata Definitions for Tuxedo Adapter.
In the Import Metadata step, select Yes to transfer the metadata from the computer with Oracle Studio to the computer where the Tuxedo Gateway adapter runs, and then 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:
Advanced Tuning of the Metadata for details about fine tuning the adapter metadataIn this step you can add Tuxedo configuration files and Tuxedo record definition files (FML or VIEW). The step is displayed in the Editor as shown below.
This step is optional for both types of files. To get the import files, do the following.
In the Get Input Files step that is displayed in the Editor, click Add for either type of file. The Add button is at the top and bottom of the 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 or 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 OracleAS Adapter and password to access the computer (if anonymous connection is used, select Anonymous connection), then click OK.
Right-click the required computer and select Set Transfer Type. Enter the transfer type (ASCII or BINARY) and click OK.
Click 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 Get Input File step.
Click Next for Adding FML Records for Tuxedo Gateway Adapter (FML and View).
The Add FML records step is displayed in the Editor as shown below.
In this step, add FML records by selecting fields from the files imported in the first step. If you did not import any files, you can skip this step and add records in the Getting Tuxedo Records for Tuxedo Gateway Adapter (FML and View Files) step.
In the Records column, enter a name for the record.
Notes:
Use an expression to filter the records displayed in the list.
User the + and - buttons to change the record order in the list.
From the Available Fields section, select a field or multiple fields to add to the record.
Click the Use Selected Button to add the selected fields to the record. The Use Selected button is a blue triangle that points up.
Note:
If you want to use all of the fields, click the Use All button (the button with the double triangle pointing up).Click Next for Getting Tuxedo Records for Tuxedo Gateway Adapter (FML and View Files).
To remove fields from an FML record
Select a record from the Records column.
From the Selected Fields section, select a field or multiple fields to remove from the record.
Click the Remove Selected button to remove the selected fields. The Remove Selected button is a blue triangle that points down.
Note:
If you want to remove all of the fields, click the Remove All button (the button with the double triangle pointing down).The Get Tuxedo Records step is displayed in the Editor as shown below.
In this step, add additional simple record definitions that are not included in the FML or VIEW files used for the import.
Enter the name of the record and select the buffer type from the list in the Field Type field.
Select one of the following message buffer types:
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.
Click Next for Generating Interactions for Tuxedo Adapter (FML and View Files).
In the Add Interaction step, you can add interactions to the Tuxedo Gateway adapter.
Note:
Interactions in Oracle Connect are the Tuxedo Services that you are using.Click Add to add as many interactions as required. Provide the following information for each interaction. The Add Interaction screen is displayed in the following figure:
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 (Tuxedo service) that 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 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.
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.
The records include those generated from the input files, and those defined in the previous step.
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.Description: Free text describing the interaction.
Interaction-Specific Parameters: Tuxedo specific parameters, described below:
Output Buffer Type: The type of the buffer to use for the results of an outbound interaction
Click Next for Configuring Tuxedo Records for Tuxedo Adapter.
The non-transactional Tuxedo Gateway can be configured as a regular Tuxedo server that advertises the services (interactions) configured when you Configure the Tuxedo Gateway as a Regular Adapter. This is done using the UBB configuration file.
In the UBB configuration file, add a new entry to the SERVERS section called <acgw_tuxedo
>, where acgw_tuxedo
is the name of the executable TNS provided in the Oracle Connect bin
folder. You must use lowercase letters. The following is an example of the acgw_tuxedo
entry:
"acgw_tuxedo" SRVGRP="GROUP3" SRVID=3 CLOPT=" -- -wMSGATEWAY" RQPERM=0666 REPLYQ=N RPPERM=0666 MIN=1 MAX=10 CONV=N SYSTEM_ACCESS=FASTPATH MAXGEN=1 GRACE=86400 RESTART=N MINDISPATCHTHREADS=10 MAXDISPATCHTHREADS=10 THREADSTACKSIZE=0 SICACHEENTRIESMAX="500"
The configuration in this entry is the standard Tuxedo Server configuration, which may also be used to configure the number of server occurrences and concurrently dispatched threads that each server process that is supported by the Tuxedo Gateway. In addition to the standard configuration, the following parameters should be passed to the Tuxedo Server using the CLOPT
property:
CLOPT=" -- -w<workspace_name> [-u<username> [-p<password>]]
[-l[<ip>]:<port>]
Where:
workspace
is the name of the workspace where the Tuxedo Gateway adapter is defined. It has the same name as the adapter.
Enter information for these parameters if you are using a secure daemon:
username
is the name of a user with permission to access the daemon
password
is the password for this user
ip
is the ip address of the computer where the daemon is running (optional)
port
is the port in which the daemon is running. This is optional unless the daemon is running on a port that is not the default port.
Note:
The Tuxedo configuration must be set to thread capable.After you finish configuring the Tuxedo Adapter in Oracle Studio and Configure a Non-Transactional Tuxedo Gateway as a Tuxedo Server, you can start Tuxedo.
Note:
Ensure that you set the following in the Tuxedo environment before running Tuxedo:
For Windows:
* Add $NAVROOT/bin
to the PATH
For UNIX:
* Add $NAVROOY/bin
to the PATH
* Add $NAVROOT/lib
to the LD_LIBRARY_PATH
The transactional Tuxedo Gateway should be defined as a separate Tuxedo group. This group should configure the Oracle Tuxedo Gateway TMS and the Oracle Tuxedo Gateway Server.
The TMS executable named acgw_tuxedo_xa
is supplied in the Oracle Connect bin
folder or directory. The supplied TMS is not always sufficient. If you cannot use this TMS, you can build a new one using the following parameters:
XA_SWITCH
: acgw_xa_switch
XA library name: tuxgateway.lib
Note:
Run thenav_login
before running the buildtms
command to build acgw_tuxedo-xa
.The Tuxedo Gateway Server advertises the services (interactions) configured when you Configure the Tuxedo Gateway as a Regular Adapter.
The configuration is done by adding two new entries to the UBB configuration file. You must use lowercase letters for the value definitions.
You must add an new entry to the GROUPS section. This group should define the Oracle Tuxedo Gateway TMS as follows:
TMSNAME=acgw_tuxedo_xa OPENINFO="Oracle_BPEL:<connect information>"
In the TMS that you define, the connect information must match the connect information that is defined in your Tuxedo Server. The following is an example of a group entry:
"GROUP3" LMID="TUX1" GRPNO=3 TMSCOUNT=2 TMSNAME=acgw_tuxedo_xa OPENINFO="Oracle_BPEL:-wINTTEST5040 -l:2551"
Add a new entry to the SERVERS section called <acgw_tuxedo
>, where acgw_tuxedo
is the name of the executable TNS provided in the Oracle Connect bin
folder. The following is an example of the acgw_tuxedo
entry:
"acgw_tuxedo" SRVGRP="GROUP3" SRVID=3 CLOPT=" -- -wMSGATEWAY" RQPERM=0666 REPLYQ=N RPPERM=0666 MIN=1 MAX=10 CONV=N SYSTEM_ACCESS=FASTPATH MAXGEN=1 GRACE=86400 RESTART=N MINDISPATCHTHREADS=10 MAXDISPATCHTHREADS=10 THREADSTACKSIZE=0 SICACHEENTRIESMAX="500"
The configuration in this entry is the standard Tuxedo Server configuration, which may also be used to configure the number of server occurrences and concurrently dispatched threads that each server process that is supported by the Tuxedo Gateway. In addition to the standard configuration, the following parameters should be passed to the Tuxedo Server using the CLOPT
property:
CLOPT=" -- <connect information>"
The connect information is defined as follows:
-w<workspace_name> [-u<username> [-p<password>]][-l[<ip>]:<port>]
Where:
workspace
is the name of the workspace where the Tuxedo Gateway adapter is defined. It has the same name as the adapter.
Enter information for these parameters if you are using a secure daemon:
username
is the name of a user with permission to access the daemon
password
is the password for this user
ip
is the ip address of the computer where the daemon is running (optional)
port
is the port in which the daemon is running. This is optional unless the daemon is running on a port that is not the default port.
Notes:
The Tuxedo configuration must be set to thread capable.Note:
Ensure that you set the following in the Tuxedo environment before running Tuxedo:
For Windows:
* Add $NAVROOY/bin
to the PATH
For UNIX:
* Add $NAVROOY/bin
to the PATH
* Add $NAVROOT/lib
to the LD_LIBRARY_PATH
In most cases, you should not start the transaction group until at least one message driven bean application is activated in the Oracle Application Server for the Tuxedo Gateway adapter.
If you start the Tuxedo group when no message driven bean application is activated, TMS cannot start, therefore the group can be used only without transactions.
When activated, TMS waits for a connection from the resource adapter. The wait time is defined in the tmsConnectTimeout property of the Tuxedo Gateway adapter.
When determining the value for the tmsConnectTimeout
property you should decide whether to use a large or small value. If you start the transaction group separately, it is recommended to use a large value, such as 9999999
. In this case, the TMS waits for the connection for a long period. This gives time to activate the message driven bean when necessary.
If you start the entire Tuxedo configuration, it is recommended to use a small value for the tmsConnectTimout
property. In this case a large value may prevent other groups from starting.
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".