Copyright © TIBCO Software Inc. All Rights Reserved


Chapter 3 Adapter Instance Options : Adapter Instance Tabs

Adapter Instance Tabs
The following tabs can be used to define an adapter instance:
Configuration Tab
After you drag and drop a TuxedoAdapterConfiguration icon from the palette panel to the design panel, the Configuration tab is selected by default.
Click Apply to apply the changes before leaving this tab.
The version string indicates the TIBCO ActiveEnterprise (AE) configuration format in which the adapter instance is saved. An adapter instance can be saved in AE 4.0, AE 5.0 or AE fro1 format.
When a new adapter instance is created in TIBCO Designer 5.x, the version string is set to AE Version 5.1. When a 4.x adapter instance is opened in Designer 5.x, the Version field is set to AE Version 4.0.
If you are using TIBCO Designer 5.x to modify 4.x adapter instances, only change features supported by the 4.x. runtime adapter and use the validation utility to verify the instance before deploying the project. Invoke the utility from the Project>Validate Project for Deployment menu command in Designer.
To change versions, click the Change Version button.
Specify a message filter, if you have configured a message filter resource for use with the adapter. The plugin allows you to manipulate incoming and outgoing data before sending it on the network or handing it to the target application. Plugins can be written using the TIBCO Adapter SDK. See TIBCO Adapter SDK Programmer’s Guide for information about writing a message filter.
Select adtuxedo_wrkstn if the adapter works as a Tuxedo Workstation client. Select adtuxedo_native if the adapter works as a Tuxedo Native client.
Guidelines for Choosing an Instance Name
Use the default name or replace it with a name of your choice.
An instance name must use alphanumeric characters. An underscore (_) character can be used. The entire instance name must be less than 80 characters. The space character cannot be used in an instance name.
Each instance name must be unique per adapter within a project even if each instance is defined in a different folder. That is, configuring same-named adapter instances in different folders will not make their names unique.
When you create an adapter instance, the palette automatically creates several resources for it. The names of these resources derive from the name of the instance they belong to. Changing the adapter instance name results in an automatic regeneration of the resources names. If you manually modify any resource name, that particular name will not be automatically regenerated the next time you rename the adapter instance.
Run-time Connection Tab
Many of the following fields can use global variables. Click the Global Variables tab in the project panel to add or modify a global variable. See Using Global Variables for more information
The parameters that need to be specified in the Run-time Connection tab depend on the authorization level set on the Tuxedo server (ubbconfig file). The authorization levels and the fields to be specified for each are as follows:
TPNOAUTH: User Name
TPSYSAUTH: User Name and Application Password
TPAPPAUTH: User Name, Application Password, User Password, Client Name, Group Name (should be null if the adapter is to be used as a workstation client) and Initialization flags.
The adtuxedo.authinfo property in the adapter properties file indicates the authorization level set on the Tuxedo server.
There are three possible values:
TPNOAUTH: No authorization check. This is the default value.
TPSYSAUTH: System authorization.
TPAPPAUTH: Application authorization.
If the parameter is not specified, the adapter will attempt to connect to each of these levels sequentially.
Click Apply to apply the changes before leaving this tab.
The password associated with the Tuxedo user specified in the User Name field. This field cannot be edited. If a value has to be specified, use the Global Variables. This is the variable length data that is forwarded to the application defined authentication service.
You can toggle between global variables and plain text values. This value is visible in non-readable form in the project. Plain text values are stored in the project in encrypted form.
When the adapter is used as a workstation client, the value in this field should be set to null, which is the default. When the adapter is used as a native client, specify a valid Tuxedo group name in this field.
The password associated with a particular application domain. All users in a domain will use this password to access the application, depending on the level of authorization set on Tuxedo. The password should be less than 30 characters. This field cannot be edited. If a value has to be specified, use Global Variables.
You can toggle between global variables and plain text values. This value is visible in non-readable form in the project. Plain text values are stored in the project in encrypted form.
Maximum Number of Reconnect Attempts
The total number of reconnection attempts to make after the service has been suspended. When this number is reached, the runtime adapter or adapter service will be stopped.
Number of Reconnect Attempts Before Suspending Impacted Service(s)
Note that reconnection with the application does not depend on this parameter. Reconnection depends on the value specified in the Maximum Number of Reconnect Attempts field.
Interval between Reconnect Attempts (milliseconds)
Adapter Termination Criteria (after max number of reconnect attempts)
The adapter and all of its services are stopped if any one of its services has been unable to re-establish connection after the Maximum Number of Reconnect Attempts has been made. This option cannot be changed.
Initialization Flags Values
The valid values in the Initialization Flags field are given in Table 7. These values are used while initiating connections to Tuxedo. The values are set in the TPINIT structure. Refer to the Oracle Tuxedo documentation for more information.
Adapter Services Tab
These settings affect publication and request-response services defined for the adapter. Click Apply to apply the changes before leaving this tab.
Polling Interval (milliseconds)
This parameter determines how often the request-response service polls for a reply from Tuxedo in an asynchronous mode. The default value is 1000 milliseconds. This field can be set as a global variable or it can be set in the TRA properties file.
Polling Interval for Outstanding Invocations (milliseconds)
This parameter determines how often the Request-Response service polls Tuxedo in an asynchronous mode for the outstanding invocations. The default setting is 2000 milliseconds.
Example: If you have not changed default settings, the Request-Response service in asynchronous mode polls for replies every 1000 milliseconds till the maximum number of pending invocations configured is reached after which polling is done every 2000 milliseconds. This field can be set as a global variable or it can be set in the TRA properties file.
Maximum Number of Pending Invocations
Specify the maximum number of pending invocations. Once maximum number of pending invocations is reached, the value specified in the polling interval for outstanding invocations field is used to poll for replies. The default setting is 50. Tuxedo allows a maximum of 50 pending invocations and any subsequent additional invocation will yield a TPELIMIT error. This field can be set as a global variable or it can be set in the TRA properties file.
General Tab
This tab allows you to set a termination subject or topic and specify the encoding type. Note that the adapter should communicate only with other applications that support the same code pages or Unicode.
Click Apply to apply the changes before leaving this tab.
A message sent on this subject (if TIBCO Rendezvous is the transport) or topic (if JMS is the transport) stops the adapter. In most cases, you should use the default value.
See the TIBCO Rendezvous documentation for information about specifying subject names. See the TIBCO Enterprise Message Service documentation for information about publishing on a topic.
Select the encoding from the drop-down list. The default encoding is ASCII. If you do not set a value in this field, the default value (ASCII) is used.
ASCII 7-bit ASCII
UTF8 Unicode Transformation Format-8
Shift_JIS (CP943) Japanese Shift-JIS, CP943
Shift_JIS (TIBCO) Variant of IBM-943, flavoring some MS-932 conversions
Big5 Traditional Chinese Big5 (with Euro Sign)
The Adapter Encoding field is editable. See TIBCO ActiveMatrix Adapter for Tuxedo Concepts for a list of additional encodings that can be typed into this field.
The palette does not validate encoding values that you type into the field. The runtime adapter will throw an error if the encoding value you type is not supported.
MultiThreading Tab
Every adapter instance has one or more sessions linked to it. Sessions encapsulate stateful connections to a messaging source, such as a TIBCO Rendezvous daemon. When you configure an adapter instance, sessions and the associated endpoints are created automatically. Click Advanced in the project panel, then click Sessions to view the sessions created. Click the required endpoint to view the parameters for the endpoint.
Click Apply to apply the changes before leaving this tab.
The session name for which multithreading is being set. The DefaultRVSession and HawkSession sessions are set by default.
If using Oracle Tuxedo 6.5, the number of threads should be set to zero. If using Oracle Tuxedo 7.1 or higher, the adapter supports multiple connections for inbound services. The number of connections made to the Tuxedo application will be equal to one more than the number of threads configured. For example: If you set 3 for the number of threads, the number of connections made is 4. The minimum value for number of threads in the Hawk session is one and for other sessions, it is zero.
Logging Tab
Use these settings to configure a log file or log sinks, including which types of trace messages you want logged and where they are sent.
Click Apply to apply the changes before leaving this tab.
When unchecked, the standard log file is used. This is the default. Fill out the remaining fields on this tab. You do not need to read the rest of this field description.
When checked, you can set two standard output destinations (sinks) for trace messages and set the tracing level for the roles selected. The following sink types are available:
See Creating Log Sinks for more information.
When checked, trace messages are displayed in the command prompt window where the adapter is started. This is the same as creating a STDIO sink. When unchecked, trace messages do not display in the window.
Specify the name of the log file to which trace messages are written. This is the same as creating a file sink. Global variables can be used to specify the location of the log file. See Using Global Variables for more information.
Type the name and file system path, or click Browse and select an existing log file. If no file name is specified, trace information is not written to a file.
By default all error, warning, debug and information messages are printed in the console window in which the adapter was started. Alternatively, you can specify a log file and path to redirect trace output to a log file located anywhere in your file system. The default log file name is %%DirTrace%%/%%Deployment%%.%%InstanceId%%.log, and is saved in the same directory where your project (repository instance) is stored.
Most errors received by the adapter are logged. The only errors that might not be logged are any TIBCO Rendezvous or TIBCO Adapter SDK errors that appear at startup time before tracing can be initialized.
Logging trace messages is helpful for troubleshooting. There are four levels of trace messages that you can log: Information, Warning, Debug, and Error. Trace messages are described and listed in Appendix B, Trace Messages
Logging affects system performance. It is recommended that you use logging only as needed.
Debug messages should not be logged unless requested by the TIBCO Product Support Group. This option writes a lot of information to the log file and significantly reduces the speed of the adapter.
Creating Log Sinks
When you check the Use Advanced Logging checkbox, you configure log sinks using icons in the TIBCO Designer project panel. This gives you complete control on selecting the destinations and associating desired roles with each of the destinations.
1.
Check the Use Advanced Logging box.
2.
Click Apply.
3.
In the TIBCO Designer project panel, select the Log Sinks folder under the Advanced folder.
Figure 2 Creating Log Sinks
4.
Creating a new log sink by dragging and dropping the Generic log sink icon from the palette panel into the design panel, then assigning a type to it from the drop down menu in the configuration panel. Click Apply.
5.
With the desired log sink icon selected in the design panel, fill in the fields in the configuration panel. You can also change the name and enter a description for each sink by right-clicking on the sink icon in the project panel.
File sink logs the trace messages to a file. Specify the file limit, file count, and the option to append or overwrite. By default, the file limit is 30000 bytes, the file count is 3, and the mode is append.
STDIO sink sends trace messages to stdout or stderr. By default, stdout is selected.
Hawk sink sends each trace message to TIBCO Hawk Monitor or TIBCO Hawk Display using the Hawk session, which is created by the adapter for monitoring purposes. Specify the MicroAgent Name. (For details on Hawk sessions, see Using Global Variables.)
Network sink publishes each trace message on TIBCO Rendezvous. Specify the session and the subject on which the trace messages need to be published.
Startup Tab
This tab displays the startup behavior.
The startup banner displays the runtime adapter version, the infrastructure version on which the adapter is built, and copyright information in the console window when the adapter is started. Check this checkbox to display the startup banner.
This field is predefined and cannot be changed. It specifies the location where the adapter searches for base schemas. All schemas that have been defined and saved at this location are loaded at startup.
Monitoring Tab
These settings do not need to be configured unless TIBCO Hawk is installed.
Many of the following fields can use global variables. Click the Global Variables tab in the project panel to add or modify a global variable.
See Chapter 7, Monitoring the Adapter Using TIBCO Hawk for a list of supported microagents.
Click Apply to apply the changes before leaving this tab.
Allows you to turn on or off the standard TIBCO Hawk Microagent. Clicking the globe icon changes the checkbox to a text field, allowing you to specify a global variable. When this is a text field, turn the microagent on and off by entering true or false.
This is the name for the standard microagent that will be registered with the TIBCO Hawk system. In most cases the default value is used, COM.TIBCO.ADAPTER.adtuxedo.%%Deployment%%.%%InstanceId%%.
The value for the %%deployment%% global variable can be set or modified by selecting the session icon and then clicking the Global Variables tab in the project panel.
The %%InstanceId%% variable does not need to be set because it is automatically set at runtime by the runtime adapter.
Specifies the amount of time the Hawk Agent should wait for the HMA method invocations to complete before timing them out. The default is 10000 milliseconds. Normally there is no need to change this value, however, on machines under extreme stress where method invocations are timing out, this new option allows the timeout value to be increased.
Allows you to turn on or off the instance-specific or class-specific standard TIBCO Hawk Microagent. You can configure how the class microagent is turned on and off in this field: clicking the globe icon changes the checkbox to a a true/false text field.
This is the name for the class microagent that will be registered with the TIBCO Hawk system. In most cases the default value is used, COM.TIBCO.adtuxedo.%%Deployment%%.%%InstanceId%%.
Specifies the amount of time the Hawk Agent should wait for HMA method invocations to complete before timing them out. The default is 10000 milliseconds. Normally there is no need to change this value, however, on machines under extreme stress where method invocations are timing out, this new option allows the timeout value to be increased.
This is the name of the TIBCO Rendezvous session that is predefined and cannot be changed. The session is automatically generated by TIBCO Designer and will be used by the standard, class, and custom microagents.
Make sure you have set the correct parameter value for the global variables that correspond to the TIBCO Hawk configuration. If the session parameters are not set properly, the microagents will not display in the TIBCO Hawk Display.

Copyright © TIBCO Software Inc. All Rights Reserved