- Connection attributes
- The connection
attribute is specified in the ValuePtr argument of the SQLSetConnectAttr() function.
- SQL_ATTR_ACCESS_MODE
- A 32-bit integer value which can be either SQL_MODE_READ_ONLY or SQL_MODE_READ_ONLY:
- SQL_MODE_READ_ONLY: Indicates that an application
intends to perform read operations on data. Therefore, a less restrictive
isolation level and locking such as uncommitted read (SQL_TXN_READ_UNCOMMITTED)
can be used on transactions. The CLI driver
does not ensure that requests to the database are read-only.
If an update request is issued, the CLI driver
process the update request with the transaction isolation level that
is selected as a result of the SQL_MODE_READ_ONLY setting.
- SQL_MODE_READ_WRITE (default): Indicates
that an application intends to modify data. The CLI driver
uses the default transaction isolation level for the connection where
the SQL_MODE_READ_WRITE attribute is specified.
There must not be any outstanding transactions on a connection
where the SQL_ATTR_ACCESS_MODE attribute was specified.
- SQL_ATTR_ALLOW_INTERLEAVED_GETDATA
- The SQL_ATTR_ALLOW_INTERLEAVED_GETDATA attribute
only affects connections to database servers that support Dynamic
Data Format, also known as progressive streaming.
Specifies whether
an application can call the SQLGetData() function
for the previously accessed LOB columns and maintain the data offset
position from the previous call to the SQLGetData() function.
when querying data servers that support Dynamic Data Format.
The
SQL_ATTR_ALLOW_INTERLEAVED_GETDATA attribute can have one of the following
values: - SQL_ALLOW_INTERLEAVED_GETDATA_OFF (default):
Specify that an application does not intend to call the SQLGetData() function
for the previously accessed LOB columns.
- SQL_ALLOW_INTERLEAVED_GETDATA_ON: Specify that
an application intend to call SQLGetData() for
previously accessed LOB columns and reads LOB data from where an application
stopped reading during the previous read.
Setting the AllowInterleavedGetData CLI/ODBC configuration keyword is an alternative
method to specifying the SQL_ATTR_ALLOW_INTERLEAVED_GETDATA attribute.
- SQL_ATTR_ANSI_APP
- A 32-bit unsigned integer that identifies an application as an
ANSI or Unicode application. The SQL_ATTR_ANSI_APP attribute has
one of the following values:
- SQL_AA_TRUE (default): Specify that an
application is an ANSI application. All character data that is passed
to and from an application is in the client code page with the ANSI
version of the CLI/ODBC functions.
- SQL_AA_FALSE: Specify that an application is
a Unicode application. All character data that is passed to and from
an application is in Unicode when the Unicode (W) versions of the CLI/ODBC functions
are called.
- SQL_ATTR_APP_USES_LOB_LOCATOR
- The SQL_ATTR_APP_USES_LOB_LOCATOR attribute indicates whether
the LOB locators are used by an application. The SQL_ATTR_APP_USES_LOB_LOCATOR
attribute can have one of the following values:
- 1 (default): Indicates use of the LOB
locators.
- 0: Indicates that the LOB locators are not used.
If the application is querying a server that supports the Dynamic
Data Format feature, also known as progressive streaming, the 0 value
can be specified to stream the data and avoid use of the LOB locators.
The SQL_ATTR_APP_USES_LOB_LOCATOR attribute is ignored for
stored procedure result sets.
If the SQL_ATTR_APP_USES_LOB_LOCATOR
attribute is set to 0 and an application binds a
LOB locator to a result set with the SQLBindCol() function,
an Invalid conversion error is returned by the SQLFetch() function.
Setting
the AppUsesLOBLocator CLI/ODBC configuration keyword is an alternative method for
indicating the use of the LOB locators.
- SQL_ATTR_APPEND_FOR_FETCH_ONLY
The SQL_ATTR_APPEND_FOR_FETCH_ONLY attribute allows an application
to specify when the CLI driver
appends the "FOR FETCH ONLY" clause. For example, if the CLI packages
are bound with BLOCKING UNAMBIG option, application can specify 0 value
for the SQL_ATTR_APPEND_FOR_FETCH_ONLY attribute to prevent cursor
blocking or specify 1 to allow cursor blocking.
The
SQL_ATTR_APPEND_FOR_FETCH_ONLY attribute can have one of the following
values:
- 0: The CLI driver
never appends the "FOR FETCH ONLY" clause to SELECT statements regardless
of the server type it is connecting to.
- 1: The CLI driver
always appends the "FOR FETCH ONLY" clause to SELECT statements regardless
of the server type it is connecting to.
By default, the
CLI driver
appends the "FOR FETCH ONLY" clause to SELECT statements when connected
to the
DB2® for z/OS® servers
or the
IBM® DB2 for IBM i (
DB2 for i)
servers.
The SQL_ATTR_APPEND_FOR_FETCH_ONLY can be set
either before a connection is allocated or immediately after a connection
is established. Application can query the SQL_ATTR_APPEND_FOR_FETCH_ONLY
attribute with the SQLGetConnectAttr() function
after connection is established or after the SQL_ATTR_APPEND_FOR_FETCH_ONLY
attribute is set.
Setting the AppendForFetchOnly CLI/ODBC configuration keyword is
an alternative method to specify when the CLI driver
appends the "FOR FETCH ONLY" clause.
- SQL_ATTR_ASYNC_ENABLE
- A 32-bit integer value that specifies whether the execution of
statements on the specified connection is asynchronous:
- SQL_ASYNC_ENABLE_OFF (default): Disables
the asynchronous statement execution.
- SQL_ASYNC_ENABLE_ON: Enables the asynchronous
statement execution.
Setting the SQL_ASYNC_ENABLE_ON value enables
asynchronous execution of statements across all statement handles
on a connection where the SQL_ASYNC_ENABLE_ON value
is specified. An error is returned if asynchronous execution is turned
on while there is an active statement on the connection. This attribute
can be set when the SQLGetInfo() function
that is called with the SQL_ASYNC_MODE (for the InfoType argument)
value returns SQL_AM_CONNECTION or SQL_AM_STATEMENT.
When a
function is called asynchronously in a statement, only the following
functions can be issued in the same statement handle for the connection
where the
SQL_ASYNC_ENABLE_ON value is set:
- Original function that is currently running.
- The SQLAllocHandle() function.
- The SQLCancel() function.
- The SQLGetDiagField() function.
- The SQLGetDiagRec() function.
Any other function calls on the same statement handle returns
SQL_ERROR with an SQLSTATE of HY010 (Function sequence error). If
the original function is issued again on the same statement handle
while it is still running, the original function returns the SQL_STILL_EXECUTING
value.
The following functions can be issued asynchronously:
- SQLBulkOperations()
- SQLColAttribute()
- SQLColumnPrivileges()
- SQLColumns()
- SQLDescribeCol()
- SQLDescribeParam()
- SQLExecDirect()
- SQLExecute()
- SQLExtendedFetch()
- SQLExtendedPrepare()
- SQLFetch()
- SQLFetchScroll()
- SQLForeignKeys()
- SQLGetData()
- SQLGetLength()
- SQLGetPosition()
- SQLMoreResults()
- SQLNumResultCols()
- SQLParamData()
- SQLPrepare()
- SQLPrimaryKeys()
- SQLProcedureColumns()
- SQLProcedures()
- SQLRowCount()
- SQLSetPos()
- SQLSpecialColumns()
- SQLStatistics()
- SQLTablePrivileges()
- SQLTables()
Note: Unicode equivalent functions can also be called asynchronously.
- SQL_ATTR_AUTO_IPD
- A read-only 32-bit unsigned integer value that specifies whether
automatic population of the IPD after a call to SQLPrepare() is
supported:
- SQL_TRUE = Automatic population of the IPD after a call to SQLPrepare() is
supported by the server.
- SQL_FALSE = Automatic population of the IPD after a call to SQLPrepare() is
not supported by the server. Servers that do not support prepared
statements will not be able to populate the IPD automatically.
If SQL_TRUE is returned for the SQL_ATTR_AUTO_IPD connection
attribute, the statement attribute SQL_ATTR_ENABLE_AUTO_IPD can be
set to turn automatic population of the IPD on or off. If SQL_ATTR_AUTO_IPD
is SQL_FALSE, SQL_ATTR_ENABLE_AUTO_IPD cannot be set to SQL_TRUE.
The
default value of SQL_ATTR_ENABLE_AUTO_IPD is equal to the value of
SQL_ATTR_AUTO_IPD.
This connection attribute can be returned
by SQLGetConnectAttr(),
but cannot be set by SQLSetConnectAttr().
- SQL_ATTR_AUTOCOMMIT
- A 32-bit unsigned integer value that specifies whether to use
auto-commit or manual commit mode:
Since in many DB2 environments,
the execution of the SQL statements and the commit might be flowed
separately to the database server, autocommit can be expensive. It
is recommended that the application developer take this into consideration
when selecting the auto-commit mode.
Note: Changing from
manual commit to auto-commit mode will commit any open transaction
on the connection.
- SQL_ATTR_CLIENT_CODEPAGE
- A connection level attribute value that enables the user to specify
connection level code page from the CLI application.
Specifying this attribute will override any environment level default
code page setting:
Example 1: Setting
the code page to be used by this database connection
Unicode = 1208;
cliRC = SQLSetConnectAttr(hdbc,
SQL_ATTR_CLIENT_CODEPAGE,
(SQLPOINTER)&unicode, SQL_NTS);
char *connStr = "DSN=EBCDICDB;";
cliRC = SQLDriverConnect (hdbc, (SQLHWND)NULL, connStr, SQL_NTS, NULL, 0, NULL, SQL_DRIVER_NOPROMPT);
Example 2: Getting the current value of SQL_ATTR_CLIENT_CODEPAGE
cliRC = SQLConnect(hdbc,
(SQLCHAR *)"SAMPLE",
SQL_NTS,
(SQLCHAR *)"USER1",
SQL_NTS,
(SQLCHAR *)"PASSWD1",
SQL_NTS);
cliRC = SQLGetConnectAttr(hdbc,
SQL_ATTR_CLIENT_CODEPAGE,
&codePage, 0, NULL);
- SQL_ATTR_CLIENT_LOB_BUFFERING
-
Specifies whether LOB locators or the underlying LOB data
is returned in a result set for LOB columns that are not bound. By
default, locators are returned. If an application usually fetches
unbound LOBs and then must retrieve the underlying LOB data, the application's
performance can be improved by retrieving the LOB data from the outset;
this reduces the number of synchronous waits and network flows. The
possible values for this attribute are:
- SQL_CLIENTLOB_USE_LOCATORS (default) - LOB locators are returned
- SQL_CLIENTLOB_BUFFER_UNBOUND_LOBS - actual LOB data is returned
- SQL_ATTR_CLIENT_TIME_ZONE
- A null-terminated character string in the format ±hh:mm, containing
the Time Zone information. Specifying this attribute will override
the default Operating System Time Zone value of Client host.
- SQL_ATTR_COLUMNWISE_MRI
- A 32-bit unsigned integer
that enables CLI applications
that are connected to the DB2 for z/OS servers
to convert array input chaining into column-wise array input for INSERT
operations. The possible values for the SQL_ATTR_COLUMNWISE_MRI attribute
are SQL_COLUMNWISE_MRI_OFF and SQL_COLUMNWISE_MRI_ON:
- SQL_COLUMNWISE_MRI_OFF (default): The CLI driver
does not convert chaining data to column-wise array input.
- SQL_COLUMNWISE_MRI_ON: The CLI driver
converts array input chaining to column-wise array input. The Multi-Row
Insert (MRI) feature inDB2 for z/OS expects
data to be in column-wise array form. If your application uses array
input chaining, this conversion helps you optimize your application
performance because data is sent in a compact array form each time
you call SQLExecute (). For more information about
array input chaining, see SQL_ATTR_CHAINING_BEGIN.
For outside a DB2 for z/OS servers,
the CLI driver
automatically converts chaining data to row-wise array input and setting
this attribute has no effect.
The conversion is not performed
in the following cases:
- Bind parameters with a LOB data type such as SQL_CLOB, SQL_BLOB,
SQL_LONGVARBINARY, SQL_LONGVARGRAPHIC, SQL_DBCLOB, or SQL_XML.
- Bind input data-at-execute parameters by setting their value to
SQL_DATA_AT_EXEC to pass data to INSERT operations by calling the SQLPutData() and SQLParamData() functions.
- Space to store all the application data in the internal buffers
is not available.
- SQL_ATTR_COMMITONEOF
- The SQL_ATTR_COMMITONEOF attribute specifies whether the implicit
COMMIT statement is issued immediately following the retrieval of
the entire result set and the EOF marker. The SQL_ATTR_COMMITONEOF
attribute can have one of the following values
- SQL_COMMITONEOF_ON: The implicit COMMIT statement
is issued following the retrieval of the entire result set and the
EOF marker.
- SQL_COMMITONEOF_OFF (default): The COMMIT
statement is not implicitly issued following the retrieval of the
entire result set and the EOF marker. You must explicitly call the SQLFreeStmt() function
to close the cursor and release resources. The SQL_COMMITONEOF_OFF value
is the default.
You must ensure that the following conditions are satisfied
to enable the
SQL_COMMITONEOF_ON attribute:
- The autocommit mode is enabled.
- The cursor is read-only and forward-only.
- The SQL_ATTR_EARLYCLOSE statement attribute is set to SQL_EARLYCLOSE_ON (default).
Note: Usage of this attribute does not replace the requirement
to call the SQLFreeStmt() function.
- SQL_ATTR_CONCURRENT_ACCESS_RESOLUTION
- A 32-bit integer value that specifies the concurrent access resolution
to use at the statement level. This setting overrides the default
behavior specified for cursor stability (CS) scans.
- 0 = No setting. The client does not supply a prepare option.
- 1 = Use currently committed semantics. CLI flows "currently committed" on every prepare, which means
that the database manager can use the currently committed version
of the data for applicable scans when the data is in the process of
being updated or deleted. Rows in the process of being inserted can
be skipped. This setting applies when the isolation level in effect
is Cursor Stability or Read Stability (for Read Stability it skips
uncommitted inserts only) and is ignored otherwise. Applicable scans
include read-only scans that can be part of a read-only statement
as well as a non read-only statement. The
settings for the registry variables DB2_EVALUNCOMMITTED, DB2_SKIPDELETED, and DB2_SKIPINSERTED do not apply to scans using currently committed. However, the settings
for these registry variables still apply to scans that do not use
currently committed.
- 2
= Wait for outcome. CLI flows "wait for outcome" on every prepare, which means
that Cursor Stability and higher scans wait for the commit or rollback
when encountering data in the process of being updated or deleted.
Rows in the process of being inserted are not skipped. The settings
for the registry variables DB2_EVALUNCOMMITTED, DB2_SKIPDELETED, and
DB2_SKIPINSERTED no longer apply.
- 3 = Skip locked data. CLI flows "skip locked data" on every prepare, which means
that currently committed semantics are used and rows in the process
of being inserted are skipped. This option is not supported on DB2 for Linux, UNIX, and Windows. If specified, this setting is ignored.
For DB2 for Linux, UNIX, and Windows,
use this attribute to override the default behavior for currently
committed that is defined by the cur_commit configuration
parameter. For DB2 for z/OS,
use this attribute to enable currently committed behavior. There is
no equivalent database configuration parameter available on DB2 for z/OS for
specifying this behavior.
Setting the ConcurrentAccessResolution CLI/ODBC configuration keyword is
an alternative method of specifying this behavior.
- SQL_ATTR_CONN_CONTEXT
- Indicates which context the connection should use. An SQLPOINTER
to either:
- a valid context (allocated by the sqleBeginCtx() DB2 API)
to set the context
- a NULL pointer to reset the context
This attribute can only be used when the application is
using the DB2 context APIs to
manage multi-threaded applications. By default, CLI manages
contexts by allocating one context per connection handle, and ensuring
that any executing thread is attached to the correct context.
For
more information about contexts, refer to the sqleBeginCtx() API.
This attribute is not supported when accessing Informix® database
servers.
- SQL_ATTR_CONNECT_NODE
- A 32-bit integer that specifies the target logical partition of
a DB2 Enterprise Server Edition
database partition server that you want to connect to. The possible
values for this attribute are:
- an integer between 0 and 999
- SQL_CONN_CATALOG_NODE
If this variable is not set, the target logical node defaults
to the logical node which is defined with port 0 on the machine.
This attribute is not supported when accessing Informix database
servers.
There
is also a corresponding keyword, the ConnectNode CLI/ODBC configuration keyword.
- SQL_ATTR_CONNECTION_DEAD
- A read only 32-bit integer value that indicates whether or not
the connection is still active. CLI will
return one of the following values:
- SQL_CD_FALSE - the connection is still active.
- SQL_CD_TRUE - an error has already happened and caused the connection
to the server to be terminated. The application should still perform
a disconnect to clean up any CLI resources.
This attribute is used mainly by the Microsoft ODBC Driver Manager 3.5x before
pooling the connection.
- SQL_ATTR_CONNECTION_TIMEOUT
- This connection attribute is defined by ODBC, but is not supported
by CLI.
Any attempt to set or get this attribute will result in an SQLSTATE
of HYC00 (Driver not capable).
- SQL_ATTR_CONNECTTYPE
- A 32-bit integer value that specifies whether this application
is to operate in a coordinated or uncoordinated distributed environment.
The possible values are as follows:
If changing this attribute from the default then it must
be set before any connections have been established on the environment
handle.
It is recommended that the application set this attribute
as an environment attribute with a call to SQLSetEnvAttr(),
if necessary, as soon as the environment handle has been allocated.
However, since ODBC applications cannot access SQLSetEnvAttr(),
they must set this attribute using SQLSetConnectAttr() after
each connection handle is allocated, but before any connections have
been established.
All connections on an environment handle
must have the same SQL_ATTR_CONNECTTYPE setting. An environment cannot
have a mixture of concurrent and coordinated connections. The type
of the first connection will determine the type of all subsequent
connections. SQLSetEnvAttr() will
return an error if an application attempts to change the connection
type while there is an active connection.
The default connect
type can also be set using the ConnectType CLI/ODBC configuration keyword.
Note: This
is an IBM defined
attribute.
- SQL_ATTR_CURRENT_CATALOG
- A null-terminated character string containing the name of the
catalog used by the data source. The catalog name is typically the
same as the database name.
This connection attribute can be returned
by SQLGetConnectAttr(),
but cannot be set by SQLSetConnectAttr().
Any attempt to set this attribute will result in an SQLSTATE of HYC00
(Driver not capable).
- SQL_ATTR_CURRENT_IMPLICIT_XMLPARSE_OPTION
- A null-terminated character string that is the string constant
used to set the CURRENT IMPLICIT XMLPARSE OPTION special register.
Setting this attribute causes the SET CURRENT IMPLICIT XMLPARSE OPTION
SQL statement to be issued. If this attribute is set before a connection
has been established, the SET CURRENT IMPLICIT XMLPARSE OPTION SQL
statement will be issued when the connection is made.
This
attribute is not supported when accessing Informix database
servers.
- SQL_ATTR_CURRENT_PACKAGE_PATH
- A null-terminated character string of package qualifiers that
the DB2 database server uses
to try to resolve the package when multiple packages have been configured.
Setting this attribute causes the "SET CURRENT PACKAGE PATH = schema1,
schema2, ..." statement to be issued after every connection
to the database server.
This attribute is best suited for use
with ODBC static processing applications, rather than CLI applications.
This attribute is not supported when accessing Informix database
servers.
Note: This
is an IBM defined
attribute.
- SQL_ATTR_CURRENT_PACKAGE_SET
-
A null-terminated character string that indicates the schema
name (collection identifier) that is used to select the package for
subsequent SQL statements. Setting this attribute causes the SET CURRENT
PACKAGESET SQL statement to be issued. If this attribute is set before
a connection, the SET CURRENT PACKAGESET SQL statement will be issued
at connection time.
CLI/ODBC applications
issue dynamic SQL statements. Using this connection attribute, you
can control the privileges used to run these statements:
- Choose a schema to use when running SQL statements from CLI/ODBC applications.
- Ensure the objects in the schema have the required privileges
and then rebind accordingly. This typically means binding the CLI packages
(sqllib/bnd/db2cli.lst) using the COLLECTION <collid> option.
Refer to the BIND command for further details.
- Set the CURRENTPACKAGESET option to this schema.
The SQL statements from the
CLI/ODBC applications
will now run under the specified schema and use the privileges defined
there.
Setting the CurrentPackageSet CLI/ODBC configuration keyword is an
alternative method of specifying the schema name.
The following
package set names are reserved: NULLID, NULLIDR1, NULLIDRA.
SQL_ATTR_REOPT
and SQL_ATTR_CURRENT_PACKAGE_SET are mutually exclusive, therefore,
if one is set, the other is not allowed.
This
attribute is not supported when accessing Informix database
servers.
- SQL_ATTR_CURRENT_SCHEMA
- A null-terminated character string containing the name of the
schema to be used by CLI for
the SQLColumns() call
if the szSchemaName pointer is set to null.
To reset this option, specify this option with a zero length
string or a null pointer for the ValuePtr argument.
This option is useful when the application developer has coded a generic
call to SQLColumns() that
does not restrict the result set by schema name, but needs to constrain
the result set at isolated places in the code.
This option
can be set at any time and will be effective on the next SQLColumns() call
where the szSchemaName pointer is null.
Note: The
SQL_ATTR_CURRENT_SCHEMA attribute is an IBM defined attribute.
- SQL_ATTR_DB2_APPLICATION_HANDLE
- A user-defined character string that returns the application handle
of the connection. If the string is not large enough to contain the
complete application handle, it will be truncated.
This connection
attribute can be returned by SQLGetConnectAttr(),
but cannot be set by SQLSetConnectAttr().
This attribute is not supported when accessing Informix database
servers.
- SQL_ATTR_DB2_APPLICATION_ID
- A user-defined character string that returns the application identifier
of the connection. If the string is not large enough to contain the
complete application identifier, it will be truncated.
This connection
attribute can be returned by SQLGetConnectAttr(),
but cannot be set by SQLSetConnectAttr().
This attribute is not supported when accessing Informix database
servers.
- SQL_ATTR_DB2_SQLERRP
- An sqlpointer to a null-terminated string containing the sqlerrp field
of the sqlca.
Begins with a three-letter identifier indicating
the product, followed by five alphanumeric characters indicating
the version, release, and modification level of the product. The characters
A-Z indicate a modification level higher than 9. A indicates modification
level 10, B indicates modification level 11, and so on. For example,
SQL0907C means DB2 Version
9 Release 7 Modification level 12.
If SQLCODE indicates an error
condition, then this field identifies the module that returned the
error.
This field is also used when a successful connection
is completed.
Note: This is an IBM defined attribute.
- SQL_ATTR_DB2ESTIMATE
- This attribute has been deprecated in the DB2 for Linux, UNIX, and Windows product.
- SQL_ATTR_DB2EXPLAIN
- A 32-bit integer that specifies whether Explain snapshot, Explain
mode information, or both should be generated by the server. Permitted
values are:
- SQL_DB2EXPLAIN_OFF: Both the Explain Snapshot and the Explain
table option facilities are disabled (a SET CURRENT EXPLAIN SNAPSHOT=NO
and a SET CURRENT EXPLAIN MODE=NO are sent to the server).
- SQL_DB2EXPLAIN_SNAPSHOT_ON: The Explain Snapshot facility is enabled,
and the Explain table option facility is disabled (a SET CURRENT EXPLAIN
SNAPSHOT=YES and a SET CURRENT EXPLAIN MODE=NO are sent to the server).
- SQL_DB2EXPLAIN_MODE_ON: The Explain Snapshot facility is disabled,
and the Explain table option facility is enabled (a SET CURRENT EXPLAIN
SNAPSHOT=NO and a SET CURRENT EXPLAIN MODE=YES are sent to the server).
- SQL_DB2EXPLAIN_SNAPSHOT_MODE_ON: Both the Explain Snapshot and
the Explain table option facilities are enabled (a SET CURRENT EXPLAIN
SNAPSHOT=YES and a SET CURRENT EXPLAIN MODE=YES are sent to the server).
Before the explain information can be generated, the explain
tables must be created.
This statement is not under transaction
control and is not affected by a ROLLBACK. The new SQL_ATTR_DB2EXPLAIN
setting is effective on the next statement preparation for this connection.
The
current authorization ID must have INSERT privilege for the Explain
tables.
The default value can also be set using the DB2Explain CLI/ODBC configuration keyword.
This attribute
is not supported when accessing Informix database
servers.
Note: This
is an IBM defined
attribute.
- SQL_ATTR_DBC_SYS_NAMING
- A 32-bit integer that specifies whether the system naming mode
or the SQL naming mode is used when connecting to the DB2 for i V7R1
server and later with PTF SI46944. Possible values are:
- SQL_TRUE: The DB2 for i system
naming mode is used. Files are qualified with the slash (/) delimiter.
Unqualified files are resolved with the library list for the job.
- SQL_FALSE: The SQL naming mode which is the default
value. Files are qualified with the period (.) delimiter. Unqualified
files are resolved with either the default library or the current
user ID.
Example of setting the SQL_ATTR_DBC_SYS_NAMING attribute:cliRC = SQLSetConnectAttr(hdbc,
SQL_ATTR_DBC_SYS_NAMING ,
(SQLPOINTER)SQL_TRUE,
SQL_NTS);
Note: This is an IBM defined attribute
which is only applicable when connecting to the DB2 for i V7R1
server and later with PTF SI46944.
- SQL_ATTR_DECFLOAT_ROUNDING_MODE
-
The decimal float rounding
mode determines what type of rounding will be used if a value is put
into a DECFLOAT variable or column but the value has more digits than
are allowed in the DECFLOAT data type. This can occur when inserting,
updating, selecting, converting from another type, or as the result
of a mathematical operation.
The value of SQL_ATTR_DECFLOAT_ROUNDING_MODE
determines the decimal float rounding mode that will be used for new
connections unless another mode is specified by a connection attribute
for that connection. For any given connection both CLI and DB2 will use the same decimal float rounding mode for all
action initiated as part of that connection.
When your applications
are connecting to a DB2 for Linux, UNIX, and Windows Version 9.5 server, you must set the decimal float rounding
mode on the database client to the same mode that is set on the server.
If you set the decimal float rounding mode on the client to a value
that is different from the decimal float rounding mode that is set
on the database server, the database server will return SQL0713N on
connection.
The settings correspond to these decimal float rounding modes:
- 0 = Half even (default)
- 1 = Half up
- 2 = Down
- 3 = Ceiling
- 4 = Floor
The different modes are:
- Half even (default)
- In this mode CLI and DB2 use the number that will fit in the target variable and
that is closest to the original value. If two numbers are equally
close, they use the one that is even. This mode produces the smallest
rounding errors over large amounts of data.
- Half up
- In this mode CLI and DB2 use the number that will fit in the target variable and
that is closest to the original value. If two numbers are equally
close, they use the one that is greater than the original value.
- Down
- In this mode CLI and DB2 use the number that will fit in the target variable and
that is closest to the original value and for which the absolute value
is not greater than the absolute value of the original value. You
can also think of this as rounding toward zero or as using ceiling
for negative values and using floor for positive values.
- Ceiling
- In this mode CLI and DB2 use the smallest number that will fit in the target variable
and that is greater than or equal to the original value.
- Floor
- In this mode CLI and DB2 use the largest number that will fit in the target variable
and that is less than or equal to the original value.
This attribute is not supported
when accessing Informix database
servers.
- SQL_ATTR_DESCRIBE_CALL
- A 32-bit integer value that indicates when stored procedure arguments
are described. By default, CLI does
not request input parameter describe information when it prepares
a CALL statement. If an application has correctly bound parameters
to a statement, then this describe information is unnecessary and
not requesting it improves performance. The option values are:
- 1 = SQL_DESCRIBE_CALL_BEFORE.
- -1 = SQL_DESCRIBE_CALL_DEFAULT.
Setting this attribute can be done using the DescribeCall CLI/ODBC configuration keyword. Refer to the keyword for usage information
and descriptions of the available options.
Note: This is an IBM defined attribute.
- SQL_ATTR_DESCRIBE_OUTPUT_LEVEL
- A null-terminated character string that controls the amount of
information the CLI driver
requests on a prepare or describe request. By default, when the server
receives a describe request, it returns the information contained
in level 2 of Table 2 for the
result set columns. An application, however, might not need all of
this information or might need additional information. Setting the
SQL_ATTR_DESCRIBE_OUTPUT_LEVEL attribute to a level that suits the
needs of the client application might improve performance because
the describe data transferred between the client and server is limited
to the minimum amount that the application requires. If the SQL_ATTR_DESCRIBE_OUTPUT_LEVEL
setting is set too low, it might impact the functionality of the application
(depending on the application's requirements). The CLI functions
to retrieve the describe information might not fail in this case,
but the information returned might be incomplete. Supported settings
for SQL_ATTR_DESCRIBE_OUTPUT_LEVEL are:
- 0 - no describe information is returned to the client application
- 1 - describe information categorized in level 1 (see Table 2) is returned to the client
application
- 2 - (default) describe information categorized in level 2 (see Table 2) is returned to the client
application
- 3 - describe information categorized in level 3 (see Table 2) is returned to the client
application
The following table lists the fields that form the describe
information that the server returns when it receives a prepare or
describe request. These fields are grouped into levels, and the SQL_ATTR_DESCRIBE_OUTPUT_LEVEL
attribute controls which levels of describe information the CLI driver
requests.
Note: - Not all levels of describe information are supported by all DB2 servers.
All levels of describe information are supported on the following DB2 servers:
- DB2 for Linux, UNIX, and Windows
- DB2 for z/OS Version
8 and later
- DB2 for i Version
5 Release 3 and later
All other DB2 servers
support only the 2 or 0 setting for the SQL_ATTR_DESCRIBE_OUTPUT_LEVEL
attribute.
- The default behavior will allow CLI to
promote the level to 3 if the application asks for describe information
that was not initially retrieved using the default level 2. This might
result in two network flows to the server. If an application uses
this attribute to explicitly set a describe level, then no promotion
will occur. Therefore, if the attribute is used to set the describe
level to 2, then CLI will
not promote to level 3 even if the application asks for extended information.
Table 2. Levels
of describe informationLevel 1 |
Level 2 |
Level 3 |
SQL_DESC_COUNT
SQL_COLUMN_COUNT
SQL_DESC_TYPE
SQL_DESC_CONCISE_TYPE
SQL_COLUMN_LENGTH
SQL_DESC_OCTET_LENGTH
SQL_DESC_LENGTH
SQL_DESC_PRECISION
SQL_COLUMN_PRECISION
SQL_DESC_SCALE
SQL_COLUMN_SCALE
SQL_DESC_DISPLAY_SIZE
SQL_DESC_NULLABLE
SQL_COLUMN_NULLABLE
SQL_DESC_UNSIGNED
SQL_DESC_SEARCHABLE
SQL_DESC_LITERAL_SUFFIX
SQL_DESC_LITERAL_PREFIX
SQL_DESC_CASE_SENSITIVE
SQL_DESC_FIXED_PREC_SCALE
|
all fields of level 1 and:
SQL_DESC_NAME
SQL_DESC_LABEL
SQL_COLUMN_NAME
SQL_DESC_UNNAMED
SQL_DESC_TYPE_NAME
SQL_DESC_DISTINCT_TYPE
SQL_DESC_REFERENCE_TYPE
SQL_DESC_STRUCTURED_TYPE
SQL_DESC_USER_TYPE
SQL_DESC_LOCAL_TYPE_NAME
SQL_DESC_USER_DEFINED_
TYPE_CODE
|
all fields of levels 1
and 2 and:
SQL_DESC_BASE_COLUMN_NAME
SQL_DESC_UPDATABLE
SQL_DESC_AUTO_UNIQUE_VALUE
SQL_DESC_SCHEMA_NAME
SQL_DESC_CATALOG_NAME
SQL_DESC_TABLE_NAME
SQL_DESC_BASE_TABLE_NAME
|
Setting the DescribeOutputLevel CLI/ODBC configuration keyword is an alternative
method of specifying this behavior.
- SQL_ATTR_ENLIST_IN_DTC
- An SQLPOINTER which can be either of the following values:
- non-null transaction pointer: The application requests to CLI to
change the state of the connection from non-distributed transaction
state to distributed state. The connection is enlisted with the Distributed
Transaction Coordinator (DTC).
- null: The application requests to CLI to
change the state of the connection from distributed transaction state
to a non-distributed transaction state.
This attribute is only used in a Microsoft Transaction Server (MTS) environment
to enlist or un-enlist a connection with MTS.
Each time this
attribute is used with a non-null transaction pointer, the previous
transaction is assumed to be ended and a new transaction is initiated.
The application must call the ITransaction member function Endtransaction
before calling this API with a non-null pointer. Otherwise the previous
transaction will be aborted. The application can enlist multiple connections
with the same transaction pointer.
Note: This connection attribute
is specified by MTS automatically for each transaction and is not
coded by the user application.
It is imperative for
CLI/ODBC
applications that there will be no concurrent SQL statements executing
on 2 different connections into the same database that are enlisted
in the same transaction.
- SQL_ATTR_EXTENDED_INDICATORS
- A 32-bit integer that allows users to use the extended indicator
feature from the supported server. If the user attempts to set this
attribute against the data server which does not support extended
indicators, an appropriate error is returned to the CLI application.
This attribute can take the following value:
- SQL_EXTENDED_INDICATOR_ENABLE: Enables users to specify values
to signify SQL_UNASSIGNED and SQL_DEFAULT_PARAM on the SQLBindParameter() / SQLExtendedBind() methods.
- SQL_EXTENDED_INDICATOR_NOT_SET (default): This feature is disabled
by default. The user gets an InvalidArgument value error, CLI0124E,
if the SQL_UNASSIGNED and SQL_DEFAULT_PARAM are used before enabling
this feature using SQL_ATTR_EXTENDED_INDICATORS.
- Extended indicators support is supported on following IBM Data Server products:
- The DB2 for Linux, UNIX, and Windows database
server.
- The DB2 for z/OS Version
10 server.
- The DB2 for i V7.1
data servers server.
- SQL_ATTR_FET_BUF_SIZE
- A connection level attribute to allow applications to set the
default query block size to an optimum value in range of 64K-256K.
This attribute should be set before a connection is made. CLI will
also provide a db2cli.ini level keyword, FET_BUF_SIZE,
which can be set in db2cli.ini file and connection
string.
- An equivalent db2dsdriver.cfg keyword, FetchBufferSize is also
available, which can be set in the db2dsdriver.cfg file.
- SQL_ATTR_FORCE_ROLLBACK
- A 32-bit unsigned integer value that allows calls to the SQLEndTran() function
in a data-at-execution flow for connections to DB2 for z/OS servers.
To
call the SQLEndTran() function specifying SQL_ROLLBACK
as CompletionType in your applications during
a data-at-execution flow, the StreamPutData configuration keyword
must be set to 1, and the SQL_ATTR_FORCE_ROLLBACK connection attribute
must also be set.
The CLI0150E error message is returned for
connections to database servers that are not DB2 for z/OS servers.
Note: This
is an IBM defined
attribute.
- SQL_ATTR_FREE_LOCATORS_ON_FETCH
- A boolean attribute that specifies if LOB locators are freed when SQLFetch() is
executed, rather than when a COMMIT is issued. Setting this attribute
to 1 (true) frees the locators that are used internally when applications
fetch LOB data without binding the LOB columns with SQLBindCol() (or
equivalent descriptor APIs). Locators that are explicitly returned
to the application must still be freed by the application. This attribute
value can be used to avoid scenarios where an application receives
SQLCODE = -429 (no more locators). The default for this attribute
is 0 (false).
Note: This is an IBM defined attribute.
- SQL_ATTR_FREE_MEMORY_ON_STMTCLOSE
- A connection level attribute that specifies whether the SQL_CLOSE action
that is specified with the SQLFreeStmt() function
frees large memory allocation by the CLI driver.
The CLI driver
allocates large memory under the following scenarios:
- When client fetches the LOB columns from a server that does not
support the Dynamic Data Format feature.
- When client calls the SQLGetData() function with AllowInterleavedGetData
keyword set.
The SQL_ATTR_FREE_MEMORY_ON_STMTCLOSE attribute can be set to
the following value:- SQL_FREE_MEMORY_ON_STMTCLOSE_NO: The default
value. The memory allocation by the CLI driver
for specified scenario is not freed when SQL_CLOSE action
takes place.
- SQL_FREE_MEMORY_ON_STMTCLOSE_YES: The memory
allocation by the CLI driver
for specified scenario is freed when SQL_CLOSE action
takes place.
Example of setting the SQL_ATTR_FREE_MEMORY_ON_STMTCLOSE attribute:cliRC = SQLSetConnectAttr(hdbc,
SQL_ATTR_FREE_MEMORY_ON_STMTCLOSE ,
(SQLPOINTER)SQL_FREE_MEMORY_ON_STMTCLOSE_YES,
SQL_IS_INTEGER);
Note: This is
an IBM defined
attribute.
- SQL_ATTR_GET_LATEST_MEMBER
- A connection
level attribute that enables CLI applications
to retrieve the most recent TCP/IP address used by the client for
a logical connection.
When the workload balancing (WLB) feature
is enabled, the last member address can be a member address, primary
group address, or alternate group address. If WLB is not enabled,
the SQL_ATTR_GET_LATEST_MEMBER attribute returns the DSN information
that is used to establish the logical connection. The DSN information
that is returned can be a primary group address or an alternate group
address. The DSN information is obtained from the local db2dsdriver.cfg file,
or the node directory if the db2dsdriver.cfg file
is not in use. The alternate group address is obtained from the local db2dsdriver.cfg file.
The value returned is an IP address and a port, expressed as a port
number or service name. The format of the returned value is: "hostname:port".
The CLI0106E error message is returned if you try to
use this attribute before establishing a database connection.
- SQL_ATTR_INFO_ACCTSTR
- The SQL_ATTR_INFO_ACCTSTR attribute is used to set the client
accounting string that is sent to a database.
Some servers might
not be able to handle the entire length of the value and might truncate
the SQL_ATTR_INFO_ACCTSTR attribute value. The SQL_ATTR_INFO_ACCTSTR
attribute is subject to the following conditions:
- DB2 for z/OS servers
support up to a length of 200 characters.
- CLI applications
can set the SQL_ATTR_INFO_ACCTSTR attribute on DB2 for i V6R1
and later servers. DB2 for i servers
support a length of up to 255 characters.
To ensure that the data is converted correctly when transmitted
to a host system, use only the characters A - Z and 0 - 9 and the
underscore (_) or period (.).
Note: The SQL_ATTR_INFO_ACCTSTR
attribute is an IBM defined
attribute.
- SQL_ATTR_INFO_APPLNAME
- The SQL_ATTR_INFO_APPLNAME attribute is used to set the client
application name that is sent to a database.
Some servers might
not be able to handle the entire length of the value and might truncate
the SQL_ATTR_INFO_APPLNAME attribute value. The SQL_ATTR_INFO_APPLNAME
attribute is subject to the following conditions:
- DB2 for z/OS Version
10 and earlier servers support a length of up to 32 characters.
- CLI applications
can set the SQL_ATTR_INFO_APPLNAME attribute on DB2 for i V6R1
and later servers. DB2 for i servers
support a length of up to 255 characters.
To ensure that the data is converted correctly when transmitted
to a host system, use only the characters A - Z and 0 - 9 and the
underscore (_) or period (.).
If
you change the client application name and the accounting string is
set by the WLM_SET_CLIENT_INFO procedure, the accounting string that
is stored on the server is updated with the value of the accounting
string from the client information.
The SQL_ATTR_INFO_APPLNAME
attribute is an IBM defined
attribute.
- SQL_ATTR_INFO_PROGRAMID
- A user-defined character string, with a maximum length of 80 bytes,
that associates an application with a connection. Once this attribute
is set, DB2 for z/OS Version
8 and later associates this identifier with any statements inserted
into the dynamic SQL statement cache.
This attribute is only supported
for CLI applications
accessing DB2 for z/OS Version
8 and later or Informix database
server.
Note: The
SQL_ATTR_INFO_PROGRAMID attribute is an IBM defined attribute.
- SQL_ATTR_INFO_PROGRAMNAME
- A null-terminated user-defined character string, up to 20 bytes
in length, used to specify the name of the application running on
the client.
When this attribute is set before the connection to
the server is established, the value specified overrides the actual
client application name and will be the value that is displayed in
the appl_name monitor element. When connecting to a DB2 for z/OS server,
the first 12 characters of this setting are used as the CORRELATION
IDENTIFIER of the associated DB2 for z/OS thread.
Note: The
SQL_ATTR_INFO_PROGRAMNAME attribute is an IBM defined attribute.
- SQL_ATTR_INFO_USERID
- The SQL_ATTR_INFO_USERID attribute is used to set the client user
ID (accounting user ID) that is sent to a database. The SQL_ATTR_INFO_USERID
attribute is for identification purposes only and is not used for
any authentication. Do not confuse the SQL_ATTR_INFO_USERID attribute
with the authentication user ID.
Some servers might not be able
to handle the entire length of the value and might truncate the SQL_ATTR_INFO_USERID
attribute value. The SQL_ATTR_INFO_USERID attribute is subject to
the following conditions:
- DB2 for z/OS Version
10 and earlier servers support a length of up to 16 characters.
- CLI applications
can set the SQL_ATTR_INFO_USERID attribute on DB2 for i V6R1
and later servers. DB2 for i servers
support a length of up to 255 characters.
To ensure that the data is converted correctly when transmitted
to a host system, use only the characters A - Z and 0 - 9 and the
underscore (_) or period (.).
If
you change the client user ID and the accounting string is set by
the WLM_SET_CLIENT_INFO procedure, the accounting string that is stored
on the server is updated with the value of the accounting string from
the client information.
The SQL_ATTR_INFO_USERID attribute is
an IBM defined attribute.
- SQL_ATTR_INFO_WRKSTNNAME
- The SQL_ATTR_INFO_WRKSTNNAME attribute is used to set the client
workstation name that is sent to a database.
Some servers might
not be able to handle the entire length of the value and might truncate
the SQL_ATTR_INFO_WRKSTNNAME attribute value. The SQL_ATTR_INFO_WRKSTNNAME
attribute is subject to the following conditions:
- DB2 for z/OS Version
10 and earlier servers support a length of up to 18 characters.
- CLI applications
can set the SQL_ATTR_INFO_WRKSTNNAME attribute on DB2 for i V6R1
and later servers. DB2 for i servers
support a length of up to 255 characters.
To ensure that the data is converted correctly when transmitted
to a host system, use only the characters A - Z and 0 - 9 and the
underscore (_) or period (.).
If
the SQL_ATTR_INFO_WRKSTNNAME attribute is not
specified, a default value that consists of the host name is used.
The host name is obtained by calling the gethostname() function.
If the host name is not configured or an error is encountered during
the gethostname() function call, no value for the SQL_ATTR_INFO_WRKSTNNAME attribute
is sent to the server.
The SQL_ATTR_INFO_WRKSTNNAME attribute
is an IBM defined attribute.
- SQL_ATTR_KEEP_DYNAMIC
- A 32-bit unsigned integer value which specifies whether the KEEPDYNAMIC
option has been enabled. If enabled, the server will keep dynamically
prepared statements in a prepared state across transaction boundaries.
- 0 - KEEPDYNAMIC functionality is not available; CLI packages
were bound with the KEEPDYNAMIC NO option
- 1 - KEEPDYNAMIC functionality is available; CLI packages
were bound with the KEEPDYNAMIC YES option
It is recommended that when this attribute is set, the SQL_ATTR_CURRENT_PACKAGE_SET
attribute also be set.
This attribute is not supported when
accessing Informix database
servers.
Note: This
is an IBM defined
attribute.
- SQL_ATTR_LOB_CACHE_SIZE
- A 32-bit unsigned integer that specifies maximum cache size (in
bytes) for LOBs. By default, LOBs are not cached.
See the LOBCacheSize CLI/ODBC configuration keyword for further usage information.
- SQL_ATTR_LOGIN_TIMEOUT
- A 32-bit integer value corresponding to the number of seconds
to wait for a reply when trying to establish a connection to a server
before terminating the attempt and generating a communication timeout.
Specify a positive integer, up to 32 767. The default setting of 0
will allow the client to wait indefinitely.
Setting a connection
timeout value can also be done using the ConnectTimeout CLI/ODBC configuration keyword.
Refer to the keyword for usage information.
- SQL_ATTR_LONGDATA_COMPAT
- A 32-bit integer value indicating whether the character, double
byte character and binary large object data types should be reported
as SQL_LONGVARCHAR, SQL_LONGVARGRAPHIC or SQL_LONGBINARY, enabling
existing applications to access large object data types seamlessly.
The option values are:
- SQL_LD_COMPAT_NO (default): The large object data types
are reported as IBM defined
types (SQL_BLOB, SQL_CLOB, SQL_DBCLOB).
- SQL_LD_COMPAT_YES: The IBM large object data types (SQL_BLOB, SQL_CLOB
and SQL_DBCLOB) are mapped to SQL_LONGVARBINARY, SQL_LONGVARCHAR and
SQL_LONGVARGRAPHIC; SQLGetTypeInfo() returns
one entry each for SQL_LONGVARBINARY SQL_LONGVARCHAR, and SQL_LONGVARGRAPHIC.
Note: This is an IBM defined
attribute.
- SQL_ATTR_MAPCHAR
- A 32-bit integer value used to specify the default SQL type associated
with SQL_CHAR, SQL_VARCHAR, SQL_LONGVARCHAR. The option values are:
- SQL_MAPCHAR_DEFAULT (default): return the default SQL type
representation
- SQL_MAPCHAR_WCHAR: return SQL_CHAR as SQL_WCHAR, SQL_VARCHAR as
SQL_WVARCHAR, and SQL_LONGVARCHAR as SQL_WLONGVARCHAR
Only the following
CLI functions
are affected by setting this attribute:
- SQLColumns()
- SQLColAttribute()
- SQLDescribeCol()
- SQLDescribeParam()
- SQLGetDescField()
- SQLGetDescRec()
- SQLProcedureColumns()
Setting the default SQL type associated with SQL_CHAR,
SQL_VARCHAR, SQL_LONGVARCHAR can also be done using the MapCharToWChar CLI/ODBC configuration keyword.
Note: This is an IBM defined attribute.
- SQL_ATTR_MAXCONN
- The SQL_ATTR_MAXCONN attribute is deprecated.
- SQL_ATTR_MAX_LOB_BLOCK_SIZE
- A 32-bit unsigned integer that indicates the maximum size of LOB
or XML data block. Specify a positive integer, up to 2 147 483 647.
The default setting of 0 indicates that there is no limit to the data
block size for LOB or XML data.
During data retrieval, the server
includes all of the information for the current row in its reply to
the client even if the maximum block size is reached.
If both
the MaxLOBBlockSize keyword and the db2set registry
variable DB2_MAX_LOB_BLOCK_SIZE are specified, the value for the MaxLOBBlockSize keyword
is used.
Setting the MaxLOBBlockSize CLI/ODBC configuration keyword is
an alternative method of specifying the maximum size of LOB or XML
data block.
- SQL_ATTR_METADATA_ID
- This connection attribute is defined by ODBC, but is not supported
by CLI.
Any attempt to set or get this attribute will result in an SQLSTATE
of HYC00 (Driver not capable).
- SQL_ATTR_NETWORK_STATISTICS
- The SQL_ATTR_NETWORK_STATISTICS is a 32-bit integer connection
attribute controls whether CLI collects
network statistics for a connection. An application can retrieve
the network statistics for a connection by calling the SQLGetDiagField() function
and specifying SQL_DIAG_NETWORK_STATISTICS for the DiagIdentifier argument.
- The permitted values are as follows:
- SQL_NETWORK_STATISTICS_OFF (default)
- Disables network statistics collection for a connection.
- SQL_NETWORK_STATISTICS_ON
- Enables network statistics collection for a connection.
- SQL_NETWORK_STATISTICS_ON_SKIP_NOSERVER
- In addition to enabling network statistics collection for a connection,
network flows are omitted that are known to have no server time reported,
for example explicit COMMIT and ROLLBACK statements.
Requests that
have no server time reported can affect the usefulness of returned
information, if calculations are made that subtract the server time
from the network time. The SQL_NETWORK_STATISTICS_ON_SKIP_NOSERVER
option excludes these requests from the values reported. Only explicit,
unchained requests are excluded; autocommit and chained COMMIT statements
are not skipped.
The CLI driver
collects statistics for server time reported on COMMIT and ROLLBACK.
The IBM data server must support
the feature that reports server time for COMMIT and ROLLBACK.
- SQL_ATTR_ODBC_CURSORS
- This connection attribute is defined by ODBC, but is not supported
by CLI.
Any attempt to set or get this attribute will result in an SQLSTATE
of HYC00 (Driver not capable).
- SQL_ATTR_OVERRIDE_CHARACTER_CODEPAGE
- The SQL_ATTR_OVERRIDE_CHARACTER_CODEPAGE connection
attribute enables CLI applications
to specify the database code page. The code page does not have to
be available on the database client where the application reside.
If
you specify the same code page as the database code page, applications
can fetch or insert data of CHARACTER data type without any code page
conversions.
Setting the SQL_ATTR_OVERRIDE_CHARACTER_CODEPAGE
attribute after allocating statement handles results in the CLI0126E
(invalid operation) error. Setting the attribute to a value that is
not supported by the database results in the CLI0210E error (inconsistent
code page value error).
If you set SQL_ATTR_OVERRIDE_CHARACTER_CODEPAGE
after setting SQL_ATTR_OVERRIDE_CODEPAGE to SQL_OVERRIDE_CODEPAGE_ON,
the CLI driver
returns the CLI0126E error message.
During a bind-out operation,
ensure that the CLI applications
allocate buffers large enough to hold the retrieved data during bind-out
operations. If there is insufficient space, the CLI0002W error is
returned.
Restriction: The SQL_ATTR_OVERRIDE_CHARACTER_CODEPAGE
attribute is supported for connections to DB2 for z/OS database
servers only.
- SQL_ATTR_OVERRIDE_CODEPAGE
- The SQL_ATTR_OVERRIDE_CODEPAGE connection attribute
enables CLI applications
to fetch or insert data of CHARACTER or GRAPHIC data type without
code page conversions. The SQL_ATTR_OVERRIDE_CODEPAGE connection attribute
can have following listed values:
- SQL_OVERRIDE_CODEPAGE_ON: The CLI driver
does not perform code page conversions for binding of character or
graphic data.
- SQL_OVERRIDE_CODEPAGE_OFF (default): The CLI driver
performs code page conversions for binding of character or graphic
data.
If you set the SQL_ATTR_OVERRIDE_CODEPAGE attribute to SQL_OVERRIDE_CODEPAGE_ON,
you must ensure that data is in the correct code page.
If you
set SQL_ATTR_OVERRIDE_CODEPAGE to SQL_OVERRIDE_CODEPAGE_ON after setting
SQL_ATTR_OVERRIDE_CHARACTER_CODEPAGE, the CLI driver
returns the CLI0126E error message.
Restriction: The SQL_ATTR_OVERRIDE_CODEPAGE attribute
is supported for connections to DB2 for z/OS database
servers only.
- SQL_ATTR_OVERRIDE_PRIMARY_AFFINITY
- The SQL_ATTR_OVERRIDE_PRIMARY_AFFINITY connection attribute enables CLI applications
to specify a new temporary primary member for the client affinities
feature.
The SQL_ATTR_OVERRIDE_PRIMARY_AFFINITY attribute can
be specified under following conditions:
- The client affinities feature must be enabled in the db2dsdriver.cfg file.
- The new primary member that is specified with the SQL_ATTR_OVERRIDE_PRIMARY_AFFINITY
attribute must be part of the members that are listed for the client
affinities feature in the db2dsdriver.cfg file
or an empty string.
- The SQL_ATTR_OVERRIDE_PRIMARY_AFFINITY attribute can be specified
only after the connection is established.
When the new primary member is specified with the SQL_ATTR_OVERRIDE_PRIMARY_AFFINITY
attribute, the client affinities member list consists of sequence
of member after the selected new primary member. For example, if you
have three members Server1, Server2, and Server3 listed for the client
affinities feature in the
db2dsdriver.cfg file
and you specify the Server2 as the new primary member with the SQL_ATTR_OVERRIDE_PRIMARY_AFFINITY
attribute, the new client affinities member list consists of Server2,
Server3, and Server1.
If the empty string value is specified
for the SQL_ATTR_OVERRIDE_PRIMARY_AFFINITY attribute, the primary
member is reverted to first member listed in the db2dsdriver.cfg file
for the client affinities feature.
The new temporary primary
member that is specified with the SQL_ATTR_OVERRIDE_PRIMARY_AFFINITY
attribute is stored in memory and does not affect the order of members
that are listed in the db2dsdriver.cfg file.
- SQL_ATTR_PACKET_SIZE
- The SQL_ATTR_PACKET_SIZE connection attribute is
defined in the ODBC specification. However, the SQL_ATTR_PACKET_SIZE
attribute is not supported by the CLI driver.
Any attempt to set or get this attribute results in an SQLSTATE of
HYC00 (Driver not capable).
- SQL_ATTR_PARC_BATCH
- For applications that use array input to achieve
bulk inserts, deletes, or updates, the SQL_ATTR_PARC_BATCH attribute
indicates whether the application receives the number of rows in a
table that were affected by each parameter set or the cumulative number
of rows that were affected for the entire parameter set. This connection
attribute is available for non-atomic operations. The possible values
are as follows:
- SQL_PARC_BATCH_ENABLE: CLI returns
the number of rows in a table that were affected by each parameter
set.
- SQL_PARC_BATCH_DISABLE (default): CLI returns
the total number of rows that were affected for the entire parameter
set.
If you set this connection attribute to SQL_PARCH_BATCH_ENABLE,
you must indicate an array as the RowCountPtr parameter in
the SQLRowCount () function and you must set SQL_ATTR_PARAMOPT_ATOMIC
to SQL_ATOMIC_NO. If SQL_ATTR_PARAMOPT_ATOMIC is set to SQL_ATOMIC_YES,
the CLI0150E error message is returned when you call the SQLExecute
() function.
- SQL_ATTR_PING_DB
- A 32-bit integer which is used with the SQLGetConnectAttr() function
to get the ping time in microseconds.
If an existing connection
is dropped by the database, a value of 0 is reported. If the connection
is closed by the application, then an SQLSTATE of 08003 is reported.
The SQL_ATTR_PING_DB attribute can be returned by the SQLGetConnectAttr() function,
but cannot be set by the SQLSetConnectAttr() function.
Any attempt to set this attribute results in an SQLSTATE of 7HYC00
(Driver not capable)
Note: The SQL_ATTR_PING_DB attribute is an IBM defined attribute.
- SQL_ATTR_PING_NTIMES
- A 32-bit integer that sets the number of ping iterations the CLI driver
issues. The time value that is associated with the ping operation
is retrieved with the SQLGetConnectAttr() function
with the SQL_ATTR_PING_DB attribute. If you set SQL_ATTR_PING_NTIMES
to a value greater than 1, SQL_ATTR_PING_DB returns the average time
that the CLI driver
took to ping the database for the set of iterations.
- This attribute has a valid range from 1 to 32767 (inclusive).
The SQLGetConnectAttr() function
checks the value and returns the appropriate error code when the value
is outside this range.
- When automatic client reroute is enabled and the ping operation to
a member fails, the CLI driver
pings SQL_ATTR_PING_NTIMES to the new member, after a seamless failover.
The CLI driver
pings the new member until all iterations are successful for that
member. If there are no available members, the SQLGetConnectAttr() function
with the SQL_ATTR_PING_DB attribute returns an error to the application.
A time value of zero (0) is reported.
- SQL_ATTR_PING_REQUEST_PACKET_SIZE
- A 32-bit integer that is used with SQLGetConnectAttr() that
sets the size of the ping packet that CLI uses
when the application uses SQL_ATTR_PING_DB.
- This attribute has a valid range from 1 to 32767 (inclusive).SQLGetConnectAttr() checks
the value and returns the appropriate error code when the value is
outside this range.
- SQL_ATTR_QUIET_MODE
- A 32-bit platform specific window handle.
If the application
has never made a call to SQLSetConnectAttr()
with this option, then CLI would
return a null parent window handle on SQLGetConnectAttr() for
this option and use a null parent window handle to display dialogue
boxes. For example, if the end user has asked for (via an entry in
the CLI initialization
file) optimizer information to be displayed, CLI would
display the dialogue box containing this information using a null
window handle. (For some platforms, this means the dialogue box would
be centered in the middle of the screen.)
If ValuePtr is
set to null , then CLI does
not display any dialogue boxes. In cases where end user asked for
the optimizer estimates to be displayed, CLI would
not display these estimates because the application explicitly wants
to suppress all such dialogue boxes.
If ValuePtr is
not null, then it should be the parent window handle of the application. CLI uses
this handle to display dialogue boxes. (For some platforms, this means
the dialogue box would be centered with respect to the active window
of the application.)
Note: This connection option cannot be used
to suppress the SQLDriverConnect() dialogue
box (which can be suppressed by setting the fDriverCompletion argument
to SQL_DRIVER_NOPROMPT).
- SQL_ATTR_RECEIVE_TIMEOUT
-
A 32-bit integer value that is the number of seconds a client
waits for a reply from a server on an established connection before
terminating the attempt and generating a communication timeout error.
The default value of 0 indicates the client waits indefinitely for
a reply. The receive timeout has no effect during connection establishment;
it is only supported for TCP/IP, and is ignored for any other protocol.
Supported values are integers from 0 to 32767.
Note: This is an IBM defined attribute.
- SQL_ATTR_REOPT
-
A 32-bit integer value that enables query optimization for
SQL statements that contain special registers or parameter markers.
Optimization occurs by using the values available at query execution
time for special registers or parameter markers, instead of the default
estimates that are chosen by the compiler. The valid values of the
attribute are:
- 2 = SQL_REOPT_NONE (default): No query optimization occurs
at query execution time. The default estimates chosen by the compiler
are used for the special registers or parameter markers. The default
NULLID package set is used to execute dynamic SQL statements.
- 3 = SQL_REOPT_ONCE: Query optimization occurs once at query execution
time, when the query is executed for the first time. The NULLIDR1
package set, which is bound with the REOPT ONCE bind option, is used.
- 4 = SQL_REOPT_ALWAYS: Query optimization or reoptimization occurs
at query execution time every time the query is executed. The NULLIDRA
package set, which is bound with the REOPT ALWAYS bind option, is
used.
The NULLIDR1 and NULLIDRA are reserved package set names, and
when used, REOPT ONCE and REOPT ALWAYS are implied. These package
sets have to be explicitly created with these commands:
db2 bind db2clipk.bnd collection NULLIDR1
db2 bind db2clipk.bnd collection NULLIDRA
SQL_ATTR_REOPT
and SQL_ATTR_CURRENT_PACKAGE_SET are mutually exclusive, therefore,
if one is set, the other is not allowed.
This
attribute is not supported when accessing Informix database
servers.
Note: This
is an IBM defined
attribute.
- SQL_ATTR_REPORT_ISLONG_FOR_LONGTYPES_OLEDB
- A 32-bit integer value. The OLE DB client cursor engine and the
OLE DB .NET Data Provider CommandBuilder object generate UPDATE and
DELETE statements based on column information provided by the IBM DB2 OLE
DB Provider. If the generated statement contains a LONG type in the
WHERE clause, the statement will fail because LONG types cannot be
used in a search with an equality operator. The possible values are
as follows:
- 0 (default): LONG types (LONG VARCHAR, LONG VARCHAR FOR
BIT DATA, LONG VARGRAPHIC and LONG VARGRAPHIC FOR BIT DATA) do not
have the DBCOLUMNFLAGS_ISLONG flag set, which might cause the columns
to be used in the WHERE clause.
- 1: The IBM DB2 OLE DB Provider reports LONG types (LONG
VARCHAR, LONG VARCHAR FOR BIT DATA, LONG VARGRAPHIC and LONG VARGRAPHIC
FOR BIT DATA) with the DBCOLUMNFLAGS_ISLONG flag set. This will prevent
the long columns from being used in the WHERE clause.
This attribute is supported by the following database servers:
- DB2 for z/OS
- Version 8 with PTF UQ93890
- Versions later than Version 8, PTFs are not required
- DB2 for Linux, UNIX, and Windows
This attribute is not supported when
accessing Informix database
servers.
Note: This
is an IBM defined
attribute.
- SQL_ATTR_REPORT_SEAMLESSFAILOVER_WARNING
- A
32-bit unsigned integer value that specifies whether to return a warning
message on execute requests if a seamless failover occurred during
the request. The SQL_ATTR_REPORT_SEAMLESSFAILOVER_WARNING attribute
has following possible values:
- SQL_REPORT_SEAMLESSFAILOVER_WARNING_YES: If
a seamless failover occurred during an execute request, a warning
message is returned.
- SQL_REPORT_SEAMLESSFAILOVER_WARNING_NO (default):
If a seamless failover occurred during an execute request, a warning
message is not returned.
- SQL_ATTR_REPORT_TIMESTAMP_TRUNC_AS_WARN
- A 32-bit unsigned integer value that specifies
whether a datetime overflow results in an error (SQLSTATE 22008) or
warning (SQLSTATE 01S07). The possible values are as follows:
- 0 (default): Datetime overflow results in an error (SQLSTATE
22008).
- 1: Datetime overflow results in a warning (SQLSTATE 01S07).
- SQL_ATTR_RETRYONERROR
- CLI attempts
recover from non-fatal errors, such as incorrect binding of application
parameters, by retrieving additional information about the failing
SQL statement and then executing the statement again. The additional
information retrieved includes input parameter information from the
database catalog tables. If CLI is
able to recover successfully from the error, by default, it does not
report the error to the application. The CLI/ODBC
configuration keyword ReportRetryErrorsAsWarnings allows you to set
whether error recovery warnings are returned to the application or
not.
Note: Once CLI has
successfully completed the error recovery, the application may behave
differently, because CLI uses
the catalog information gathered during the recovery for subsequent
executions of that particular SQL statement, rather than the information
provided in the original SQLBindParameter() function calls. If you
do not want this behavior, set RetryOnError to 0, forcing CLI not
to attempt recovery. You should, however, modify the application to
correctly bind statement parameters..
- SQL_ATTR_SERVER_MSGTXT_MASK
- A 32-bit integer value used to indicate when CLI should
request the error message from the server. This attribute is used
in conjunction with the SQL_ATTR_SERVER_MSGTXT_SP attribute. The attribute
can be set to:
- SQL_ATTR_SERVER_MSGTXT_MASK_LOCAL_FIRST (default): CLI will
check the local message files first to see if the message can be retrieved.
If no matching SQLCODE is found, then CLI will
request the information from the server.
- SQL_ATTR_SERVER_MSGTXT_MASK_WARNINGS: CLI always
requests the message information from the server for warnings but
error messages are retrieved from the local message files.
- SQL_ATTR_SERVER_MSGTXT_MASK_ERRORS: CLI always
requests the message information from the server for errors but warning
messages are retrieved from the local message files.
- SQL_ATTR_SERVER_MSGTXT_MASK_ALL: CLI always
requests the message information from the server for both error and
warning messages.
Setting the ServerMsgMask CLI/ODBC configuration keyword is an alternative
method of specifying this behavior.
Note: This is an IBM defined attribute.
- SQL_ATTR_SERVER_MSGTXT_SP
- A pointer to a character string used to identify a stored procedure
that is used for generating an error message based on an SQLCA. This
can be useful when retrieving error information from a server such
as DB2 for z/OS.
The attribute can be set to:
- SYSIBM.SQLCAMESSAGE: The default procedure called to retrieve
the message text from DB2 for z/OS servers.
If you do not set this attribute, this procedure is called.
- DSNACCMG: The default procedure called to retrieve the message
text from DB2 for z/OS Version
7 servers. The SYSIBM.SQLCAMESSAGE procedure is called to retrieve
the message text from DB2 for z/OS Version
8 or later. DSNACCMG has been deprecated in DB2 for z/OS Version
9 and might be removed in a future release.
- Any user-created stored procedure.
Applications using this attribute can also set the SQL_ATTR_SERVER_MSGTXT_MASK
attribute to indicate when CLI should
call this procedure to retrieve the message information from the server.
If the SQL_ATTR_SERVER_MSGTXT_MASK is not set, then the default is
to check the local message files first (see SQL_ATTR_SERVER_MSGTXT_MASK_LOCAL_FIRST
in SQL_ATTR_SERVER_MSGTXT_MASK).
Setting the UseServerMsgSP CLI/ODBC configuration keyword is an alternative method of specifying
this behavior.
Note: This is an IBM defined attribute.
- SQL_ATTR_SESSION_TIME_ZONE
- A null-terminated character string in the format ±hh:mm, containing
the server session time zone information. This is a set-only attribute.
The supported time zone values range from -12:59 through +14:00.
- SQL_ATTR_SQLCOLUMNS_SORT_BY_ORDINAL_OLEDB
- A 32-bit integer value. The Microsoft OLE
DB specification requires that IDBSchemaRowset::GetRowset(DBSCHEMA_COLUMNS)
returns the row set sorted by the columns TABLE_CATALOG, TABLE_SCHEMA,
TABLE_NAME, COLUMN_NAME. The IBM DB2 OLE DB Provider conforms to
the specification, however, applications that use the Microsoft ODBC Bridge provider (MSDASQL)
have been typically coded to get the row set sorted by ORDINAL_POSITION.
The possible values are as follows:
- 0 (default): The IBM DB2 OLE DB Provider returns a row
set sorted by the columns TABLE_CATALOG, TABLE_SCHEMA, TABLE_NAME,
COLUMN_NAME.
- 1: The IBM DB2 OLE DB Provider returns a row set sorted
by ORDINAL_POSITION.
This attribute is supported by the following database servers:
- DB2 for z/OS
- Version 8 with PTF UQ93890
- Versions later than version 8, PTFs are not required
- DB2 for Linux, UNIX, and Windows
This attribute is not supported when
accessing Informix database
servers.
Note: This
is an IBM defined
attribute.
- SQL_ATTR_STMT_CONCENTRATOR
- Specifies whether dynamic statements that
contain literal values use the statement cache.
- SQL_STMT_CONCENTRATOR_OFF - The statement concentrator behavior
is disabled.
- SQL_STMT_CONCENTRATOR_WITH_LITERALS - The statement concentrator
with literal behavior is enabled for situations that are supported
by the server. For example, the statement concentrator is not enabled
if the statement has parameter markers, named parameter markers, or
a mix of literals, parameter markers, and named parameter markers.
Setting the StmtConcentrator CLI/ODBC configuration keyword is an alternative
method of specifying this behavior.
- SQL_ATTR_STREAM_GETDATA
- A 32-bit unsigned integer that indicates if the data output stream
for the SQLGetData()
function will be optimized. The values are:
- 0 (default): CLI buffers
all the data on the client.
- 1: For applications that do not need to buffer data and are querying
data on a server that supports Dynamic Data Format, also known as
progressive streaming, specify 1 to indicate that data buffering is
not required. The CLI client
will optimize the data output stream.
This keyword is ignored if Dynamic Data Format is not supported
by the server.
If StreamGetData is set to 1 and CLI cannot
determine the number of bytes still available to return in the output
buffer, SQLGetData() returns
SQL_NO_TOTAL (-4) as the length when truncation occurs. Otherwise, SQLGetData() returns
the number of bytes still available.
Setting the StreamGetData CLI/ODBC configuration keyword is an alternative method of specifying
this behavior.
- SQL_ATTR_SYNC_POINT
- The SQL_ATTR_SYNC_POINT attribute has been deprecated.
- SQL_ATTR_TRACE
- This connection attribute can be set by an application for the
ODBC Driver Manager. Any attempt to set this connection attribute
for the CLI Driver
will result in an SQLSTATE of HYC00 (Driver not capable).
Instead
of using this connection attribute, the CLI trace
facility can be set using the Trace CLI/ODBC configuration keyword.
Alternatively, the environment attribute SQL_ATTR_TRACE can be used
to configure tracing features. Note that the environment attribute
does not use the same syntax as the ODBC Driver Manager's connection
attribute.
- SQL_ATTR_TRACEFILE
- This connection attribute is defined by ODBC, but is not supported
by CLI.
Any attempt to set or get this attribute will result in an SQLSTATE
of HYC00 (Driver not capable).
Instead of using this attribute,
the CLI trace
file name is set using the TraceFileName CLI/ODBC configuration keyword.
- SQL_ATTR_TRANSLATE_LIB
- This connection attribute is defined by ODBC, but is not supported
by CLI.
Any attempt to set or get this attribute on other platforms will result
in an SQLSTATE of HYC00 (Driver not capable).
- SQL_ATTR_TRANSLATE_OPTION
- This connection attribute is defined by ODBC, but is not supported
by CLI.
Any attempt to set or get this attribute on other platforms will result
in an SQLSTATE of HYC00 (Driver not capable).
- SQL_ATTR_TRUSTED_CONTEXT_PASSWORD
- A user defined string containing a password. Use this attribute
if the database server requires a password when switching users on
a trusted connection. Set this attribute after setting the attribute
SQL_ATTR_TRUSTED_CONTEXT_USERID and before executing any SQL statements
that access the database server. If SQL_ATTR_TRUSTED_CONTEXT_USERID
is not set before setting this attribute, an error (CLI0198E) is returned.
This attribute is not supported when accessing Informix database
servers.
- SQL_ATTR_TRUSTED_CONTEXT_USERID
-
A user defined string containing a user ID. Use this on existing
trusted connections to switch users. Do not use it when creating a
trusted connection.
After setting this attribute the user switch
will occur the next time that you execute an SQL statement that accesses
the database server. (SQLSetConnectAttr does not access the database
server.) If the user switch is successful the user ID in this attribute
becomes the new user of the connection. If the user switch fails the
call that initiated the switch will return an error indicating the
reason for the failure.
The user ID must be a valid authorization
ID on the database server unless you are using an identity server,
in which case you can use any user name recognized by the identity
server. (If you are using an identity server see also SQL_ATTR_USER_REGISTRY_NAME.)
If
you set this attribute while the connection handle is not yet connected
to a database or if the connection is not a trusted connection then
an error (CLI0197E) is returned.
This attribute
is not supported when accessing Informix database
servers.
- SQL_ATTR_TXN_ISOLATION
- A 32-bit bitmask that sets the transaction isolation level for
the current connection referenced by ConnectionHandle.
The valid values for ValuePtr can be determined
at runtime by calling SQLGetInfo() with fInfoType set
to SQL_TXN_ISOLATION_OPTIONS. The following values are accepted by CLI,
but each server might only support a subset of these isolation levels:
- SQL_TXN_READ_UNCOMMITTED - Dirty reads, non-repeatable reads,
and phantom reads are possible.
- SQL_TXN_READ_COMMITTED (default) - Dirty reads are not
possible. Non-repeatable reads and phantom reads are possible.
- SQL_TXN_REPEATABLE_READ - Dirty reads and reads that cannot be
repeated are not possible. Phantoms are possible.
- SQL_TXN_SERIALIZABLE - Transactions can be serialized. Dirty reads,
non-repeatable reads, and phantoms are not possible.
- SQL_TXN_NOCOMMIT - Any changes are effectively committed at the
end of a successful operation; no explicit commit or rollback is allowed.
This is analogous to autocommit. This is not an SQL92 isolation level,
but an IBM defined
attribute, supported only by the DB2 for i server.
In IBM terminology,
- SQL_TXN_READ_UNCOMMITTED is Uncommitted Read;
- SQL_TXN_READ_COMMITTED is Cursor Stability;
- SQL_TXN_REPEATABLE_READ is Read Stability;
- SQL_TXN_SERIALIZABLE is Repeatable Read.
This option cannot be specified while there is an open
cursor on any statement handle, or an outstanding transaction for
this connection; otherwise, SQL_ERROR is returned on the function
call (SQLSTATE S1011).
This attribute (or corresponding
keyword) is only applicable if the default isolation level is used.
If the application has specifically set the isolation level then
this attribute will have no effect.
Note: There is an IBM attribute that
permits the setting of transaction isolation levels on a per statement
handle basis. See the SQL_ATTR_STMTTXN_ISOLATION statement attribute.
- SQL_ATTR_USE_TRUSTED_CONTEXT
- When connecting to a DB2 database
server that supports trusted contexts, set this attribute if you want
the connection you are creating to be a trusted connection. If this
attribute is set to SQL_TRUE and the database server determines that
the connection can be trusted then the connection is a trusted connection.
If this attribute is not set, if it is set to SQL_FALSE, if the database
server does not support trusted contexts, or if the database server
determines that the connection cannot be trusted then a regular connection
is created instead and a warning (SQLSTATE 01679) is returned. This
value can only be specified before the connection is established either
for the first time or following a call to the SQLDisconnect() function.
- SQL_ATTR_USER_REGISTRY_NAME
-
This attribute is only used when authenticating a user on
a server that is using an identity mapping service. It is set to a
user defined string that names an identity mapping registry. The format
of the registry name varies depending on the identity mapping service
used. By providing this attribute you tell the server that the user
name provided can be found in this registry.
After setting
this attribute the value will be used on subsequent attempts to establish
a normal connection, establish a trusted connection, or switch the
user id on a trusted connection.
This attribute
is not supported when accessing Informix database
servers.
- SQL_ATTR_WCHARTYPE
- A 32-bit integer that specifies, in a double-byte environment,
which wchar_t (SQLDBCHAR) character format you want to use in your
application. This option provides you the flexibility to choose between
having your wchar_t data in multi-byte format or in wide-character
format. There two possible values for this option:
- SQL_WCHARTYPE_CONVERT: character codes are converted between the
graphic SQL data in the database and the application variable. This
allows your application to fully exploit the ANSI C mechanisms for
dealing with wide character strings (for example, L-literals, 'wc'
string functions) without having to explicitly convert the data to
multi-byte format before communicating with the database. The disadvantage
is that the implicit conversions might have an impact on the runtime
performance of your application, and might increase memory requirements.
If you want WCHARTYPE CONVERT behavior then define the C preprocessor
macro SQL_WCHART_CONVERT at compile time. This ensures that certain
definitions in the DB2 header
files use the data type wchar_t instead of sqldbchar.
- SQL_WCHARTYPE_NOCONVERT (default): no implicit character
code conversion occurs between the application and the database. Data
in the application variable is sent to and received from the database
as unaltered DBCS characters. This allows the application to have
improved performance, but the disadvantage is that the application
must either refrain from using wide-character data in wchar_t (SQLDBCHAR)
application variables, or it must explicitly call the wcstombs() and
mbstowcs() ANSI C functions to convert the data to and from multi-byte
format when exchanging data with the database.
Note: This is an IBM-defined attribute.
- SQL_ATTR_XML_DECLARATION
- A 32-bit unsigned integer that specifies which elements of an
XML declaration are added to XML data when it is implicitly serialized.
This attribute does not affect the result of the XMLSERIALIZE function.
Set this attribute to the sum of each component required:
- 0: No declarations or byte order marks (BOMs) are added to the
output buffer.
- 1: A byte order mark (BOM) in the appropriate endianness is prepended
to the output buffer if the target encoding is UTF-16 or UTF-32. (Although
a UTF-8 BOM exists, DB2 does
not generate it, even if the target encoding is UTF-8.)
- 2: A minimal XML declaration is generated, containing only the
XML version.
- 4: An encoding attribute that identifies the target encoding is
added to any generated XML declaration. Therefore, this setting only
has effect when the setting of 2 is also included when computing the
value of this attribute.
Attempts to set any other value using SQLSetConnectAttr() or SQLSetConnectOption() will
result in a CLI0191E (SQLSTATE HY024) error, and the value will remain
unchanged. The default setting is 7, which indicates that a BOM
and an XML declaration containing the XML version and encoding attribute
are generated during implicit serialization.
This setting
affects any statement handles allocated after the value is changed.
Existing statement handles retain their original values.
This attribute is not supported when accessing Informix database
servers.