Skip Headers
Oracle® Database Gateway for IMS, VSAM, and Adabas Installation and Configuration Guide
11g Release 2 (11.2) for AIX 5L Based Systems (64-Bit), HP-UX Itanium, Solaris Operating System (SPARC 64-Bit), Linux x86, and Linux x86-64

Part Number E12076-02
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Index
Index
Go to Master Index
Master Index
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
View PDF

13 Configuring Oracle Connect through Oracle Studio for IMS, VSAM, and Adabas Gateways

This section describes how to manage and configure Oracle Connect for IMS, VSAM, and Adabas Gateways by using Oracle Studio for IMS, VSAM, and Adabas Gateways. It describes the procedures necessary for smooth data integration at production time.

This section includes the following topics:

Starting and Stopping Daemons

This section includes the following topics:

Starting a Daemon

You start a daemon from a privileged account on the system where the daemon will run. A privileged account is, for example, the super user account on a UNIX platform. If not run from a privileged account, the daemon can start servers only with the same user ID as the account that started it. In this case, the daemon may also have problems validating user name/password pairs within the system.

Use Oracle Studio for IMS, VSAM, and Adabas Gateways to manage all daemon operations, except for starting the daemon. A daemon can only be started through the command line. A daemon cannot be started from within Oracle Studio for IMS, VSAM, and Adabas Gateways.

The daemon startup processes vary according to the type of platform.

Enabling Automatic Startup

The daemon is usually started automatically when the system boots up.

Manually Starting a Daemon on z/OS Platforms

The IBM /s command is used to start the daemon on z/OS platforms.

To start the daemon

  1. Ensure the following:

    • The NAVROOT.loadaut library is APF authorized. NAVROOT is the high-level qualifier specified during installation.

      Note:

      To define a DSN as APF authorized, in the SDSF screen, enter the following command, where nav002 is the volume where you installed Oracle Connect for IMS, VSAM, and Adabas Gateways:
      /setprog apf,add,dsn=navroot.loadaut,volume=nav002
      
    • NAVROOT.USERLIB(ATTSRVR) and NAVROOT.USERLIB(ATTDAEMN) have been copied to a library within the started tasks path. If they have not been copied, add the NAVROOT.USERLIB library to this path.

  2. Activate NAVROOT.USERLIB(ATTDAEMN)as a started task to invoke the daemon.

    For example, in the SDSF screen, enter the following:

    /s ATTDAEMN
    

    To submit the daemon as a job, uncomment the first two lines of the ATTDAEMN JCL and run the job using the sub command. The ATTDAEMN JCL is similar to the following:

    //*ATTDAEMN JOB 'RR','TTT',MSGLEVEL=(1,1),CLASS=A,
    //*MSGCLASS=A,NOTIFY=&SYSUID,REGION=8M
    //STEP1 EXEC PGM=IRPCD,
    // PARM='-B START ''NAVROOT.DEF.IRPCDINI'''
    //STEPLIB DD DSN=NAVROOT.LOADAUT,DISP=SHR
    //SYSPRINT DD SYSOUT=A
    //GBLPARMS DD DSN=NAVROOT.DEF.GBLPARMS,DISP=SHR
    // EXEC PGM=IRPCD,COND=((1,EQ,STEP1),(2,EQ,STEP1)),
    // PARM='-KATTDAEMN START ''NAVROOT.DEF.IRPCDINI'''
    //STEPLIB DD DSN=NAVROOT.LOADAUT,DISP=SHR
    //SYSPRINT DD SYSOUT=A
    //GBLPARMS DD DSN=NAVROOT.DEF.GBLPARMS,DISP=SHR
    //SYSDUMP DD DUMMY
    

    Note:

    You can also run ATTDAEMN by submitting the job, without making any changes to the JCL.

Starting Multiple Daemons

You can start more than one daemon on the same system by specifying a different port number for each daemon. This option is useful, for example, when you want different users to access data on the same system using different daemon configurations.

Each daemon started must have its own configuration, which is specified when starting the daemon. In addition, the workspaces in all the configurations must be unique, so that there is no conflict between configurations and workspaces.

If you use different startup scripts in the daemon configuration settings, specify a profile of started tasks for each startup script in the security manager.

Stopping a Daemon

You can shut down the daemon on any system with Oracle Studio for IMS, VSAM, and Adabas Gateways or from the command line.

Shutting Down a Daemon Using Oracle Studio for IMS, VSAM, and Adabas Gateways

You can shut down the daemon on any system defined in Oracle Studio for IMS, VSAM, and Adabas Gateways from within the Runtime Manager perspective.

To shut down the daemon using Oracle Studio for IMS, VSAM, and Adabas Gateways

In the Runtime explorer, right-click the daemon you want to shut down and select Shutdown Daemon.

Shutting Down a Daemon Using the Command Line

You can shut down the system locally through the command line.

To shut down the daemon using the command line

On z/OS platforms, enter the appropriate command line as follows:

NAVROOT.USERLIB(IRPCDCMD)

Enter shutdown [abort[why]] at the prompt or enter a control command:

S/P ATTDAEMN or /F ATTDAEMN,STOP

Shutting down the daemon does not immediately terminate active servers. To terminate active servers, add the NVSHKILL parameter, with a value of 1, to the NAVROOT.DEF.GBLPARMS dataset (where NAVROOT is the high-level qualifier where Oracle Server is installed).

where

  • abort: If non-zero, the daemon shuts down regardless of any outstanding activity or active clients.

  • why: The reason for the shutdown, which is written to the log file.

Disabling a Workspace

You can disable a workspace, so that although it is defined for a daemon it is not operable. Server processes are not started through this workspace and a client requesting this workspace receives an error.

To disable a workspace using Oracle Studio for IMS, VSAM, and Adabas Gateways

In the Design perspective Configuration view, right-click the workspace to be disabled and select Disable.

Checking the Daemon

Check the daemon on any system defined in Oracle Studio for IMS, VSAM, and Adabas Gateways, from within the Runtime Manager perspective.

To check the status of a daemon using Oracle Studio for IMS, VSAM, and Adabas Gateways

In the Runtime explorer, right-click the server to be checked and select Status. The Runtime Explorer displays the daemon activity.

To check the status of a daemon using the command line

On z/OS platforms, enter the appropriate command line as follows:

NAVROOT.USERLIB(NAVCMD)

Enter CHECK IRPCD (daemon_location [, username, password]) at the prompt.

where

  • daemon_location: The host name with an optional port number (specified after a colon)

  • username, password: Used for logging onto the daemon.

For example, if you check a system named proc.acme.com, the following is returned if the daemon is active:

Checking IRPCD on host 'prod.acme.com'
            Trying anonymous login - OK
            This test took 0.500 seconds.

The following is displayed if the daemon is not active:

Checking IRPCD on host 'prod.acme.com'
            Trying anonymous login - FAILED, [C043]
Failed to connect to host prod.acme.com:
            PC: Connect failed - Connection refused.
            This test took 1.042 seconds.

Managing Daemon Configurations

Use Oracle Studio for IMS, VSAM, and Adabas Gateways to manage daemon configurations. The daemon can be initially configured from the Design perspective Configuration view. After initial setup, it is recommended that you make changes to the daemon configuration after monitoring it in the Runtime Manager perspective.

The Runtime Manager perspective enables managing and monitoring daemon activity. Open the Runtime Manager perspective by right-clicking a system in the Design perspective Configuration view and selecting Open Runtime Perspective. Alternatively, from the Window menu, point to Open a Perspective and select Runtime Manager.

