Cursores em bloco, cursores roláveis e compatibilidade com versões anteriores para aplicativos ODBC 3.x

A existência de SQLFetchScroll e SQLExtendedFetch representa a primeira divisão clara no ODBC entre a API (Application Programming Interface), que é o conjunto de funções que o aplicativo chama, e a SPI (Service Provider Interface), que é o conjunto de funções que o driver implementa. Essa divisão é necessária para equilibrar o requisito no ODBC 3.x, que usa SQLFetchScroll, para alinhar com os padrões e ser compatível com ODBC 2.x, que usa SQLExtendedFetch.

A API ODBC 3.x , que é o conjunto de funções que o aplicativo chama, inclui SQLFetchScroll e atributos de instrução relacionados. O ODBC 3.x SPI, que é o conjunto de funções que o driver implementa, inclui SQLFetchScroll, SQLExtendedFetch e atributos de instrução relacionados. Como o ODBC não impõe formalmente essa divisão entre a API e o SPI, é possível que aplicativos ODBC 3.x chamem SQLExtendedFetch e atributos de instrução relacionados. No entanto, não há razão para aplicativos ODBC 3.x para fazer isso. Para obter mais informações sobre APIs e SPIs, consulte a introdução à arquitetura ODBC.

Para obter informações sobre como o Gerenciador de Driver ODBC 3.x mapeia chamadas para drivers ODBC 2.x e ODBC 3.x e quais funções e atributos de instrução um driver ODBC 3.x deve implementar para cursores de bloco e roláveis, consulte O que o driver faz no Apêndice G: Diretrizes de driver para compatibilidade com versões anteriores.

A tabela a seguir resume quais funções e atributos de instrução um aplicativo ODBC 3.x deve usar com cursores de bloco e roláveis. Ele também lista as alterações entre ODBC 2.x e ODBC 3.x nesta área que os aplicativos ODBC 3.x devem estar cientes de serem compatíveis com drivers ODBC 2.x.

Função ou atributo de instrução	Comentários
SQL_ATTR_FETCH_BOOKMARK_PTR	Aponta para o indicador a ser usado com SQLFetchScroll. Quando um aplicativo define isso em um driver ODBC 2.x , isso deve apontar para um indicador de comprimento fixo.
SQL_ATTR_ROW_STATUS_PTR	Aponta para a matriz de status de linha preenchida por SQLFetch, SQLFetchScroll, SQLBulkOperations, e SQLSetPos. Se um aplicativo definir isso em um driver ODBC 2.x e chamar SQLBulkOperation com uma Operação de SQL_ADD antes de chamar SQLFetchScroll, SQLFetch, ou SQLExtendedFetch, SQLSTATE HY011 (atributo não pode ser definido aora) será retornado. Quando um aplicativo chama SQLFetch em um driver ODBC 2.x, SQLFetch é mapeado para SQLExtendedFetch e, portanto, retorna valores nessa matriz.
SQL_ATTR_ROWS_FETCHED_PTR	Aponta para o buffer no qual SQLFetch e SQLFetchScroll retornam o número de linhas buscadas. Quando um aplicativo chama SQLFetch em um driver ODBC 2.x, SQLFetch é mapeado para SQLExtendedFetch e, portanto, retorna um valor nesse buffer.
SQL_ATTR_ROW_ARRAY_SIZE	Define o tamanho do conjunto de linhas. Se um aplicativo chamar SQLBulkOperations com uma operação de SQL_ADD em um driver ODBC 2.x, SQL_ROWSET_SIZE será usado para a chamada, não SQL_ATTR_ROW_ARRAY_SIZE, porque a chamada é mapeada para SQLSetPos com uma operação de SQL_ADD, que usa SQL_ROWSET_SIZE. Chamar SQLSetPos com uma operação de SQL_ADD ou SQLExtendedFetch em um driver ODBC 2.x usa SQL_ROWSET_SIZE. Chamar SQLFetch ou SQLFetchScroll em um driver ODBC 2.x usa SQL_ATTR_ROW_ARRAY_SIZE.
SQLBulkOperations	Executa operações de inserção e marcador. Quando SQLBulkOperations com uma operação de SQL_ADD é chamado em um driver ODBC 2.x, ele é mapeado para SQLSetPos com uma operação de SQL_ADD. A seguir estão os detalhes da implementação: - Ao trabalhar com um driver ODBC 2.x , um aplicativo deve usar apenas a ARD implicitamente alocada associada ao StatementHandle; ele não pode alocar outro ARD para adicionar linhas, porque operações de descritor explícito não são suportadas em um driver ODBC 2.x. Um aplicativo deve usar SQLBindCol para vincular à ARD, não SQLSetDescField ou SQLSetDescRec. - Ao chamar um driver ODBC 3.x, um aplicativo pode chamar SQLBulkOperations com uma Operação de SQL_ADD antes de chamar SQLFetch ou SQLFetchScroll. Ao chamar um driver ODBC 2.x, um aplicativo deve chamar SQLFetchScroll antes de chamar SQLBulkOperations com uma operação de SQL_ADD.
SQLFetch	Retorna o conjunto de linhas. A seguir estão os detalhes da implementação: - Quando um aplicativo chama SQLFetch em um driver ODBC 2.x , ele é mapeado para SQLExtendedFetch. - Quando um aplicativo chama SQLFetch em um driver ODBC 3.x , ele retorna o número de linhas especificadas com o atributo de instrução SQL_ATTR_ROW_ARRAY_SIZE.
SQLFetchScroll	Retorna o conjunto de linhas especificado. A seguir estão os detalhes da implementação: - Quando um aplicativo chama SQLFetchScroll em um driver ODBC 2.x , ele retorna SQLSTATE 01S01 (Erro na linha) antes de cada erro que se aplica a uma única linha. Ele faz isso somente porque o Gerenciador de Driver ODBC 3.x mapeia isso para SQLExtendedFetch e SQLExtendedFetch retorna esse SQLSTATE. Quando um aplicativo chama SQLFetchScroll em um driver ODBC 3.x , ele nunca retorna SQLSTATE 01S01 (erro na linha). - Quando um aplicativo chama SQLFetchScroll em um driver ODBC 2.x com FetchOrientation definido como SQL_FETCH_BOOKMARK, o argumento FetchOffset deve ser definido como 0. SQLSTATE HYC00 (recurso opcional não implementado) é retornado se a busca de marcadores baseada em deslocamento for tentada com um driver ODBC 2.x.

Observação

Os aplicativos ODBC 3.x não devem usar SQLExtendedFetch ou o atributo de instrução SQL_ROWSET_SIZE. Em vez disso, eles devem usar SQLFetchScroll e o atributo de instrução SQL_ATTR_ROW_ARRAY_SIZE. Aplicativos ODBC 3.x não devem usar SQLSetPos com uma operação de SQL_ADD, mas devem usar SQLBulkOperations com uma operação de SQL_ADD.