DB2 ODBC initialization keywords

DB2® ODBC initialization keywords control the run time environment for DB2 ODBC applications.

The section (common, subsystem, or data source) in the initialization file where each keyword must be defined is identified.

ACCOUNTINGINTERVAL = COMMIT
This keyword is placed in the subsystem section.

Use the ACCOUNTINGINTERVAL keyword to specify whether DB2 accounting records are produced at commit points. When ACCOUNTINGINTERNVAL is set to COMMIT, an accounting record is produced each time that a transaction is committed on a connection handle. When ACCOUNTINGINTERVAL is not specified, or a keyword value other than COMMIT is specified, accounting records are produced when the physical connection on the connection handle is terminated.

DB2 ODBC ignores ACCOUNTINGINTERVAL if MVSATTACHTYPE=CAF is specified, or if the DB2 ODBC application is running as a DB2 for z/OS® stored procedure.

APPLTRACE = 0 | 1
This keyword is placed in the common section.
The APPLTRACE keyword controls whether the DB2 ODBC application trace is enabled. The application trace is designed for diagnosis of application errors. If enabled, every call to any DB2 ODBC API from the application is traced, including input parameters. The trace is written to the file specified on the APPLTRACEFILENAME keyword.
0
Disabled (default)
1
Enabled
APPLTRACEFILENAME = dataset_name
This keyword is placed in the common section.

APPLTRACEFILENAME is only used if a trace is started by the APPLTRACE keyword. When APPLTRACE is set to 1, use the APPLTRACEFILENAME keyword to identify a z/OS data set name or z/OS UNIX environment HFS file name that records the DB2 ODBC application trace.

AUTOCOMMIT = 1 | 0
This keyword is placed in the data source section.
To be consistent with ODBC, DB2 ODBC defaults with AUTOCOMMIT on, which means each statement is treated as a single, complete transaction. This keyword can provide an alternative default, but is only used if the application does not specify a value for AUTOCOMMIT as part of the program.
1
On (default)
0
Off

Most ODBC applications assume that the default of AUTOCOMMIT is on. Use extreme care when you override this default during run time. The application might depend on this default to operate properly.

Although you can specify only two different values for this keyword, you can also specify whether AUTOCOMMIT is enabled in a distributed unit of work (DUW) environment. If a connection is part of a coordinated DUW, and AUTOCOMMIT is not set, the default does not apply. Implicit commits that arise from autocommit processing are suppressed. If AUTOCOMMIT is set to 1, and the connection is part of a coordinated DUW, the implicit commits are processed. This situation can result in severe performance degradations, and possibly other unexpected results elsewhere in the DUW system. However, some applications might not work at all unless this is enabled.

A thorough understanding of the transaction processing of an application is necessary, especially applications that are written by a third party, before you apply it to a DUW environment.

To enable global transaction processing in an application, specify AUTOCOMMIT=0, MULTICONTEXT=0, and MVSATTACHTYPE=RRSAF.

BITDATA = 1 | 0
This keyword is placed in the data source section.

You can use the BITDATA keyword to specify whether ODBC SQL_BINARY, SQL_VARBINARY, SQL_LONGVARBINARY, and SQL_BLOB types are reported as binary type data. IBM® database servers support columns with binary data types by defining CHAR, VARCHAR, and LONG VARCHAR columns with the FOR BIT DATA attribute, or by defining BINARY or VARBINARY columns.

Set BITDATA = 0 only if you are sure that all columns defined as FOR BIT DATA, BLOB, BINARY, or VARBINARY contain only character data, and the application is incapable of displaying binary data columns.

1
Report FOR BIT DATA, BLOB, BINARY, or VARBINARY data types as binary data. This value is the default.
0
Report FOR BIT DATA, BLOB, BINARY, or VARBINARY data types as character data.
CLISCHEMA = schema_name
Start of change

This keyword is deprecated.

If you specify this keyword, the ODBC driver does not use the database metadata stored procedures to retrieve catalog information.

End of change
COLLECTIONID = collection_id
This keyword is placed in the data source section.

Specifies the collection identifier that is used to resolve the name of the package that is allocated at the server. This package supports the execution of subsequent SQL statements.

The value is a character string and must not exceed 128 characters. It can be overridden by executing the SET CURRENT PACKAGESET statement.

Start of changeCONCURRENTACCESSRESOLUTION = 0 | 1 | 2| 3End of change
Start of changeThe CONCURRENTACCESSRESOLUTION keyword controls how access to uncommitted data is resolved for a read transaction.
0
No setting. This value is the default value.
1
USE CURRENTLY COMMITTED. A read transaction can access the currently committed version of the data when the data is being updated or deleted. Rows that are in the process of being inserted are skipped. After this value is set, all user SELECT statements are prepared with the attribute USE CURRENTLY COMMITTED attribute. This option applies only when cursor stability (CS) or read stability (RS) isolation are in effect.
2
WAIT FOR OUTCOME. Read transactions that require access to data that is being updated or deleted must wait for a COMMIT or ROLLBACK operation to complete. Rows that are in the process of being inserted are not skipped. After this value is set, all user SELECT statements are prepared with the WAIT FOR COMMIT attribute.
3
SKIP LOCKED DATA. Read transactions can skip any rows that are incompatibly locked by other transactions. After this value is set, all user SELECT statements are prepared with the SKIP LOCKED attribute. This option applies only when cursor stability (CS) or read stability (RS) isolation are in effect.

When CONCURRENTACCESSRESOLUTION=1, the same rules and restrictions that apply to DB2 currently committed semantics also apply to ODBC. Access to currently committed data is supported for uncommitted INSERT and DELETE operation only in Version 10 and newer. Read transactions must still wait for uncommitted UPDATE operations to complete.

