当前位置: 首页 > 工具软件 > FreeTDS > 使用案例 >

FreeTDS库函数dbbind参数详解

曾绯辞
2023-12-01

dbbind

Binds a regular result column (a column of results from a SELECT statement's select list) to a program variable.

Syntax

RETCODE dbbind ( 
PDBPROCESS 
dbproc
INT 
column
INT 
vartype
DBINT 
varlen
LPBYTE 
varaddr  );

Arguments

dbproc

Is the DBPROCESS structure that is the handle for a particular workstation or Microsoft® SQL Server™ 2000 process. It contains all the information that DB-Library uses to manage communications and data between the workstation and SQL Server.

column

Is the column number of the row data to be copied to a program variable. The first column is number 1.

vartype

Is a description of the binding's data type. It corresponds to the data type of the program variable that receives the copy of the data from the DBPROCESS. The dbbind  function supports a wide range of type conversions, so vartype  can be different from the type returned by the SQL query. For instance, a SQLMONEY result can be bound to a DBFLT8 program variable, using FLT8BIND, and the appropriate data conversion happens automatically. For more information about a list of the data conversions provided by DB-Library, see dbwillconvert . For more information about a list of the type definitions used by DB-Library, see DB-Library for C Data Types .

The following table lists legal vartypes  recognized by dbbind  and the program variable and SQL Server type tokens that each refers to.


vartype

varaddr
SQL Server data type 
of column
CHARBINDDBCHARSQLCHAR, SQLVARCHAR, or SQLTEXT
STRINGBINDDBCHARSQLCHAR, SQLVARCHAR, or SQLTEXT
NTBSTRINGBINDDBCHARSQLCHAR, SQLVARCHAR, or SQLTEXT
VARYCHARBINDDBVARYCHARSQLCHAR, SQLVARCHAR, or SQLTEXT
BINARYBINDDBBINARYSQLBINARY, SQLVARBINARY, or SQLIMAGE
VARYBINBINDDBVARYBINSQLBINARY, SQLVARBINARY, or SQLIMAGE
TINYBINDDBTINYINTSQLINT1 or SQLINTN
SMALLBINDDBSMALLINTSQLINT2 or SQLINTN
INTBINDDBINTSQLINT4 or SQLINTN
FLT4BINDDBFLT4SQLFLT4 or SQLFLTN
FLT8BINDDBFLT8SQLFLT8 or SQLFLTN
BITBINDDBBITSQLBIT
SMALLMONEYBINDDBMONEY4SQLMONEY4 or SQLMONEYN
MONEYBINDDBMONEYSQLMONEY or SQLMONEYN
DECIMALBINDDBDECIMALSQLDECIMAL
NUMERICBINDDBNUMERICSQLNUMERIC
SRCDECIMALBINDDBDECIMALSQLDECIMAL
SRCNUMERICBINDDBNUMERICSQLNUMERIC
SMALLDATETIBINDDBDATETIM4SQLDATETIM4 or SQLDATETIMN
DATETIMEBINDDBDATETIMESQLDATETIME or SQLDATETIMN

Note that the SQL Server type in the preceding table is listed merely for your information. The vartype  you specify does not necessarily have to correspond to a particular SQL Server data type because dbbind  converts SQL Server data into the specified vartype .

The following table lists the four representations for character and text data. They differ according to whether the data is blank-padded or null-terminated.

vartype varaddr PaddingTerminator
CHARBINDDBCHARblanksnone
STRINGBINDDBCHARblanks/0
NTBSTRINGBINDDBCHARnone/0
VARYCHARBINDDBVARYCHARnonenone

Note that "/0" is the null terminator character. Similarly, binary and image data can be stored in two different ways.

vartype varaddr Padding
BINARYBINDDBBINARYnulls
VARYBINBINDDBVARBINARYnone

When the source column specified by the column  parameter has a type of SQLDECIMAL or SQLNUMERIC, you can keep the same precision and scale in your bound C variable by using SRCDECIMALBIND or SRCNUMERICBIND.

varlen

Is the length of the varaddr  program variable in bytes. For fixed-length vartypes , such as MONEYBIND or FLT8BIND, this length is ignored. For character, text, binary, and image types, varlen  must describe the total length of the available destination buffer space, including any space that can be required for special terminating bytes, such as a null terminator. If varlen  is 0, the number of bytes available is copied into the program variable. (For char  and binary  SQL Server data, the number of bytes available is equal to the defined length of the database column, including any blank padding. For varcharvarbinarytext , and image  data, the 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 set varlen  to 0.

In some cases, DB-Library issues a message indicating that data conversion resulted in an overflow. This is usually caused by a varlen  specification being too small for the data being received from SQL Server. For example, if varlen  is set to 5, vartype  is set to VARYCHARBIND, and the SQL Server column being bound is of type VARCHAR with a length of 20. When the bind occurs (using dbnextrow ), the overflow message is issued. Note however that five bytes of data will be bound. Other types of binds also can cause the overflow message to be issued. For information about data type conversions, see dbconvert .

varaddr

Is the address of the program variable to which the data is copied. Calling dbbind  with a NULL varaddr  parameter breaks a previously set binding.

When binding using DECIMALBIND or NUMERICBIND, the varaddr  parameter must be a pointer to a DBNUMERIC or DBDECIMAL C variable, respectively, with the precision  and scale  fields of the structure already set to the desired values. You can use DEFAULTPRECISION to specify a default precision and DEFAULTSCALE to specify a default scale.

Returns

SUCCEED or FAIL. The dbbind  function returns FAIL if the column number given isn't valid, if the vartype  isn't compatible with the SQL Server data type being returned, or if varaddr  is NULL.

Remarks

Data comes back from SQL Server one row at a time. This function 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 to be copied. It is not necessary to bind every column to a program variable. A result column can be bound to only one program variable.

SQL Server can return two types of rows: regular rows and compute rows resulting from the COMPUTE clause of a SELECT statement. The dbbind  function binds data from regular rows. Use dbaltbind  for binding data from compute rows.

Calls to dbbind  must be made after a call to dbresults  and before the first call to dbnextrow .

Using dbbind  causes some overhead because it copies the row data into the designated program variable. To avoid this copying, the returned data can be accessed more directly with dbdatlen  and dbdata .

Because null values can be returned from SQL Server, there is a set of default values, one for each data type that will be substituted when binding null values. You can explicitly set your own values to be substituted for the default null value with the dbsetnull  function. (For more information about a list of the default substitution values, see dbsetnull .)

For the Microsoft Windows® operating system, DB-Library retrieves information about date, time, numeric, and currency formatting from the Sqlcommn.loc file. The location of Sqlcommn.loc is pointed to by the SQLLocalizationFile key in the Windows initialization file (Win.ini) under the [SQLSERVER ] application heading. For example:

[SQLSERVER]
SQLLocalizationFile=C:/SQL60/BIN/SQLCOMMN.LOC

For the Microsoft Windows NT® 4.0 operating system, you set the date, time, numeric, and currency formatting using the International application in Control Panel. Use the SQL Server Client Network Utility Use International Settings option to activate this for DB-Library.

Examples

This example shows the typical sequence of calls:

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);
// 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
}

 

See Also

DB-Library for C Data Types

dbgetrow

dbaltbind

dbnextrow

dbanullbind

dbresults

dbconvert

dbsetnull

dbdata

dbwillconvert

dbdatlen

 类似资料: