Dados longos e SQLSetPos e SQLBulkOperations

Tal como acontece com parâmetros em instruções SQL, dados longos podem ser enviados ao atualizar linhas com SQLBulkOperations ou SQLSetPos ou ao inserir linhas com SQLBulkOperations. Os dados são enviados em partes, com múltiplas chamadas para SQLPutData. As colunas para as quais os dados são enviados em tempo de execução são conhecidas como colunas de dados na execução.

Observação

Uma aplicação pode, na verdade, enviar qualquer tipo de dados em tempo de execução com SQLPutData, embora apenas dados de caracteres e binários possam ser enviados em partes. No entanto, se os dados forem suficientemente pequenos para caber num único buffer, geralmente não há razão para usar SQLPutData. É muito mais fácil vincular o buffer e deixar o driver recuperar os dados do buffer.

Como as colunas de dados longas normalmente não estão ligadas, a aplicação deve associar a coluna antes de chamar SQLBulkOperations ou SQLSetPos e desvinculá-la após chamar SQLBulkOperations ou SQLSetPos. A coluna deve ser limitada porque SQLBulkOperations ou SQLSetPos opera apenas em colunas limitadas e deve ser desvinculada para que SQLGetData possa ser usado para recuperar dados da coluna.

Para enviar dados no momento de execução, a aplicação faz o seguinte:

1. Coloca um valor de 32 bits no buffer de linhas em vez de um valor de dados. Este valor será devolvido à aplicação mais tarde, pelo que a aplicação deve defini-lo para um valor significativo, como o número da coluna ou o handle de um ficheiro contendo dados.

2. Define o valor no buffer de comprimento/indicador como o resultado da macro SQL_LEN_DATA_AT_EXEC(comprimento). Este valor indica ao condutor que os dados do parâmetro serão enviados com SQLPutData. O valor de comprimento é usado ao enviar dados longos para uma fonte de dados que precisa de saber quantos bytes de dados longos serão enviados para poder pré-alocar espaço. Para determinar se uma fonte de dados requer este valor, a aplicação chama SQLGetInfo com a opção SQL_NEED_LONG_DATA_LEN. Todos os drivers devem suportar este macro; Se a fonte de dados não exigir o comprimento do byte, o driver pode ignorá-lo.

3. Chamadas SQLBulkOperations ou SQLSetPos. O driver descobre que um buffer de comprimento/indicador contém o resultado da macro SQL_LEN_DATA_AT_EXEC(comprimento) e devolve SQL_NEED_DATA como valor de retorno da função.

4. Chama SQLParamData em resposta ao valor de retorno SQL_NEED_DATA. Se for necessário enviar dados longos, o SQLParamData devolve SQL_NEED_DATA. No buffer indicado pelo argumento ValuePtrPtr, o driver retorna o valor único que a aplicação inseriu no buffer do conjunto de linhas. Se existirem mais do que uma coluna de dados na execução, a aplicação usa este valor para determinar para que coluna enviar dados; O driver não é obrigado a solicitar dados para colunas de dados na execução em qualquer ordem específica.

5. Chama SQLPutData para enviar os dados da coluna para o driver. Se os dados da coluna não caberem num único buffer, como acontece frequentemente com dados longos, a aplicação chama SQLPutData repetidamente para enviar os dados em partes; cabe ao driver e à fonte de dados reconstituir os dados. Se a aplicação passar dados de cadeia terminada por nulo, o driver ou fonte de dados deve remover o carácter de terminação nula como parte do processo de reassemblagem.

6. Chama novamente SQLParamData para indicar que enviou todos os dados da coluna. Se existirem colunas de dados na execução para as quais os dados não foram enviados, o driver devolve SQL_NEED_DATA e o valor único para a próxima coluna de dados na execução; A candidatura regressa ao Passo 5. Se os dados tiverem sido enviados para todas as colunas de dados durante a execução, os dados da linha são enviados para a origem de dados. O SQLParamData devolve então SQL_SUCCESS ou SQL_SUCCESS_WITH_INFO e pode devolver qualquer estado SQLSTATE que o SQLBulkOperations ou SQLSetPos possam devolver.

Depois de SQLBulkOperations ou SQLSetPos devolver SQL_NEED_DATA e antes de os dados terem sido completamente enviados para a última coluna de dados a ser executada, a instrução está num estado de Necessidade de Dados. Neste estado, a aplicação pode chamar apenas SQLPutData, SQLParamData, SQLCancel, SQLGetDiagField ou SQLGetDiagRec; todas as outras funções devolvem SQLSTATE HY010 (erro de sequência de funções). Chamar o SQLCancel cancela a execução da instrução e devolve-a ao seu estado anterior. Para mais informações, consulte o Apêndice B: Tabelas de Transição de Estado ODBC.