End of change
CONNECTTYPE = 1 | 2
This keyword is placed in the common section.
You can use the CONNECTTYPE keyword to specify the default connection type for all connections to data sources.
1
Multiple concurrent connections, each with its own commit scope. If MULTICONTEXT=0 is specified, a new connection might not be added unless the current transaction on the current connection is on a transaction boundary (either committed or rolled back). This value is the default.
2
Coordinated connections where multiple data sources participate under the same distributed unit of work. CONNECTTYPE=2 is ignored if MULTICONTEXT=1 is specified.
CURRENTAPPENSCH = EBCDIC | UNICODE | ASCII | ccsid
This keyword is placed in the common section.
Use the CURRENTAPPENSCH keyword to specify either of the following items:
  • The encoding scheme (Unicode, EBCDIC, or ASCII) that the ODBC driver uses for the following items:
    • Bound input or output host variables with the symbolic C data type SQL_C_CHAR
    • Character string arguments on a generic API call
  • A CCSID value that provides the following information to the ODBC driver:
    • The same information that an encoding scheme provides. The ODBC driver derives the encoding scheme from the CCSID value.
    • The default values for the statement attributes SQL_CCSID_CHAR and SQL_CCSID_GRAPHIC. The CCSID value overrides the default CCSID settings in the DSNHDECP load module for application data with the SQL_C_CHAR data type.

The suffix-W APIs, which support UCS-2 string arguments, are not affected by CURRENTAPPENSCH. ODBC assumes UCS-2 for bound input or output host variables with the symbolic C data type SQL_C_WCHAR, regardless of the value of CURRENTAPPENSCH.

Result of specifying an encoding scheme for CURRENTAPPENSCH: When CURRENTAPPENSCH is set to EBCDIC, ASCII, or UNICODE, a SET CURRENT APPLICATION ENCODING SCHEME statement is sent to the data source after a successful connect. If this keyword is not present, the driver assumes EBCDIC as the default application encoding scheme.

Result of specifying a CCSID for CURRENTAPPENSCH: When CURRENTAPPENSCH is set to a CCSID value, the CCSID value provides default values to the statement attributes SQL_CCSID_CHAR and SQL_CCSID_GRAPHIC as follows:
  • If ccsid is an SBCS CCSID, ccsid is the default value for SQL_CCSID_CHAR. SQL_CCSID_DEFAULT is the default value for SQL_CCSID_GRAPHIC.
  • If ccsid is a DBCS CCSID, ccsid is the default value for SQL_CCSID_GRAPHIC. SQL_CCSID_DEFAULT is the default value for SQL_CCSID_CHAR.

    Specifying any of the UCS-2 CCSIDs (1200, 13488, or 17584) for ccsid is equivalent to specifying CURRENTAPPENSCH=UNICODE. If ccsid has any of those values, ccsid is not the default value for SQL_CCSID_GRAPHIC.

  • If ccsid is a mixed CCSID, ccsid is the default value for SQL_CCSID_CHAR. The DBCS CCSID that is derived from ccsid is the default value for SQL_CCSID_GRAPHIC.

    If ccsid is 1208, 1208 is the default value for SQL_CCSID_CHAR. SQL_CCSID_DEFAULT is the default value for SQL_CCSID_GRAPHIC.

If an application calls SQLSetStmtAttr() to set the values for SQL_CCSID_CHAR or SQL_CCSID_GRAPHIC, those values override the default CCSID values that are set by CURRENTAPPENSCH.

Result of not specifying CURRENTAPPENSCH or specifying an invalid value for CURRENTAPPENSCH: When CURRENTAPPENSCH is not specified or the CURRENTAPPENSCH value is invalid, the ODBC driver uses EBCDIC as the default application encoding scheme.

CURRENTFUNCTIONPATH = "'schema1', 'schema2' ,…"
This keyword is placed in the data source section.

Use the CURRENTFUNCTIONPATH keyword to define the path that resolves unqualified user-defined functions, distinct types, and stored procedure references that are used in dynamic SQL statements. It contains a list of one or more schema names, which are used to set the CURRENT PATH special register. The SET CURRENT PATH SQL is used to set the value statement upon connection to the data source. Each schema name in the keyword string must be delimited with single quotation marks and separated by commas. The entire keyword string must be enclosed in double quotation marks and must not exceed 2048 characters.

The default value of the CURRENT PATH special register is:
"SYSIBM", "SYSFUN", "SYSPROC", X
X is the value of the USER special register as a delimited identifier. The schemas SYSIBM, SYSFUN, and SYSPROC do not need to be specified. If any of these schemas is not included in the current path, DB2 implicitly assumes that each schema name begins the path, in the order that is shown in the default value. The order of the schema names in the path determines the order in which the names are resolved.
Unqualified user-defined functions, distinct types, and stored procedures are searched from the list of schemas that are specified in the CURRENTFUNCTIONPATH setting in the order specified. If the user-defined function, distinct type, or stored procedures is not found in a specified schema, the search continues in the schema specified next in the list. For example:
CURRENTFUNCTIONPATH="'USER01', 'PAYROLL', 'SYSIBM', 'SYSFUN', 'SYSPROC'"
This example of CURRENTFUNCTIONPATH settings searches schema "USER01", followed by schema "PAYROLL", followed by schema "SYSIBM", and so on.

Although the SQL statement CALL is a static statement, the CURRENTFUNCTIONPATH setting affects a CALL statement if the stored procedure name is specified with a host variable (making the CALL statement a pseudo-dynamic SQL statement). This is always the case for a CALL statement that is processed by DB2 ODBC.

CURRENTSQLID = current_sqlid
This keyword is placed in the data source section.

The CURRENTSQLID keyword is valid only for those DB2 database servers that support SET CURRENT SQLID (such as DB2 for z/OS). If this keyword is present, then a SET CURRENT SQLID statement is sent to the database server after a successful connect. Users and the application can name SQL objects without having to qualify by schema name. The value that you specify for current_sqlid must be no more than 128 bytes.

