B Initialization Parameters

The Oracle Database initialization parameters in the init.ora file are distinct from heterogeneous services (HS) initialization parameters. Set HS parameters in the initialization parameter file using an agent-specific mechanism, or set them in the Oracle data dictionary using the DBMS_HS package.

This appendix describes the following initialization parameters:

See Also:

Oracle Database Heterogeneous Connectivity User's Guide for information on other available initialization parameters and Oracle Database Error Messages for information on handling Oracle error messages.

The initialization parameter file must be available when the gateway is started. During installation, the following default HS initialization parameter file is created:


Where ORACLE_HOME is the device under which the gateway is installed.

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>


    <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.


Property Description
Default value WORLD
Range of values 1 to 199 characters

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.


The HS-BD_Name and HS_DB_DOMAIN initialization parameters must combine to forma unique address in a cooperative server environment.


Property Description
Default value 01010101
Range of values 1 to 16 hexadecimal characters

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.


Property Description
Default value HO
Range of values 1 to 8 characters

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.


Property Description
Default value 100
Description 1 to 4000

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.


Property Description
Default value System-specific
Description Any of the character sets listed in theCodepage Values table.

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



The globalization support initialization parameters affect error messages, the data for the SQL Service, and parameters in distributed external procedures.

The following table describes the supported charset values.

Table B-1 Codepage Values

Value Description


Arabic bilingual


Arabic + Latin


Baltic multilingual


Cyrillic multilingual


Cyrillic Ukraine + Euro


German (Austria) + Euro


German (Austria)


Danish and Norwegian + Euro


Danish and Norwegian


Latin 2 multilingual




French + Euro




Italian + Euro










Finnish and Swedish + Euro


Finnish and Swedish - Sweden


Thai IS 620-2533 EBCDIC 8-bit




Latin 1


English (USA, Canada) + Euro


Spanish + Euro


English (UK) + Euro


International ECECP + Euro


Western European + Euro




English (UK)


English (USA, Canada)


French (Canada)


Western Europe




Latin 9


Simplified Chinese


Traditional Chinese

B.6.1 Character Sets

Ideally, the character sets of the Oracle database and the non-Oracle data source are the same. If they are not the same, Heterogeneous Services attempts to translate the character set of the non-Oracle data source to the Oracle database character set, and back again. The translation can degrade performance. In some cases, Heterogeneous Services cannot translate a character from one character set to another.


The specified character set must be a superset of the operating system character set on the platform where the agent is installed.

B.6.2 Language

The language component of the HS_LANGUAGE initialization parameter determines:

  • Day and month names of dates

  • AD, BC, PM, and AM symbols for date and time

  • Default sorting mechanism

Note that Oracle does not determine the language for error messages for the generic Heterogeneous Services messages (ORA-25000 through ORA-28000). These are controlled by the session settings in the Oracle database.


Use the HS_NLS_DATE_LANGUAGE initialization parameter to set the day and month names, and the AD, BC, PM, and AM symbols for dates and time independently from the language.

B.6.3 Territory

The territory clause specifies the conventions for day and week numbering, default date format, decimal character and group separator, and ISO and local currency symbols. Note that the level of globalization support between the Oracle database and the non-Oracle data source depends on how the gateway is implemented.


Property Description
Default value 64 KB
Range of values Any value up to 2 GB

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.


Property Description
Default value 50
Range of values 1 to the value of OPEN_CURSORS initialization parameter of Oracle database

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.


Property Description
Default value On
Range of values Off, On

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.


Property Description
Default value 50000
Range of values 1 to 100000000

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.


Property Description
Default value Database Gateway for VSAM (batch) - SINGLE_SITE

Database Gateway for VSAM (cics) - 2_PHASE_COMMIT

Database Gateway for IMS (DLIBATCH) - SINGLE_SITE

Database Gateway for IMS (imsdbdc) - SINGLE_SITE

Database Gateway for IMS (dbctl) - 2_PHASE_COMMIT

Database Gateway for ADABAS - SINGLE_SITE




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:

  • 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.

  • 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.

  • 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.


Property Description
Default value None
Range of values Valid parameter file names

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.


Property Description
Default value None
Range of values Not applicable

Specifies the system 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:

  • If you use a workspace other than the default:

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


  • 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).


Property Description
Default value 1,000 Characters
Range of values Any positive integer value

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


Property Description
Default value RECOVER
Range of values Any valid user ID

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.


Property Description
Default value Recover
Range of values Any valid password

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.


Property Description
Default value OFF
Range of values OFF, ON, DEBUG

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:[dg4<data_source>.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


Property Description
Default value None
Range of values Any valid character set specification
Syntax HS_NLS_NCHAR=character_set

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.


Property Description
Default value Value determined by the HS_LANGUAGE initialization parameter
Range of values Any valid NLS_NUMERIC_CHARACTER value (any two valid numeric characters).

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.


Property Description
Default value Gateway SID
Range of values Any valid data source 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.


Property Description
Range of values VSAM-BATCH, VSAM-CICS


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.