xcall SQL, SQLOP_SET_STMATR, cmdhdr, optionval
This function is used in the ODBC interface to set attributes associated with statements (queries) as opposed to connections.
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 |
Set to one of the SQL_ATTR_xxx values from the table below |
cmdarg1,2 |
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 |
in |
Set to 0 unless setting attributes specifically for a certain prepared statement. |
optionval [num,in]
Numeric value from which to set the attribute specified in opflags. See table below.
opflags Symbol (ODBC) |
Value |
Notes |
|---|---|---|
SQL_ATTR_ASYNC_ENABLE |
4 |
not yet implemented |
SQL_ATTR_CONCURRENCY |
7 |
SQL_CONCUR_READ_ONLY (default), SQL_CONCUR_LOCK, SQL_CONCUR_ROWVER, SQL_CONCUR_VALUES |
SQL_ATTR_CURSOR_SCROLLABLE |
-1 |
SQL_NONSCROLLABLE (default), SQL_SCROLLABLE |
SQL_ATTR_CURSOR_SENSITIVITY |
-2 |
SQL_UNSPECIFIED (default), SQL_INSENSITIVE, SQL_SENSITIVE |
SQL_ATTR_CURSOR_TYPE |
6 |
SQL_CURSOR_FORWARD_ONLY (default), SQL_CURSOR_KEYSET_DRIVEN, SQL_CURSOR_DYNAMIC, SQL_CURSOR_STATIC. See Cursors and Cursor Types. |
SQL_ATTR_KEYSET_SIZE |
8 |
Number of rows in the keyset for a keyset-driven cursor. If 0 (default), cursor is fully keyset-driven, else the cursor is mixed (keyset-driven within the keyset and dynamic outside). |
SQL_ATTR_MAX_LENGTH |
3 |
The maximum number of bytes to be returned for a string or blob column. If 0 (default), driver will attempt to return all data; otherwise it will truncate the data returned for a column at the specified maximum length. |
SQL_ATTR_MAX_ROWS |
1 |
The maximum number of rows to return for a SELECT statement. If 0 (default), the driver returns all matching rows. Otherwise the result set is truncated. |
SQL_ATTR_NOSCAN |
2 |
If SQL_NOSCAN_OFF (default), the driver scans SQL strings for escape sequences. If SQL_NOSCAN_ON, it doesn’t and instead just sends them directly to the data source. |
SQL_ATTR_QUERY_TIMEOUT |
0 |
Number of seconds to wait for an SQL statement to execute before returning. If 0 (default), there is no timeout. Applies to be synchronous and asynchronous modes. |
SQL_ATTR_RETRIEVE_DATA |
11 |
to be described / implemented later… |
SQL_ATTR_ROW_ARRAY_SIZE |
27 |
Number of rows returned by each SQLOP_FETCH_ROW operation. Default is1. |
SQL_ATTR_ROW_NUMBER |
14 |
(Get only) The number of the current row in the entire result set. If it cannot be determined, or does not exist, 0 is returned. |
SQL_ATTR_SIMULATE_CURSOR |
10 |
Options related to whether drivers that simulate positioned update and delete statements guarantee that such statements affect only one row. SQL_SC_NON_UNIQUE, SQL_SC_TRY_UNIQUE, SQL_SC_UNIQUE |
SQL_ATTR_USE_BOOKMARKS |
12 |
SQL_UB_OFF, SQL_UB_FIXED, SQL_UB_VARIABLE |
Notes
If there is no current statement handle allocated, this call will allocate one and apply the attribute to it. Otherwise it applies the attribute to the current statement handle. The statement handle remains active for subsequent calls to SQLOP_SET_STMATR, SQLOP_GET_STMATR, SQLOP_QUERY, SQLOP_GET_COLDEFS, SQLOP_SET_COLDEFS, SQLOP_FETCH_ROW and SQLOP_FREE_RESULT.
As each call to SQLOP_SET_STMATR can only set one attribute, you may need to call it several times if you have several attributes to set.
To avoid having to re-establish the same set of statement attributes prior to each SQLOP_QUERY, use one of the SQLOP_FREE_RESULT options other than SQL_DROP.
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 above).
See the ++include module SQL:FNSQLATR.BSI for functions which simplify the setting of attributes.