Do not specify this keyword if you are binding the DB2 ODBC packages with DYNAMICRULES(BIND).

CURSORHOLD = 1 | 0
This keyword is placed in the data source section.
The CURSORHOLD keyword controls the effect of a transaction completion on open cursors.
1
Cursor hold. The cursors are not destroyed when the transaction is committed. This is the default.
0
Cursor no hold. The cursors are destroyed when the transaction is committed.

Cursors are always destroyed when transactions are rolled back.

Specify zero for this keyword to improve application performance when both the following conditions are true:
  • Start of changeApplication behavior does not depend on any information that is returned by SQLGetInfo() for SQL_CURSOR_COMMIT_BEHAVIOR or SQL_CURSOR_ROLLBACK_BEHAVIOR End of change
  • The application does not require cursors to be preserved from one transaction to the next.

The database server operates more efficiently as resources no longer need to be maintained after the end of a transaction.

Start of changeDB2EXPLAIN = 0 | 1 | 2 | 3End of change
Start of changeThis keyword is placed in the data source section.

The DB2EXPLAIN keyword sets the CURRENT EXPLAIN MODE special register to either YES or NO. You can specify one of the following values:

0
Sets the CURRENT EXPLAIN MODE special register to NO, which disables the EXPLAIN facility. In this case, DB2 does not capture any EXPLAIN information when explainable dynamic statements are executed. This value is the default.
1
Has the same effect as the value 0. This value is supported for DB2 family compatibility. For DB2 for Linux, UNIX, and Windows, the value 1 has a different meaning, but on DB2 for z/OS, the value 1 has the same meaning as the value 0.
2
Sets the CURRENT EXPLAIN MODE special register to YES, which enables the EXPLAIN facility. In this case, DB2 inserts EXPLAIN information into the EXPLAIN tables for explainable dynamic SQL statements.
3
Has the same effect as the value 2. This value is supported for DB2 family compatibility. For DB2 for Linux, UNIX, and Windows, the value 3 has a different meaning, but on DB2 for z/OS, the value 3 has the same meaning as the value 2.

Alternatively, you can set the CURRENT EXPLAIN MODE special register for ODBC applications by using the SQLSetConnectAttr() function with the SQL_ATTR_DB2EXPLAIN attribute or the SET CURRENT EXPLAIN MODE SQL statement.

If you want to set the CURRENT EXPLAIN MODE special register to EXPLAIN, you must use the SET CURRENT EXPLAIN MODE statement.

To get the EXPLAIN behavior that you want, you must also consider how you set the REOPT bind option.

End of change
DBNAME = dbname
This keyword is placed in the data source section.

The DBNAME keyword is used only for connections to DB2 for z/OS, and only if (base) table catalog information is requested by the application.

If many tables exist in the DB2 for z/OS subsystem, a dbname can be specified to reduce the time it takes for the database to process the catalog query for table information, and reduce the number of tables that are returned to the application.

The value of the dbname keyword maps to the DBNAME column in the DB2 for z/OS catalog tables. If no value is specified, or if views, synonyms, system tables, or aliases are also specified using TABLETYPE, only table information is restricted; views, aliases, and synonyms are not restricted with DBNAME. This keyword can be used with SCHEMALIST and TABLETYPE to further limit the number of tables for which information is returned.

DECIMALFLOATROUNDINGMODE=0 | 1 | 2 | 3 | 4 | 5 | 6
This keyword is placed in the data source section.
DECIMALFLOATROUNDINGMODE specifies the rounding mode that is used when DECFLOAT data values are manipulated. If DECIMALFLOATROUNDINGMODE is present, DB2 ODBC sends a SET CURRENT DECFLOAT ROUNDING MODE statement to the data source after a successful connect. If DECIMALFLOATROUNDINGMODE is not present, ROUND_HALF_EVEN is assumed at the data source. Possible values and the corresponding CURRENT DECFLOAT ROUNDING MODE values are:
0
ROUND_HALF_EVEN

Round to the nearest integer. If the value is equidistant from two integers, round so that the final digit is even.

1
ROUND_HALF_UP

Round to the nearest integer. If the value is equidistant from two integers, round up.

2
ROUND_DOWN

Round toward 0. This is equivalent to truncation.

3
ROUND_CEILING

Round toward positive infinity.

4
ROUND_FLOOR

Round toward negative infinity.

5
ROUND_HALF_DOWN

Round to the nearest integer. If the value is equidistant from two integers, round down.

6
ROUND_UP

Round away from zero.

DIAGTRACE = 0 | 1
This keyword is placed in the common section.
You can use the DIAGTRACE keyword to enable the DB2 ODBC diagnostic trace.
0
The DB2 ODBC diagnostic trace is not enabled. No diagnostic data is captured. This is the default.

You can enable the diagnostic trace by using the appropriate ODBC diagnostic trace command when the DIAGTRACE keyword is set to 0.

1
The DB2 ODBC diagnostic trace is enabled. Diagnostic data is recorded in the application address space. If you include a DSNAOTRC data definition statement in your job or TSO logon procedure that identifies a z/OS data set or a z/OS UNIX environment HFS file name, the trace is externalized at normal program termination. You can format the trace by using the appropriate ODBC diagnostic trace command.
DIAGTRACE_BUFFER_SIZE = buffer size
This keyword is placed in the common section.

The DIAGTRACE_BUFFER_SIZE keyword controls the size of the DB2 ODBC diagnostic trace buffer. This keyword is only used if a trace is started by using the DIAGTRACE keyword.

