xcall SQL, opcode, cmdhdr {,parm1,…,parmN}
SQL.SBR provides low level functional access to the API of typical SQL databases. Currently it supports the native MySQL C API, as well as the standard ODBC 3.0 API. The individual functions are determined by the opcode parameter, each of which is documented in a separate section below, following this discussion of the cmdhdr parameter common to all opcodes.
Note that ASQL is a licensed A-Shell option. If you try to use XCALL SQL without having licensed ASQL, you will get an error message and a usage restriction. That restriction—A-Shell going into demo mode—can be reset by closing and then restarting the session.
cmdhdr (ST_SQL_CMDHDR), [in/out]
All of the SQL functions pass this common structure as the second parameter, as a way of minimizing the overhead and differences between the various function calls. The structure is defined in SQL.DEF, along with all of the related symbols, and thus should be included into each program. The structure fields are described in the following table:
Field |
Dir |
Type |
Meaning |
|---|---|---|---|
handle |
in/ out |
b,1 |
Handle to a database connection. Returned from the SQLOP_INIT_CONN operation; must be passed to all other calls relating to that connection |
dbmsconid |
in |
b,1 |
Identifies database connector; see DBMS Connector ID. |
opflags |
in |
i,2 |
Flags modifying opcode |
cmdarg1 |
in |
i,4 |
general purpose argument #1 |
cmdarg2 |
in |
f,8 |
general purpose argument #2 (non-integers and values > 32 bits) |
lastop |
out |
i,2 |
The opcode parameter (first parameter) is replicated here as a convenience to routines that may process the rest of the cmdhdr based on the opcode. A judgment call was made to specify the opcode as a separate parameter to make source code more readable. |
rc |
out |
i,2 |
Interface return code 0 = OK; else see Error codes |
rcext |
out |
i,4 |
Extended return status. When rc = SQLERR_DBMSERR, rcext will contain the actual database error code. For other rc values, may contain additional information related to error. |
info1 |
out |
i,4 |
Return information |
info2 |
out |
f,8 |
Additional return information: non-integers and values > 32 bits, such as record numbers and row counts |
sqlstate |
out |
s,5 |
5 character ANSI standard SQL state code indicating warnings or errors. The function Fn’SQL’State$() in the include module SQL:FNSQLSTATE.BSI provides a handy way to display the meaning of these codes, although an Internet search will also work. |
reshdl |
in |
b,1 |
Result set handle, 0 – max; see SQLOP_INIT_LIB. Used only when you need to manipulate more than one result set at one time for a single connection. This only applies to directly executed statements; each prepared statement has its own result set. Set reshdl=0 when working with prepared statements. |
stmthdl |
in |
b,1 |
Prepared statement handle, 1-max; see SQLOP_INIT_LIB. Used in conjunction with prepared statement functions to identify the particular statement. Should be left at zero for operations not related to prepared statements. Note that each prepared statement supports a single implicit result set if applicable, which takes precedence over the reshdl |
parm1,…, parmN
These parameters depend on the opcode. In most cases, there will be only one input string, such as an SQL statement, and/or one output string (returning information in response to a specific request), but for read/write operations they may be a list of variables to read into or write from.
