Nota
O acesso a esta página requer autorização. Pode tentar iniciar sessão ou alterar os diretórios.
O acesso a esta página requer autorização. Pode tentar alterar os diretórios.
Conformidade
Versão Introduzida: Normas ODBC 1.0 Conformidade: ISO 92
Summary
O SQLParamData é usado em conjunto com o SQLPutData para fornecer dados de parâmetros no momento da execução da instrução, e com o SQLGetData para recuperar dados de parâmetros de saída transmitidos.
Syntax
SQLRETURN SQLParamData(
SQLHSTMT StatementHandle,
SQLPOINTER * ValuePtrPtr);
Arguments
HandleStatement
[Entrada] Identificador do extrato.
ValuePtrPtr
[Saída] Apontador para um buffer no qual devolver o endereço do buffer ParameterValuePtr especificado em SQLBindParameter (para dados de parâmetros) ou o endereço do buffer TargetValuePtr especificado em SQLBindCol (para dados de coluna), conforme contido no campo de registo de SQL_DESC_DATA_PTR descritor.
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 o SQLParamData devolve 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 seguinte lista os valores SQLSTATE normalmente devolvidos pelo SQLParamData e explica cada um no contexto desta função; a notação "(DM)" precede as descrições dos SQLSTATEs devolvidas pelo Gestor de Drivers. O código de retorno associado a cada valor SQLSTATE é SQL_ERROR, salvo indicação em contrário.
| SQLSTATE | Erro | Description |
|---|---|---|
| 01000 | Aviso geral | Mensagem informativa específica para o condutor. (Função devolve SQL_SUCCESS_WITH_INFO.) |
| 07006 | Violação de atributo de tipo de dado restrito | O valor de dados identificado pelo argumento ValueType em SQLBindParameter para o parâmetro limitado não pôde ser convertido para o tipo de dado identificado pelo argumento ParameterType em SQLBindParameter. O valor de dados devolvido para um parâmetro limitado como SQL_PARAM_INPUT_OUTPUT ou SQL_PARAM_OUTPUT não podia ser convertido para o tipo de dado identificado pelo argumento ValueType no SQLBindParameter. (Se os valores de dados de uma ou mais linhas não pudessem ser convertidos, mas uma ou mais linhas fossem devolvidas com sucesso, esta função devolve SQL_SUCCESS_WITH_INFO.) |
| 08S01 | Falha da ligação de comunicação | A ligação de comunicação entre o driver e a fonte de dados à qual o driver estava ligado falhou antes de a função concluir o processamento. |
| 22026 | Dados de cadeia de caracteres, incompatibilidade de comprimento | O SQL_NEED_LONG_DATA_LEN tipo de informação no SQLGetInfo era "Y", e menos dados eram enviados para um parâmetro longo (o tipo de dados era SQL_LONGVARCHAR, SQL_LONGVARBINARY ou um tipo longo específico de fonte de dados) do que era especificado com o argumento StrLen_or_IndPtr no SQLBindParameter. O SQL_NEED_LONG_DATA_LEN tipo de informação no SQLGetInfo era "Y", e menos dados eram enviados para uma coluna longa (o tipo de dados era SQL_LONGVARCHAR, SQL_LONGVARBINARY ou um tipo de dado longo específico da fonte de dados) do que era especificado no buffer de comprimento correspondente a uma coluna numa linha de dados adicionada ou atualizada com SQLBulkOperations ou atualizada com SQLSetPos. |
| 40001 | Falha de serialização | A transação foi revertida devido a um bloqueio de recursos com outra transação. |
| 40003 | Conclusão da afirmação desconhecida | A ligação associada falhou durante a execução desta função, e o estado da transação não pode ser determinado. |
| HY000 | Erro geral | Ocorreu um erro para o qual não existia um SQLSTATE específico e para o qual não estava definido nenhum SQLSTATE específico da implementação. A mensagem de erro devolvida pelo SQLGetDiagRec no buffer *MessageText descreve o erro e a sua causa. |
| HY001 | Erro de alocação de memória | O controlador não conseguiu alocar a memória necessária para suportar a execução ou conclusão da função. |
| HY008 | Operação cancelada | O processamento assíncrono foi ativado para o StatementHandle. A função era chamada e, antes de terminar a execução, o SQLCancel ou SQLCancelHandle era chamado no StatementHandle; a função era então chamada novamente no StatementHandle. A função era chamada e, antes de terminar a execução, o SQLCancel ou SQLCancelHandle era chamado no StatementHandle a partir de um thread diferente numa aplicação multithread. |
| HY010 | Erro de sequência de funções | (DM) A chamada de função anterior não era uma chamada para SQLExecDirect, SQLExecute, SQLBulkOperations ou SQLSetPos onde o código de retorno era SQL_NEED_DATA, nem 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 era chamada para o handle de ligação associado ao StatementHandle. Esta função assíncrona ainda estava a ser executada quando a função SQLParamData foi chamada. (DM) Uma função de execução assíncrona (não esta) era chamada para o StatementHandle e continuava a ser executada quando esta função era chamada. SQLExecute, SQLExecDirect, SQLBulkOperations ou SQLSetPos eram chamados para o StatementHandle e retornavam SQL_NEED_DATA. O SQLCancel era chamado antes de os dados serem enviados para todos os parâmetros ou colunas de dados na execução. |
| HY013 | Erro de gestão de memória | A chamada de função não podia ser processada porque os objetos de memória subjacentes não podiam ser acedidos, possivelmente devido a condições de baixa memória. |
| HY117 | A ligação é suspensa devido ao estado desconhecido da transação. Apenas funções de desconexão e de leitura são permitidas. | (DM) Para mais informações sobre o estado suspenso, veja Função SQLEndTran. |
| HYT01 | Expirou o tempo limite de ligação | O período de timeout da ligação expirou antes de a fonte de dados responder ao pedido. O período de tempo de expiração da ligação é definido através do SQLSetConnectAttr, SQL_ATTR_CONNECTION_TIMEOUT. |
| IM001 | O driver não suporta esta função | (DM) O driver que corresponde ao StatementHandle não suporta a função. |
| IM017 | A sondagem está desativada no modo de notificação assíncrona | Sempre que o modelo de notificação é utilizado, o sonding é desativado. |
| IM018 | O SQLCompleteAsync não foi chamado para completar a operação assíncrona anterior neste handle. | Se a chamada de função anterior no handle devolver SQL_STILL_EXECUTING e se o modo de notificação estiver ativado, o SQLCompleteAsync deve ser chamado no handle para fazer o pós-processamento e completar a operação. |
Se o SQLParamData for chamado ao enviar dados para um parâmetro numa instrução SQL, pode devolver qualquer estado SQLSTATE que possa ser devolvido pela função chamada para executar a instrução (SQLExecute ou SQLExecDirect). Se for chamada enquanto envia dados para uma coluna que está a ser atualizada ou adicionada com SQLBulkOperations ou atualizada com SQLSetPos, pode devolver qualquer estado SQLSTATE que possa ser devolvido por SQLBulkOperations ou SQLSetPos.
Comments
O SQLParamData pode ser chamado para fornecer dados de execução para dois usos: dados de parâmetros que serão usados numa chamada para SQLExecute ou SQLExecDirect, ou dados de coluna que serão usados quando uma linha é atualizada ou adicionada por uma chamada para SQLBulkOperations ou atualizada por uma chamada para SQLSetPos. No momento da execução, o SQLParamData devolve à aplicação um indicador dos dados que o driver necessita.
Quando uma aplicação chama SQLExecute, SQLExecDirect, SQLBulkOperations ou SQLSetPos, o driver devolve SQL_NEED_DATA se precisar de dados na execução. Uma aplicação chama então SQLParamData para determinar quais os dados a enviar. Se o driver requer dados de parâmetros, devolve no *ValuePtrPtr output buffer o valor que a aplicação colocou no rowset buffer. A aplicação pode usar este valor para determinar que dados de parâmetros o driver está a solicitar. Se o driver necessitar de dados de coluna, devolve no *ValuePtrPtr buffer o endereço ao qual a coluna estava originalmente associada, da seguinte forma:
Endereço + VinculadoDeslocamento de ligação + ((Número da Linha - 1) x Tamanho do Elemento)
onde as variáveis são definidas conforme indicado na tabela seguinte.
| Variable | Description |
|---|---|
| Endereço Vinculado | O endereço especificado com o argumento TargetValuePtr no SQLBindCol. |
| Deslocamento de encadernação | O valor armazenado no endereço especificado com o atributo da instrução SQL_ATTR_ROW_BIND_OFFSET_PTR. |
| Número da Fila | O número baseado em 1 da linha no conjunto de linhas. Para buscas de linha única, que são o padrão, isto é 1. |
| Tamanho dos elementos | O valor do atributo da instrução SQL_ATTR_ROW_BIND_TYPE tanto para dados como para buffers de comprimento/indicador. |
Também devolve SQL_NEED_DATA, que é um indicador para a aplicação de que deve chamar SQLPutData para enviar os dados.
A aplicação chama SQLPutData tantas vezes quanto necessário para enviar os dados na execução da coluna ou parâmetro. Depois de todos os dados terem sido enviados para a coluna ou parâmetro, a aplicação chama novamente SQLParamData . Se o SQLParamData voltar a devolver SQL_NEED_DATA, os dados devem ser enviados para outro parâmetro ou coluna. Assim, a aplicação volta a chamar SQLPutData. Se todos os dados na execução foram enviados para todos os parâmetros ou colunas, então o SQLParamData devolve SQL_SUCCESS ou SQL_SUCCESS_WITH_INFO, o valor em *ValuePtrPtr é indefinido, e a instrução SQL pode ser executada ou a chamada SQLBulkOperations ou SQLSetPos pode ser processada.
Se o SQLParamData fornece dados de parâmetros para uma instrução de atualização ou eliminação pesquisada que não afeta linhas na fonte de dados, a chamada ao SQLParamData devolve SQL_NO_DATA.
Para mais informações sobre como os dados do parâmetro de execução são passados no momento da execução da instrução, consulte "Passing Parameter Values" em SQLBindParameter e Sending Long Data. Para mais informações sobre como os dados da coluna na execução são atualizados ou adicionados, veja a secção "Usando SQLSetPos" no SQLSetPos, "Realizando Atualizações em Massa Usando Favoritos" no SQLBulkOperations, e Dados Longos e SQLSetPos e SQLBulkOperations.
O SQLParamData pode ser chamado para recuperar parâmetros de saída em streaming. Quando o SQLMoreResults, SQLExecute, SQLGetData ou SQLExecDirect SQL_PARAM_DATA_AVAILABLE, chame o SQLParamData para determinar qual o parâmetro que tem um valor disponível. Para mais informações sobre SQL_PARAM_DATA_AVAILABLE e parâmetros de saída transmitidos, veja Recuperar Parâmetros de Saída Usando SQLGetData.
Exemplo de código
Ver SQLPutData.
Funções relacionadas
| Para obter informações sobre | Veja |
|---|---|
| Ligar um buffer a um parâmetro | Função SQLBindParameter |
| Cancelamento do processamento de extratos | Função SQLCancel |
| Devolver informação sobre um parâmetro numa instrução | Função SQLDescribeParam |
| Execução de uma instrução SQL | Função SQLExecDirect |
| Execução de uma instrução SQL preparada | Função SQLExecute |
| Envio de dados de parâmetros no momento da execução | da função SQLPutData |