The buffer size value is an integer value that represents the number of bytes to allocate for the trace buffer. The buffer size is rounded down to a multiple of 65536 (64 K). If the value specified is less than 65536, 65536 is used. The default value for the trace buffer size is 65536. For 64-bit applications, specify a buffer size value that is up to 10% bigger than what you would specify for 31-bit applications.

If a trace is active, this keyword is ignored.

DIAGTRACE_NO_WRAP = 0 | 1
This keyword is placed in the common section.

The DIAGTRACE_NO_WRAP keyword controls the behavior of the DB2 ODBC diagnostic trace when the DB2 ODBC diagnostic trace buffer fills up. This keyword is only used if a trace is started by the DIAGTRACE keyword.

0
The trace table is a wraparound trace. In this case, the trace remains active to capture the most current trace records. This is the default.
1
The trace stops capturing records when the trace buffer fills. The trace captures the initial trace records that were written.

If a trace is active, this keyword is ignored.

DIAGTRACE = 0 | 1
This keyword is placed in the common section.
You can use the DIAGTRACE keyword to enable the DB2 ODBC diagnostic trace.
0
The DB2 ODBC diagnostic trace is not enabled. No diagnostic data is captured. This is the default.

You can enable the diagnostic trace by using the appropriate ODBC diagnostic trace command when the DIAGTRACE keyword is set to 0.

1
The DB2 ODBC diagnostic trace is enabled. Diagnostic data is recorded in the application address space. If you include a DSNAOTRC data definition statement in your job or TSO logon procedure that identifies a z/OS data set or a z/OS UNIX environment HFS file name, the trace is externalized at normal program termination. You can format the trace by using the appropriate ODBC diagnostic trace command.
DIAGTRACE_MASK = *.*.*.*.* | trace_mask
This keyword is placed in the common section.

The DIAGTRACE_MASK enables a trace mask, which limits the trace records collected by the DB2 ODBC diagnostic trace. Use this keyword only if a trace is started by the DIAGTRACE keyword.

The track mask consists of five parts that are delimited by periods.

  • Types
  • Products
  • Components
  • Functions
  • Categories

Each part can consist of comma-separated lists, hyphen separated ranges, or single entries. The default setting of DIAGTRACE_MASK=*.*.*.*.* captures all trace records. To capture specific records, set the mask to the numbers that correspond to specific types, products, components, functions, and/or categories that you want to trace. If you want to trace all entry and exit records for component 41, set DIAGTRACE_MASK=1,2.*.41.*.* where 41 specifies the component, and 1 and 2 limit tracing to entry and exit records only.

The trace mask is intended for activating tracing for IBM debugging.

Start of changeEXTENDEDTABLEINFO = 0 | 1End of change
Start of changeThis keyword is placed in the data source section.

The EXTENDEDTABLEINFO keyword specifies whether information about extended table types is returned from a SQLTables() function call. Currently, there is one extended table type: ACCEL-ONLY TABLE.

Possible values are:

0
The result set that is returned by the SQLTables() function does not contain columns for extended table types.

Rows for extended table types are returned only if "TABLE" is explicitly specified in the szTableType parameter value in the SQLTables() call, or in the TABLETYPE initialization keyword, if szTableType is a null pointer. In this case, extended table types are listed as TABLE in the TABLE_TYPE column of the result set.

1
The result set that is returned by the SQLTables() function contains rows and columns for extended table types. In particular:
  • The result set contains extra columns TEMPORAL_TABLE_TYPE, IS_ACCELERATED, ACCEL_ARCHIVE_STATUS, and IS_ARCHIVE_ENABLED after the columns that are always returned in the result set from SQLTables(). See SQLTables() - Get table information for a description of those columns.
  • Rows for extended table types are returned under the following circumstances:
    • All table types are implicitly requested by specifying a null pointer in the szTableType parameter of the SQLTables() call, and not specifying the TABLETYPE initialization keyword.
    • An extended table type name is explicitly specified in the szTableType parameter of the SQLTables() call, or in the TABLETYPE initialization keyword.

      In this case, the extended table type is listed by its extended table type name in the TABLE_TYPE column of the result set.

End of change
Start of changeGRANTEELIST = userID1, userID2, ... userIDnEnd of change
Start of change

This keyword is placed in the data source section.

You can use the GRANTEELIST keyword to reduce the amount of information that is returned when the application gets a list of privileges for tables, or privileges for columns in a table. The list of authorization IDs specified is used as a filter. If an application gets a list of privileges for a specific table, only the columns that have a privilege that is granted to the specified user IDs are returned.

This keyword is applicable to the APIs SQLColumnPrivileges and SQLTablePrivileges

End of change
Start of changeGRANTORLIST = userID1, userID2, ... userIDnEnd of change
Start of change

This keyword is placed in the data source section.

You can use the GRANTORLIST keyword to reduce the amount of information that is returned when the application gets a list of privileges for tables, or privileges for columns in a table. The list of authorization IDs specified is used as a filter. If the application gets a list of privileges for a specific table, only those columns that have a privilege that is granted by the specified user IDs are returned.

This keyword is applicable to the APIs SQLColumnPrivileges and SQLTablePrivileges

End of change
GRAPHIC =0 | 1 | 2 | 3
This keyword is placed in the data source section.
The GRAPHIC keyword controls whether DB2 ODBC reports IBM GRAPHIC (double-byte character support) as one of the supported data types when SQLGetTypeInfo() is called. SQLGetTypeInfo() lists the data types supported by the data source for the current connection. These are not native ODBC types but have been added to expose these types to an application connected to a DB2 family product.
0
Disabled (default)
1
Enabled
2
Report the length of graphic columns that are returned by DESCRIBE in number of bytes rather than DBCS characters. This applies to all DB2 ODBC and ODBC functions that return length or precision either on the output argument or as part of the result set.
3
Settings 1 and 2 combined; that is, GRAPHIC=3 achieves the combined effect of 1 and 2.