Daemon Configuration Groups

You can have a number of daemon configurations on any system.

The daemon configuration is divided into the following groups:

  • Daemon Control: Specifies the server details, including daemon failure recovery, maximum request file size, default language, and time out parameters.

  • Daemon Logging: Specifies the logging details, such as the log file format and location, and the parameters to log and trace (as opposed to server logging, which is performed in the Workspace section).

  • Daemon Security: Specifies the administrative privileges and access for the daemon.

  • Daemon Workspaces: The workspaces defined for the daemon. A daemon can include a number of workspaces. A workspace defines the server processes and environment that are used for the communication between the client and the server system for the duration of the client request. Each workspace has its own definition and includes the data sources and applications that can be accessed as well as various environment variables.

    The workspace definition is divided into the following groups:

    • WS Info: Specifies general information including the server type, the command procedure used to start the workspace, the binding configuration associated with this workspace (which dictates the data sources and applications that can be accessed), and the timeout parameters.

    • WS Server: Specifies workspace server information including features that control the operation of the servers started up by the workspace and allocated to clients.

    • WS Logging: Specifies workspace tracing options.

    • WS Security: Specifies administration privileges, user access, ports available for access to the workspace and workspace account specifications.

    • WS Governing: Specifies the way queries are executed. This is used particularly when running queries against large tables.

    Note:

    The default daemon configuration supplied with Oracle Connect for IMS, VSAM, and Adabas Gateways includes the default Navigator Workspace. This workspace is automatically used if a workspace is not specified.

Adding and Editing Daemon Configurations

The daemon is configured in the Design perspective Configuration view in Oracle Studio for IMS, VSAM, and Adabas Gateways.

A system can have a number of daemons running at the same time, each on its own port.

Configuring Logging

You can set up logging for the following:

  • Daemon log files

  • Workspace server process log files

Adding and Editing Workspaces

Daemons include workspaces that define the server processes and environment that are used for the communication between the client and the server system for the duration of the client request. A workspace definition is set in the Oracle Studio for IMS, VSAM, and Adabas Gateways Design perspective Configuration view, under the daemon that manages it.

Adding a Workspace

When you define a new workspace, you can copy the values of an existing workspace on the same daemon or have Oracle Connect for IMS, VSAM, and Adabas Gateways set its default values.

To add a new workspace

  1. In Oracle Studio for IMS, VSAM, and Adabas Gateways Design Perspective Configuration view, expand the Machine folder and then expand the system with the daemon where you want to add the workspace.

  2. Expand the daemon folder.

  3. Right-click the daemon where you want to add the workspace and select New Workspace.

    Figure 13-1 New Daemon Workspace

    This is the New Daemon Workspace screen.
    Description of "Figure 13-1 New Daemon Workspace"

    Note:

    You can add a new daemon configuration in offline design mode, in a design system and later drag-and-drop the daemon configuration to this system.
  4. In the New Daemon Workspace screen, enter the following:

    • Name: The name used to identify the workspace. The workspace name is made up of letters, digits, underscores (_) or hyphens (-)

      Note:

      On HP NonStop or mainframe computers, limit the name of a workspace to five characters so that the system environment file, workspaceDEF, does not exceed eight characters. Workspace names greater than five characters are truncated to five character and the default workspace, Navigator, will look for a system environment called NavigDEF.
    • Description: A short description of the workspace.

  5. From the Workspace data section, select one of the following:

    • Create empty workspace with default values

    • Copy properties from another workspace

      If you copy the properties from another workspace, the fields below the selection become active. You must indicate the workspace from where you want to copy the properties. Enter the following information:

      <name of the workspace> in <name of the daemon where the workspace is located> on <name of machine where the daemon is located>.

      Alternatively, you can click the browse button to select the workspace you want to use. The above information is added automatically.

  6. Click Next to open the select scenario screen. In this screen you select the type of applications the daemon works with. Select from the following options:

    • Application server using connection pooling.

    • Stand-alone applications that connect and disconnect frequently.

    • Applications that require long connections, such as reporting programs and bulk extractors.

    • Custom (configure manually). If you select this option, the Workspace editor opens.

  7. Click Next to open the next screen. In this screen, select one of the following. The options available depend on the scenario selected:

    • The minimum number of server instances available at any time: This is the minimum number of connections that are available at any time. If the number of available connections drops below this number, the system will create new connections. (Available if you select Stand-alone applications that connect and disconnect frequently).

    • The maximum number of server instances available at any time: This is the maximum number of connections that are available at any time. If the number of connections used reaches this number, no additional server connections can be made. (Available if you select Stand-alone applications that connect and disconnect frequently).

    • The average number of expected concurrent connections: This lets the system know how much the average load will be and helps to distribute the resources correctly. (Available if you select Application server using connection pooling. or Stand-alone applications that connect and disconnect frequently).

    • The maximum number of connections: This is the maximum number of connections that will be available. If the number of requests exceeds this number, an error message is displayed that informs the user to try again when a connection becomes available. (Available if you select Application server using connection pooling. or Stand-alone applications that connect and disconnect frequently).

    • How many connections you want to run concurrently. This sets the number of connections that will run at the same time. (Available if you select Applications that require long connections, such as reporting programs and bulk extractors).

  8. Click Next to open the next screen and enter the amount of wait time for the following parameters. If your system is not too overloaded, you can leave the default times.

    • How long to wait for a new connection: Enter the amount of time (in seconds) to wait for a connection to be established before the system times out. For example if you want a wait time of one minute enter 60 (the default). If you enter 0, the time is unlimited.

    • How long to wait for a response that is usually fast: Enter the time (in seconds) to wait for a response from the system before the system times out. For example if you want to wait for one minute, enter 60. The default is 0, which indicates unlimited wait time.

  9. Click Next to open the next screen. Enter the workspace security information in this screen. You can determine which users or groups can access the workspace you are defining. See Chapter 14, "Managing Security for Oracle Connect for IMS, VSAM, and Adabas Gateways" for more information.

  10. Click Next to open the summary screen. Look at the summary to be sure that all the information entered is correct. If you need to make any changes, click Back to get to the required screen.

  11. Click Finish to close the wizard and add the new workspace to the Configuration view.

Editing a Workspace

After you add a workspace, you can make changes to the workspace's configuration. You can edit the information in the following workspace editor tabs:

  • WS Info: Specifies general information including the server type, the command procedure used to start the workspace, the binding configuration associated with this workspace (which dictates the data sources and applications that can be accessed) and the timeout parameters.

  • WS Server: Contains the workspace server information including features that control the operation of the servers started up by the workspace and allocated to clients.

  • WS Logging: Contains the information about workspace tracing options.

  • WS Security: Contains administration privileges, user access, ports available for access to the workspace and workspace account specifications.

  • WS Governing: Contains information about how queries are executed. This is often used when running queries on large tables.

To edit a workspace

  1. In the Design Perspective Configuration view, expand the Machines folder and then expand the system where you want to edit the workspace.

  2. Expand the daemon folder.

  3. Expand the daemon with the workspace you want to edit.

  4. Right-click the workspace you want to edit and select one of the following:

    • Workspace Setup Wizard: Opens the wizard that was used to add a new workspace (see Adding a Workspace). Make any required changes to the wizard settings to change the workspace definition.

    • Edit Workspace: Opens the editor. The editor includes the information that was entered in the New Workspace wizard. Click the following tabs to edit the information:

    Note:

    The default daemon configuration supplied with Oracle Connect for IMS, VSAM, and Adabas Gateways includes the default Navigator Workspace. This workspace is automatically used if no workspace is selected.

