Função SQLExecute
Compatibilidade
Versão introduzida: ODBC 1.0 Conformidade com os padrões: ISO 92
Resumo
SQLExecute executa uma instrução preparada, usando os valores atuais das variáveis de marcador de parâmetro se houver algum marcador de parâmetro na instrução.
Sintaxe
SQLRETURN SQLExecute(
SQLHSTMT StatementHandle);
Argumentos
Identificador de declaração
[Entrada] Identificador de instrução.
Devoluções
SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_NEED_DATA, SQL_STILL_EXECUTING, SQL_ERROR, SQL_NO_DATA, SQL_INVALID_HANDLE ou SQL_PARAM_DATA_AVAILABLE.
Diagnósticos
Quando SQLExecute 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 comumente retornados por SQLExecute e explica cada um 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.) |
| 01001 | Conflito de operação do cursor | A instrução preparada associada ao StatementHandle continha uma instrução de atualização ou exclusão posicionada e nenhuma linha ou mais de uma linha foi atualizada ou excluída. (Para obter mais informações sobre atualizações em mais de uma linha, consulte a descrição do SQL_ATTR_SIMULATE_CURSOR Atributo em SQLSetStmtAttr.) (A função retorna SQL_SUCCESS_WITH_INFO.) |
| 01003 | Valor NULL eliminado na função set | A instrução preparada associada a StatementHandle continha uma função set (como AVG, MAX, MIN e assim por diante), mas não a função set COUNT , e os valores de argumento NULL foram eliminados antes que a função fosse aplicada. (A função retorna SQL_SUCCESS_WITH_INFO.) |
| 01004 | Dados de cadeia de caracteres, truncados à direita | Os dados binários ou de cadeia de caracteres retornados para um parâmetro de saída resultaram no truncamento de caracteres não em branco ou dados binários não NULL. Se fosse um valor de string, era truncado à direita. (A função retorna SQL_SUCCESS_WITH_INFO.) |
| 01006 | Privilégio não revogado | A instrução preparada associada ao StatementHandle era uma instrução REVOKE e o usuário não tinha o privilégio especificado. (A função retorna SQL_SUCCESS_WITH_INFO.) |
| 01007 | Privilégio não concedido | A instrução preparada associada ao StatementHandle era uma instrução GRANT e o usuário não pôde receber o privilégio especificado. |
| 01S02 | Valor da opção alterado | Um atributo de instrução especificado era inválido devido às condições de trabalho de implementação, portanto, um valor semelhante foi substituído temporariamente. (SQLGetStmtAttr pode ser chamado para determinar qual é o valor temporariamente substituído.) O valor substituto é válido para o StatementHandle até que o cursor seja fechado, momento em que o atributo de instrução é revertido para seu valor anterior. Os atributos de instrução que podem ser alterados são: SQL_ATTR_CONCURRENCY, SQL_ATTR_CURSOR_TYPE, SQL_ATTR_KEYSET_SIZE, SQL_ATTR_MAX_LENGTH, SQL_ATTR_MAX_ROWS, SQL_ATTR_QUERY_TIMEOUT e SQL_ATTR_SIMULATE_CURSOR. (A função retorna SQL_SUCCESS_WITH_INFO.) |
| 01S07 | Truncamento fracionário | Os dados retornados para um parâmetro de entrada/saída ou saída foram truncados de modo que a parte fracionária de um tipo de dados numérico foi truncada ou a parte fracionária do componente de tempo de um tipo de dados de tempo, carimbo de data/hora ou intervalo foi truncada. (A função retorna SQL_SUCCESS_WITH_INFO.) |
| 07002 | Campo COUNT incorreto | O número de parâmetros especificados em SQLBindParameter era menor do que o número de parâmetros na instrução SQL contida em *StatementText. SQLBindParameter foi chamado com ParameterValuePtr definido como um ponteiro nulo, StrLen_or_IndPtr não definido como SQL_NULL_DATA ou SQL_DATA_AT_EXEC e InputOutputType não definido como SQL_PARAM_OUTPUT, de modo que o número de parâmetros especificados em SQLBindParameter fosse maior do que o número de parâmetros na instrução SQL contida em *StatementText. |
| 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.) |
| 07007 | Violação de valor de parâmetro restrito | O tipo de parâmetro SQL_PARAM_INPUT_OUTPUT_STREAM é usado somente para um parâmetro que envia e recebe dados em peças. Um buffer associado de entrada não é permitido para esse tipo de parâmetro. Esse erro ocorrerá quando o tipo de parâmetro for SQL_PARAM_INPUT_OUTPUT e quando o *StrLen_or_IndPtr especificado em SQLBindParameter não for igual a SQL_NULL_DATA, SQL_DEFAULT_PARAM, SQL_LEN_DATA_AT_EXEC(len) ou SQL_DATA_AT_EXEC. |
| 07S01 | Uso inválido do parâmetro padrão | Um valor de parâmetro, definido com SQLBindParameter, foi SQL_DEFAULT_PARAM e o parâmetro correspondente não foi um parâmetro para uma invocação de procedimento canônico ODBC. |
| 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. |
| 21S02 | O grau da tabela derivada não corresponde à lista de colunas | A instrução preparada associada ao StatementHandle continha uma instrução CREATE VIEW e a lista de colunas não qualificadas (o número de colunas especificadas para a exibição nos argumentos do identificador de coluna da instrução SQL) continha mais nomes do que o número de colunas na tabela derivada definida pelo argumento de especificação de consulta da instrução SQL. |
| 22001 | Dados de cadeia de caracteres, truncamento à direita | A atribuição de um caractere ou valor binário a uma coluna resultou no truncamento de caracteres ou bytes não vazios (caracteres) ou não nulos (binários). |
| 22002 | Variável indicadora necessária, mas não fornecida | Os dados NULL foram associados a um parâmetro de saída cujo StrLen_or_IndPtr definido por SQLBindParameter era um ponteiro nulo. |
| 22003 | Valor numérico fora do intervalo | A instrução preparada associada ao StatementHandle continha um parâmetro numérico associado, e o valor do parâmetro fazia com que toda a parte (em oposição à fracionária) do número fosse truncada quando atribuída à coluna da tabela associada. Retornar um valor numérico (como numérico ou cadeia de caracteres) para um ou mais parâmetros de entrada/saída ou saída teria feito com que toda a parte (em oposição à fracionária) do número fosse truncada. |
| 22007 | Formato de data e hora inválido | A instrução preparada associada ao StatementHandle continha uma instrução SQL que continha uma estrutura de data, hora ou carimbo de data/hora como um parâmetro associado, e o parâmetro era, respectivamente, uma data, hora ou carimbo de data/hora inválido. Um parâmetro de entrada/saída ou saída foi associado a uma estrutura C de data, hora ou carimbo de data/hora, e um valor no parâmetro retornado foi, respectivamente, uma data, hora ou carimbo de data/hora inválido. (A função retorna SQL_SUCCESS_WITH_INFO.) |
| 22008 | Estouro de campo de data e hora | A instrução preparada associada ao StatementHandle continha uma instrução SQL que continha uma expressão datetime que, quando calculada, resultava em uma estrutura de data, hora ou carimbo de data/hora inválida. Uma expressão datetime calculada para um parâmetro de entrada/saída ou saída resultou em uma estrutura C de data, hora ou carimbo de data/hora inválida. |
| 22012 | Divisão por zero | A instrução preparada associada ao StatementHandle continha uma expressão aritmética que causava divisão por zero. Uma expressão aritmética calculada para um parâmetro de entrada/saída ou saída resultou na divisão por zero. |
| 22015 | Estouro de campo de intervalo | *StatementText continha um parâmetro numérico ou de intervalo exato que, quando convertido em um tipo de dados SQL de intervalo, causava uma perda de dígitos significativos. *StatementText continha um parâmetro de intervalo com mais de um campo que, quando convertido em um tipo de dados numérico em uma coluna, não tinha representação no tipo de dados numérico. *StatementText continha dados de parâmetro atribuídos a um tipo SQL de intervalo e não havia representação do valor do tipo C no tipo SQL de intervalo. Atribuir um parâmetro de entrada/saída ou saída que era um tipo SQL numérico ou de intervalo exato a um tipo C de intervalo causava uma perda de dígitos significativos. Quando um parâmetro de entrada/saída ou saída foi atribuído a uma estrutura de intervalo C, não houve representação dos dados na estrutura de dados de intervalo. |
| 22018 | Valor de caractere inválido para especificação de conversão | *StatementText continha um tipo C que era um tipo de dados numérico exato ou aproximado, uma data/hora ou um tipo de dados de intervalo; o tipo SQL da coluna era um tipo de dados de caractere; e o valor na coluna não era um literal válido do tipo C associado. Quando um parâmetro de entrada/saída ou saída era retornado, o tipo SQL era um tipo de dados numérico exato ou aproximado, uma data/hora ou um tipo de dados de intervalo; o tipo C foi SQL_C_CHAR; e o valor na coluna não era um literal válido do tipo SQL associado. |
| 22019 | Caractere de escape inválido | A instrução preparada associada a StatementHandle continha um predicado LIKE com um ESCAPE na cláusula WHERE , e o comprimento do caractere de escape após ESCAPE não era igual a 1. |
| 22025 | Sequência de escape inválida | A instrução preparada associada a StatementHandle continha "caractere de escape ESCAPE do valor do padrão LIKE" na cláusula WHERE e o caractere após o caractere de escape no valor do padrão não era um de "%" ou "_". |
| 23000 | Violação de restrição de integridade | A instrução preparada associada ao StatementHandle continha um parâmetro. O valor do parâmetro era NULL para uma coluna definida como NOT NULL na coluna da tabela associada, um valor duplicado era fornecido para uma coluna restrita a conter apenas valores exclusivos ou alguma outra restrição de integridade era violada. |
| 24000 | Estado de cursor inválido | Um cursor foi posicionado no StatementHandle por SQLFetch ou SQLFetchScroll. Esse erro será retornado pelo Gerenciador de Driver se SQLFetch ou SQLFetchScroll não tiver retornado SQL_NO_DATA e será retornado pelo driver se SQLFetch ou SQLFetchScroll tiver retornado SQL_NO_DATA. Um cursor estava aberto no StatementHandle. A instrução preparada associada ao StatementHandle continha uma instrução de atualização ou exclusão posicionada e o cursor foi posicionado antes do início do conjunto de resultados ou após o final do conjunto de resultados. |
| 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. |
| 42000 | Erro de sintaxe ou violação de acesso | O usuário não tinha permissão para executar a instrução preparada associada ao StatementHandle. |
| 44000 | Violação COM OPÇÃO DE VERIFICAÇÃO | A instrução preparada associada a StatementHandle continha uma instrução INSERT executada em uma tabela exibida ou uma tabela derivada da tabela exibida que foi criada especificando WITH CHECK OPTION, de modo que uma ou mais linhas afetadas pela instrução INSERT não estarão mais presentes na tabela exibida. A instrução preparada associada ao StatementHandle continha uma instrução UPDATE executada em uma tabela exibida ou uma tabela derivada da tabela exibida que foi criada especificando WITH CHECK OPTION, de modo que uma ou mais linhas afetadas pela instrução UPDATE não estarão mais presentes na tabela exibida. |
| 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. Em seguida, 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) 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 SQLExecute foi chamada. (DM) SQLExecute, SQLExecDirect ou SQLMoreResults foi chamado para o StatementHandle e retornado SQL_PARAM_DATA_AVAILABLE. Essa função foi chamada antes que os dados fossem recuperados para todos os parâmetros transmitidos. (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. (DM) SQLExecute, SQLExecDirect, SQLBulkOperations ou SQLSetPos foi chamado para o StatementHandle e retornado SQL_NEED_DATA. Essa função foi chamada antes que os dados fossem enviados para todos os parâmetros ou colunas de dados em execução. (DM) O StatementHandle não foi preparado. |
| 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. |
| HY090 | Cadeia de caracteres ou comprimento de buffer inválido | Um valor de parâmetro, definido com SQLBindParameter, era um ponteiro nulo e o valor de comprimento do parâmetro não era 0, SQL_NULL_DATA, SQL_DATA_AT_EXEC, SQL_DEFAULT_PARAM ou menor ou igual a SQL_LEN_DATA_AT_EXEC_OFFSET. Um valor de parâmetro, definido com SQLBindParameter, não era um ponteiro nulo; o tipo de dados C era SQL_C_BINARY ou SQL_C_CHAR; e o valor de comprimento do parâmetro era menor que 0, mas não era SQL_NTS, SQL_NULL_DATA, SQL_DEFAULT_PARAM ou SQL_DATA_AT_EXEC, ou menor ou igual a SQL_LEN_DATA_AT_EXEC_OFFSET. Um valor de comprimento de parâmetro associado por SQLBindParameter foi definido como SQL_DATA_AT_EXEC; o tipo SQL era SQL_LONGVARCHAR, SQL_LONGVARBINARY ou um tipo de dados específico da fonte de dados longa; e o tipo de informação SQL_NEED_LONG_DATA_LEN em SQLGetInfo era "Y". |
| HY105 | Tipo de parâmetro inválido | O valor especificado para o argumento InputOutputType em SQLBindParameter foi SQL_PARAM_OUTPUT e o parâmetro foi um parâmetro de entrada. |
| HY109 | Posição inválida do cursor | A instrução preparada era uma instrução de atualização ou exclusão posicionada e o cursor foi posicionado (por SQLSetPos ou SQLFetchScroll) em uma linha que havia sido excluída ou não pôde ser buscada. |
| 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. |
| HYC00 | Recurso opcional não implementado | A combinação das configurações atuais dos atributos de instrução SQL_ATTR_CONCURRENCY e SQL_ATTR_CURSOR_TYPE não era compatível com o driver ou a fonte de dados. O atributo de instrução SQL_ATTR_USE_BOOKMARKS foi definido como SQL_UB_VARIABLE e o atributo de instrução SQL_ATTR_CURSOR_TYPE foi definido como um tipo de cursor para o qual o driver não dá suporte a indicadores. |
| HYT00 | Timeout expired | O período de tempo limite da consulta expirou antes que a fonte de dados retornasse o conjunto de resultados. O período de tempo limite é definido por meio de SQLSetStmtAttr, SQL_ATTR_QUERY_TIMEOUT. |
| 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 associado 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. |
SQLExecute pode retornar qualquer SQLSTATE que possa ser retornado por SQLPrepare, com base em quando a fonte de dados avalia a instrução SQL associada à instrução.
Comentários
SQLExecute executa uma instrução preparada por SQLPrepare. Depois que o aplicativo processa ou descarta os resultados de uma chamada para SQLExecute, o aplicativo pode chamar SQLExecute novamente com novos valores de parâmetro. Para obter mais informações sobre a execução preparada, consulte Execução preparada.
Para executar uma instrução SELECT mais de uma vez, o aplicativo deve chamar SQLCloseCursor antes de executar novamente a instrução SELECT .
Se a fonte de dados estiver no modo de confirmação manual (exigindo o início explícito da transação) e uma transação ainda não tiver sido iniciada, o driver iniciará uma transação antes de enviar a instrução SQL. Confira Transações para obter mais informações.
Se um aplicativo usar SQLPrepare para preparar e SQLExecute para enviar uma instrução COMMIT ou ROLLBACK , ele não será interoperável entre produtos DBMS. Para confirmar ou reverter uma transação, chame SQLEndTran.
Se o SQLExecute encontrar um parâmetro de dados em execução, ele retornará SQL_NEED_DATA. O aplicativo envia os dados usando SQLParamData e SQLPutData. Consulte SQLBindParameter, SQLParamData, SQLPutData e envio de dados longos.
Se SQLExecute executar uma instrução de atualização, inserção ou exclusão pesquisada que não afete nenhuma linha na fonte de dados, a chamada para SQLExecute retornará SQL_NO_DATA.
Se o valor do atributo de instrução SQL_ATTR_PARAMSET_SIZE for maior que 1 e a instrução SQL contiver pelo menos um marcador de parâmetro, SQLExecute executará a instrução SQL uma vez para cada conjunto de valores de parâmetro nas matrizes apontadas pelo argumento *ParameterValuePtr nas chamadas para SQLBindParameter. Para obter mais informações, consulte Matrizes de valores de parâmetro.
Se os indicadores estiverem habilitados e for executada uma consulta que não pode dar suporte a indicadores, o driver deverá tentar forçar o ambiente a um que dê suporte a indicadores alterando um valor de atributo e retornando SQLSTATE 01S02 (valor da opção alterado). Se o atributo não puder ser alterado, o driver deverá retornar SQLSTATE HY024 (valor de atributo inválido).
Observação
Ao usar o pool de conexões, um aplicativo não deve executar instruções SQL que alteram o banco de dados ou o contexto do banco de dados, como a instrução de banco de dados USE no SQL Server, que altera o catálogo usado por uma fonte de dados.
Exemplo de código
Consulte SQLBindParameter, SQLBulkOperations, SQLPutData e SQLSetPos.
Funções relacionadas
| Para obter informações sobre | Consulte |
|---|---|
| Associando um buffer a uma coluna em um conjunto de resultados | Função SQLBindCol |
| Cancelando o processamento de instruções | Função SQLCancel |
| Fechando o cursor | Função SQLCloseCursor |
| Executando uma operação de confirmação ou reversão | Função SQLEndTran |
| Executando uma instrução SQL | Função SQLExecDirect |
| Buscando várias linhas de dados | Função SQLFetch |
| Buscando um bloco de dados ou rolando por um conjunto de resultados | Função SQLFetchScroll |
| Liberando um identificador de instrução | Função SQLFreeStmt |
| Retornando um nome de cursor | Função SQLGetCursorName |
| Buscando parte ou toda uma coluna de dados | Função SQLGetData |
| Retornando o próximo parâmetro para o qual enviar dados | Função SQLParamData |
| Preparando uma instrução para execução | Função SQLPrepare |
| Enviando dados de parâmetro em tempo de execução | Função SQLPutData |
| Definindo um nome de cursor | Função SQLSetCursorName |
| Configurando um atributo de instrução | Função SQLSetStmtAttr |