The default is that GRAPHIC is not returned because many applications do not recognize this data type and cannot provide proper handling.

INTERRUPT = 0 | 1 | 2
You can use the INTERRUPT keyword to specify the interrupt processing mode when SQLCancel() is called to cancel the processing on a statement.
0
Disable interrupt processing (SQLCancel() calls do not interrupt the processing.)
1
Interrupts are supported (default). In this mode, if interrupt is supported for the connection at the server, an interrupt is sent. Otherwise, the connection is dropped.
3
Interrupt drops the connection regardless of server's interrupt capabilities (SQLCancel() drops the connection.)

This keyword is applicable only to applications that have MVSATTACHTYPE=RRSAF specified in the initialization file. Only connections that are attached through the RRSAF attachment facility can be dropped.

When INTERRUPT is set to 1, DB2 ODBC always drops the connection that is associated with the statement.

Start of changeLIMITEDBLOCKFETCH = 0 | 1End of change
Start of changeThis keyword is placed in the data source section.

LIMITEDBLOCKFETCH specifies whether DB2 ODBC attempts to use limited block fetch when it fetches result sets from the connected data source. Limited block fetch can significantly reduce the number of trips to the DB2 server for data retrieval by grouping the rows that are retrieved by an SQL query into a block of rows in a query buffer. Limited block fetch benefits DB2 ODBC applications that retrieve large read-only result sets with forward-only cursors from a local DB2 server. LIMITEDBLOCKFETCH affects FETCH operations that are performed by the SQLFetch(), SQLExtendedFetch(), and SQLFetchScroll() functions. Possible values are:

0
Limited block fetch is not used. 0 is the default.
1
DB2 ODBC attempts to use limited block fetch. If blocking is supported at the server for the result set that is being fetched, DB2 ODBC retrieves as many rows as it can fit in a query data block in a single fetch request.

When you enable limited block fetch, you can also set the size of the query data block by setting the QUERYDATASIZE initialization parameter.

The specification of LIMITEDBLOCKFETCH=1 turns off any alternative fetch optimization that DB2 ODBC might otherwise use, such as DB2 multi-row fetch.

DB2 ODBC limited block fetch is not supported in the following cases:

  • For connections to remote data sources
  • For result sets other than read-only result sets
  • For cursor types other than SQL_CURSOR_FORWARD_ONLY
  • If any column in the result set is a LOB column, an XML column, or a file reference variable
  • For stored procedure result sets
  • For result sets that are generated by catalog API calls
  • If the application sets the statement attribute SQL_NODESCRIBE to SQL_NODESCRIBE_ON and uses SQLSetColAttributes() to set the data source result descriptor for result set columns

If you enable limited block fetch for situations in which it is not supported, performance might be impacted.

Related information:
End of change
Start of changeLITERALREPLACEMENT = 0 | 1End of change
Start of changeThis keyword is placed in the data source section.

The LITERALREPLACEMENT keyword specifies whether a dynamic SQL statement that contains literals is cached with the literal constants or with replacement markers for the literal constants. The default value is 0.

0
The statement is cached with the literal constants. If the statement contains one or more constants that are different from the cached version of the same dynamic statement, the statement is cached as a unique statement entry.
1
The statement is cached with replacement markers for literal constants. DB2 can share a cache entry for dynamic statements that are identical except for the literal constants if those statements also satisfy the following criteria:
  • The statements do not contain parameter markers.
  • The constants in the new statement can be reused in place of the constants in the cached statement.
  • The statements satisfy all other conditions for dynamic statement cache sharing.
By sharing the dynamic cache entry, DB2 does not have to fully prepare the new statement, and the application performance might improve.
This keyword is equivalent to the CONCENTRATE STATEMENTS clause of the SQL PREPARE statement.End of change
MAXCONN = 0 | positive number
This keyword is placed in the common section.

The MAXCONN keyword is used to specify the maximum number of connections that are allowed for each DB2 ODBC application program. This can be used by an administrator as a governor for the maximum number of connections that are established by each application.

0
Can be used to represent no limit. That is, an application is allowed to open up as many connections as permitted by the system resources. This is the default.
positive number
Set the keyword to any positive number to specify the maximum number of connections each application can open.

This parameter limits the number of SQLConnect() statements that the application can successfully issue. In addition, if the application is executing with CONNECT (type 1) semantics, then this value specifies the number of logical connections. Only one physical connection to either the local DB2 subsystem or a remote DB2 subsystem or remote DRDA-1 or DRDA-2 server is made at one time.

MULTICONTEXT = 0 | 1 | Start of change2End of change
This keyword is placed in the common section.
The MULTICONTEXT keyword controls whether each connection in an application can be treated as a separate unit of work with its own commit scope that is independent of other connections.
0
The DB2 ODBC code does not create an independent context for a data source connection. Connection switching among multiple data sources that are governed by the CONNECTTYPE=1 rules is not allowed unless the current transaction on the current connection is on a transaction boundary (either committed or rolled back). This is the default.

Specify MULTICONTEXT=0 and MVSATTACHTYPE=RRSAF to allow an ODBC application to use z/OS Context Services to create and manage its own contexts. With these services, an application can manage its own contexts outside of ODBC with each context operating as an independent unit of work.

DB2 ODBC support for external contexts is disabled if the application is running as DB2 ODBC stored procedure.

To enable global transaction processing in an application, specify AUTOCOMMIT=0, MULTICONTEXT=0, and MVSATTACHTYPE=RRSAF.

1
The DB2 ODBC code creates an independent context for a data source connection at the connection handle level when SQLAllocHandle() is issued. Each connection to multiple data sources is governed by CONNECTTYPE=1 rules and is associated with an independent DB2 thread. Connection-switching among multiple data sources is not prevented due to the commit status of the transaction. An application can use multiple connection handles without having to commit or roll back on a connection before it switches to another connection handle.