WS Info

You enter information about the features that control the workspace operations in the WS Info tab. This information includes the server type, the command procedure used to start the workspace and the binding configuration associated with this workspace.

The following figure shows the WS Info tab:

Note:

You can also change daemon settings using the Configuration view, by selecting a computer and scrolling the list to the required daemon. Right-click the daemon and select Edit Daemon.

Changes made to the daemon configuration do not take effect immediately. They will take effect only after the configuration is reloaded using the Reload Configuration option in the Runtime Manager.

The following table shows the WS Info tab's fields:

Table 13-1 WS Info Tab

Field Description

Workspace name

The name used to identify the workspace.

Note: The default configuration includes the default Navigator workspace. This workspace is automatically used if a workspace is not specified as part of the connection settings.

Description

A description of the workspace.

Startup script

The full path name of the script that starts the workspace server processes. The script specified here must always activate the nav_login procedure and then run the server program (svc). If you do not specify the directory, the startup procedure is taken from the directory where the daemon resides. Oracle Connect for IMS, VSAM, and Adabas Gateways includes a default startup script, which is recommended. Enter the script name only because the server is activated as a started task.

Server type

The workspace server type. For example, IMS, Java, events, or native.

Workspace binding name

The name of a specific binding configuration on the server system that you want to use with this workspace.

For z/OS, the name of the binding must be five characters or less and the name must be surrounded by single quotes.

If the high-level qualifier is not specified here, INSTROOT.DEF is assumed, where INSTROOT is the high-level qualifier specified when Oracle Connect for IMS, VSAM, and Adabas Gateways server is installed.

Workspace database name

Enter a name of a virtual database that this workspace accesses if applicable. A virtual database presents a limited view of the available data because only selected tables from either one or more data sources are available, as if from a single data source. If a value is entered in this field, only the virtual database can be accessed using this workspace.

Timeout parameters

The following two properties define the time the client waits for the workspace server to start. If the workspace server does not start within this period, then the client is notified that the server did not respond. Entering a timeout value for these properties overrides the default setting entered in the Daemon Control tab.

Client idle timeout

The maximum amount of time a workspace client can be idle before the connection with the server is closed.

Connect timeout

The time the client waits for a workspace server to start. If the workspace server does not start within this period, then the client is notified that the server did not respond.


WS Server

You enter the features that control the operation of the servers started up by the workspace and allocated to clients in the WS Server tab. For example, you can configure the workspace to use connection pooling and to start up a number of servers for future use, prior to any client request, instead of starting each server when a request is received from a client.

Figure 13-3 WS Server Tab

WS Server tab
Description of "Figure 13-3 WS Server Tab"

Notes:

  • You can also change daemon settings using the Configuration view, by selecting a computer and scrolling the list to the required daemon. Right-click the daemon and select Edit Daemon.

  • Changes made to the daemon configuration do not take effect immediately. They will take effect only after the configuration is reloaded using the Reload Configuration option in the Runtime Manager.

The following table shows the WS Server tab's fields:

Table 13-2 WS Server Tab

Field Description

Workspace server mode

Specifies the type of new server processes that the daemon starts up. The daemon supports the following server modes:

  • singleClient: Each client receives a dedicated server process. The account in which a server process runs is determined either by the client login information or by the specific server workspace.

    This mode enables servers to run under a particular user account and isolates clients from each other, as each receives its own process. However, this server mode incurs a high overhead due to process startup times and can use a lot of server resources as it requires as many server processes as concurrent clients.

  • multiClient: Clients share a server process and are processed serially. This mode has low overhead because the server processes are already initialized. However, because clients share the same process, they can impact one another, especially if they issue lengthy queries. The number of clients that share a process is determined by the Clients per server limit field.

  • multiThreaded (Windows only): Clients are allocated a dedicated thread in a shared server process.

    This mode has low overhead since the servers are already initialized. However, because clients share the same process, they may impact one another, especially if the underlying database is not multi-threaded.

    The number of multi-threaded clients that share a process is set in the Clients per server limit field (the maximum number of concurrent clients a server process for the current workspace accepts) in the Oracle Studio for IMS, VSAM, and Adabas Gateways Design perspective configuration tab. This value is set in the daemon configuration settings maxNClientsPerServer parameter.

    Notes:

    Multiple multi-client and multi-threaded servers can be started at the same time for optimal performance.

  • reusable: An extension of single-client mode. Once the client processing finishes, the server process does not die and can be used by another client, reducing startup times and application startup overhead.

    This mode does not have the high overhead of single-client mode because the servers are already initialized. However, this server mode can use a lot of server resources as it requires as many server processes as concurrent clients.

    The other modes can be set so that the server processes are reusable. The number of times a process can be reused is controlled by the Reuse limit field value in Oracle Studio for IMS, VSAM, and Adabas Gateways (the maximum number of times a server process can be reused or how many clients it can serve before it finishes). Reuse of servers enhances performance since it eliminates the need to repeat initializations. However, reuse runs a risk or using more memory over time. The default for the Reuse Limit field value is 0, which means that there is no limit.

Reuse limit

Sets the maximum number of times a particular server can be reused. A one-client server can be reused after its (single) client has disconnected. Reuse of servers enhances startup performance because it avoids the need to repeat initialization.

  • Select none, if the server reuse is unlimited

  • Select maximum, and then enter a maximum number of clients accepted in a server process.

This parameter is not available if the server mode value is singleClient.

Clients per server limit

Sets the maximum number of clients that a server process for the current workspace accepts. The default for this field is None, indicating that the number of clients for each server is unlimited. This field is available if the server mode value is multiClient or multiThreaded.

Server availability

Specifies the number of servers in a pool of servers, available to be assigned to a client.

The following options are available:

  • Initial number of servers: The number of server processes that are prestarted for this workspace when the daemon starts up. When the number of available server processes drops lower than the value specified in the Minimum number field, the daemon again starts server processes until this number of available server processes is reached. The default for this field is 0.

  • Minimum number of available servers: The minimum number of server processes in the prestarted pool before the daemon resumes creating new server processes (to the value specified in the Initial number of servers field). If this field is set to a value higher than the Initial number of servers field, the daemon uses the value specified in the Initial number of servers field. The default for this field is 0.

  • Keep when daemon ends: Select this to kill all servers started by that daemon when a daemon is shutdown, even if they are active. Select this if you want the servers for the workspace to remain active, even after the daemon has been shut down. If selected, it is the responsibility of the system operator or manager to ensure that the servers are eventually killed. This must be done at the system level.

  • Set maximum number of servers: The maximum number of available server processes. Once this number is reached, no new nonactive server processes are created for the particular workspace. For example, if a number of server processes are released at the same time, so that there are more available server processes than specified by this field, the additional server processes higher than this value are terminated. The default for this field is zero, meaning that there is no maximum.

Resource limitations

Lets you set the number of servers that can be in use at any one time. The more servers used, the greater the system resources that are used.

Number of sub-tasks: Set the maximum number of active server processes (either available or in use). Once reached, no new server processes will be created for the particular workspace and client connections will be rejected if there is no available server to accept them. Once the number of active servers drops below the maximum (for example, a client disconnects from a server and the server terminates), new servers can again be started. If the value of this field is set to a value other than zero, and is lower than the value for the Initial number of servers field, the daemon assumes it is set to the same value as the Initial number of servers field. The default for this field is 0, meaning that no maximum is enforced.

