Enviando dados longos

Os DBMSs definem dados longos como qualquer caractere ou dados binários em um determinado tamanho, como 254 caracteres. Talvez não seja possível armazenar um item inteiro de dados longos 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 para o driver em partes com SQLPutData quando a instrução é executada. Os parâmetros para os quais os dados são enviados no tempo de execução são conhecidos como parâmetros de dados em execução.

Observação

Um aplicativo pode realmente enviar qualquer tipo de dados em tempo de execução com SQLPutData, embora apenas dados binários e caracteres possam ser enviados em partes. No entanto, se os dados forem pequenos o suficiente para caber em um único buffer, geralmente não haverá motivo para usar SQLPutData. É muito mais fácil associar o buffer e permitir que o driver recupere os dados do buffer.

Para enviar dados no momento da execução, o aplicativo executa as seguintes ações:

1. Passa um valor de 32 bits que identifica o parâmetro no argumento ParameterValuePtr no SQLBindParameter em vez de passar o endereço de um buffer. Esse valor não é analisado pelo controlador. Ele será retornado ao aplicativo mais tarde, 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(comprimento) 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 longos para uma fonte de dados que precisa saber quantos bytes de dados longos serão enviados para que ele 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 do byte, o driver poderá ignorá-la.

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 SQL_NEED_DATA. Se dados longos precisarem ser enviados, SQLParamData retornará SQL_NEED_DATA. No buffer apontado pelo argumento ValuePtrPtr , o driver retorna o valor que identifica o parâmetro data-at-execution. Se houver mais de um parâmetro de dados em tempo de execução, o aplicativo deverá usar esse valor para determinar para qual parâmetro enviar dados; o driver não é obrigado a solicitar dados para parâmetros de dados em tempo de execução em qualquer ordem específica.

6. Chama SQLPutData para enviar os dados de parâmetro para o driver. Se os dados de parâmetro não se ajustarem a um único buffer, como geralmente ocorre com dados longos, o aplicativo chamará SQLPutData repetidamente para enviar os dados em partes; cabe ao driver e à fonte de dados remontar os dados. Se o aplicativo passar dados de strings terminadas com nulo, o driver ou a fonte de dados deverá remover o caractere de terminação nula como parte do processo de reassemblagem.

7. Chama SQLParamData novamente para indicar que enviou todos os dados para o parâmetro. Se houver parâmetros de dados em execução para os quais os dados não foram 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 tiverem sido enviados para 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 sejam completamente enviados para o último parâmetro de dados-durante-execução, a instrução estará em um estado de necessidade de dados. Embora uma instrução esteja em um estado Need Data, o aplicativo pode chamar apenas SQLPutData, SQLParamData, SQLCancel, SQLGetDiagField ou SQLGetDiagRec; todas as outras funções retornam SQLSTATE HY010 (erro de sequência de funções). Chamar o SQLCancel cancela a execução da instrução e a retorna ao estado anterior. Para obter mais informações, consulte 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 .