使用长度和指示器值Using Length and Indicator Values

长度/指示器缓冲区用于传递的数据缓冲区或如 SQL_NULL_DATA,指示数据为 NULL 的特殊指示器中的数据的字节长度。The length/indicator buffer is used to pass the byte length of the data in the data buffer or a special indicator such as SQL_NULL_DATA, which indicates that the data is NULL. 根据使用它的函数,定义长度/指示器缓冲区为 SQLINTEGER 或 SQLSMALLINT。Depending on the function in which it is used, a length/indicator buffer is defined to be an SQLINTEGER or an SQLSMALLINT. 因此,单个参数需要对其进行描述。Therefore, a single argument is needed to describe it. 数据缓冲区是否 nondeferred 输入的缓冲区,则此参数包含数据本身的字节长度或指示器值。If the data buffer is a nondeferred input buffer, this argument contains the byte length of the data itself or an indicator value. 它通常名为StrLen_or_Ind或类似名称。It is often named StrLen_or_Ind or a similar name. 例如,下面的代码调用SQLPutData传递缓冲区的数据; 的字节长度 (ValueLen) 直接传递,因为数据缓冲区 (ValuePtr) 是输入的缓冲区。For example, the following code calls SQLPutData to pass a buffer full of data; the byte length (ValueLen) is passed directly because the data buffer (ValuePtr) is an input buffer.

SQLCHAR      ValuePtr[50];  
SQLINTEGER   ValueLen;  
  
// Call local function to place data in ValuePtr. In ValueLen, return the  
// number of bytes of data placed in ValuePtr. If there is not enough  
// data, this will be less than 50.  
FillBuffer(ValuePtr, sizeof(ValuePtr), &ValueLen);  
  
// Call SQLPutData to send the data to the driver.  
SQLPutData(hstmt, ValuePtr, ValueLen);  

如果延迟的输入的缓冲区、 nondeferred 的输出缓冲区或输出缓冲区的数据缓冲区,该参数包含长度/指示器缓冲区的地址。If the data buffer is a deferred input buffer, a nondeferred output buffer, or an output buffer, the argument contains the address of the length/indicator buffer. 它通常名为StrLen_or_IndPtr或类似名称。It is often named StrLen_or_IndPtr or a similar name. 例如,下面的代码调用SQLGetData若要检索的数据; 完整的缓冲区的字节长度返回到长度/指示器缓冲区中的应用程序 (ValueLenOrInd),其地址是传递给SQLGetData因为相应的数据缓冲区 (ValuePtr) 是 nondeferred 的输出缓冲区。For example, the following code calls SQLGetData to retrieve a buffer full of data; the byte length is returned to the application in the length/indicator buffer (ValueLenOrInd), whose address is passed to SQLGetData because the corresponding data buffer (ValuePtr) is a nondeferred output buffer.

SQLCHAR      ValuePtr[50];  
SQLINTEGER   ValueLenOrInd;  
SQLGetData(hstmt, 1, SQL_C_CHAR, ValuePtr, sizeof(ValuePtr), &ValueLenOrInd);  

除非明确禁止,长度/指示器缓冲区参数可以是 0 (如果 nondeferred 的输入) 或 null 指针 (如果输出或延迟的输入)。Unless it is specifically prohibited, a length/indicator buffer argument can be 0 (if nondeferred input) or a null pointer (if output or deferred input). 对于输入缓冲区,这会导致驱动程序忽略数据的字节长度。For input buffers, this causes the driver to ignore the byte length of the data. 这将传递长度可变的数据时将返回错误,但时很常见传递非 null 的固定长度数据,因为长度和指示器值都不需要。This returns an error when passing variable-length data but is common when passing non-null, fixed-length data, because neither a length nor an indicator value is needed. 对于输出缓冲区,这会导致要返回的数据或指示器值的字节长度的驱动程序。For output buffers, this causes the driver to not return the byte length of the data or an indicator value. 如果驱动程序返回的数据为 NULL,但因为长度和指示器值都不需要为常见检索固定长度,不可以为 null 的数据时,这是一个错误。This is an error if the data returned by the driver is NULL but is common when retrieving fixed-length, non-nullable data, because neither a length nor an indicator value is needed.

