Função SQLExecDirect

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

Resumo
SQLExecDirect executa uma instrução preparavel, usando os valores atuais das variáveis de marcador de parâmetro se houver parâmetros na instrução . SQLExecDirect é a maneira mais rápida de enviar uma instrução SQL para execução única.

Sintaxe

  
SQLRETURN SQLExecDirect(  
     SQLHSTMT     StatementHandle,  
     SQLCHAR *    StatementText,  
     SQLINTEGER   TextLength);  

Argumentos

StatementHandle
[Entrada] Identificador de instrução.

StatementText
[Entrada] Instrução SQL a ser executada.

Textlength
[Entrada] Comprimento de *StatementText em caracteres.

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 SQLExecDirect 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 SQLExecDirect 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.)
01001 Conflito de operação do cursor *StatementText 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 atributo SQL_ATTR_SIMULATE_CURSOR em SQLSetStmtAttr.)

(A função retorna SQL_SUCCESS_WITH_INFO.)
01003 Valor NULL eliminado na função set O argumento StatementText continha uma função set (como AVG, MAX, MIN e assim por diante), mas não a função de conjunto COUNT e os valores de argumento NULL foram eliminados antes da função ser aplicada. (A função retorna SQL_SUCCESS_WITH_INFO.)
01004 Dados de cadeia de caracteres, truncados à direita A cadeia de caracteres ou os dados binários retornados para um parâmetro de entrada/saída ou 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 estava truncado à direita. (A função retorna SQL_SUCCESS_WITH_INFO.)
01006 Privilégio não revogado *StatementText continha 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 *StatementText era uma instrução GRANT e o usuário não podia 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 temporariamente substituído. (SQLGetStmtAttr pode ser chamado para determinar qual é o valor temporariamente substituído.) O valor substituto é válido para 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 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 time, timestamp ou interval foi truncada.

(A função retorna SQL_SUCCESS_WITH_INFO.)
07002 Campo COUNT incorreto O número de parâmetros especificados em SQLBindParameter foi 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 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 apenas para um parâmetro que envia e recebe dados em partes. 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 tinha um valor padrão.
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.
21S01 Inserir lista de valores não corresponde à lista de colunas *StatementText continha uma instrução INSERT e o número de valores a serem inseridos não correspondia ao grau da tabela derivada.
21S02 O grau da tabela derivada não corresponde à lista de colunas *StatementText 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 de identificador de coluna da instrução SQL) continha mais nomes do que o número de colunas na tabela derivada definida pelo argumento query-specification 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 dados de caracteres não em branco ou dados binários não nulos.
22002 Variável de indicador 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 *StatementText continha uma instrução SQL que continha um parâmetro numérico associado ou literal e o valor fazia com que toda a parte (em vez de 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 vez de fracionária) do número fosse truncada.
22007 Formato de datetime inválido *StatementText 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 estava associado 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 do campo datetime *StatementText 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 computada 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 *StatementText continha uma instrução SQL que 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 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 intervalo 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 havia representação dos dados na estrutura de dados do intervalo.
22018 Valor de caractere inválido para especificação de conversão *StatementText continha um tipo C que era um numérico exato ou aproximado, um datetime 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 foi retornado, o tipo SQL era um numérico exato ou aproximado, um datetime 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 *StatementText continha uma instrução SQL que 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 *StatementText continha uma instrução SQL que continha "caractere de escapeESCAPE de valor de padrão LIKE" na cláusula WHERE e o caractere que seguia o caractere de escape no valor padrão não era um de "%" ou "_".
23000 Violação da restrição de integridade *StatementText continha uma instrução SQL que continha um parâmetro ou literal. O valor do parâmetro era NULL para uma coluna definida como NOT NULL na coluna de tabela associada, um valor duplicado foi fornecido para uma coluna restrita para conter apenas valores exclusivos ou alguma outra restrição de integridade foi violada.
24.000 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 for retornado pelo driver se SQLFetch ou SQLFetchScroll tiver retornado SQL_NO_DATA.

