xcall SQL, SQLOP_PST_BIND, cmdhdr, recvar, bindmap
xcall SQL, SQLOP_PST_BIND, cmdhdr, param1, … , paramN
xcall SQL, SQLOP_PST_BIND, cmdhdr, param1,opt1, … , paramN,optN
The SQLOP_PST_BIND function is used to define the bindings between the parameters (marked with ‘?’ placeholders in the SQLOP_PREPARE operation) and the application variables providing or receiving the corresponding data when the prepared statement is executed.
This is optional for SELECT statements, since you can use the SQLOP_FETCH_ROW function to retrieve the results (for both direct and prepared SELECT statements), and it already supports a simple binding capability. SQLOP_PST_BIND is mandatory for non-SELECT statements.
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 |
BINDF_xxx (see table below) |
cmdarg1 |
n/a |
|
cmdarg2 |
n/a |
|
rc |
out |
return code (0 = ok, see SQLERR_xxx) |
rcext |
out |
extended error code |
info1 |
out |
param # (in case of error) |
info2 |
n/a |
|
sqlstate |
out |
ANSI standard SQL state code |
reshdl |
n/a |
|
psthdl |
in |
Must match the value returned from the corresponding SQLOP_PST_PREPARE and passed to the subsequent SQLOP_STMT_EXECUTE statements |
opflags Symbol |
Value |
Notes |
|---|---|---|
BINDF_MAPFILE |
&h0001 |
bindmap is the file specification of file containing a ‘record’ definition similar to a record layout (MAP) file. See notes below. |
BINDF_MAPSTR |
&h0002 |
bindmap contains a ‘record’ definition using the same format rules as for BINDF_MAPFILE |
BINDF_LIST1 |
&h0004 |
(Second syntax above.) Parameters (after cmdhdr) form a list of individual parameters, each using default binding rules. |
BINDF_LIST2 |
&h0008 |
(Third syntax above.) Parameters (after cmdhdr) form a list of <param, info> pairs. |
recvar [unformatted, in]
A “record” (or “structure”) variable containing all of the fields to be bound to the prepared statement. The order of the fields must match that of the field placeholders, and the types and sizes must be appropriate. See the notes for restrictions on the bindmap layout (which similarly apply to this structure.)
bindmap [string, in]
Depending on the BINDF_MAPFILE and BINDF_MAPSTR flags, specifies either the filespec of a file containing a binding map, or the binding map itself. A binding map is based on the concept of a record map, defining all of the fields which make up a unit of database access (e.g. a row). See below for the specifications.
paramN [any type, in]
The actual variable to be bound to the corresponding parameter in the prepared statement. The parameter type should match the database field type as closely as possible. For example, for a database field of type DOUBLE, the corresponding param type for the variable to be bound should be F,8. In the case of BIND_LIST2, additional binding options can be specified for each parameter, but with BIND_LIST1, only default bindings are possible.
bindinfoN [string, in]
A string providing additional binding information about the field. This can be used to tailor data conversions between the Basic parameter types and the SQL database field types. (Details yet to be defined.)
Bindmap Specification
A bindmap is a variation of a standard set of map statements, similar to those used to define a structure or record. The main differences are:
A bindmap does not allow arrays
Only MAPx fields (x>=2) with explicit types and sizes are processed (any others are ignored for the purposes of binding).
Any additional information about the field to affect the way it is bound must be contained within <angle brackets> following a comment marker (“!”).
Example bindmap:
MAP1 STUDENT
MAP2 ID,S,6 ! Student identifier
MAP2 NAME
MAP3 FIRST,S,10 ! First name
MAP3 LAST,S,20 ! Last name
MAP2 DOB,X,32 ! Date of birth <DATESTAMP>
MAP2 UNITS,B,2 ! Accumulated units
MAP2 GPA,F,4 ! Grade Point Average
In the above example, the fields will be bound to the parameters as follows:
Statement |
Bound |
Notes |
|---|---|---|
First |
ID |
Default string binding |
Second |
FIRST |
NAME variable is ignored because it has no explicit type,size. Default string binding |
Third |
LAST |
Default string binding |
Fourth |
DOB |
Uses additional binding options <DATESTAMP> to convert the contents of the X,32 data into a DATESTAMP database format. |
Fifth |
UNITS |
Default unsigned short integer binding (B,2) |
Sixth |
GPA |
Default FLOAT binding (F,4) |
Notes
The qrystr parameter in the SQLOP_PST_PREPARE function allows for the database field types to be retrieved, which then allow default bindings to be applied. For example, if a field type is FLOAT, regardless of the type of variable you bind it to, the appropriate conversion will be automatically supplied. So there is little need to specify additional information in the bindmap or via the optN parameters (in the third syntax form), except when the standard format/type conversions aren’t adequate.
