| Oracle® Database Gateway for IMS, VSAM, and Adabas Installation and Configuration Guide 11g Release 1 (11.1) for AIX 5L Based Systems (64-Bit), HP-UX PA-RISC (64-Bit), Solaris Operating System (SPARC 64-Bit), Linux x86, and Linux x86-64 Part Number B32526-01 |
|
|
View PDF |
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:
This section includes the following topics:
You start a daemon from a privileged account on the machine 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.
The daemon is usually started automatically when the system boots up.
The IBM /s command is used to start the daemon on z/OS platforms.
To start the daemon
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.
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 runATTDAEMN by submitting the job, without making any changes to the JCL.You can start more than one daemon on the same machine 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 machine 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.
You can shut down the daemon on any machine with Oracle Studio for IMS, VSAM, and Adabas Gateways or from the command line.
You can shut down the daemon on any machine 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.
You can shut down the machine 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.
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.
Check the daemon on any machine 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, as shown in Figure 13-1.
Figure 13-1 Daemon Activity in the Runtime Explorer
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 machine 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.
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 machine 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.
You can have a number of daemon configurations on any machine.
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 machine 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.The daemon is configured in the Design perspective Configuration view in Oracle Studio for IMS, VSAM, and Adabas Gateways.
A machine can have a number of daemons running at the same time, each on its own port.
You can set up logging for the following:
Daemon log files
Workspace server process log files
Daemons include workspaces that define the server processes and environment that are used for the communication between the client and the server machine 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.
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
In Oracle Studio for IMS, VSAM, and Adabas Gateways Design Perspective Configuration view, expand the Machine folder and then expand the machine with the daemon where you want to add the workspace.
Expand the daemon folder.
Right-click the daemon where you want to add the workspace and select New Workspace.
Note:
You can add a new daemon configuration in offline design mode, in a design machine and later drag-and-drop the daemon configuration to this machine.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 machines running HP NonStop, OS/390, or z/OS, 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.
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.
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. See
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 most 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).
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.
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.
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.
Click Finish to close the wizard and add the new workspace to the Configuration view.
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
In the Design Perspective Configuration view, expand the Machines folder and then expand the machine where you want to edit the workspace.
Expand the daemon folder.
Expand the daemon with the workspace you want to edit.
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.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 are not implemented. They are only implemented after the configuration is reloaded using the Reload Configuration option in the Runtime Manager.
The table below 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 |
|
Server type |
The workspace server type. For example, |
|
Workspace binding name |
The name of a specific binding configuration on the server machine 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. |
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.
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 are not implemented. They are only implemented after the configuration is reloaded using the Reload Configuration option in the Runtime Manager.
The table below shows the WS Server tab's fields:
Table 13-2 WS Server Tab
| Field | Description |
|---|---|
|
Specifies the type of new server processes that the daemon starts up. The daemon supports the following server modes:
|
|
|
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.
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:
|
|
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. Select this if you want to limit the number of active servers. If this is selected, 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. |
|
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 this tab to configure the Logging preferences for the workspace. The following figure shows 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 are not implemented. They are only implemented 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 |
Defines 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:
|
|
Trace options |
Specifies the type of tracing. The following tracing options are available:
|
|
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:
|
|
Server |
Specifies the server connection events to log. The following server events are available:
|
|
Client |
Specifies the type of tracing performed. The following client events are available:
|
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 Logging Tab:
The following table describes the fields in this tab:
Table 13-4 WS Security Tab
| Field | Description |
|---|---|
|
Workspace access: This section defines 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
|
|
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:
|
|
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: This section defines 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:
|
|
Allow Listing |
Select this if you want this workspace to appear in the list of workspaces. |
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:
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.
|
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 machine, where data sources and applications to be accessed using Oracle reside. Additionally, a binding configuration can be defined on a client machine to point to data sources on a server machine.
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 machines and other server machines that can be accessed from the current machine.
Event queue definitions for event queues that are managed using Oracle Connect for IMS, VSAM, and Adabas Gateways, including event specific properties.
A binding configuration on a client includes:
Data source shortcuts to data sources on other server machines and other server machines that can be accessed from the current machine.
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.
The binding settings in XML format include the following statements:
A <remoteMachines>statement, specifying the remote machines that can be accessed, through <remoteMachine> statements.
<remoteMachine> statements, defining the remote machines available from the current machine.
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.
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 machine.
<remoteMachine> Statement
The <remoteMachine> statement lists names and IP addresses of the remote machines where data sources reside and which are accessed using data source shortcuts on the current machine. 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 machine) 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 machine 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 machine on the network.address: The IP address type of the remote machine.
port: The port on the remote machine 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 machine.
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 machine 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
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 machine 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 machine) 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. Table 13–6 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 ( |
syntaxName="value" |
A section name in the
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.
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.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.
Table 13-7 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 machine. |
|
|
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:
|
|
|
debug |
acxTrace |
false |
When set to |
|
|
|||
|
analyzerQueryPlan |
false |
When set to |
|
|
|
|||
|
binaryXmlLogLevel |
none |
Sets the binary XML log level. This parameter is used for troubleshooting. The following logging levels are available:
|
|
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
gdbTrace |
false |
When set to |
|
|
generalTrace |
false |
When set to Note: Changing the default setting can degrade Oracle Connect for IMS, VSAM, and Adabas Gateways performance. |
|
|
|
|||
|
|
|||
|
|
|||
|
logFile |
The full path and filename of the log file for messages. The default log file ( To send log messages to the console, instead of a file, set The following types of message are written to the log:
z/OS: The default Oracle Connect for IMS, VSAM, and Adabas Gateways log file is |
||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
oledbTrace |
false |
When set to 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 |
|
|
queryWarnings |
false |
When set to |
|
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
timeTrace |
false |
When set to |
|
|
traceDir |
The directory where Oracle Connect for IMS, VSAM, and Adabas Gateways writes the log generated by the optimizer files (with a |
||
|
transactionTrace |
false |
When set to |
|
|
triggerTrace |
false |
When set to |
|
|
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 machine. For details of these defaults, refer to 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 |
|
|
cvtLevelSeverity |
0 |
The data type conversion policy when a conversion error occurs. The following policies are available:
|
|
|
edit |
The text editor for use by the |
||
|
exposeXmlField |
false |
When set to |
|
|
generateUniqueIndexNames |
false |
Enables to expose non relational index names. When set to |
|
|
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 machine's charset. This parameter includes the following values:
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:
|
||
|
xmlDateFormat |
ISO |
Sets the XML date format used. Options include:
|
|
|
xmlFieldName |
XML |
The name used in a query to indicate that the data is returned as XML, instead of the keyword |
|
|
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 |
|
|
year2000Policy |
5 |
Determines how 2-digit years are converted into 4-digit years. Two policies are provided:
|
|
|
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 |
||
|
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 |
|
|
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 |
|
|
odbc |
enableAsyncExecuting |
Enables asynchronous execution. |
|
|
forceQualifyTables |
The catalog and table name are reported together as a single string (as |
||
|
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 |
|
|
oledb |
maxHRows |
100 |
When using OLE DB, the maximum number of |
|
optimizer |
avoidScan |
false |
When set to |
|
encourageLookupChache |
false |
||
|
goal |
none |
The optimization policy used. The following policies are available:
Note: Aggregate queries automatically use all row optimization, regardless of the value of this parameter. |
|
|
noCacheWithoutIndex |
false |
||
|
noFlattner |
false |
||
|
noHashJoin |
false |
When set to |
|
|
noIndexCache |
false |
||
|
noLojDelegation |
|||
|
noLookupCache |
false |
||
|
noMultiIndex |
false |
||
|
noPassthru |
false |
||
|
noSemiJoin |
false |
When set to |
|
|
noSubqueryCache |
false |
||
|
noTdpUnion |
false |
||
|
preferredSite |
server |
The machine 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 machine as the data source). If a situation arises in which it is more efficient to process the query on the client machine (for example, when the remote machine 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:
Before adjusting this parameter, check the log to see if other tuning is more appropriate. The options are:
|
|
|
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 |
|
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:
|
|
|
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 |
|
|
noCompilationCache |
false |
When set to |
|
|
noDSPropertyCache |
false |
When set to |
|
|
noInsertParameterization |
false |
When set to |
|
|
noMetadataCaching |
false |
When set to |
|
|
noParallelExecution |
false |
When set to |
|
|
noQueryParametrization |
false |
When set to |
|
|
noQueryReadAhead |
false |
When set to |
|
|
noRowMarkFieldFetch |
false |
When set to |
|
|
noSQSCache |
false |
When set to |
|
|
noThreadedReadAhead |
false |
When set to |
|
|
noThreads |
false |
When set to |
|
|
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 |
|
|
promptDbUserPassword |
false |
When set to |
|
|
tokenSize |
350 |
The maximum length of a string in an SQL query. The minimum value is 64. |
|
|
useAlternateQualifier |
false |
When set to Note: This value is needed when building an application using PowerBuilder from Sybase Inc. or Genio from Hummingbird Ltd. |
|
|
useTableFilterExpressions |
false |
When set to |
|
|
transactions |
commitOnDestroy |
false |
|
|
convertAllToDistributed |
false |
When set to |
|
|
convertAllToSimple |
false |
When set to |
|
|
disable2PC |
false |
When set to true, disables global transaction capabilities, even in drivers that support 2PC. |
|
|
extendedLogging |
false |
When set to |
|
|
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 ( |
||
|
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 |
|
|
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 |
|
dsmMaxHashFilesize |
200000000 bytes |
||
|
dsmMaxSortBufferSize |
1000000 bytes |
The maximum size of the sort buffers. Use this parameter instead of |
|
|
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 |
|
|
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 |
|
|
useGloablFilepool |
false |
When set to |
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.