Envio de dados longos

Os SGBD definem dados longos como qualquer carácter ou dado binário acima de um determinado tamanho, como 254 caracteres. Pode não ser possível armazenar um elemento inteiro de dados longos na memória, como quando o item representa um documento de texto longo ou um bitmap. Como tais dados não podem ser armazenados num único buffer, a fonte de dados envia-os para o driver em partes com SQLPutData quando a instrução é executada. Os parâmetros para os quais os dados são enviados em tempo de execução são conhecidos como parâmetros 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.

Para enviar dados durante a execução, a aplicação executa as seguintes ações:

1. Passa um valor de 32 bits que identifica o parâmetro no argumento ParameterValuePtr em SQLBindParameter em vez de passar o endereço de um buffer. Este valor não é analisado pelo condutor. Será devolvido à aplicação mais tarde, portanto, deve ter significado para a aplicação. Por exemplo, pode ser o número do parâmetro ou o handle de um ficheiro que contém dados.

2. Passa o endereço de um buffer de comprimento/indicador no argumento StrLen_or_IndPtr do SQLBindParameter.

3. Armazena SQL_DATA_AT_EXEC ou o resultado da macro SQL_LEN_DATA_AT_EXEC(comprimento) no buffer de comprimento/indicador. Ambos estes valores indicam ao driver que os dados do parâmetro serão enviados com SQLPutData. SQL_LEN_DATA_AT_EXEC(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.

4. Chama SQLExecute ou SQLExecDirect. O driver descobre que um buffer de comprimento/indicador contém o valor SQL_DATA_AT_EXEC ou o resultado da macro SQL_LEN_DATA_AT_EXEC(comprimento) e devolve SQL_NEED_DATA como valor de retorno da função.

5. 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 apontado pelo argumento ValuePtrPtr, o driver devolve o valor que identifica o parâmetro de dados em tempo de execução. Se existirem mais do que um parâmetro de dados na execução, a aplicação deve usar esse valor para determinar para que parâmetro enviar dados; O driver não é obrigado a solicitar dados para parâmetros de dados na execução em qualquer ordem específica.

6. Chama o SQLPutData para enviar os dados dos parâmetros ao driver. Se os dados dos parâmetros não caberem num único buffer, como é frequente 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.

7. Liga novamente ao SQLParamData para indicar que enviou todos os dados do parâmetro. Se existirem parâmetros de dados na execução para os quais os dados não foram enviados, o driver devolve SQL_NEED_DATA e o valor que identifica o parâmetro seguinte; A candidatura regressa ao Passo 6. Se os dados foram enviados para todos os parâmetros de dados na execução, a instrução é executada. O SQLParamData devolve SQL_SUCCESS ou SQL_SUCCESS_WITH_INFO e pode devolver qualquer valor de retorno ou diagnóstico que o SQLExecute ou SQLExecDirect possam devolver.

Depois de o SQLExecute ou SQLExecDirect devolver SQL_NEED_DATA e antes de os dados terem sido completamente enviados para o último parâmetro de dados na execução, a instrução está num estado Need Data. Enquanto uma instrução está num estado Need Data, 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.

Para um exemplo de envio de dados na altura da execução, consulte a descrição da função SQLPutData .