Um cursor estava aberto, mas não posicionado no StatementHandle.

*StatementText 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.
34000 Nome de cursor inválido *StatementText continha uma instrução de atualização ou exclusão posicionada e o cursor referenciado pela instrução que estava sendo executada não estava aberto.
3D000 Nome do catálogo inválido O nome do catálogo especificado em StatementText era inválido.
3F000 Nome do esquema inválido O nome do esquema especificado em StatementText era inválido.
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 Falha na conexão associada 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 *StatementText continha uma instrução SQL que não era preparavel ou continha um erro de sintaxe.

O usuário não tinha permissão para executar a instrução SQL contida em *StatementText.
42S01 A tabela ou exibição base já existe *StatementText continha uma instrução CREATE TABLE ou CREATE VIEW e o nome da tabela ou o nome da exibição especificado já existe.
42S02 Tabela base ou exibição não encontrada *StatementText continha uma instrução DROP TABLE ou DROP VIEW e o nome da tabela ou nome de exibição especificado não existia.

*StatementText continha uma instrução ALTER TABLE e o nome da tabela especificado não existia.

*StatementText continha uma instrução CREATE VIEW e um nome de tabela ou nome de exibição definido pela especificação de consulta não existia.

*StatementText continha uma instrução CREATE INDEX e o nome da tabela especificado não existia.

*StatementText continha uma instrução GRANT ou REVOKE e o nome da tabela ou o nome de exibição especificado não existia.

*StatementText continha uma instrução SELECT e um nome de tabela ou nome de exibição especificado não existia.

*StatementText continha uma instrução DELETE, INSERT ou UPDATE e o nome da tabela especificado não existia.

*StatementText continha uma instrução CREATE TABLE e uma tabela especificada em uma restrição (referenciando uma tabela diferente da que está sendo criada) não existia.

*StatementText continha uma instrução CREATE SCHEMA e um nome de tabela ou nome de exibição especificado não existia.
42S11 O índice já existe *StatementText continha uma instrução CREATE INDEX e o nome do índice especificado já existia.

*StatementText continha uma instrução CREATE SCHEMA e o nome do índice especificado já existia.
42S12 Índice não encontrado *StatementText continha uma instrução DROP INDEX e o nome do índice especificado não existia.
42S21 A coluna já existe *StatementText continha uma instrução ALTER TABLE e a coluna especificada na cláusula ADD não é exclusiva ou identifica uma coluna existente na tabela base.
42S22 Coluna não encontrada *StatementText continha uma instrução CREATE INDEX e um ou mais dos nomes de coluna especificados na lista de colunas não existiam.

*StatementText continha uma instrução GRANT ou REVOKE e um nome de coluna especificado não existia.

*StatementText continha uma instrução SELECT, DELETE, INSERT ou UPDATE e um nome de coluna especificado não existia.

*StatementText continha uma instrução CREATE TABLE e uma coluna especificada em uma restrição (referenciando uma tabela diferente da que está sendo criada) não existia.

*StatementText continha uma instrução CREATE SCHEMA e um nome de coluna especificado não existia.
44000 Violação COM OPÇÃO DE VERIFICAÇÃO O argumento StatementText continha uma instrução INSERT executada em uma tabela visualizada 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 INSERT não estarão mais presentes na tabela exibida.

