Bind a regular result column to a program variable.
RETCODE dbbind(dbproc, column, vartype, varlen,
varaddr)
DBPROCESS *dbproc;
int column;
int vartype;
DBINT varlen;
BYTE *varaddr;
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 following table shows the correspondence between vartype values and program variable types.
dbbind supports a wide range of type conversions, so the vartype can be different from the type returned by the SQL query. For example, 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.
The dbbind routine
does not offer explicit precision and scale support for numeric and decimal datatypes.
When handling numeric or decimal data, dbbind uses a default
precision and scale of 18 and 0, respectively, unless the bind is to
a numeric or decimal column,
in which case dbbind uses
the precision and scale of the source data. Use dbbind_ps to explicitly
specify precision and scale values—calling dbbind is equivalent
to calling dbbind_ps with
a NULL typeinfo value.
For a list of the type definitions used by DB-Library, see Types.
Table 2-3 lists the legal vartype values recognized by dbbind, along with the server and program variable types that each one refers to:
Vartype |
Program variable type |
Server datatype |
|---|---|---|
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! An error occurs when you 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 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 can be stored in two different ways:
Vartype |
Program 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.
Note that if varlen is 0, no padding takes place.
In some cases, DB-Library issues a message indicating that data conversion resulted in an overflow. This can be caused by a varlen specification that is too small for the server data.
The address of the program variable to which the data will be copied.
SUCCEED or FAIL.
dbbind returns FAIL if the column number is not valid, if the data conversion specified by vartype is not legal, or if varaddr is 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 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. dbbind binds data from regular rows. Use dbaltbind for binding data from compute rows.
You must make the calls to dbbind after a call to dbresults and before the first call to dbnextrow.
The typical sequence of calls is:
DBINT xvariable;
DBCHAR yvariable[10];
/* read the query into the command buffer */
dbcmd(dbproc, "select x = 100, y = ’hello’");
/* send the query to Adaptive Server Enterprise */
dbsqlexec(dbproc);
/* get ready to process the query results */
dbresults(dbproc);
/* bind column data to program variables */
dbbind(dbproc, 1, INTBIND, (DBINT) 0,
(BYTE *) &xvariable);
dbbind(dbproc, 2, STRINGBIND, (DBINT) 0,
yvariable);
/* now process each row */
while (dbnextrow(dbproc) != NO_MORE_ROWS)
{
C-code to print or process row data
}
dbbind incurs a little 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 only bind a result column 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, dbnullbind, dbbind_ps, dbconvert, dbconvert_ps, dbdata, dbnullbind, dbsetnull, dbsetversion, dbwillconvert, Types
