提取数据的行Fetching a Row of Data

若要提取的数据行,应用程序调用SQLFetchTo fetch a row of data, an application calls SQLFetch. SQLFetch可以调用与任何类型的游标,但它仅会移动行集只进的方向。SQLFetch can be called with any kind of cursor, but it only moves the rowset cursor in a forward-only direction. SQLFetch将光标前进到下一行,并返回调用绑定所有列的数据SQLBindColSQLFetch advances the cursor to the next row and returns the data for any columns that were bound with calls to SQLBindCol. 光标在到达最终结果的设置,请SQLFetch返回 sql_no_data 为止。When the cursor reaches the end of the result set, SQLFetch returns SQL_NO_DATA. 例如,调用SQLFetch,请参阅使用 SQLBindColFor examples of calling SQLFetch, see Using SQLBindCol.

精确SQLFetch实现是特定于驱动程序,但常规模式是,若要检索的数据的任何列绑定从数据源,将其根据绑定变量的类型转换并将该驱动程序在这些变量的已转换的数据。Exactly how SQLFetch is implemented is driver-specific, but the general pattern is for the driver to retrieve the data for any bound columns from the data source, convert it according to the types of the bound variables, and place the converted data in those variables. 如果该驱动程序不能将任何数据,转换SQLFetch返回错误。If the driver cannot convert any data, SQLFetch returns an error. 应用程序可以继续提取行,但当前行数据都将丢失。The application can continue fetching rows, but the data for the current row is lost. 未绑定列的数据会发生什么情况取决于该驱动程序,但大多数驱动程序检索,放弃它或者永远不会在所有检索它。What happens to the data for unbound columns depends on the driver, but most drivers either retrieve and discard it or never retrieve it at all.

驱动程序还将设置都已绑定任何长度/指示器缓冲区的值。The driver also sets the values of any length/indicator buffers that have been bound. 如果列的数据值为 NULL,驱动程序会将相应的长度/指示器缓冲区设置为 SQL_NULL_DATA。If the data value for a column is NULL, the driver sets the corresponding length/indicator buffer to SQL_NULL_DATA. 如果数据值不为 NULL,驱动程序将设置的长度/指示器缓冲区的字节长度的数据的转换后。If the data value is not NULL, the driver sets the length/indicator buffer to the byte length of the data after conversion. 如果此长度不能确定,因为有时是由多个函数调用检索的长整型数据与这种情况,该驱动程序将设置为 SQL_NO_TOTAL 长度/指示器缓冲区。If this length cannot be determined, as is sometimes the case with long data that is retrieved by more than one function call, the driver sets the length/indicator buffer to SQL_NO_TOTAL. 对于固定长度的数据类型,如整数和日期结构的字节长度是数据类型的大小。For fixed-length data types, such as integers and date structures, the byte length is the size of the data type.

对于可变长度数据,例如字符和二进制数据的驱动程序检查转换后的数据对绑定到列; 的缓冲区的字节长度的字节长度在指定缓冲区的长度BufferLength中的参数SQLBindColFor variable-length data, such as character and binary data, the driver checks the byte length of the converted data against the byte length of the buffer bound to the column; the buffer's length is specified in the BufferLength argument in SQLBindCol. 如果转换后的数据的字节长度大于缓冲区的字节长度,该驱动程序将截断数据缓冲区中容纳不下,则返回长度/指示器缓冲区中的未截断的长度返回 SQL_SUCCESS_WITH_INFO,并将放 SQLSTATE 01004 (数据已截断) 诊断中。If the byte length of the converted data is greater than the byte length of the buffer, the driver truncates the data to fit in the buffer, returns the untruncated length in the length/indicator buffer, returns SQL_SUCCESS_WITH_INFO, and places SQLSTATE 01004 (Data truncated) in the diagnostics. 唯一的例外是返回时,如果截断长度可变的书签SQLFetch,这会返回 SQLSTATE 22001 (字符串数据,右端被截断)。The only exception to this is if a variable-length bookmark is truncated when returned by SQLFetch, which returns SQLSTATE 22001 (String data, right truncated).

固定长度的数据永远不会被截断,因为驱动程序假定绑定的缓冲区的大小是数据类型的大小。Fixed-length data is never truncated, because the driver assumes that the size of the bound buffer is the size of the data type. 数据截断往往很少见,因为应用程序通常将绑定的缓冲区大小不足以容纳整个数据值;它确定从元数据所需大小。Data truncation tends to be rare, because the application usually binds a buffer large enough to hold the entire data value; it determines the necessary size from the metadata. 但是,应用程序可能显式绑定它知道得太小的缓冲区。However, the application might explicitly bind a buffer it knows to be too small. 例如,它可能会检索并显示一部分说明的前 20 个字符或长文本列的前 100 个字符。For example, it might retrieve and display the first 20 characters of a part description or the first 100 characters of a long text column.

字符数据必须由驱动程序以 null 结尾之前它将返回到应用程序,即使它已被截断。Character data must be null-terminated by the driver before it is returned to the application, even if it has been truncated. Null 终止字符未包含在返回的字节长度,但需要绑定的缓冲区中的空间。The null-termination character is not included in the returned byte length but does require space in the bound buffer. 例如,假设应用程序使用字符串组成的 ASCII 字符集中的字符数据、 驱动程序包含 50 个字符的数据,若要返回,且应用程序的缓冲区是 25 个字节。For example, suppose an application uses strings composed of character data in the ASCII character set, a driver has 50 characters of data to return, and the application's buffer is 25 bytes long. 在应用程序的缓冲区中的驱动程序将返回 null 终止字符后跟第一次 24 个字符。In the application's buffer, the driver returns the first 24 characters followed by a null-termination character. 在长度/指示器缓冲区,它将返回字节长度为 50。In the length/indicator buffer, it returns a byte length of 50.

应用程序可以限制结果集通过执行语句,创建结果集之前设置 SQL_ATTR_MAX_ROWS 语句属性中的行数。The application can restrict the number of rows in the result set by setting the SQL_ATTR_MAX_ROWS statement attribute before executing the statement that creates the result set. 例如,用于设置格式的报表的应用程序中的预览模式下需要仅数据不足,无法显示报表的第一页。For example, the preview mode in an application used to format reports needs only enough data to display the first page of the report. 通过限制结果集的大小,此类功能会更快地运行。By restricting the size of the result set, such a feature would run faster. 此语句属性用于减少网络流量,并且可能不支持的所有驱动程序。This statement attribute is intended to reduce network traffic and might not be supported by all drivers.