O argumento StatementText continha uma instrução UPDATE executada em uma tabela visualizada 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 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 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.
HY009 Uso inválido de ponteiro nulo (DM) *StatementText era um ponteiro nulo.
HY010 Erro de sequência de funções (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 SQLExecDirect foi chamada.

(DM) SQLExecute, SQLExecDirect ou SQLMoreResults foi chamado para o StatementHandle e retornou SQL_PARAM_DATA_AVAILABLE. Essa função foi chamada antes de os dados serem 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 foram chamados para o StatementHandle e retornaram SQL_NEED_DATA. Essa função foi chamada 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.
HY090 Comprimento de buffer ou cadeia de caracteres inválida (DM) O argumento TextLength era menor ou igual a 0, mas não igual a SQL_NTS.

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 foi SQL_C_BINARY ou SQL_C_CHAR; e o valor do comprimento do parâmetro era menor que 0, mas não era SQL_NTS, SQL_NULL_DATA, SQL_DATA_AT_EXEC, SQL_DEFAULT_PARAM 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ções SQL_NEED_LONG_DATA_LEN no 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 era um parâmetro de entrada.
HY109 Posição inválida do cursor *StatementText continha 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 é suspensa devido ao estado de transação desconhecido. 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 Tempo limite esgotado O período de tempo limite da consulta expirou antes da fonte de dados retornar 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 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 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.

Comentários

O aplicativo chama SQLExecDirect para enviar uma instrução SQL para a fonte de dados. Para obter mais informações sobre a execução direta, consulte Execução direta. O driver modifica a instrução para usar a forma de SQL usada pela fonte de dados e, em seguida, a envia à fonte de dados. Em particular, o driver modifica as sequências de escape usadas para definir determinados recursos no SQL. Para obter a sintaxe de sequências de escape, consulte Sequências de Escape no ODBC.

O aplicativo pode incluir um ou mais marcadores de parâmetro na instrução SQL. Para incluir um marcador de parâmetro, o aplicativo insere um ponto de interrogação (?) na instrução SQL na posição apropriada. Para obter informações sobre parâmetros, consulte Parâmetros de instrução.

Se a instrução SQL for uma instrução SELECT e se o aplicativo chamar SQLSetCursorName para associar um cursor a uma instrução , o driver usará o cursor especificado. Caso contrário, o driver gerará um nome de cursor.

Se a fonte de dados estiver no modo de confirmação manual (exigindo iniciação de transação explícita) e uma transação ainda não tiver sido iniciada, o driver iniciará uma transação antes de enviar a instrução SQL. Para obter mais informações, consulte Modo de Confirmação Manual.

Se um aplicativo usar SQLExecDirect para enviar uma instrução COMMIT ou ROLLBACK , ele não será interoperável entre produtos DBMS. Para confirmar ou reverter uma transação, um aplicativo chama SQLEndTran.

Se SQLExecDirect encontrar um parâmetro de dados em execução, ele retornará SQL_NEED_DATA. O aplicativo envia os dados usando SQLParamData e SQLPutData. Confira SQLBindParameter, SQLParamData, SQLPutData e Envio de Dados Longos.

Se SQLExecDirect executar uma instrução pesquisada de atualização, inserção ou exclusão que não afete nenhuma linha na fonte de dados, a chamada para SQLExecDirect 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, SQLExecDirect executará a instrução SQL uma vez para cada conjunto de valores de parâmetro das matrizes apontadas pelo argumento ParameterValuePointer na chamada para SQLBindParameter. Para obter mais informações, consulte Matrizes de valores de parâmetro.

Se os indicadores estiverem ativados e uma consulta for executada que não possa dar suporte a indicadores, o driver deverá tentar coagir o ambiente para um que dê suporte a indicadores 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 alterem o banco de dados ou o contexto do banco de dados, como a instrução USEdatabase em SQL Server, que altera o catálogo usado por uma fonte de dados.

Exemplo de código

Consulte SQLBindCol, SQLGetData e Programa ODBC de exemplo.

Para obter informações sobre Consulte
Associar um buffer a uma coluna em um conjunto de resultados Função SQLBindCol
Cancelando o processamento de instruções Função SQLCancel
Executando uma operação de confirmação ou reversão Função SQLEndTran
Executando uma instrução SQL preparada Função SQLExecute
Buscar várias linhas de dados Função SQLFetch
Buscar um bloco de dados ou rolar por um conjunto de resultados Função SQLFetchScroll
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 no momento da execução Função SQLPutData
Definindo um nome de cursor Função SQLSetCursorName
Definindo um atributo de instrução Função SQLSetStmtAttr

Consulte Também

Referência de API do ODBC
Arquivos de cabeçalho ODBC