TN042: recomendações do desenvolvedor de driver ODBC

Observação

A nota técnica a seguir não foi atualizada desde que foi incluída pela primeira vez na documentação online. Como resultado, alguns procedimentos e tópicos podem estar desatualizados ou incorretos. Para obter as informações mais recentes, é recomendável que você pesquise o tópico de interesse no índice de documentação online.

Esta observação descreve as diretrizes para os gravadores de driver ODBC. Descreve requisitos gerais e suposições da funcionalidade ODBC que as classes do Banco de Dados MFC fazem e vários detalhes semânticos esperados. Descreve a funcionalidade de driver necessária para dar suporte aos três modos de abertura de CRecordset, (forwardOnly, instantâneo e dynaset).

Biblioteca de Cursores do ODBC

As classes de banco de dados MFC apresentam funcionalidade ao usuário que, em muitos casos, supera a funcionalidade fornecida pela maioria dos drivers ODBC de nível 1. Felizmente, a Biblioteca de Cursores do ODBC irá se sobrepor entre as classes de banco de dados e o driver, e fornecerá muitas dessas funcionalidades adicionais automaticamente.

Por exemplo, a maioria dos drivers 1.0 não oferece suporte à rolagem para trás. A Biblioteca de Cursores pode detectar isso e armazenará em cache linhas do driver e as apresentará conforme solicitado em chamadas de FETCH_PREV em SQLExtendedFetch.

Outro exemplo importante de dependência da biblioteca de cursores são as atualizações posicionadas. A maioria dos drivers 1.0 também não tem atualizações posicionadas, mas a biblioteca de cursores gera instruções de atualização que identificarão uma linha de destino na fonte de dados com base nos valores de dados atuais armazenados em cache ou em um valor de carimbo de data/hora armazenado em cache.

A biblioteca de classes nunca usa vários conjuntos de linhas. Portanto, as poucas instruções SQLSetPos são sempre aplicadas à linha 1 do conjunto de linhas.

CDatabases

Cada CDatabase aloca um único HDBC. (Se a função ExecuteSQL de CDatabase for usada, um HSTMT será alocado temporariamente). Portanto, se vários CDatabases forem necessários, vários HDBCs por HENV deve ser suportado.

As classes de banco de dados exigem a biblioteca de cursor. Isso é refletido em uma chamada de SQLSetConnections a SQL_ODBC_CURSORS, SQL_CUR_USE_ODBC.

SQLDriverConnect, SQL_DRIVER_COMPLETE é usado por CDatabase::Open para estabelecer a conexão com a fonte de dados.

O driver deve dar suporte a SQLGetInfo SQL_ODBC_API_CONFORMANCE>= SQL_OAC_LEVEL1, SQLGetInfo SQL_ODBC_SQL_CONFORMANCE>= SQL_OSC_MINIMUM.

Para que as transações tenham suporte para os CDatabase e seus conjuntos de registros dependentes, SQLGetInfo SQL_CURSOR_COMMIT_BEHAVIOR e SQL_CURSOR_ROLLBACK_BEHAVIOR devem ter SQL_CR_PRESERVE. Caso contrário, as tentativas de executar o controle de transação serão ignoradas.

SQLGetInfo SQL_DATA_SOURCE_READ_ONLY deve ser compatível. Se retornar "Y", nenhuma operação de atualização será executada na fonte de dados.

Se CDatabase for aberto como ReadOnly, uma tentativa de definir a fonte de dados lida somente será feita com SQLSetConnectOption SQL_ACCESS_MODE, SQL_MODE_READ_ONLY.

Se os identificadores exigirem aspas, essas informações deverão ser retornadas do driver com uma chamada a SQLGetInfo SQL_IDENTIFIER_QUOTE_CHAR.

Para fins de depuração, SQLGetInfo SQL_DBMS_VER e SQL_DBMS_NAME são recuperados do driver.

SQLSetStmtOption SQL_QUERY_TIMEOUT e SQL_ASYNC_ENABLE podem ser chamados em um CDatabase com HDBC's.

SQLError pode ser chamado com qualquer ou todos os argumentos NULL.

Obviamente, SQLAllocEnv SQLAllocConnect SQLDisconnect e SQLFreeConnect devem ter suporte.