MULTICONTEXT=1 is not supported for applications that contain DB2 ODBC and embedded SQL.

Start of change2End of change
Start of changeMULTICONTEXT=2 and MULTICONTEXT=1 share connection characteristics. However, when MULTICONTEXT=2 is specified, DB2 ODBC enables a multithreaded application to always maintain an active environment handle under a designated Language Environment® thread in a multiple-context environment. All restrictions that apply to MULTICONTEXT=1 also apply to MULTICONTEXT=2.
Important: Use MULTICONTEXT=2 only under the direction of IBM Software Support. Indiscriminate use of MULTICONTEXT=2 can cause applications to be abnormally terminated.
End of change

Start of changeThe application can use SQLGetInfo() with InfoType set to SQL_MULTIPLE_ACTIVE_TXN to determine whether MULTICONTEXT=1 or MULTICONTEXT=2 is supported.End of change

Start of changeMULTICONTEXT=1 and MULTICONTEXT=2 are ignored if any of these conditions are true:End of change

  • The application created a DB2 thread before it invoked DB2 ODBC. This situation is always the case for a stored procedure that uses DB2 ODBC.
  • The application created and switched to a private context that uses z/OS Context Services before it invoked DB2 ODBC.
  • The application started a unit of recovery with any RRS resource manager (for example, IMS™) before it invoked DB2 ODBC.
  • MVSATTACHTYPE=CAF is specified in the initialization file.
  • The operating system level does not support Unauthorized Context Services.
MVSATTACHTYPE = CAF | RRSAF
This keyword is placed in the subsystem section.
The MVSATTACHTYPE keyword is used to specify the DB2 for z/OS attachment type that DB2 ODBC uses to connect to the DB2 for z/OS address space. This parameter is ignored if the DB2 ODBC application is running as a DB2 for z/OS ODBC stored procedure. In that case, DB2 ODBC uses the attachment type that was defined for the stored procedure.
CAF
DB2 ODBC uses the DB2 for z/OS call attachment facility (CAF). CAF is the default value.
RRSAF
DB2 ODBC uses the DB2 for z/OS Resource Recovery Services attachment facility (RRSAF).

Specify MVSATTACHTYPE=RRSAF and MULTICONTEXT=0 to allow an ODBC application to create and manage its own contexts by using the z/OS Context Services. For more information, see MULTICONTEXT = 0 | 1 | 2.

For transactions on a global connection, specify AUTOCOMMIT=0, MULTICONTEXT=0, and MVSATTACHTYPE=RRSAF to complete global transaction processing.

To enable global transaction processing in an application, specify MVSATTACHTYPE=RRSAF, AUTOCOMMIT=0, and MULTICONTEXT=0.

MVSDEFAULTSSID = ssid
This keyword is placed in the common section.

The MVSDEFAULTSSID keyword specifies the default DB2 subsystem that the application connects to when it invokes the SQLAllocHandle() function (with HandleType set to SQL_HANDLE_ENV). Start of changeSpecify the DB2 subsystem name, the subgroup attachment name, or group attachment name (if used in a data sharing group) to which connections are made.End of changeThe default subsystem is 'DSN'.

OPTIMIZEFORNROWS = integer
This keyword is placed in the data source section.

The OPTIMIZEFORNROWS keyword appends the "OPTIMIZE FOR n ROWS" clause to every select statement, where n is an integer larger than 0. The default action is not to append this clause.

Start of changePARAMOPTATOMIC = 0 | 1End of change
Start of changeThis keyword is placed in the data source section.

The PARAMOPTATOMIC keyword determines whether the underlying processing for multi-row inserts is done through atomic or non-atomic SQL. PARAMOPTATOMIC has the following values:

0
The underlying processing uses non-atomic SQL.
1
The underlying processing uses atomic SQL. This is the default.
End of change
PATCH2 = patch number
This keyword is placed in the data source section.
The PATCH2 keyword specifies a workaround for known problems with ODBC applications. To set multiple PATCH2 values, list the values sequentially, separated by commas. For example, if you want patches 300, 301, and 302, specify PATCH2= "300,301,302" in the initialization file. The valid values for the PATCH2 keyword are:
0
No workaround (default).
300
SQLExecute() and SQLExecDirect() returns SQL_NO_DATA_FOUND instead of SQL_SUCCESS when SQLCODE=100. In this case, a delete or update affected no rows, or the result of the subselect of an insert statement is empty.
  • 0: No workaround (default).
  • 300

PATCH2=300 behavior: SQLExecute() and SQLExecDirect() return SQL_NO_DATA_FOUND instead of SQL_SUCCESS when SQLCODE=100. In this case, a delete or update affected no rows, or the result of the subselect of an insert statement is empty.

The following table explains how PATCH2 settings affect return codes.
Table 1. PATCH2 settings and SQL return codes
SQL statement SQLExecute() and SQLExecDirect() return value
A searched update or searched delete and no rows satisfy the search condition
  • SQL_SUCCESS without a patch (PATCH2=0)
  • SQL_NO_DATA_FOUND with a patch (PATCH2=300)
A mass delete or update and no rows satisfy the search condition
  • SQL_SUCCESS_WITH_INFO without a patch (PATCH2=0)
  • SQL_NO_DATA_FOUND with a patch (PATCH2=300)
A mass delete or update and one or more rows satisfy the search condition SQL_SUCCESS_WITH_INFO without a patch (PATCH2=0) or with a patch (PATCH2=300)

In ODBC 3.0, applications do not need to set the patch on. ODBC 3.0 behavior is equivalent to setting PATCH2=300.

PLANNAME = planname
This keyword is placed in the subsystem section.

