Construir instruções pesquisadas

Importante

Esse recurso será removido em uma versão futura do Windows. Evite usar esse recurso em um novo trabalho de desenvolvimento e planeje modificar aplicativos que atualmente usam esse recurso. A Microsoft recomenda usar a funcionalidade de cursor do driver.

Para dar suporte a instruções de atualização e exclusão posicionadas, a biblioteca de cursores constrói uma instrução UPDATE ou DELETE pesquisada da instrução posicionada. Para dar suporte a chamadas para SQLGetData em um bloco de dados, a biblioteca de cursores constrói uma instrução SELECT pesquisada para criar um conjunto de resultados que contém a linha de dados atual. Em cada uma dessas instruções, a cláusula WHERE enumera os valores armazenados no cache para cada coluna associada que retorna SQL_PRED_SEARCHABLE ou SQL_PRED_BASIC para o identificador de campo SQL_DESC_SEARCHABLE em SQLColAttribute.

Cuidado

A cláusula WHERE construída pela biblioteca de cursores para identificar a linha atual pode falhar ao identificar quaisquer linhas, identificar uma linha diferente ou identificar mais de uma linha.

Se uma instrução de atualização ou exclusão posicionada afetar mais de uma linha, a biblioteca de cursores atualizará a matriz de status da linha somente para a linha na qual o cursor está posicionado e retornará SQL_SUCCESS_WITH_INFO e SQLSTATE 01001 (conflito de operação do cursor). Se a instrução não identificar nenhuma linha, a biblioteca de cursores não atualizará a matriz de status da linha e retornará SQL_SUCCESS_WITH_INFO e SQLSTATE 01001 (conflito de operação do cursor). Um aplicativo pode chamar SQLRowCount para determinar o número de linhas que foram atualizadas ou excluídas.

Se a cláusula SELECT usada para posicionar o cursor de uma chamada para SQLGetData identificar mais de uma linha, NÃO há garantia de que SQLGetData retorne os dados corretos. Se ele não identificar nenhuma linha, SQLGetData retornará SQL_NO_DATA.

Se um aplicativo estiver em conformidade com as diretrizes a seguir, a cláusula WHERE construída pela biblioteca de cursores deverá identificar exclusivamente a linha atual, exceto quando isso for impossível, como quando a fonte de dados contiver linhas duplicadas.

• Associe colunas que identificam exclusivamente a linha. Se as colunas associadas não identificarem exclusivamente a linha, a cláusula WHERE construída pela biblioteca de cursores poderá identificar mais de uma linha. Em uma instrução de atualização ou exclusão posicionada, essa cláusula pode fazer com que mais de uma linha seja atualizada ou excluída. Em uma chamada para SQLGetData, essa cláusula pode fazer com que o driver retorne dados para a linha errada. Associar todas as colunas em uma chave exclusiva garante que cada linha seja identificada exclusivamente.

• Aloque buffers de dados grandes o suficiente para que nenhum truncamento ocorra. O cache da biblioteca de cursores é uma cópia dos valores nos buffers de conjunto de linhas associados ao conjunto de resultados com SQLBindCol. Se os dados forem truncados quando forem colocados nesses buffers, eles também serão truncados no cache. Uma cláusula WHERE construída com base em valores truncados pode não identificar corretamente a linha subjacente na fonte de dados.

• Especifique buffers de comprimento não nulo para dados C binários. A biblioteca de cursores aloca buffers de comprimento em seu cache somente se o argumento StrLen_or_IndPtr em SQLBindCol não for nulo. Quando o argumento TargetType é SQL_C_BINARY, a biblioteca de cursores requer o comprimento dos dados binários para construir uma cláusula WHERE com base nos dados. Se não houver nenhum buffer de comprimento para uma coluna SQL_C_BINARY e o aplicativo chamar SQLGetData ou tentar executar uma instrução de atualização ou exclusão posicionada, a biblioteca de cursores retornará SQL_ERROR e SQLSTATE SL014 (uma solicitação posicionada foi emitida e nem todos os campos de contagem de colunas foram armazenados em buffer).

• Especifique buffers de comprimento não nulo para colunas anuláveis. A biblioteca de cursores aloca buffers de comprimento em seu cache somente se o argumento StrLen_or_IndPtr em SQLBindCol não for nulo. Como SQL_NULL_DATA é armazenado no buffer de comprimento, a biblioteca de cursores pressupõe que qualquer coluna para a qual nenhum buffer de comprimento seja especificado não seja anulável. Se nenhuma coluna de comprimento for especificada para uma coluna anulável, a biblioteca de cursores construirá uma cláusula WHERE que usa o valor de dados para a coluna. Essa cláusula não identificará corretamente a linha.