Limit number of active servers: Select this if you want to limit the number of active servers.

Server Priority

The priority for servers. For example, a workspace for applications with online transaction processing can be assigned a higher priority than a workspace that requires only query processing.

The following priority options are available:

  • Use default priority: Sets the priority as 0. There is no specific priority for this workspace.

  • Use priority specified: Enables setting the priority.


WS Logging

Use this tab to configure the Logging preferences for the workspace. The following figure shows the WS Logging tab:

Figure 13-4 The WS Logging Tab

This is the WS Logging Tab
Description of "Figure 13-4 The WS Logging Tab"

Notes:

  • You can also change daemon settings using the Configuration view, by selecting a computer and scrolling the list to the required daemon. Right-click the daemon and select Edit Daemon.

  • Changes made to the daemon configuration do not take effect immediately. They will take effect only after the configuration is reloaded using the Reload Configuration option in the Runtime Manager.

  • For z/OS, the default is to write the log entries to the job only

The following table describes the fields in the WS Logging tab:

Table 13-3 WS Logging Tab

Field Description

Specific log file format

Select this to define the name and location of the server log file if you want the data written to a file instead of SYSOUT for the server process. The parameter must specify the name and the high level qualifier.

You can enter the following wildcards in this field to generate the following information:

  • %A: workspace name

  • %D: date (yymmdd)

  • %I: instance number of the given workspace server

  • %L: server account's login directory

  • %P: server's process ID

  • %T: time (hhmmss)

  • %U: server's account name (username)

Trace options

Specifies the type of tracing. The following tracing options are available:

  • No timeout: Select this to disable the standard RPC timeouts, setting them to a long duration (approximately an hour) to facilitate debugging.

  • Call trace: Select this to generate a message in the server log file for each RPC function called. This is useful for troubleshooting the server.

  • RPC trace: Select this to enable debugging messages on the server.

  • Sockets: Select this to generate a message in the server log file for each socket operation. This is useful for troubleshooting client/server communication by providing a detailed trace of every client/server communication.

  • Extended RPC trace: Select this to generate a more detailed message in the server log file for each low-level RPC function called. This is useful for troubleshooting the server.

  • System trace: Select this to generate operating system-specific tracing.

  • Timing: Select this to generate a timestamp for every entry to the server log file.

Event Information

This section is divided into the following categories.

Logging

Specifies the level of events that are logged for the workspace. The following event levels are available:

  • none: Select this to only display the IP addresses of client that have logged in and out from the workspace.

  • error: Select this to display the IP addresses for clients that have logged in and out from the workspace and any generated errors.

  • debug: Select this to display the IP addresses for clients that have logged in and out from the workspace, any generated errors, and all trace results that were specified in the Daemon Logging tab.

Server

Specifies the server connection events to log. The following server events are available:

  • Connect: Select this to display the server connection events.

  • Disconnect: Select this to display the server disconnect events.

Client

Specifies the type of tracing performed. The following client events are available:

  • Connect: Select this to display the client connection events.

  • Disconnect: Select this to display the client disconnect events.


WS Security

Configure the security level for a workspace in the Workpace editor WS Logging tab. This lets you set the security options for the workspace only. See Appendix 14, "Managing Security for Oracle Connect for IMS, VSAM, and Adabas Gateways" for more information. The WS Security section is used:

  • To grant administration rights for the workspace

  • To determine access to the workspace by a client

The following figure shows the WS Security Tab:

Figure 13-5 WS Security Tab

The WS Security Tab
Description of "Figure 13-5 WS Security Tab"

The following table describes the fields in this tab:

Table 13-4 WS Security Tab

Field Description

Workspace access:

The following fields define the users (accounts) allowed to access the workspace, firewall access ports, workspace account, and anonymous login permissions.

Workspace users

Indicate which users are allowed to use the workspace. Select one of the following

  • All users: Any user who has logged on to the daemon may use the workspace

  • Selected users only: Select this to allow only users (or accounts) with specific permission to use the workspace.

    When this is selected, add the names of users (or accounts) and groups that can use the workspace in the field below.

    To define a group of users on z/OS platforms, preface the name of the group in the configuration with '@'. The group name is validated by a security system such as RACF.

    Note: If no user is specified, any user who has logged on to the daemon may use the workspace.

Enable port range

Select this to define specific firewall ports through which you access the workspace. Specifies the range of ports available for this workspace when starting server processes. Use this option when you want to control the port number, so that Oracle Connect for IMS, VSAM, and Adabas Gateways can be accessed through a firewall.

If this is selected, enter the port range in the following fields:

  • To port: Enter the highest numbered port in the range

  • From port: Enter the lowest numbered port in the range

Use specific workspace account

Select this if you want to define the operating system account used for the workspace.

If selected, enter the name of the workspace account in the workspace account field.

If not selected, the account name that was provided by the client is used.

Allow anonymous client login to server account

Select this if you want to allow this workspace to be invoked without authentication.

If selected, enter the name of the workspace account in the workspace account field.

If this field is not selected, then the value in the Workspace account field is used.

Administration:

The following fields define the users (accounts) allowed to perform administrative tasks (tasks that require administrative login) on this workspace.

Administrator privileges

Identifies the users (accounts) with administrator privileges. Select one of the following:

  • All users: Indicates that anyone can access the workspace and change the settings.

  • Selected users only: Select this to allow only users (or accounts) with specific permission to be administrators.

    When this is selected, add the names of users (or accounts) and groups that can be workspace administrators.

    If no user is specified, any user who has logged on to the daemon may administrator this workspace.

Allow Listing

Select this if you want this workspace to appear in the list of workspaces.


WS Governing

The WS Governing tab lets you manage the way queries are executed for the workspace.

Query governing parameters are defined at the workspace levels. All restrictions that are configured apply to all queries for all data sources that require Oracle Connect for IMS, VSAM, and Adabas Gateways metadata and which are defined in the binding associated with the workspace.

The workspace governing parameters only apply to data sources that require Oracle Connect for IMS, VSAM, and Adabas Gateways metadata.

The following figure shows the WS Governing tab:

Figure 13-6 WS Governing Tab

The WS GoverningTab
Description of "Figure 13-6 WS Governing Tab"

The following table describes the WS Governing tab's fields:

Table 13-5 WS Governing Tab

Field Description

Max Number of Row in a Table That Can Be Read

Enter the maximum number of table rows that are read in a query. When the number of rows read from a table exceeds the number stated, the query returns an error.

Max Number of Rows Allowed in a Table Before Scan is Rejected

Enter the maximum number of table rows that can be scanned. This parameter has different behavior for query optimization and execution.

  • For query optimization, the value set is compared to the table cardinality. If the cardinality is greater than the value, the scan strategy is ignored as a possible strategy (unless it is the only available strategy).

  • For query execution, a scan is limited to the value set. When the number of rows scanned exceeds the number entered, the query returns an error.


Managing Binding Configurations

The information needed by Oracle for accessing applications, data sources and events is defined in a binding configuration.

A binding configuration always exists on a server system, where data sources and applications to be accessed using Oracle reside. Additionally, a binding configuration can be defined on a client system to point to data sources on a server system.

Server Binding