The PLANNAME keyword specifies the name of the DB2 for z/OS PLAN that was created during installation. A PLAN name is required when initializing the application connection to the DB2 for z/OS subsystem, which occurs during the processing of the SQLAllocHandle() call (with HandleType set to SQL_HANDLE_ENV).

If no PLANNAME is specified, the default value DSNACLI is used.

Start of changeQUERYDATASIZE = integerEnd of change
Start of changeThis keyword is placed in the data source section.

QUERYDATASIZE specifies the amount of query data, in bytes, that DB2 returns on each FETCH operation when limited block fetch is enabled. The QUERYDATASIZE value can be used to optimize limited block fetch. It controls the number of trips to the data source that are required to retrieve data.

Using a larger value for QUERYDATASIZE can result in better performance. For example, if the result set size is 50 KB, and the value of QUERYDATASIZE is 32767 (32 KB), two trips to the data source are required to retrieve the result set. However, if QUERYDATASIZE is 65535 (62 KB), only one trip to the data source is required to retrieve the result set.

integer
One of the following QUERYDATASIZE values:
  • 32767
  • 65535
  • 98303
  • 131071
  • 163839
  • 196607
  • 229375
  • 262143
  • 294911
  • 327679
  • 360447
  • 393215
  • 425983
  • 458751
  • 491519
  • 524287
  • 557055
  • 589823
  • 622591
  • 655359
  • 688127
  • 720895
  • 753663
  • 786431
  • 819199
  • 851967
  • 884735
  • 917503
  • 950271
  • 983039
  • 1015807
  • 1048575

The default is 32767.

If you specify a value that is not a valid value, DB2 ODBC sets QUERYDATASIZE to the nearest valid value.

End of change
Start of changeRETURNALIASES = 0 | 1End of change
Start of change

This keyword is placed in the data source section.

The RETURNALIASES keyword specifies whether aliases are included when you qualify rows for metadata procedures. If you exclude aliases and do not qualify them, you avoid costly joins with the base tables and improve performance.

0
Aliases are not considered when rows are qualified for metadata procedures
1
Aliases are considered when rows are qualified for metadata procedures

This keyword affects the following ODBC APIs.

  • SQLColumns()
  • SQLColumnPrivileges()
  • SQLTables()
  • SQLTablePrivileges()
  • SQLStatistics()
  • SQLSpecialColumns()
  • SQLForeignKeys()
  • SQLPrimaryKeys()
End of change
Start of changeRETCATALOGASCURRSERVER = 0 | 1End of change
Start of change

This keyword is placed in the data source section.

You can use the RETCATALOGASCURRSERVER keyword to instruct the DBMS to return the CURRENT SERVER value instead of the null value for catalog columns.

0
Catalog functions return the null value for the catalog columns.
1
Catalog functions return the CURRENT SERVER value, instead of the null value, for the catalog columns.

This keyword affects the following ODBC APIs.

  • SQLColumns()
  • SQLColumnPrivileges()
  • SQLTables()
  • SQLTablePrivileges()
  • SQLStatistics()
  • SQLSpecialColumns()
  • SQLForeignKeys()
  • SQLPrimaryKeys()
  • SQLProcedures()
  • SQlProcedureColumns()
End of change
Start of changeRETURNSYSNONYMSCHEMA = 0 | 1End of change
Start of change

This keyword is placed in the data source section.

The RETURNSYSNONYMSCHEMA controls whether the catalog APIs report the schema name for synonyms in the TABLE_SCHEM columns.

0
Catalog functions return NULL for the schema columns.
1
Catalog functions return the creator of the synonym for the schema columns.

This keyword affects the following ODBC APIs.

  • SQLColumns()
  • SQLColumnPrivileges()
  • SQLTables()
  • SQLTablePrivileges()
  • SQLStatistics()
  • SQLSpecialColumns()
  • SQLForeignKeys()
  • SQLPrimaryKeys()
End of change
SCHEMALIST = "'schema1', 'schema2' ,…"
This keyword is placed in the data source section.

The SCHEMALIST keyword specifies a list of schemas in the data source.

If a database contains many tables, you can specify a schema list to reduce the time it takes for the application to query table information and the number of tables that are listed by the application. Each schema name is case-sensitive, must be delimited with single quotation marks and separated by commas. The entire string must also be enclosed in double quotation marks, for example:
SCHEMALIST="'USER1','USER2',USER3'"
For DB2 for z/OS ODBC, CURRENT SQLID can also be included in this list, but without the single quotation marks, for example:
SCHEMALIST="'USER1',CURRENT SQLID,'USER3'"

The maximum length of the keyword string is 2048 bytes.

This keyword can be used with DBNAME and TABLETYPE to further limit the number of tables for which information is returned.

SCHEMALIST is used to provide a more restrictive default in the case of those applications that always give a list of every table in the database server. This improves performance of the table list retrieval in cases where the user is only interested in seeing the tables in a few schemas.

SYSSCHEMA = sysschema
This keyword is placed in the data source section. The value that you specify for sysschema must be no longer than 128 bytes.

The SYSSCHEMA keyword indicates an alternative schema to be searched in place of the SYSIBM (or SYSTEM, QSYS2) schemas when the DB2 ODBC and ODBC catalog function calls are issued to obtain catalog information.

Using this schema name, the system administrator can define a set of views consisting of a subset of the rows for each of the following DB2 catalog tables:

  • SYSCOLAUTH
  • SYSCOLUMNS
  • SYSDATABASE
  • SYSFOREIGNKEYS
  • SYSINDEXES
  • SYSKEYS
  • SYSPARMS
  • SYSRELS
  • SYSROUTINES
  • SYSSYNONYMS
  • SYSTABAUTH
  • SYSTABLES

For example, if the set of views for the catalog tables are in the ACME schema, the view for SYSIBM.SYSTABLES is ACME.SYSTABLES, and SYSSCHEMA should then be set to ACME.

