Função SQLParamData
Compatibilidade
Versão introduzida: ODBC 1.0 Conformidade com os padrões: ISO 92
Resumo
SQLParamData é usado junto com SQLPutData para fornecer dados de parâmetro no momento da execução da instrução e com SQLGetData para recuperar dados de parâmetro de saída transmitidos.
Sintaxe
SQLRETURN SQLParamData(
SQLHSTMT StatementHandle,
SQLPOINTER * ValuePtrPtr);
Argumentos
Identificador de declaração
[Entrada] Identificador de instrução.
ValorPtrPtr
[Saída] Ponteiro para um buffer no qual retornar o endereço do buffer ParameterValuePtr especificado em SQLBindParameter (para dados de parâmetro) ou o endereço do buffer TargetValuePtr especificado em SQLBindCol (para dados de coluna), conforme contido no campo de registro do descritor SQL_DESC_DATA_PTR.
Devoluções
SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_NEED_DATA, SQL_NO_DATA, SQL_STILL_EXECUTING, SQL_ERROR, SQL_INVALID_HANDLE ou SQL_PARAM_DATA_AVAILABLE.
Diagnósticos
Quando SQLParamData retorna SQL_ERROR ou SQL_SUCCESS_WITH_INFO, um valor SQLSTATE associado pode ser obtido chamando SQLGetDiagRec com um HandleType de SQL_HANDLE_STMT e um Handle de StatementHandle. A tabela a seguir lista os valores SQLSTATE normalmente retornados por SQLParamData e explica cada um deles no contexto dessa função; a notação "(DM)" precede as descrições de SQLSTATEs retornadas pelo Gerenciador de Driver. O código de retorno associado a cada valor SQLSTATE é SQL_ERROR, a menos que indicado de outra forma.
| SQLSTATE | Erro | Descrição |
|---|---|---|
| 01000 | Aviso geral | Mensagem informativa específica do driver. (A função retorna SQL_SUCCESS_WITH_INFO.) |
| 07006 | Violação de atributo de tipo de dados restrito | O valor de dados identificado pelo argumento ValueType em SQLBindParameter para o parâmetro associado não pôde ser convertido no tipo de dados identificado pelo argumento ParameterType em SQLBindParameter. O valor de dados retornado para um parâmetro associado como SQL_PARAM_INPUT_OUTPUT ou SQL_PARAM_OUTPUT não pôde ser convertido no tipo de dados identificado pelo argumento ValueType em SQLBindParameter. (Se os valores de dados de uma ou mais linhas não puderem ser convertidos, mas uma ou mais linhas tiverem sido retornadas com êxito, essa função retornará SQL_SUCCESS_WITH_INFO.) |
| 08S01 | Falha no link de comunicação | O link de comunicação entre o driver e a fonte de dados à qual o driver estava conectado falhou antes que a função concluísse o processamento. |
| 22026 | Incompatibilidade de comprimento de dados String | O tipo de informação SQL_NEED_LONG_DATA_LEN em SQLGetInfo era "Y" e menos dados foram enviados para um parâmetro longo (o tipo de dados era SQL_LONGVARCHAR, SQL_LONGVARBINARY ou um tipo de dados específico da fonte de dados longa) do que o especificado com o argumento StrLen_or_IndPtr em SQLBindParameter. O tipo de informação SQL_NEED_LONG_DATA_LEN em SQLGetInfo era "Y" e menos dados foram enviados para uma coluna longa (o tipo de dados era SQL_LONGVARCHAR, SQL_LONGVARBINARY ou um tipo de dados específico da fonte de dados longa) do que o especificado no buffer de comprimento correspondente a uma coluna em uma linha de dados que foi adicionada ou atualizada com SQLBulkOperations ou atualizada com SQLSetPos. |
| 40001 | Falha de serialização | A transação foi revertida devido a um deadlock de recursos com outra transação. |
| 40003 | Conclusão da instrução desconhecida | A conexão associada falhou durante a execução dessa função e o estado da transação não pode ser determinado. |
| HY000 | Erro geral | Ocorreu um erro para o qual não havia SQLSTATE específico e para o qual nenhum SQLSTATE específico da implementação foi definido. A mensagem de erro retornada por SQLGetDiagRec no buffer *MessageText descreve o erro e sua causa. |
| HY001 | Erro de alocação de memória | O driver não pôde alocar a memória necessária para dar suporte à execução ou conclusão da função. |
| HY008 | Operação cancelada | O processamento assíncrono foi habilitado para o StatementHandle. A função foi chamada e, antes de concluir a execução, SQLCancel ou SQLCancelHandle foi chamado no StatementHandle; a função foi chamada novamente no StatementHandle. A função foi chamada e, antes de concluir a execução, SQLCancel ou SQLCancelHandle foi chamado no StatementHandle de um thread diferente em um aplicativo multithread. |
| HY010 | Erro de sequência de função | (DM) A chamada de função anterior não era uma chamada para SQLExecDirect, SQLExecute, SQLBulkOperations ou SQLSetPos em que o código de retorno era SQL_NEED_DATA, ou a chamada de função anterior era uma chamada para SQLPutData. A chamada de função anterior era uma chamada para SQLParamData. (DM) Uma função de execução assíncrona foi chamada para o identificador de conexão associado ao StatementHandle. Essa função assíncrona ainda estava em execução quando a função SQLParamData foi chamada. (DM) Uma função de execução assíncrona (não esta) foi chamada para o StatementHandle e ainda estava em execução quando essa função foi chamada. SQLExecute, SQLExecDirect, SQLBulkOperations ou SQLSetPos foi chamado para o StatementHandle e retornado SQL_NEED_DATA. SQLCancel foi chamado antes que os dados fossem enviados para todos os parâmetros ou colunas de dados em execução. |
| HY013 | Erro de gerenciamento de memória | A chamada de função não pôde ser processada porque os objetos de memória subjacentes não puderam ser acessados, possivelmente devido a condições de memória baixa. |
| HY117 | A conexão está suspensa devido ao estado desconhecido da transação. Somente funções de desconexão e somente leitura são permitidas. | (DM) Para obter mais informações sobre o estado suspenso, consulte Função SQLEndTran. |
| HYT01 | O tempo limite da conexão expirou | O período de tempo limite da conexão expirou antes que a fonte de dados respondesse à solicitação. O período de tempo limite da conexão é definido por meio de SQLSetConnectAttr, SQL_ATTR_CONNECTION_TIMEOUT. |
| IM001 | O driver não suporta esta função | (DM) O driver que corresponde ao StatementHandle não dá suporte à função. |
| IM017 | A sondagem está desabilitada no modo de notificação assíncrona | Sempre que o modelo de notificação é usado, a sondagem é desabilitada. |
| IM018 | SQLCompleteAsync não foi chamado para concluir a operação assíncrona anterior nesse identificador. | Se a chamada de função anterior no identificador retornar SQL_STILL_EXECUTING e se o modo de notificação estiver habilitado, SQLCompleteAsync deverá ser chamado no identificador para fazer o pós-processamento e concluir a operação. |
Se SQLParamData for chamado durante o envio de dados para um parâmetro em uma instrução SQL, ele poderá retornar qualquer SQLSTATE que possa ser retornado pela função chamada para executar a instrução (SQLExecute ou SQLExecDirect). Se ele for chamado durante o envio de dados para uma coluna que está sendo atualizada ou adicionada com SQLBulkOperations ou sendo atualizada com SQLSetPos, ele poderá retornar qualquer SQLSTATE que possa ser retornado por SQLBulkOperations ou SQLSetPos.
Comentários
SQLParamData pode ser chamado para fornecer dados em execução para dois usos: dados de parâmetro que serão usados em uma chamada para SQLExecute ou SQLExecDirect, ou dados de coluna que serão usados quando uma linha for atualizada ou adicionada por uma chamada para SQLBulkOperations ou atualizada por uma chamada para SQLSetPos. No tempo de execução, SQLParamData retorna ao aplicativo um indicador de quais dados o driver exige.
Quando um aplicativo chama SQLExecute, SQLExecDirect, SQLBulkOperations ou SQLSetPos, o driver retorna SQL_NEED_DATA se precisar de dados em execução. Em seguida, um aplicativo chama SQLParamData para determinar quais dados enviar. Se o driver exigir dados de parâmetro, o driver retornará no buffer de saída *ValuePtrPtr o valor que o aplicativo colocou no buffer do conjunto de linhas. O aplicativo pode usar esse valor para determinar quais dados de parâmetro o driver está solicitando. Se o driver exigir dados de coluna, o driver retornará no buffer *ValuePtrPtr o endereço ao qual a coluna foi originalmente associada, da seguinte maneira:
Deslocamento de vinculação de endereço + vinculado + ((Número da linha - 1) x Tamanho do elemento)
onde as variáveis são definidas conforme indicado na tabela a seguir.
| Variável | Descrição |
|---|---|
| Endereço de Ligação | O endereço especificado com o argumento TargetValuePtr em SQLBindCol. |
| Deslocamento de encadernação | O valor armazenado no endereço especificado com o atributo de instrução SQL_ATTR_ROW_BIND_OFFSET_PTR. |
| Row Number | O número baseado em 1 da linha no conjunto de linhas. Para buscas de linha única, que são o padrão, é 1. |
| Tamanho do elemento | O valor do atributo de instrução SQL_ATTR_ROW_BIND_TYPE para buffers de dados e comprimento/indicador. |
Ele também retorna SQL_NEED_DATA, que é um indicador para o aplicativo de que ele deve chamar SQLPutData para enviar os dados.
O aplicativo chama SQLPutData quantas vezes forem necessárias para enviar os dados de dados em execução para a coluna ou parâmetro. Depois que todos os dados tiverem sido enviados para a coluna ou parâmetro, o aplicativo chamará SQLParamData novamente. Se SQLParamData retornar novamente SQL_NEED_DATA, os dados deverão ser enviados para outro parâmetro ou coluna. Portanto, o aplicativo chama novamente SQLPutData. Se todos os dados de dados em execução tiverem sido enviados para todos os parâmetros ou colunas, SQLParamData retornará SQL_SUCCESS ou SQL_SUCCESS_WITH_INFO, o valor em *ValuePtrPtr será indefinido e a instrução SQL poderá ser executada ou a chamada SQLBulkOperations ou SQLSetPos poderá ser processada.
Se SQLParamData fornecer dados de parâmetro para uma instrução de atualização ou exclusão pesquisada que não afete nenhuma linha na fonte de dados, a chamada para SQLParamData retornará SQL_NO_DATA.
Para obter mais informações sobre como os dados de parâmetro de dados em execução são passados no tempo de execução da instrução, consulte "Passando valores de parâmetro" em SQLBindParameter e enviando dados longos. Para obter mais informações sobre como os dados da coluna de dados em execução são atualizados ou adicionados, consulte a seção "Usando SQLSetPos" em SQLSetPos, "Executando atualizações em massa usando indicadores" em SQLBulkOperations e Dados longos e SQLSetPos e SQLBulkOperations.
SQLParamData pode ser chamado para recuperar parâmetros de saída transmitidos. Quando SQLMoreResults, SQLExecute, SQLGetData ou SQLExecDirect retornar SQL_PARAM_DATA_AVAILABLE, chame SQLParamData para determinar qual parâmetro tem um valor disponível. Para obter mais informações sobre parâmetros de saída SQL_PARAM_DATA_AVAILABLE e transmitidos, consulte Recuperando parâmetros de saída usando SQLGetData.
Exemplo de código
Consulte SQLPutData.
Funções relacionadas
| Para obter informações sobre | Consulte |
|---|---|
| Associando um buffer a um parâmetro | Função SQLBindParameter |
| Cancelando o processamento de instruções | Função SQLCancel |
| Retornando informações sobre um parâmetro em uma instrução | Função SQLDescribeParam |
| Executando uma instrução SQL | Função SQLExecDirect |
| Executando uma instrução SQL preparada | Função SQLExecute |
| Enviando dados de parâmetro em tempo de execução | Função SQLPutData |
Confira também
Referência de API do ODBC
Arquivos de cabeçalho ODBC
Recuperando parâmetros de saída usando SQLGetData