Função SQLParamData

  • Artigo

Conformidade
Versão introduzida: Conformidade de padrões do ODBC 1.0: ISO 92

Resumo
SQLParamData é usado junto com SQLPutData para fornecer dados de parâmetro no tempo de 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

StatementHandle
[Entrada] Identificador de instrução.

ValuePtrPtr
[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 SQL_DESC_DATA_PTR descritor.

Retornos

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 Identificador 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 o contrário.

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 foi conectado falhou antes da função concluir o processamento.
22026 Incompatibilidade de comprimento de dados String O tipo de informações SQL_NEED_LONG_DATA_LEN no SQLGetInfo era "Y" e menos dados foram enviados para um parâmetro longo (o tipo de dados foi SQL_LONGVARCHAR, SQL_LONGVARBINARY ou um tipo de dados específico da fonte de dados longa) do que foi especificado com o argumento StrLen_or_IndPtr em SQLBindParameter.

O tipo de informações SQL_NEED_LONG_DATA_LEN 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 dados específico de fonte de dados longo) do que foi 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 na 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 nenhum 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 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 StatementHandle. A função foi chamada e, antes de concluir a execução, SQLCancel ou SQLCancelHandle foi chamado no StatementHandle; a função foi então 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ções (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 foi uma chamada para SQLParamData.

(DM) Uma função em 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 StatementHandle e ainda estava em execução quando essa função foi chamada.

SQLExecute, SQLExecDirect, SQLBulkOperations ou SQLSetPos foram chamados para StatementHandle e retornados SQL_NEED_DATA. SQLCancel foi chamado antes de os dados serem 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 de transação desconhecido. Somente funções desconectar 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 da fonte de dados responder à 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 dá suporte a essa 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 ao enviar 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 for chamado ao enviar dados para uma coluna que está sendo atualizada ou adicionada com SQLBulkOperations ou ser atualizada com SQLSetPos, ela poderá retornar qualquer SQLSTATE que possa ser retornado por SQLBulkOperations ou SQLSetPos.

Comentários

SQLParamData pode ser chamado para fornecer dados de 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 momento da execução, SQLParamData retorna ao aplicativo um indicador de quais dados o driver requer.

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 vinculada originalmente, da seguinte maneira:

Endereço + associado Deslocamento de associação + ((Número da Linha - 1) x Tamanho do Elemento)

em que as variáveis são definidas conforme indicado na tabela a seguir.

Variável Descrição
Endereço associado O endereço especificado com o argumento TargetValuePtr em SQLBindCol.
Deslocamento de associaçã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, este é 1.
Tamanho do elemento O valor do atributo de instrução SQL_ATTR_ROW_BIND_TYPE para buffers de dados e de 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 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 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 de 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 SQL_PARAM_DATA_AVAILABLE e parâmetros de saída transmitidos, consulte Recuperando parâmetros de saída usando SQLGetData.

Exemplo de código

Consulte SQLPutData.

Para obter informações sobre Consulte
Associar um buffer a um parâmetro Função SQLBindParameter
Cancelando o processamento da instrução 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 no momento da execução Função SQLPutData

Consulte Também

Referência de API do ODBC
Arquivos de cabeçalho ODBC
Recuperar parâmetros de saída usando SQLGetData