Bind a regular result column to a program variable, with precision and scale support for numeric and decimal datatypes.
RETCODE dbbind_ps(dbproc, column, vartype, varlen,
varaddr, typeinfo)
DBPROCESS *dbproc;
int column;
int vartype;
DBINT varlen;
BYTE *varaddr;
DBTYPEINFO *typeinfo;
A pointer to the DBPROCESS structure that provides the connection for a particular front-end/server process. It contains all the information that DB-Library uses to manage communications and data between the front end and server.
The column number of the row data that is to be copied to a program variable. The first column is column number 1.
This describes the datatype of the binding. It must correspond to the datatype of the program variable that will receive the copy of the data from the DBPROCESS. The table below shows the correspondence between vartype values and program variable types.
dbbind_ps supports a wide range of type conversions, so the vartype can be different from the type returned by the SQL query. For instance, a SYBMONEY result may be bound to a DBFLT8 program variable through FLT8BIND, and the appropriate data conversion will happen automatically. For a list of the data conversions provided by DB-Library, see the reference page for dbwillconvert.
For a list of the type definitions used by DB-Library, see Types.
Table 2-4 lists the legal vartype values recognized by dbbind_ps, along with the server and program variable types that each one refers to:
Vartype |
Program variable type |
Server type |
|---|---|---|
CHARBIND |
DBCHAR |
SYBCHAR or SYBTEXT |
STRINGBIND |
DBCHAR |
SYBCHAR or SYBTEXT |
NTBSTRINGBIND |
DBCHAR |
SYBCHAR or SYBTEXT |
VARYCHARBIND |
DBVARYCHAR |
SYBCHAR or SYBTEXT |
BINARYBIND |
DBBINARY |
SYBBINARY or SYBIMAGE |
VARYBINBIND |
DBVARYBIN |
SYBBINARY or SYBIMAGE |
TINYBIND |
DBTINYINT |
SYBINT1 |
SMALLBIND |
DBSMALLINT |
SYBINT2 |
INTBIND |
DBINT |
SYBINT4 |
FLT8BIND |
DBFLT8 |
SYBFLT8 |
REALBIND |
DBREAL |
SYBREAL |
NUMERICBIND |
DBNUMERIC |
SYBNUMERIC |
DECIMALBIND |
DBDECIMAL |
SYBDECIMAL |
BITBIND |
DBBIT |
SYBBIT |
DATETIMEBIND |
DBDATETIME |
SYBDATETIME |
SMALLDATETIMEBIND |
DBDATETIME4 |
SYBDATETIME4 |
MONEYBIND |
DBMONEY |
SYBMONEY |
SMALLMONEYBIND |
DBMONEY4 |
SYBMONEY4 |
BOUNDARYBIND |
DBCHAR |
SYBBOUNDARY |
SENSITIVITYBIND |
DBCHAR |
SYBSENSITIVITY |
WARNING! It is an error to use any of the following values for vartype if the library version has not been set (with dbsetversion) to DBVERSION_100 or higher: BOUNDARYBIND, DECIMALBIND, NUMERICBIND, or SENSITIVITYBIND.*
The server type in the table above is listed merely for your information. The vartype you specify does not necessarily have to correspond to a particular server type, because, as mentioned earlier, dbbind_ps will convert server data into the specified vartype.
The server types nchar and nvarchar are converted
internally to char and varchar types, which
correspond to the DB-Library type constant SYBCHAR.
The available representations for character and text data are shown below. They differ according to whether the data is blank-padded or null-terminated. Note that if varlen is 0, no padding takes place and that the “\0” is the null terminator character:
Vartype |
Program type |
Padding |
Terminator |
|---|---|---|---|
CHARBIND |
DBCHAR |
blanks |
none |
STRINGBIND |
DBCHAR |
blanks |
\0 |
NTBSTRINGBIND |
DBCHAR |
none |
\0 |
VARYCHARBIND |
DBVARYCHAR |
none |
none |
BOUNDARYBIND |
DBCHAR |
none |
\0 |
SENSITIVITYBIND |
DBCHAR |
none |
\0 |
If overflow occurs when converting integer or float data to a character/text binding type, the first character of the resulting value will contain an asterisk (“*”) to indicate the error.
binary and image data may be stored in two different ways:
Vartype |
Program variable type |
Padding |
|---|---|---|
BINARYBIND |
DBBINARY |
nulls |
VARYBINBIND |
DBVARBINARY |
none |
The length of the program variable in bytes.
For values of vartype that represent a fixed-length type, such as MONEYBIND or FLT8BIND, this length is ignored.
For char, text, binary, and image types, varlen must describe the total length of the available destination buffer space, including any space that may be required for special terminating bytes, such as a null terminator. If varlen is 0, the total number of bytes available will be copied into the program variable. (For char and binary server data, the total number of bytes available is equal to the defined length of the database column, including any blank padding. For varchar, varbinary, text, and image data, the total number of bytes available is equal to the actual data contained in the column.) Therefore, if you are sure that your program variable is large enough to handle the results, you can just set varlen to 0.
If varlen is 0, no padding takes
place.
The address of the program variable to which the data will be copied.
A pointer to a DBTYPEINFO structure containing information about the precision and scale of decimal or numeric data. An application sets a DBTYPEINFO structure with values for precision and scale before calling dbbind_ps to bind columns to DBDECIMAL or DBNUMERIC variables.
If typeinfo is NULL:
If the result column is of type numeric or decimal, dbbind_ps picks up precision and scale values from the result column.
If the result column is not numeric or decimal, dbbind_ps uses a default precision of 18 and a default scale of 0.
If vartype is not DECIMALBIND or NUMERICBIND, typeinfo is ignored.
A DBTYPEINFO structure is defined as follows:
typedef struct typeinfo {
DBINTprecision;
DBINTscale;
} DBTYPEINFO;
Legal values for precision are from 1 to 77. Legal values for scale are from 0 to 77. scale must be less than or equal to precision.
SUCCEED or FAIL.
dbbind_ps returns FAIL if the column number is not valid, if the data conversion specified by vartype is not legal, or if varaddr is NULL.
dbbind_ps parameters are identical to dbbind’s, except that dbbind_ps has the additional parameter typeinfo, which contains information about precision and scale for DBNUMERIC or DBDECIMAL variables.
dbbind_ps is the equivalent of dbbind, except that dbbind_ps provides scale and precision support for numeric and decimal datatypes, which dbbind does not. Calling dbbind is equivalent to calling dbbind_ps with typeinfo as NULL.
Data comes back from the server one row at a time. This routine directs DB-Library to copy the data for a regular column (designated in a select statement’s select list) into a program variable. When each new row containing regular (not compute) data is read using dbnextrow or dbgetrow, the data from the designated column in that row is copied into the program variable with the address varaddr. There must be a separate dbbind or dbbind_ps call for each regular column that is to be copied. It is not necessary to bind every column to a program variable.
The server can return two types of rows: regular rows and compute rows resulting from the compute clause of a select statement. Use dbbind_ps to bind data from regular rows, and dbaltbind_ps to bind data from compute rows.
You must make the calls to dbbind_ps after a call to dbresults and before the first call to dbnextrow.
dbbind_ps incurs some overhead, because it causes the data to be copied into a program variable. To avoid this copying, you can use the dbdata routine to directly access the returned data.
You can bind a result column only to a single program variable. If you bind a result column to multiple variables, only the last binding takes effect.
Since the server can return null values, DB-Library provides a set of default values, one for each datatype, that it will automatically substitute when binding null values. The dbsetnull function allows you to explicitly set your own null substitution values. See the reference page for the dbsetnull function for a list of the default substitution values.
dbaltbind, dbaltbind_ps, dbanullbind, dbbind, dbconvert, dbconvert_ps, dbdata, dbnullbind, dbsetnull, dbsetversion, dbwillconvert, Types