当延迟的数据缓冲区的地址传递给驱动程序,作为延迟的长度/指示器缓冲区的地址必须保持有效,直到取消绑定此缓冲区。As when the address of a deferred data buffer is passed to the driver, the address of a deferred length/indicator buffer must remain valid until the buffer is unbound.

以下的长度是作为长度/指示器值无效:The following lengths are valid as length/indicator values:

  • n,其中n > 0。n, where n > 0.

  • SQL_NTS.SQL_NTS. 发送到相应的数据缓冲区中的驱动程序的字符串是以 null 结尾;这是 C 程序员可以传递字符串,而无需计算它们的字节长度的简便方法。A string sent to the driver in the corresponding data buffer is null-terminated; this is a convenient way for C programmers to pass strings without having to calculate their byte length. 仅当应用程序将数据发送到该驱动程序时,此值是合法的。This value is legal only when the application sends data to the driver. 当驱动程序将数据返回到应用程序时,它始终返回数据的实际字节长度。When the driver returns data to the application, it always returns the actual byte length of the data.

以下值是作为长度/指示器值无效。The following values are valid as length/indicator values. SQL_NULL_DATA 存储在 SQL_DESC_INDICATOR_PTR 描述符字段;所有其他值都存储在 SQL_DESC_OCTET_LENGTH_PTR 描述符字段。SQL_NULL_DATA is stored in the SQL_DESC_INDICATOR_PTR descriptor field; all other values are stored in the SQL_DESC_OCTET_LENGTH_PTR descriptor field.

  • SQL_NULL_DATA.SQL_NULL_DATA. 数据为 NULL 数据值,而忽略相应的数据缓冲区中的值。The data is a NULL data value, and the value in the corresponding data buffer is ignored. 此值是合法只能用于 SQL 数据发送到或从该驱动程序检索到的。This value is legal only for SQL data sent to or retrieved from the driver.

  • SQL_DATA_AT_EXEC.SQL_DATA_AT_EXEC. 数据缓冲区不包含任何数据。The data buffer does not contain any data. 相反,数据将发送具有SQLPutData执行该语句时或当SQLBulkOperationsSQLSetPos调用。Instead, the data will be sent with SQLPutData when the statement is executed or when SQLBulkOperations or SQLSetPos is called. 此值是仅对发送到该驱动程序的 SQL 数据合法的。This value is legal only for SQL data sent to the driver. 有关详细信息,请参阅SQLBindParameterSQLBulkOperations,并SQLSetPosFor more information, see SQLBindParameter, SQLBulkOperations, and SQLSetPos.

  • 结果 SQL_LEN_DATA_AT_EXEC (长度) 宏。Result of the SQL_LEN_DATA_AT_EXEC(length) macro. 此值是类似于 SQL_DATA_AT_EXEC。This value is similar to SQL_DATA_AT_EXEC. 有关详细信息,请参阅发送长数据For more information, see Sending Long Data.

  • SQL_NO_TOTAL。SQL_NO_TOTAL. 该驱动程序无法确定长数据仍可用于在输出缓冲区中返回的字节数。The driver cannot determine the number of bytes of long data still available to return in an output buffer. 此值是只能用于从驱动程序检索到的 SQL 数据合法的。This value is legal only for SQL data retrieved from the driver.

  • SQL_DEFAULT_PARAM。SQL_DEFAULT_PARAM. 一个过程是而不是相应的数据缓冲区中的值的过程中使用输入参数的默认值。A procedure is to use the default value of an input parameter in a procedure instead of the value in the corresponding data buffer.

  • SQL_COLUMN_IGNORE。SQL_COLUMN_IGNORE. SQLBulkOperationsSQLSetPos是忽略数据缓冲区中的值。SQLBulkOperations or SQLSetPos is to ignore the value in the data buffer. 通过调用更新数据行时SQLBulkOperationsSQLSetPos, 列的值不会更改。When updating a row of data by a call to SQLBulkOperations or SQLSetPos, the column value is not changed. 通过调用插入新数据行时SQLBulkOperations,列的值设置为其默认值; 如果列没有默认值为 NULL。When inserting a new row of data by a call to SQLBulkOperations, the column value is set to its default or, if the column does not have a default, to NULL.