A binding configuration on a server includes:

  • Data source definitions for data sources that can be accessed using Oracle Connect for IMS, VSAM, and Adabas Gateways, including data source specific properties.

  • Data source shortcuts to data sources on other server systems and other server systems that can be accessed from the current system.

  • Event queue definitions for event queues that are managed using Oracle Connect for IMS, VSAM, and Adabas Gateways, including event specific properties.

Client Binding

A binding configuration on a client includes:

  • Data source shortcuts to data sources on other server systems and other server systems that can be accessed from the current system.

  • You can create a new binding configuration or modify existing binding settings using the Oracle Studio for IMS, VSAM, and Adabas Gateways Design perspective Configuration view.

    NAV is the default binding configuration. You can use this configuration to define all the data sources you want to access through Oracle Connect for IMS, VSAM, and Adabas Gateways.

Binding Syntax

The binding settings in XML format include the following statements:

  • A <remoteMachines>statement, specifying the remote systems that can be accessed, through <remoteMachine> statements.

  • <remoteMachine> statements, defining the remote systems available from the current system.

  • A <datasources> statement, specifying the data sources that can be accessed, through <datasource>> statements.

  • <datasource> statements, specifying the following for each data source the client can access: a name to identify the data source, the type of the data source and general information.

  • <config> statements, specifying specific properties for a data source driver.

<remoteMachines> Statement

The <remoteMachines> statement lists the names of the accessible servers, through <remoteMachine> statements. These statements are only necessary when connecting to data sources through a shortcut on the client system.

<remoteMachine> Statement

The <remoteMachine> statement lists names and IP addresses of the remote systems where data sources reside and which are accessed using data source shortcuts on the current system. The names are used as aliases for the IP addresses in the <datasource> statements. This enables you to redefine the location of a group of data sources (on a given system) by changing the IP address associated with this alias. The format is:

<remoteMachine name="alias" address="address"
               port="port_number"
               workspace="workspace"
               encryptionProtocol="RC4|DES3"
               firewallProtocol="none|nat|fixednat"/>

where:

name: The name of the remote system that will be recognized by Oracle Connect for IMS, VSAM, and Adabas Gateways. The maximum length is 32 characters and must start with a character. This name cannot be the name of a data source specified in a <datasources> statement.

Note:

The name does not need to relate to the name of the system on the network.

address: The IP address type of the remote system.

port: The port on the remote system where the Oracle Connect for IMS, VSAM, and Adabas Gateways daemon is running. If you do not specify a port number, the system allocates the default Oracle-uda-server port number 2551.

workspace: The specific working configuration specified for this binding by the daemon. A workspace must be defined in the daemon configuration on the remote system.

encryptionProtocol: The protocol used to encrypt network communications. Oracle Connect for IMS, VSAM, and Adabas Gateways currently supports the RC4 and DES3 protocols.

firewallProtocol: The firewall protocol used. Valid values are none, nat or fixednat. The default is none. NAT (Network Address Translation) is a firewall protocol where internal IP addresses are hidden, enabling a network to use one set of IP addresses for internal traffic and a second set of addresses for external traffic. NAT makes all necessary IP address translations. However, using NAT requires every access by every client to go through the daemon port, even after a specific server process has been assigned to handle the client. Specifying fixednat for this parameter sets Oracle Connect for IMS, VSAM, and Adabas Gateways to access this remote system through a firewall using NAT with a fixed IP address. When the server address is returned to the client and the client sees that the IP is not the same IP of the daemon, it ignores the IP and uses the daemon's IP instead. It is recommended to use fixednat to access data through a firewall.

Example <remoteMachines> Statement

Example 13-1 <remoteMachines> Statement

<remoteMachines>
  <remoteMachine name="ALPHA_ACME_COM"
                 address="alpha.acme.com" /> 
  <remoteMachine name="SUN_ACME_COM"
                 address="sun.acme.com
                 port="8888" workspace="PROD" /> 
</remoteMachines>

<datasources> Statement

Lists the accessible data sources, through <datasource> statements.

<datasource> Statement

A <datasource> statement specifies the name and type of the data source and information required in order to connect to the data source.

The basic format is:

<datasource name="name" type="type" attribute="value">  <config .../></datasource>

where:

name: The name of the data source that will be recognized by Oracle Connect for IMS, VSAM, and Adabas Gateways. The maximum length is 32 characters. The name cannot include hyphens (“-”). It can include underscores (“_”). This name cannot be the name of a system specified in a <remoteMachines> statement.

type: The type of the data source to be accessed. This value is different for each data source driver. Refer to a specific data source driver for the value of this parameter. The value of this field when defining a data source shortcut (where the data source is located on another system) is REMOTE.

attribute: General data source attributes, such as specifying the data as read only. These attributes are set in Oracle Studio for IMS, VSAM, and Adabas Gateways in the data source advanced tab.

Table 13–6 describes additional attributes of the <datasource> statement.

When the value of an attribute can be true or false, if the value is not specified, the attribute is equivalent to a value of false. The following table describes the attribute behavior when the value is set to true.

Table 13-6 Data Source Statement Table

Data Source Advanced Tab in Oracle Studio for IMS, VSAM, and Adabas Gateways Attribute Description of Value

Transaction type

transactionType="trnLevelSupport|datasourceDefault"

The transaction level (0PC or 2PC) that is applied to this data source, irrelevant of what level the data source supports. The default is the data source default level, ("datasourceDefault").

Syntax name

For more details about this field, see Using the Oracle Connect for IMS, VSAM, and Adabas Gatewayst Syntax File (NAV.SYN).

syntaxName="value"

A section name in the NAV.SYN file specifying SQL syntax variations. The default syntax file contains the following predefined sections:

Oracle driver and Oracle case-sensitive data:syntaxName="ORACLE8_SYNTAX"Or, syntaxName="ORACLE_SYNTAX"

