1 Version 4.0 -- 5/1/89 dbbind
______________________________________________________________________
NAME: dbbind
FUNCTION:
Bind a regular result column to a program variable.
SYNTAX:
RETCODE dbbind(dbproc, column, vartype, varlen, varaddr)
DBPROCESS *dbproc;
int column;
int vartype;
DBINT varlen;
dbbind Version 4.0 -- 5/1/89 2
______________________________________________________________________
BYTE *varaddr;
COMMENTS:
o Data comes back from SQL 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 via dbnextrow() or dbgetrow(), the data from the
designated column in that row is copied into the program vari-
able 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.
o The SQL 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 dbalt-
bind() for binding data from compute rows.
3 Version 4.0 -- 5/1/89 dbbind
______________________________________________________________________
o You must make the calls to dbbind() after a call to dbresults()
and before the first call to dbnextrow().
o 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 SQL Server */
dbsqlexec(dbproc);
/* get ready to process the results of the query */
dbresults(dbproc);
dbbind Version 4.0 -- 5/1/89 4
______________________________________________________________________
/* 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
}
o 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.
o You can only bind a result column to a single program variable.
If you bind a result column to multiple variables, only the
5 Version 4.0 -- 5/1/89 dbbind
______________________________________________________________________
last binding takes effect.
o Since SQL 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 dbset-
null() function allows you to explicitly set your own null sub-
stitution values. (See the manual page for the dbsetnull()
function for a list of the default substitution values.)
PARAMETERS:
dbproc - A pointer to the DBPROCESS structure that provides the
connection for a particular front-end/SQL Server process. It
contains all the information that DB-Library uses to manage
communications and data between the front end and SQL Server.
column - The column number of the row data that is to be copied
to a program variable. The first column is column number 1.
vartype - This describes the datatype of the binding. It must
correspond to the datatype of the program variable that will
dbbind Version 4.0 -- 5/1/89 6
______________________________________________________________________
receive the copy of the data from the DBPROCESS. The table
below shows the correspondence between vartypes 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 instance, a SYBMONEY result may be bound to a
DBFLT8 program variable via FLT8BIND, and the appropriate
data conversion will happen automatically. For a list of the
data conversions provided by DB-Library, see the manual page
for dbwillconvert().
For a list of the typedefs used by DB-Library, see the manual
page for types.
Here is a list of the legal vartypes recognized by dbbind(),
along with the SQL Server and program variable types that
7 Version 4.0 -- 5/1/89 dbbind
______________________________________________________________________
each one refers to:
Vartype Program variable type SQL 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
BITBIND DBBIT SYBBIT
DATETIMEBIND DBDATETIME SYBDATETIME
MONEYBIND DBMONEY SYBMONEY
dbbind Version 4.0 -- 5/1/89 8
______________________________________________________________________
Note that the SQL 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 SQL Server
type, because, as mentioned earlier, dbbind() will convert
SQL Server data into the specified vartype.
The table shows that four representations for character and
text data are available. They differ according to whether
the data is blank-padded or null-terminated:
Vartype Program type Padding Terminator
CHARBIND DBCHAR blanks none
STRINGBIND DBCHAR blanks \0
NTBSTRINGBIND DBCHAR none \0
VARYCHARBIND DBVARYCHAR none none
Note that the "\0" in the table above is the null terminator
9 Version 4.0 -- 5/1/89 dbbind
______________________________________________________________________
character.
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 type Padding
BINARYBIND DBBINARY nulls
VARYBINBIND DBVARBINARY none
varlen - The length of the program variable in bytes.
For fixed-length vartypes, such as MONEYBIND or FLT8BIND,
this length is ignored.
dbbind Version 4.0 -- 5/1/89 10
______________________________________________________________________
For character, 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 SQL 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 con-
tained 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.
varaddr - The address of the program variable to which the data
will be copied.
RETURNS:
11 Version 4.0 -- 5/1/89 dbbind
______________________________________________________________________
SUCCEED or FAIL. dbbind() returns FAIL if the column number
isn't valid, if the data conversion specified by vartype isn't
legal, or if varaddr is NULL.
SEE ALSO:
dbaltbind, dbconvert, dbdata, dbsetnull, dbwillconvert, types