xcall SQL, SQLOP_SET_CONNATR, cmdhdr, optionval
This operation may be used to establish connection options or attributes which remain in effect for the duration of the connection. The available attributes are specific to each database/connector, so your application must take care to specify attributes that go with the connector type.
Parameters
cmdhdr (ST_SQL_CMDHDR), [in/out]
The fields of interest to this opcode in the cmdhdr structure (defined in SQL.DEF) are listed below.
Field |
Dir |
Notes |
|---|---|---|
handle |
in |
handle to connection (returned from SQLOP_INIT_CONN) |
dbmsconid |
in |
|
opflags |
in |
OPT_MY_xxx (MySQL) or SQL_ATTR_xxx (ODBC) specifies option to set. (See tables below) |
cmdarg1 |
n/a |
|
cmdarg2 |
n/a |
|
rc |
out |
return code (0 = ok, see SQLERR_xxx) |
rcext |
out |
extended error code |
info1,2 |
n/a |
|
sqlstate |
out |
ANSI standard SQL state code |
reshdl |
n/a |
|
psthdl |
n/a |
|
optionval [string or numeric, in]
A string or numeric parameter, depending on the type of option. It is acceptable to use a string variable to pass numeric values, but obviously only a string can be used for string values.
opflags Symbol (MySQL) |
Value |
Notes |
|---|---|---|
OPT_MY_COMPRESS |
1 |
enable compressed client/server protocol (optionval ignored) |
OPT_MY_CONNECT_TIMEOUT |
0 |
optionval contains timeout in seconds |
OPT_MY_INIT_COMMAND |
3 |
optionval contains statement (text) to execute when connecting to server (automatically re-executed if reconnection occurs) |
OPT_MY_LOCAL_INFILE |
8 |
If optionval = 1, enable the “LOAD LOCAL INFILE” statement |
OPT_MY_NAMED_PIPE |
2 |
use named pipes to connect to a MySQL server on Windows, if the server supports it. (option ignored) |
OPT_MY_PROTOCOL |
9 |
protocol (MYPROTO_xxx – see MySQL Protocol Types) |
OPT_MY_READ_DFT_FILE |
4 |
optionval contains filespec of option file to use instead of my.cnf. |
OPT_MY_READ_DFT_GROUP |
5 |
optionval contains group name for which to read options from the my.cnf file (or file specified by OPT_MY_READ_DFT_FILE) |
OPT_MY_READ_TIMEOUT |
11 |
timeout in seconds for attempts to read from server; 3 retries will be attempted (so total timeout is 3X this value; TCP only) |
OPT_MY_RECONNECT |
20 |
if non-zero, enable (else disable) automatic reconnection to the server if the connection is lost. Option disabled by default. |
OPT_MY_SECURE_AUTH |
18 |
if non-zero, enable connection to servers that do not support the password hashing used in MySQL 4.1.1 and later |
OPT_MY_SET_CHARSET_DIR |
6 |
optionval contains path containing character set definition files |
OPT_MY_SET_CHARSET_NAME |
7 |
optionval contains name of character set to use as the default |
OPT_MY_VERIFY_SERVER_CERT |
21 |
if non-zero, enable (else disable) verification of the server’s Common Name value in its certificate against the host name used when connecting to the server. (The connection is rejected on mismatch.) Useful for preventing “man-in-the-middle” attacks. Option disabled by default. |
OPT_MY_WRITE_TIMEOUT |
12 |
timeout in seconds for attempts to write to server; 3 retries will be attempted (so total timeout is 3X this value; TCP only) |
opflags Symbol (ODBC) |
Value |
Notes |
|---|---|---|
SQL_ATTR_ACCESS_MODE |
101 |
SQL_ACCESS_MODE_READ_WRITE (default), SQL_ACCESS_MODE_READ_ONLY. |
SQL_ATTR_ASYNC_ENABLE |
4 |
not yet implemented |
SQL_ATTR_AUTOCOMMIT |
102 |
SQL_VALUE_ON (default), SQL_VALUE_OFF |
SQL_ATTR_CONNECTION_DEAD |
1209 |
(read only) SQL_TRUE (connection is dead), SQL_FALSE (still active) |
SQL_ATTR_CONNECTION_ |
113 |
# of seconds to wait before timing out on any request (and return sqlstate HYT00 – timeout) Default is 0 (no timeout). |
SQL_ATTR_CURRENT_CATALOG |
109 |
String specifying the name of the catalog to be used by the data source. For SQL Server, this would be the name of a database; for simpler data sources, the catalog might just be a directory. |
SQL_ATTR_LOGIN_TIMEOUT |
103 |
# of seconds before timing out on the login. 0 means no timeout. (Default varies by data source.) |
SQL_ATTR_METADATA_ID |
10014 |
SQL_TRUE causes string arguments of catalog functions to be treated as identifiers (case insensitive, trailing spaces removed.) SQL_FALSE (default) causes string arguments to catalog functions to be taken literally. May also be set at the statement level. |
SQL_ATTR_ODBC_CURSORS |
110 |
SQL_CUR_USE_ODBC tells the Driver Manager to use the ODBC cursor library. SQL_CUR_USE_DRIVER (default) tells it to use the scrolling capabilities of the driver. |
SQL_ATTR_PACKET_SIZE |
112 |
Network packet size in bytes. Must be set before connecting to the data source. |
SQL_ATTR_QUIET_MODE |
111 |
0 tells the driver not to display any dialog boxes. Otherwise it should be the handle of the parent window (which will become the parent of any dialog boxes displayed by the driver). Does not apply to dialog boxes displayed during the operation to connect to the driver. |
SQL_ATTR_TRACE |
104 |
SQL_TRUE turns tracing on. SQL_FALSE (default) turns it off. |
SQL_ATTR_TRACEFILE |
105 |
Filespec of the trace file. Default is “\\SQL.LOG” |
SQL_ATTR_TRANSLATE_LIB |
106 |
Name of a DLL to be used by the driver to perform translations (such as character set translations). |
SQL_ATTR_TRANSLATE_OPTION |
107 |
32 bit flag value passed to the translation DLL. |
SQL_ATTR_TXN_ISOLATION |
108 |
32 bit bitmask that sets the transaction isolation level for the connection. (Not yet implemented.) |
Notes
Most of the connection attributes can be set any time after the connection is initialized (by SQLOP_INIT_CONN), either before or after connecting to the database (SQLOP_CONNECT). The exceptions are: SQL_ATTR_LOGIN_TIMEOUT, SQL_ATTR_ODBC_CURSORS and SQL_ATTR_PACKET_SIZE must be set prior to SQLOP_CONNECT. And SQL_ATTR_TRANSLATE_LIB and SQL_ATTR_TRANSLATE_OPTION can only be set after SQLOP_CONNECT.
If rcext is returned non-zero, this suggests that the driver may have substituted the value you attempted to set with one that it could support. To determine just what it is, you may call SQLOP_GET_STMATR.
See the ++include module SQL:FNSQLATR.BSI for functions which simplify the setting of attributes.