For case sensitive table and column names in Oracle, use quotes (") to delimit the names. Specify the case sensitivity precisely.

Default table owner

owner="value"

The name of the table owner that is used if an owner is not specified as part of the SQL.

Read/Write Information

readOnly="true|false"

true: Specifies read-only mode. All update and data definition language (DDL) operations are blocked.

Repository Information

Repository directory

objectStoreDir="value"

Specifies where the repository for a specific data source is located.

Repository Information

Repository name

objectStoreName="value"

Specifies the name of a repository for a specific data source. The name is defined as a data source in the binding configuration with a type of Virtual and is used to store Oracle Connect for IMS, VSAM, and Adabas Gateways views and stored procedures specific to the data source, when this is wanted in preference to the default SYS data.


Example 13-2 <datasources> Statement

<datasources name="NAV">
 <datasource name="ADABAS" type="ADABAS">
    <config dbNumber="3" predictFileNumber="7"/>
 <datasource name="ORACLE8" type="ORACLE8">
            <config oracleConnect="@ora9201_ibm4"/>
 </datasource>
 <datasource name="DISAM" type="ADD-DISAM">
    <config newFileLocation="/users/nav/dis"/>
 </datasource>
</datasources>

<config> Statement

A <config> statement specifies configuration properties of a data source. The configuration information is specific to each data source.

The basic format is:

<datasource name="name" type="type">
  <config attribute="value" attribute="value"
          ... />
</datasource>

where:

attribute: The name of the configuration property.

value: The value of the configuration property.

Example 13-3 <config> Statement

<datasources>
  <datasource name="ORACLE8" type="ORACLE8">
            <config oracleConnect="@ora9201_ibm4"/>
  </datasource>
</datasources>

Sample Binding

The following is an example of binding information:

<?xml version="1.0" encoding="ISO-8859-1"?>
<navobj version="...">
  <bindings>
    <binding name="NAV">
      <remoteMachines>
        <remoteMachine name="SUN_ACME_COM"
                       address="sun.acme.com"
                       workspace="PROD"/>
      </remoteMachines>
      <environment name="NAV">
        <debug generalTrace="true"/>
        <misc/>
        <queryProcessor/>
        <optimizer goal="none" preferredSite="server"/>
        <transactions/>
        <odbc/>
        <oledb/>
        <tuning/>
      </environment>
      <datasources name="NAV">
        <datasource name="NAVDEMO" type="ADD-DISAM">
            <config newFileLocation="$NAVDEMO"/>
        </datasource>
        <datasource name="ORA_EXT" type="ORACLE8"
                    connect="@ora8_ntdb"/>
        <datasource name="ORA" type="remote"
                    connect="sun_acme_com"/>
      </datasources>
    </binding>
  </bindings>
</navobj>

This binding configuration provides information for the NAVDEMO sample data source and for a local data source (an ORA_EXT Oracle database), and one remote data source.

Note:

The XML representation of the binding configuration is displayed in the Oracle Studio for IMS, VSAM, and Adabas Gateways Design perspective Configuration view, by editing the specific binding configuration and viewing the Source tab.

Environment Properties

Each binding configuration includes its own environment, specified in the environment properties.

To display environment properties for the binding configuration in Oracle Studio for IMS, VSAM, and Adabas Gateways, right-click the binding configuration and select Edit Binding.

The environment properties are listed on the Properties tab.

The following table lists the environment propertiesFoot 1  in their respective categories.

Table 13-7 Environment Properties

Category Parameter Name Default Value Description

comm

comCacheBufferSize

200000 bytes

The size of a memory buffer on a client, which is used by the Oracle Connect for IMS, VSAM, and Adabas Gateways client/server to store read-ahead data.

 

comMaxSocketSize

-1

The maximum bytes that can be written in one chunk on a socket. The default value indicates no limitation.

 

conmMaxXmlInMemory

65535 bytes

The maximum size of an XML document held in memory.

 

conmMaxXmlSize

65535 bytes

The maximum size of an XML document passed to another system.

 

commXmlTransportBufferSize

-1

The maximum size of the internal communications buffer. The default value (-1) indicates there is no size limit.

 

sockReceiveWindowSize

 

This parameter affects the communication sockets created by Oracle Connect for IMS, VSAM, and Adabas Gateways. It is intended for use for fine-tuning Oracle Connect for IMS, VSAM, and Adabas Gateways network performance. For further details, see TCP/IP documentation.

 

sockSendWindowSize

 

This parameter affects the communication sockets created by Oracle Connect for IMS, VSAM, and Adabas Gateways. It is intended for use for fine-tuning Oracle Connect for IMS, VSAM, and Adabas Gateways network performance. For further details, see TCP/IP documentation.

 

sockTcpMaxSegmentSize

 

This parameter affects the communication sockets created by Oracle Connect for IMS, VSAM, and Adabas Gateways. It is intended for use for fine-tuning Oracle Connect for IMS, VSAM, and Adabas Gateways network performance. For further details, see TCP/IP documentation.

 

sockTypeOfService

default

This parameter affects the communication sockets created by Oracle Connect for IMS, VSAM, and Adabas Gateways. It is intended for use for fine-tuning Oracle Connect for IMS, VSAM, and Adabas Gateways network performance. For further details, see TCP/IP documentation.

Supported service types are:

  • default

  • lowDelay

  • throughput

  • reliability

  • lowCost

debug

acxTrace

false

When set to true, specifies that the input XML sent to the data source and the output XML returned by the data source, are written to the log file.

 

adminTrace

   
 

analyzerQueryPlan

false

When set to true, specifies that the Query Optimizer plan is written to a plan file for analysis using the Oracle Connect for IMS, VSAM, and Adabas Gateways Query Analyzer.

 

apiTrace

   
 

binaryXmlLogLevel

none

Sets the binary XML log level. This parameter is used for troubleshooting.

The following logging levels are available:

  • none

  • api

  • info

  • debug

 

bindingTrace

   
 

consoleTrace

   
 

debugCriticalSections

   
 

debugLibraryLoad

   
 

driverTrace

   
 

fileTrace

   
 

gdbTrace

false

When set to true, logs the transactions of the driver created using the Oracle Connect for IMS, VSAM, and Adabas Gateways SDK.

 

generalTrace

false

When set to true, logs the general trace information used by Oracle Connect for IMS, VSAM, and Adabas Gateways. The default writes only error messages to the log.

Note: Changing the default setting can degrade Oracle Connect for IMS, VSAM, and Adabas Gateways performance.

 

ignoreEnv

   
 

invokeDebugger

   
 

keepTempFiles

   
 

logFile

 

The full path and filename of the log file for messages. The default log file (NAV.LOG) is located in the TMP directory under the directory where Oracle Connect for IMS, VSAM, and Adabas Gateways Server is installed.

To send log messages to the console, instead of a file, set logFile to a minus, "-", character.

The following types of message are written to the log:

  • Error messages.

  • Trace information about the query optimization strategy (when genralTrace is set to true).

z/OS: The default Oracle Connect for IMS, VSAM, and Adabas Gateways log file is NAVROOT.DEF.NAVLOG, where NAVROOT is the high-level qualifier specified when Oracle Connect for IMS, VSAM, and Adabas Gateways Server is installed.

 

memoryLogFile

   
 

memoryReport

   
 

memoryTrace

   
 

nosTrace

   
 

oledbTrace

false

When set to true, logs the trace information used when working with OLE DB providers.

The default writes only error messages to the log.

Note: Changing the default setting can degrade Oracle Connect for IMS, VSAM, and Adabas Gateways performance.

 

optimizerTrace

false

When set to true, trace information and information about the query optimizer strategy is written to the log file.

 

queryWarnings

false

When set to true, generates a log file of Query Processor warnings.

 

shellTrace

   
 

sortTrace

   
 

spyTrace

   
 

threadTrace

   
 

timeTrace

false

When set to true, adds a timestamp on each event row in the log.

 

traceDir

 

The directory where Oracle Connect for IMS, VSAM, and Adabas Gateways writes the log generated by the optimizer files (with a PLN extension). The optimizer files include details of the optimization strategy used by Oracle Connect for IMS, VSAM, and Adabas Gateways. By default, these files are written to the same directory as the log file (see logFile, above).

 

transactionTrace

false

When set to true, logs 2PC and XA transactions-related events.

 

triggerTrace

false

When set to true, logs trigger information. This parameter is used when working with triggers.

miscellaneous

arrayMetadataModel

virtualArray Views

Specifies the environment array metadata model. Changing this parameter has no effect.

 

basedDate

   
 

basedDateNullability

   
 

codepage

 

For use with National Language Support (NLS) to identify the charset for the workspace.

If the charset parameter is blank and a language is specified, a default charset is used, based on the language specified and the system. For details of these defaults, refer to language, below.

For information on the supported charsets, see any of the following:

 

compressObjectStore

false

Enables compressing objects in the repository that take up more than 2K storage. The default value is false (compression is not performed) for all bindings.

 

cvtLevelSeverity

0

The data type conversion policy when a conversion error occurs. The following policies are available:

  • 0: The data in the output column will be a null or empty value.

  • 1: The data in the output column will be a null or empty value and the error is reported to the log.

  • 2: An error is reported and processing stops.

 

edit

 

The text editor for use by the NAV_UTIL EDIT command. The default is the native text editor for the operating system.

 

exposeXmlField

false

When set to true, data returned for a query is displayed as XML, representing the true structure of the result. This is especially useful when querying a data source table that contains arrays or variants.

 

generateUniqueIndexNames

false

Enables to expose non relational index names. When set to true, all the non relational indexes names are exposed as table_name_KEYkey_number.

 

language

English

For use with National Language Support (NLS) to identify the application language.

For information on the supported language codes, see any of the following:

 

nlsString

false

Specifies the charset used by a field whose data type is defined as "nlsString". You use this for a field whose charset is other than that of the system's charset. This parameter includes the following values:

  • The name of the charset.

  • Whether the character set reads from right to left (as in middle-eastern character sets).

For example, the following specifies a Japanese EUC 16-bit charset:

<misc nlsString="JA16EUC,false"/>
 

readV3Definition

true

This parameter is used when upgrading Oracle Connect for IMS, VSAM, and Adabas Gateways from version 3.xx

 

replaceInvalidXmlCharacters

false

Replaces invalid XML characters with a '?'. It is used for diagnostic and troubleshooting purposes.

 

tempDir

 

The directory where temporary files are written, including the temporary files created for use by hash joins and for sorting files. The default is the current directory.

The following is recommended for this parameter:

  1. Specify a directory that contains temporary files only. You can then easily remove these files if necessary (for example, if the process stopped in the middle).

  2. Specify a directory on a disk that has a significant amount of free disk space.

 

xmlDateFormat

ISO

Sets the XML date format used. Options include:

  • ISO: The date format is: YY-MM-DDThh:mm:ss[.ss..]

  • ODBC: The date format is: YYYY-MM-DD HH:MM:SS[.NNN...]

 

xmlFieldName

XML

The name used in a query to indicate that the data is returned as XML, instead of the keyword XML. The parameter is effective only after the exposeXmlField parameter, described above, is set.

 

xmlTrimCharColumns

true

Enables padded spaces to be trimmed from XML string columns when the record format of is fixed. The default attribute value for this property is true, meaning that padded spaces are trimmed for fixed size char columns.

 

year2000Policy

5

Determines how 2-digit years are converted into 4-digit years. Two policies are provided:

  • Fixed Base Year: year2000Policy is set to a value greater than, or equal to 1900. In this case, the value of year2000Policy is the first 4-digit year after 1900 that can be represented by a 2-digit year. For example, if year2000Policy is set to 1905, the years 2000->2004 will be represented by 00->04. All other 2 digits will map to 19xx.

  • Sliding Base Year: year2000Policy is set to a positive value less than 100. In this case, the value of year2000Policy represents the number of years ahead of the current year that can be represented by a 2-digit number. With each passing year the earliest year that can be represented by a 2-digit number changes to a year later.

    When the parameter is not set, or when it is set to a value outside the range of values defined for the above policies, a default value of 5 and the Sliding Base Year policy is used.

 

generateUniqueIndexNames

 

Generates a unique name for every index on a table that is defined in a non-relational system. The default value for this property is false. When set to true, the names of all indexes on non-relational tables are exposed in the following format: table_name_KEYkey_number. For example, if a table is called X, the name of the first index would be X_KEY0.

 

reducedSequentialFlattening

false

Specifies whether the sequentially flattened table returns a row that lists only the parent record, without the values of the child array columns. When set to true, the sequentially flattened table does not return this row.

 

reducedVirtualViews

true

Specifies whether the virtual view returns a row that lists only the parent record, without the values of the child array columns. When set to false, the virtual view does return this row.

odbc

enableAsyncExecuting

 

Enables asynchronous execution.

 

forceQualifyTables

 

The catalog and table name are reported together as a single string (as DS:table_name).

 

maxActiveConnections

0

The maximum number of connections that an ODBC or OLE DB application can make through Oracle Connect for IMS, VSAM, and Adabas Gateways. The default indicates that the maximum is not set.

The greater the number of connections possible, the faster the application can run. However, other applications will run slower and each connection is counted as a license, restricting the total number of users who can access data through Oracle Connect for IMS, VSAM, and Adabas Gateways concurrently. This is particularly the case when using MS Access as a front-end, since MS Access allocates more than one connection whenever possible.

 

maxActiveStatements

0

The value returned for the InfoType of the ODBC SQLGetInfo API. The default (0) specifies that there is no limit on the number of active statements.

oledb

maxHRows

100

When using OLE DB, the maximum number of hrows (row handles) that can reside in memory at one time.

optimizer

avoidScan

false

When set to true, the optimizer does not choose the scan strategy if it can use some other strategy. If only a scan strategy is available, then it is used.

 

encourageLookupChache

false

 
 

goal

none

The optimization policy used. The following policies are available:

  • none: All row optimization is used.

  • first: First row optimization is performed based on the assumption that the results produced by the query are used as the rows are retrieved. The query optimizer uses a strategy that retrieves the first rows as fast as possible, which may result in a slower overall time to retrieve all the rows.

  • all: Optimization is performed based on the assumption that the results produced by the query are used after all the rows have been retrieved. The query optimizer uses a strategy that retrieves all the rows as fast as possible, which may result in a slower time to retrieve the first few rows.

Note: Aggregate queries automatically use all row optimization, regardless of the value of this parameter.

 

noCacheWithoutIndex

false

 
 

noFlattner

false

 
 

noHashJoin

false

When set to true, disables hash join optimization. When hash joins are enabled, a significant amount of disk space is required (see hashMaxDiskSpace). Therefore, if the system does not have available disk space, disable hash join optimization.

 

noIndexCache

false

 
 

noLojDelegation

   
 

noLookupCache

false

 
 

noMultiIndex

false

 
 

noPassthru

false

 
 

noSemiJoin

false

When set to true, disables semi-join optimization.

 

noSubqueryCache

false

 
 

noTdpUnion

false

 
 

preferredSite

server

The system you want to process the query. Normally the query is processed as close to the data source as possible (either using the query processing of the data source, or if this is not available, the Query Processor on the same system as the data source). If a situation arises in which it is more efficient to process the query on the client system (for example, when the remote system is heavily overloaded), you can tune Oracle Connect for IMS, VSAM, and Adabas Gateways to process all or part of the query locally.

The extent that performance is improved by processing all or some of the query locally can be determined only on a trial and error basis. Consider the following points when processing the query locally:

  • Increased communication costs.

  • Decreased server workload.

Before adjusting this parameter, check the log to see if other tuning is more appropriate. The options are:

  • server (the default): The query is processed on the server.

  • nearServer: The query is processed mostly on the server with parts of the query processed on the client (determined by the specific query).

  • nearClient: The query is processed mostly on the client with parts of the query processed on the server (determined by the specific query).

  • client: The query is processed on the client.

 

semiJoinInValuesFactor

10

The number of parameters a semi-join strategy sends to an RDBMS.

 

traceFull

false

 
 

traceGroups

false

 
 

useRecursiveLojOptimization

true

 

queryProcessor

compileAfterLoad

true

When set to true, sets Query Processor to always compile an Oracle Connect for IMS, VSAM, and Adabas Gateways procedure or view after it is read.

 

firstTreeExtensions

150 KB

The maximum size allowed for an SQL query after compilation.

 

ignoreSegmentBindfailure

false

Determines how Oracle Connect for IMS, VSAM, and Adabas Gateways responds when the execution of one of the segments of a segmented data source fails:

  • true: Logs a message and continues execution.

  • false: Logs a message and stops execution.

 

maxColumnsInParsing

500

The maximum number of columns that a query references.

 

maxSegmentedDbThreads

3

Specifies the maximum number of open threads, when working with segmented databases.

 

maxSqlCache

3

The maximum number of SQL queries stored in cache memory.

 

minNumberOfParametersAllocated

30

Specifies the minimum number of parameters that can be used in a query.

 

noCommandReuse

false

When set to true, sets the query processor not to cache for reuse the executed state of a query.

 

noCompilationCache

false

When set to true, sets the Query Processor not to save a successfully compiled statement in the cache.

 

noDSPropertyCache

false

When set to true, sets the Query Processor not to cache data source properties.

 

noInsertParameterization

false

When set to true, sets the Query Processor not to parameterize constants in INSERT statements.

 

noMetadataCaching

false

When set to true, the Query Processor does not take object metadata from the cache but from the original data source.

 

noParallelExecution

false

When set to true, disables parallel processing within query execution. See noThreads, described below.

 

noQueryParametrization

false

When set to true, sets the Query Processor not to convert constants into parameters when accessing data sources.

 

noQueryReadAhead

false

When set to true, disables read-ahead functionality for components using Query Processor services.

 

noRowMarkFieldFetch

false

When set to false, OLE DB getRows errors are marked and reshown on every getRows, as long as the rowset is active.

 

noSQSCache

false

When set to true, compiled Oracle Connect for IMS, VSAM, and Adabas Gateways procedures and views are not saved in the cache but always read from disk.

 

noThreadedReadAhead

false

When set to true, disables read-ahead functionality. Also, see noThreads, below.

 

noThreads

false

When set to true, disables multithreading.

 

parserDepth

500

The maximum depth of the expression tree.

 

prodeduresCacheSize

3

The number of Oracle Connect for IMS, VSAM, and Adabas Gateways stored queries created with a CREATE PROCEDURE statement that can be kept in cache memory.

 

promptDbUserPassword

false

When set to true, sets Oracle Connect for IMS, VSAM, and Adabas Gateways to prompt the user for security information when accessing a data source.

 

tokenSize

350

The maximum length of a string in an SQL query. The minimum value is 64.

 

useAlternateQualifier

false

When set to true, the Query Processor uses the @ symbol instead of a colon (:) when connecting to multiple data sources.

Note: This value is needed when building an application using PowerBuilder from Sybase Inc. or Genio from Hummingbird Ltd.

 

useTableFilterExpressions

false

When set to true, enables the use of tables that have filter expressions specified in their metadata. For details of filters in ADD, refer to the filter attribute.

transactions

commitOnDestroy

false

 
 

convertAllToDistributed

false

When set to true, converts all simple Transaction Managers into distributed transactions.

 

convertAllToSimple

false

When set to true, converts all distributed transactions into simple transactions.

 

disable2PC

false

When set to true, disables global transaction capabilities, even in drivers that support 2PC.

 

extendedLogging

false

When set to true, the transaction manager logs extended information concerning transactions.

 

logFile

 

The full path and filename of the log file that logs activity when using transactions. This log file is used during any recovery operations. Under Windows, the default log file (TRLOG.TLF) is written to the same directory as the NAV.LOG file (which is specified by the debug logFile parameter). It is recommended to use the default log file and perform recovery from a PC.

 

oleThreads

 

Limits the number of open threads when working with OLE transactions. These threads are used for operations received from the MSDTC. The minimum value is 5. the optimum value is 15. The maximum value is 25.

 

recoveryDelay

 

The number of minutes from the start of a transaction before any recovery operation on that transaction can be attempted. The default is 15 minutes.

 

serverUrl

   
 

timeLimit

1

Specifies the time to wait for a transaction to complete before an error is returned.

This parameter is also used when performing a RECOVERY, and it then indicates the number of minutes to wait before a forced activity can be performed, since the last transaction activity.

 

useCommitConfirmTable

false

When set to true, uses the commit-confirm table for data sources that support single-phase commit.

tuning

dsmMaxBufferSize

1000000 bytes

The maximum size of a cache memory. This cache is used when memory is required on a temporary basis (as when Oracle Connect for IMS, VSAM, and Adabas Gateways sorts data for a query output, for a subquery, or for aggregate queries). This cache size is not used for hash joins and lookup joins (see the hashBufferSize parameter, below).

 

dsmMaxHashFilesize

200000000

bytes

 
 

dsmMaxSortBufferSize

1000000 bytes

The maximum size of the sort buffers. Use this parameter instead of dsmMaxBufferSize for sorts only.

 

dsmMidBufferSize

100000 bytes

The maximum size of the index cache. This cache is not used for hash joins and lookup joins.

 

fileCloseOnTransaction

false

When set to true, the file pool will close when a transaction is committed.

 

filepoolSize

10

Specifies the file pool size. The default indicates that up to 10 files can be opened in the file pool.

 

filepoolSizePerFile

3

Specifies the file size in the file pool.

 

hashBufferSize

1000000 bytes

The amount of cache memory that is available for each hash join or lookup join.

 

hashEnableParallelism

true

Both sides of a hash join are read concurrently.

 

hashEnableRO

false

 
 

hashMaxDiskSpace

-1

The maximum amount of disk space (in MBs) that a query can use for hash joins. The default is unlimited (all the free space on the allocated disk). If a query requires more space than allocated through this parameter, the query execution will stop. The minimum value for this parameter is 20 MB.

Note: Temporary files are written per query. Therefore, if several users can execute queries at the same time, adjust the amount of space available, so that the total that can be allocated at any one time does not exceed the available space.

 

hashMaxOpenFiles

90

The maximum number of files that a query can open at one time for use when performing hash joins. The number assigned to this parameter must not exceed the system maximum.

Note: The hash join optimization strategy results in a number of files being opened to perform the join. The larger the table size, the more files are opened. By adjusting this parameter you can disable hash joins on very large tables, while allowing hash joins for small tables. (See the description of the optimizer parameter, above, for details about disabling hash optimization for all table joins).

 

useGloablFilepool

false

When set to true, a global file pool is used. When the serverMode parameter is set to multiClient or reusable, this parameter also indicates whether the file pool closes upon the client disconnection.


Sample Environment Properties

The following sample shows how different environment properties are represented in XML for the NAV binding configuration:

<environment name="NAV">
  <comm comCacheBufferSize="200000" />
  <debug logFile="" traceDir="" />
  <misc tempDir="" language="" codepage="" nlsString="" />
  <odbc maxActiveConnections="0" />
  <oledb maxHRows="100" />
  <optimizer preferredSite="server" />
  <queryProcessor proceduresCacheSize="3" firstTreeExtensions="150"
                  maxColumnsInParsing="500" />
  <transactions/>
  <tuning dsmMaxBufferSize="1000000" dsmMidBufferSize="100000"
          hashBufferSize="1000000" hashMaxDiskSpace="-1"
          hashMaxOpenFiles="90" />
</environment>

Note:

The XML representation of the environment properties are displayed on the Oracle Studio for IMS, VSAM, and Adabas Gateways Source tab when you edit the Binding in the Design perspective Configuration view.


Footnote Legend

Footnote 1: Other parameters that appear in Oracle Studio for IMS, VSAM, and Adabas Gateways are for reference only and should not be modified. These parameters are displayed when the Preferences window is opened and the Show advanced environment parameters field is checked, on the Advanced tab under the Studio node.