ASQL Reference

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.

 

 

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:

 

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.