B Initialization Parameters

B.1 Initialization Parameter File Syntax

The syntax for the initialization parameter file is as follows:

• The file is a sequence of commands.

• Each command should start on a separate line.

• End of line is considered a command terminator (unless escaped with a backslash).

• Each command can have one of the following forms:

  • <param> = <value>

  • set <param> = <value>

  • private <param> = <value>

  • set private <param> = <value>

  Where:

  <param> is an initialization parameter name.

  <value> is the initialization parameter value.

  'set' and 'private' are keywords.

• The keywords 'set' and 'private' are reserved. You cannot use either as an initialization parameter name. The 'set' keyword indicates that the initialization parameter should be set as a logical in the agent. The 'private' keyword indicates that the initialization parameter should be private to the agent and should not be uploaded to the server. Most initialization parameters should not be private. If, however, you are storing something sensitive like a password in the initialization parameter file, then you may not want it uploaded to the server because the initialization parameters and values are not encrypted when uploaded. Making these initialization parameters private prevents the upload from happening.

• An initialization parameter name is a string of characters starting with a letter and consisting of letters, digits and underscores. Initialization parameter names are case-sensitive.

• An initialization parameter value is either:

  • A string of characters that does not contain any backslashes, white space or double quotation marks (").

  • A quoted string beginning with a double quotation mark and ending with a double quotation mark. The following can be used inside a quoted string:

    • backslash (\) is the escape character

    • \n inserts a newline

    • \t inserts a tab

    • \" inserts a double quotation mark

      A backslash at the end of the line continues the string on the next line. If a backslash precedes any other character then the backslash is ignored.

If there is a syntax error in an initialization parameter file, none of the settings take effect.

B.2 HS_DB_DOMAIN

Specifies a unique network subaddress for a non-Oracle system. The HS_DB_DOMAIN initialization parameter is similar to the DB_DOMAIN initialization parameter, described in the Oracle Database Reference. The HS_DB_DOMAIN initialization parameter is required if you use the Oracle Names server. The HS_DB_NAME and HS_DB_DOMAIN initialization parameters define the global name of the non-Oracle system.

B.3 HS_DB_INTERNAL_NAME

Specifies a unique hexadecimal number identifying the instance to which the Heterogeneous Services agent is connected. This parameter's value is used as part of a transaction ID when global name services are activated. Specifying a nonunique number can cause problems when two-phase commit recovery actions are necessary for a transaction.

B.4 HS_DB_NAME

Specifies a unique alphanumeric name for the data store given to the non-Oracle system. This name identifies the non-Oracle system within the cooperative server environment. The HS_DB_NAME and HS_DB_DOMAIN initialization parameters define the global name of the non-Oracle system.

B.5 HS_DESCRIBE_CACHE_HWM

Specifies the maximum number of entries in the describe cache used by Heterogeneous Services. This limit is known as the describe cache high water mark. The cache contains descriptions of the mapped tables that Heterogeneous Services reuses so that it does not have to re-access the non-Oracle data store.

If you are accessing many mapped tables, increase the high water mark to improve performance. Increasing the high water mark improves performance at the cost of memory usage.

B.6 HS_LANGUAGE

Provides Heterogeneous Services with character set, language, and territory information of the non-Oracle data source. The value must use the following format:

language[_territory.character_set]

The following table describes the supported charset values.

B.7 HS_LONG_PIECE_TRANSFER_SIZE

Sets the size of the piece of LONG data being transferred. A smaller piece size means less memory requirement, but more round-trips to fetch all the data. A larger piece size means fewer round-trips, but more of a memory requirement to store the intermediate pieces internally. Thus, the initialization parameter can be used to tune a system for the best performance, with the best trade-off between round-trips and memory requirements, and network latency or response time.

B.8 HS_OPEN_CURSORS

Defines the maximum number of cursors that can be open on one connection to a non-Oracle system instance.

The value never exceeds the number of open cursors in the Oracle database. Therefore, setting the same value as the OPEN_CURSORS initialization parameter in the Oracle database is recommended.

B.9 HS_RPC_FETCH_REBLOCKING

Controls whether Heterogeneous Services attempts to optimize performance of data transfer between the Oracle database and the Heterogeneous Services agent connected to the non-Oracle data store.

The following values are possible:

• OFF disables reblocking of fetched data so that data is immediately sent from agent to server.

• ON enables reblocking, which means that data fetched from the non-Oracle system is buffered in the agent and is not sent to the Oracle database until the amount of fetched data is equal or higher than the value of HS_RPC_FETCH_SIZE initialization parameter. However, any buffered data is returned immediately when a fetch indicates that no more data exists or when the non-Oracle system reports an error.

B.10 HS_RPC_FETCH_SIZE

Tunes internal data buffering to optimize the data transfer rate between the server and the agent process.

Increasing the value can reduce the number of network round-trips needed to transfer a given amount of data, but also tends to increase data bandwidth and to reduce latency as measured between issuing a query and completion of all fetches for the query. Nevertheless, increasing the fetch size can increase latency for the initial fetch results of a query, because the first fetch results are not transmitted until additional data is available.

B.11 HS_TRANSACTION_MODEL

Restricts the transaction mode available with the particular target to a level that can be less than that of the gateway's maximum capability. The maximum capability level is defined by the gateway. The range of values above is in order from minimum capability to maximum capability.

For example, if the maximum is SINGLE_SITE, then the HS_TRANSACTION_MODEL cannot be set to 2_PHASE_COMMIT. However, if 2_PHASE_COMMIT is the driver's maximum allowed value, then the HS_TRANSACTION_MODEL can be SINGLE_SITE.

The following values are possible:

• READ_ONLY provides read access to the non-Oracle database.

• SINGLE_SITE provides read and write access to the non-Oracle database. However, the gateway cannot participate in distributed updates.

• COMMIT_CONFIRM provides read and write access to the non-Oracle database and allows the gateway to be part of a distributed update. To use the commit-confirm model, the following items must be created in the non-Oracle database:

  • Transaction log table. The default table name is HS_TRANSACTION_LOG. A different name can be set using the HS_FDS_TRANSACTION_LOG parameter. The transaction log table must be granted SELECT, DELETE, and INSERT privileges set to public.

  • Recovery account. The account name is assigned with the HS_FDS_RECOVERY_ACCOUNT parameter.

  • Recovery account password. The password is assigned with the HS_FDS_RECOVERY_PWD parameter.

  • COMMIT_CONFIRM does not apply to Oracle Database Gateway for VSAM (batch), IMS (dlibatch) and IMS (imsdbdc), Adabas.

• 2_PHASE_COMMIT enables the non-Oracle system to participate in distributed transactions. It can participate in the server's two-phase commit protocol, as a regular two-phase commit node, but not as a commit point site. That is, it can prepare data, but it cannot remember the outcome of a particular transaction if asked to by the global coordinator.

• 2_PHASE_COMMIT does not apply to Oracle Database Gateway for VSAM (batch), IMS (dlibatch) and IMS (imsdbdc), Adabas.

B.12 IFILE

Use the IFILE initialization parameter to embed another initialization file within the current initialization file. The value should be an absolute path and should not contain environment variables. The three levels of nesting limit does not apply.

B.13 HS_FDS_CONNECT_INFO

Specifies the machine and port information needed to connect to the non-Oracle system.

This is a required parameter that has two different formats, as follows:

• If you use the default workspace:

  HS_FDS_CONNECT_INFO="address:port"
  

• If you use a workspace other than the default:

  HS_FDS_CONNECT_INFO="address='host' port='port' workspace='workspace'"
  

Where:

• host: The name of the host computer.

• port: The port number to listen to.

• workspace: The data source workspace name (optional except for the IMS/DB DLI data source).

B.14 HS_FDS_PARSER_TOKEN_SIZE

Used for setting the parser token size in case the default size is not sufficient. The default value can be changed if the following error occurs:

pclex input buffer overflowed, try to increase the variable tokenSize in your environment.

With default value of 1000, the gateway could handle SQL statements close to 2 MB. Note that the SQL statements sent to the gateway could be very different from the SQL statements issued by the users. If in doubt, turn on gateway trace. Increase this parameter to handle larger SQL statements sent to gateways

B.15 HS_FDS_RECOVERY_ACCOUNT

Specifies the name of the recovery account used for the commit-confirm transaction model. An account with user name and password must be set up at the non-Oracle system. For more information about the commit-confirm model, see the HS_FDS_TRANSACTION_MODEL parameter.

The name of the recovery account is case-sensitive.

B.16 HS_FDS_RECOVERY_PWD

Specifies the password of the recovery account used for the commit-confirm transaction model set up at the non-Oracle system.

The name of the password of the recovery account is case-sensitive.

B.17 HS_FDS_TRACE_LEVEL

Specifies whether error tracing is turned on or off for gateway connectivity.

The following values are valid:

• OFF disables the tracing of error messages.

• ON enables the tracing of error messages that occur when you encounter problems. The results are written to a gateway connectivity log file, in ORACLE_HOME:[dg4VSAM.log].

• DEBUG enables the tracing of detailed error messages that can be used for debugging.

The trace goes to the following directory, where data_source is vsam, ims, or adbs, depending on your gateway: $ORACLE_HOME/dg4[data_source]/log

B.18 HS_NLS_NCHAR

HS_NLS_NCHAR specifies the character set that the gateway will use to interact with the non-Oracle system when accessing graphic data. Set this parameter to the same value as the character set component of the HS_LANGUAGE parameter. For additional details, see the Oracle Database Heterogeneous Connectivity Administrator's Guide.

B.19 HS_NLS_NUMERIC_CHARACTER

Specifies the characters to use as the group separator and the decimal character. The group separator separates integer groups (such as thousands, millions, and billions). The decimal character separates the integer portion of a number from the decimal portion.

B.20 HS_FDS_DATASOURCE_NAME

Specifies the name of the data source for the remote gateway. If you use this parameter, the SID name of the gateway does not need to be identical to the data source name.

B.21 HS_FDS_ACCESS_METHOD

Specifies the gateway type that is used.

The following values are possible:

• VSAM-BATCH specifies a data source that connects directly to the VSAM data.

• VSAM-CICS specifies a data source that accesses VSAM by making EXCI calls to a CICS program.

• IMS-BATCH specifies an IMS/DB DLI data source.

• IMS-DBDC specifies an IMS/DB DBDC data source that accesses IMS/DB data under IMS/TM.

• IMS-DBCTL specifies an IMS/DB DBCTL data source that accesses IMS/DB data under CICS.

The default value is used when no init parameter is defined or when an unknown value is used.