ExecuteSQL

Além de alocar e liberar um HSTMT temporário, ExecuteSQL chama SQLExecDirect, SQLFetch, SQLNumResultCol e SQLMoreResults. SQLCancel pode ser chamado no HSTMT.

GetDatabaseName

SQLGetInfo SQL_DATABASE_NAME será chamado.

BeginTrans, CommitTrans, Rollback

SQLSetConnectOption SQL_AUTOCOMMIT e SQLTransact SQL_COMMIT, SQL_ROLLBACK e SQL_AUTOCOMMIT serão chamados se forem feitas solicitações de transação.

CRecordsets

Deve haver suporte para SQLAllocStmt, SQLPrepare, SQLExecute (para Open e Requery), SQLExecDirect (para operações de atualização), SQLFreeStmt. SQLNumResultCols e SQLDescribeCol serão chamados sobre o conjunto de resultados em vários momentos.

SQLSetParam é usado extensivamente para associar dados de parâmetro e funcionalidade de DATA_AT_EXEC.

SQLBindCol é usado extensivamente para registrar locais de armazenamento de dados de coluna de saída com ODBC.

Duas chamadas para SQLGetData são usadas para recuperar dados de SQL_LONG_VARCHAR e SQL_LONG_VARBINARY. A primeira chamada tenta encontrar o comprimento total do valor da coluna chamando SQLGetData com cbMaxValue de 0, mas com um pcbValue válido. Se pcbValue tiver SQL_NO_TOTAL, uma exceção será lançada. Caso contrário, um HGLOBAL será alocado e será feita outra chamada a SQLGetData para recuperar todo o resultado.

Atualizar

Se for solicitado bloqueio pessimista, SQLGetInfo SQL_LOCK_TYPES será consultado. Se SQL_LCK_EXCLUSIVE não tiver suporte, uma exceção será lançada.

As tentativas de atualizar um CRecordset (instantâneo ou dynaset) farão com que um segundo HSTMT seja alocado. Para drivers que não dão suporte ao segundo HSTMT, a biblioteca de cursores simulará essa funcionalidade. Infelizmente, isso às vezes pode significar forçar que a consulta atual no primeiro HSTMT seja concluída antes de processar a solicitação do segundo HSTMT.

SQLFreeStmt SQL_CLOSE, SQL_RESET_PARAMS e SQLGetCursorName serão chamados durante as operações de atualização.

Se houver CLongBinarys no outputColumns, a funcionalidade de DATA_AT_EXEC do ODBC deverá ter suporte. Isso inclui o retorno de SQL_NEED_DATA de SQLExecDirect, SQLParamData e SQLPutData.

SQLRowCount é chamado após a execução para verificar se apenas 1 registro foi atualizado pelo SQLExecDirect.

Cursores ForwardOnly

Somente SQLFetch é necessário para as operações Move. Observe que os cursores forwardOnly não dão suporte a atualizações.

Cursores de instantâneo

A funcionalidade de instantâneo requer suporte de SQLExtendedFetch. Conforme observado acima, a biblioteca de cursores ODBC detectará quando um driver não oferece suporte a SQLExtendedFetch e fornecerá o suporte necessário por si.

SQLGetInfo, SQL_SCROLL_OPTIONS deve dar suporte a SQL_SO_STATIC.

Cursores de Dynaset

Abaixo está o suporte mínimo necessário para abrir um dynaset:

SQLGetInfo, SQL_ODBC_VER devem retornar "01" de >.

SQLGetInfo, SQL_SCROLL_OPTIONS devem dar suporte a SQL_SO_KEYSET_DRIVEN.

SQLGetInfo, SQL_ROW_UPDATES devem retornar "Y".

SQLGetInfo, SQL_POSITIONED_UPDATES devem dar suporte a SQL_PS_POSITIONED_DELETE e SQL_PS_POSITIONED_UPDATE.

Além disso, se for solicitado bloqueio pessimista, será feita uma chamada para SQLSetPos com irow 1, fRefresh FALSE e fLock SQL_LCK_EXCLUSIVE.

Confira também

Observações técnicas por número
Observações técnicas por categoria