Enviar dados Long

Os DBMSs definem dados long como qualquer caractere ou dado binário acima de um tamanho específico, como 254 caracteres. Talvez não seja possível armazenar um item inteiro de dados long na memória, como quando o item representa um documento de texto longo ou um bitmap. Como esses dados não podem ser armazenados em um único buffer, a fonte de dados os envia ao 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 em execução.

Observação

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

Para enviar dados em tempo de execução, o aplicativo realiza 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. Esse valor não é analisado pelo driver. Ele será retornado ao aplicativo posteriormente; portanto, deve significar algo para o aplicativo. Por exemplo, pode ser o número do parâmetro ou o identificador de um arquivo que contém dados.

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

3. Armazena SQL_DATA_AT_EXEC ou o resultado da macro SQL_LEN_DATA_AT_EXEC(length) no buffer de comprimento/indicador. Ambos os valores indicam ao driver que os dados do parâmetro serão enviados com SQLPutData. SQL_LEN_DATA_AT_EXEC(length) é usado ao enviar dados long a uma fonte de dados que precisa saber quantos bytes de dados longos serão enviados para que possa pré-alocar espaço. Para determinar se uma fonte de dados requer esse valor, o aplicativo chama SQLGetInfo com a opção SQL_NEED_LONG_DATA_LEN. Todos os drivers devem dar suporte a essa macro; se a fonte de dados não exigir o comprimento de bytes, o driver poderá 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(length) e retorna SQL_NEED_DATA como o valor retornado da função.

5. Chama SQLParamData em resposta ao valor retornado de SQL_NEED_DATA. Se dados long precisarem ser enviados, SQLParamData retornará SQL_NEED_DATA. No buffer apontado pelo argumento ValuePtrPtr, o driver retorna o valor que identifica o parâmetro de dados em execução. Se houver mais de um parâmetro de dados em execução, o aplicativo deverá usar esse valor para determinar a qual parâmetro enviar dados; o driver não precisa solicitar dados para parâmetros de dados em execução em nenhuma ordem específica.

6. Chama SQLPutData para enviar os dados do parâmetro ao driver. Se os dados do parâmetro não couberem em um único buffer, como costuma ocorrer com dados long, o aplicativo chamará SQLPutData repetidamente para enviar os dados em partes; cabe ao driver e à fonte de dados remontar os dados. Se o aplicativo transmitir dados de cadeia de caracteres com terminação nula, o driver ou a fonte de dados deverá remover o caractere de terminação nula como parte do processo de remontagem.

7. Chama SQLParamData novamente para indicar que enviou todos os dados ao parâmetro. Se houver algum parâmetro de dados em execução ao qual os dados não tenham sido enviados, o driver retornará SQL_NEED_DATA e o valor que identifica o próximo parâmetro; o aplicativo retorna à etapa 6. Se os dados foram enviados a todos os parâmetros de dados em execução, a instrução será executada. SQLParamData retorna SQL_SUCCESS ou SQL_SUCCESS_WITH_INFO e pode retornar qualquer valor retornado ou diagnóstico que SQLExecute ou SQLExecDirect possa retornar.

Depois que SQLExecute ou SQLExecDirect retornar SQL_NEED_DATA e antes que os dados tenham sido completamente enviados ao último parâmetro de dados em execução, a instrução estará em um estado Requer Dados. Enquanto uma instrução estiver no estado Requer Dados, o aplicativo poderá chamar apenas SQLPutData, SQLParamData, SQLCancel, SQLGetDiagField ou SQLGetDiagRec; todas as outras funções retornam SQLSTATE HY010 (Erro de sequência de função). Chamar SQLCancel cancela a execução da instrução e a retorna ao estado anterior. Para obter mais informações, consulte o Apêndice B: tabelas de transição de estado ODBC.

Para obter um exemplo de envio de dados em tempo de execução, consulte a descrição da função SQLPutData.