Defining and using limited views of the catalog tables reduces the number of tables listed by the application, which reduces the time it takes for the application to query table information.

If no value is specified, the following default values are used:
  • SYSIBM on DB2 for z/OS
  • SYSTEM on DB2 for VSE & VM
  • QSYS2 on DB2 for i
This keyword can be used with SCHEMALIST, TABLETYPE (and DBNAME on DB2 for z/OS) to further limit the number of tables for which information is returned.
TABLETYPE="'TABLE' | ,'ALIAS' | ,'VIEW' | , 'SYSTEM TABLE' | ,'SYNONYM' | 'GLOBAL TEMPORARY TABLE' |, 'AUXILIARY TABLE' |, 'MATERIALIZED QUERY TABLE' |, 'ACCEL-ONLY TABLE'"
This keyword is placed in the data source section.

The TABLETYPE keyword specifies a list of one or more table types. If many tables are defined in the data source, you can specify a table type string to reduce the time it takes for the application to query table information and the number of tables the application lists.

Any number of the values can be specified, but each type must be delimited with single quotation marks, separated by commas, and in uppercase. The entire string must also be enclosed in double quotation marks, for example:
TABLETYPE="'TABLE','VIEW'"
This keyword can be used with DBNAME and SCHEMALIST to further limit the number of tables for which information is returned.

TABLETYPE is used to provide a default for the SQLTables() call, which retrieves a list of table names and associated information in a data source. If the application does not specify a table type on the function call, and this keyword is not used, information about all table types is returned. If the application supplies a value for the szTableType argument on the function call, that argument value overrides this keyword value.

If TABLETYPE includes any value other than TABLE, the DBNAME keyword setting cannot be used to restrict information to a particular DB2 for z/OS subsystem.

'ACCEL-ONLY TABLE' is an extended table type name. Extended table type names are returned in the result set of an SQLTables() call only if the EXTENDEDTABLETYPE initialization parameter is set to 1.

THREADSAFE= 1 | 0
This keyword is placed in the common section.
The THREADSAFE keyword controls whether DB2 ODBC uses POSIX mutexes to make the DB2 ODBC code threadsafe for multiple concurrent or parallel Language Environment threads.
1
The DB2 ODBC code is threadsafe if the application is executing in a POSIX(ON) environment. Multiple Language Environment threads in the process can use DB2 ODBC. The threadsafe capability cannot be provided in a POSIX(OFF) environment. 1 is the default value.
0
The DB2 ODBC code is not threadsafe. This setting reduces the cost of serialization code in DB2 ODBC for applications that are not multithreaded, but provides no protection for concurrent Language Environment threads in applications that are multithreaded.
TRACEPIDTID = 0 | 1
This keyword is placed in the common section.

TRACEPIDTID is used only if a trace is started through the APPLTRACE keyword. When TRACEPIDTID is set to 1, the process ID and thread ID are added to the beginning of each line in the trace output. These IDs help you to differentiate the recorded information by process and thread when the DB2 ODBC application is running multiple concurrent Language Environment threads in a POSIX(ON) environment.

TRACECTXTOKEN = 0 | 1
This keyword is placed in the common section.

TRACECTXTOKEN is used only if a trace is started through the APPLTRACE keyword. When TRACECTXTOKEN is set to 1, the RRS context tokens are captured in the trace output. RSS context tokens help you to determine the execution path for applications that execute under different RRS contexts.

This keyword is applicable only to applications that create and manage their own RRS contexts with the z/OS Resource Recovery Services with keywords MVSATTACHTYPE=RRSAF and MULTICONTEXT=0 specified in the initialization file.

Start of changeTRACETIMESTAMP = 0 | 3End of change
Start of changeThis keyword is placed in the common section.

TRACETIMESTAMP is used only if a trace is started through the APPLTRACE keyword. When APPLTRACE is set to 1, the TRACETIMESTAMP keyword is used to capture different types of time stamp information in the DB2 ODBC application trace.

0
No time stamp information is written to the trace output.
3
An ISO time stamp is added to the beginning of each line in the trace output.
End of change
TXNISOLATION = 1 | 2 | 4 | 8 | 32
This keyword is placed in the data source section.
The TXNISOLATION keyword sets the isolation level to one of the following values:
1
Read uncommitted (uncommitted read)
2
Read committed (cursor stability) (default)
4
Repeatable read (read stability)
8
Serializable (repeatable read)
32
(No commit, DB2 for i only)

The words in round brackets are the DB2 equivalents for SQL92 isolation levels. "no commit" is not an SQL92 isolation level and is supported only on DB2 for i.

UNDERSCORE = 1 | 0
This keyword is placed in the data source section.
Specifies whether the underscore character (_) is to be used as a wildcard character (matching any one character, including no character), or to be used as itself. This parameter affects only catalog function calls that accept search pattern strings. You can set the UNDERSCORE keyword to the following values:
1
The underscore character (_) acts as a wildcard (default). The underscore is treated as a wildcard that matches any one character or none. For example, two tables are defined as follows:
CREATE TABLE "OWNER"."KEY_WORDS" (COL1 INT)
CREATE TABLE "OWNER"."KEYWORDS" (COL1 INT)
In the previous example above, SQLTables() (the DB2 ODBC catalog function call that returns table information) returns both the "KEY_WORDS" and "KEYWORDS" entries if "KEY_WORDS" is specified in the table name search pattern argument.
0
The underscore character (_) acts as itself. The underscore is treated literally as an underscore character. If two tables are defined as shown in the previous example, SQLTables() returns only the "KEY_WORDS" entry if "KEY_WORDS" is specified in the table name search pattern argument. Setting this keyword to 0 can result in performance improvement in those cases where object names (owner, table, column) in the data source contain underscores.