Função SQLExecute
Compatibilidade
Versão introduzida: ODBC 1.0 Conformidade com padrões: ISO 92
Resumo
SQLExecute executa uma instrução preparada, usando os valores atuais das variáveis de marcador de parâmetro se existirem marcadores de parâmetro na instrução.
Sintaxe
SQLRETURN SQLExecute(
SQLHSTMT StatementHandle);
Argumentos
StatementHandle
[Entrada] Identificador de instrução.
Retornos
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 pelo 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 foram atualizadas ou excluídas. (Para obter mais informações sobre atualizações para 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 COUNT set e os valores do 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 | 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 cadeia de caracteres, ele 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 substituído temporariamente.) O valor substituto é válido para StatementHandle até que o cursor seja fechado, momento em que o atributo statement reverte 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 fracionado | Os dados retornados para um parâmetro de entrada/saída ou saída foram truncados de tal forma 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 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 era 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 acoplado não pôde ser convertido para o tipo de dados identificado pelo argumento ParameterType em SQLBindParameter. O valor de dados retornado para um parâmetro vinculado como SQL_PARAM_INPUT_OUTPUT ou SQL_PARAM_OUTPUT não pôde ser convertido para o 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 forem 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 apenas para um parâmetro que envia e recebe dados em partes. Um buffer vinculado à 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 era um parâmetro para uma chamada 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 foi conectado falhou antes que o processamento da função fosse concluído. |
| 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 especificado para o modo de exibição nos argumentos de 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 em branco (caractere) ou não nulos (binários). |
| 22002 | Variável indicadora necessária, mas não fornecida | Os dados NULL foram vinculados 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 acoplado e o valor do parâmetro fazia com que a parte inteira (em oposição à fracionária) do número fosse truncada quando atribuída à coluna da tabela associada. O retorno de um valor numérico (como numérico ou string) para um ou mais parâmetros de entrada/saída ou saída teria feito com que a parte inteira (em oposição à fracionária) do número fosse truncada. |
| 22007 | Formato datetime 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 acoplado, 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 era vinculado a uma estrutura C de data, hora ou carimbo de data/hora, e um valor no parâmetro retornado era, respectivamente, uma data, hora ou carimbo de data/hora inválido. (A função retorna SQL_SUCCESS_WITH_INFO.) |
| 22008 | Estouro de campo datetime | A instrução preparada associada ao StatementHandle continha uma instrução SQL que continha uma expressão datetime que, quando computada, 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 que era 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 em 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éricos em uma coluna, não tinha representação no tipo de dados numéricos. *StatementText continha dados de parâmetro que foram atribuídos a um tipo SQL de intervalo, e não havia representação do valor do tipo C no tipo SQL de intervalo. A atribuição de um parâmetro de entrada/saída ou de saída que era um tipo SQL numérico ou intervalar exato a um tipo C de intervalo causou 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 número exato ou aproximado, uma data/hora ou um tipo de dados intervalar, 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 vinculado. Quando um parâmetro de entrada/saída ou saída era retornado, o tipo SQL era um número 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 vinculado. |
| 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 "LIKEpattern valueESCAPEescape character" na cláusula WHERE, e o caractere seguinte ao caractere escape no valor pattern 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 foi fornecido para uma coluna restrita a conter apenas valores exclusivos ou alguma outra restrição de integridade foi violada. |
| 24000 | Estado de cursor inválido | Um cursor foi posicionado no StatementHandle por SQLFetch ou SQLFetchScroll. Esse erro é 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 foi aberto no StatementHandle. A instrução preparada associada ao StatementHandle continha uma instrução de atualização ou exclusão posicionada, e o cursor era 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 impasse 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 visualizada 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 de 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 suportar a 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 retornou 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 retornou 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 pouca memória. |
| HY090 | Cadeia de caracteres inválida ou comprimento do buffer | 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 vinculado por SQLBindParameter foi definido como SQL_DATA_AT_EXEC, o tipo SQL foi 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 foi "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 era 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 suportada pelo driver ou pela 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 oferece suporte a marcadores. |
| 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 de conexão expirou antes que a fonte de dados respondesse à solicitação. O período de tempo limite de conexão é definido por meio de SQLSetConnectAttr, SQL_ATTR_CONNECTION_TIMEOUT. |
| IM001 | Driver não suporta esta função | (DM) O driver associado ao StatementHandle não oferece suporte à função. |
| IM017 | A sondagem está desativada 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 neste 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 início explícito de 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 SQLExecute encontrar um parâmetro data-at-execution, ele retornará SQL_NEED_DATA. O aplicativo envia os dados usando SQLParamData e SQLPutData. Consulte SQLBindParameter, SQLParamData, SQLPutData e Enviando dados longos.
Se SQLExecute executar uma instrução update, insert ou delete pesquisada que não afeta 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 marcadores estiverem habilitados e for executada uma consulta que não ofereça suporte a marcadores, o driver deverá tentar coagir o ambiente para um que ofereça suporte a marcadores alterando um valor de atributo e retornando SQLSTATE 01S02 (valor de 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 USEno 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 |
|---|---|
| Vinculando 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 |
| Buscar um bloco de dados ou rolar 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 |
| Buscar parte ou a totalidade de uma coluna de dados | Função SQLGetData |
| Retornando o próximo parâmetro para enviar dados para | 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 |
| Definindo um atributo de instrução | Função SQLSetStmtAttr |
Confira também
Comentários
Em breve: Ao longo de 2024, eliminaremos os problemas do GitHub como o mecanismo de comentários para conteúdo e o substituiremos por um novo sistema de comentários. Para obter mais informações, consulte https://aka.ms/ContentUserFeedback.
Enviar e exibir comentários de