Partilhar via


Função SQLPrepare

Compatibilidade
Versão introduzida: ODBC 1.0 Conformidade com os padrões: ISO 92

Resumo
SQLPrepare prepara uma string SQL para execução.

Sintaxe

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

Argumentos

Identificador de declaração
[Entrada] Identificador de instrução.

Texto da declaração
[Entrada] Cadeia de caracteres de texto SQL.

Comprimento do texto
[Entrada] Comprimento de *StatementText em caracteres.

Devoluções

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_STILL_EXECUTING, SQL_ERROR ou SQL_INVALID_HANDLE.

Diagnósticos

Quando SQLPrepare 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 SQLPrepare 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 de outra forma.

SQLSTATE Erro Descrição
01000 Aviso geral Mensagem informativa específica do driver. (A função retorna SQL_SUCCESS_WITH_INFO.)
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. 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.)
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.
21S01 A lista de valores de inserção 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 o número de nomes especificados não é o mesmo grau que a tabela derivada definida pela especificação da consulta.
22018 Valor de caractere inválido para especificação de conversão *StatementText continha uma instrução SQL que continha um literal ou parâmetro, e o valor era incompatível com o tipo de dados da coluna da tabela associada.
22019 Caractere de escape inválido O argumento StatementText 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 O argumento StatementText continha "valor de padrão LIKE Caractere de escape ESCAPE" na cláusula WHERE e o caractere após o caractere de escape no valor do padrão não era "%" nem "_".
24000 Estado de cursor inválido (DM) Um cursor estava aberto no StatementHandle e SQLFetch ou SQLFetchScroll havia sido chamado.

Um cursor estava aberto no StatementHandle, mas SQLFetch ou SQLFetchScroll não haviam sido chamados.
34000 Nome de cursor inválido *StatementText continha um DELETE posicionado ou um UPDATE posicionado, e o cursor referenciado pela instrução que está sendo preparada não estava aberto.
3D000 Nome de catálogo inválido O nome do catálogo especificado em StatementText era inválido.
3F000 Nome de esquema inválido O nome do esquema especificado em StatementText era inválido.
42000 Erro de sintaxe ou violação de acesso *StatementText continha uma instrução SQL que não era preparável ou continha um erro de sintaxe.

*StatementText continha uma instrução para a qual o usuário não tinha os privilégios necessários.
42S01 A tabela base ou exibição 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 visualização não encontrada *StatementText continha uma instrução DROP TABLE ou DROP VIEW , e o nome da tabela ou do modo 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 do modo 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.
42S11 O índice já existe *StatementText continha uma instrução CREATE INDEX e o nome do índice especificado já existia.
42S12 Índice não encontrado *StatementText continha uma instrução DROP INDEX e o nome de í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.
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 e, 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çã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 SQLPrepare 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.
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 (DM) O argumento TextLength era menor ou igual a 0, mas não igual a SQL_NTS.
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 configuração de simultaneidade era inválida para o tipo de cursor definido.

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 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.

Comentários

O aplicativo chama SQLPrepare para enviar uma instrução SQL para a fonte de dados para preparação. Para obter mais informações sobre a execução preparada, consulte Execução preparada. 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 cadeia de caracteres SQL na posição apropriada. Para obter informações sobre parâmetros, consulte Parâmetros de instrução.

Observação

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.

O driver pode modificar a instrução para usar a forma de SQL usada pela fonte de dados e, em seguida, enviá-la para a fonte de dados para preparação. Em particular, o driver modifica as sequências de escape usadas para definir a sintaxe SQL para determinados recursos. (Para obter uma descrição da gramática da instrução SQL, consulte Sequências de escape em ODBC e Apêndice C: Gramática SQL.) Para o driver, um identificador de instrução é semelhante a um identificador de instrução no código SQL inserido. Se a fonte de dados der suporte a identificadores de instrução, o driver poderá enviar um identificador de instrução e valores de parâmetro para a fonte de dados.

Depois que uma instrução é preparada, o aplicativo usa o identificador de instrução para se referir à instrução em chamadas de função posteriores. A instrução preparada associada ao identificador de instrução pode ser executada novamente chamando SQLExecute até que o aplicativo libere a instrução com uma chamada para SQLFreeStmt com a opção SQL_DROP ou até que o identificador de instrução seja usado em uma chamada para SQLPrepare, SQLExecDirect ou uma das funções de catálogo (SQLColumns, SQLTables e assim por diante). Depois que o aplicativo prepara uma instrução, ele pode solicitar informações sobre o formato do conjunto de resultados. Para algumas implementações, chamar SQLDescribeCol ou SQLDescribeParam após SQLPrepare pode não ser tão eficiente quanto chamar a função após SQLExecute ou SQLExecDirect.

Alguns drivers não podem retornar erros de sintaxe ou violações de acesso quando o aplicativo chama SQLPrepare. Um driver pode lidar com erros de sintaxe e violações de acesso, apenas erros de sintaxe ou erros de sintaxe nem violações de acesso. Portanto, um aplicativo deve ser capaz de lidar com essas condições ao chamar funções relacionadas subsequentes, como SQLNumResultCols, SQLDescribeCol, SQLColAttribute e SQLExecute.

Dependendo dos recursos do driver e da fonte de dados, as informações de parâmetro (como tipos de dados) podem ser verificadas quando a instrução é preparada (se todos os parâmetros tiverem sido associados) ou quando ela for executada (se todos os parâmetros não tiverem sido associados). Para máxima interoperabilidade, um aplicativo deve desvincular todos os parâmetros aplicados a uma instrução SQL antiga antes de preparar uma nova instrução SQL na mesma instrução. Isso evita erros devidos a informações de parâmetros antigos que estão sendo aplicadas à nova instrução.

Importante

Confirmar uma transação, chamando explicitamente SQLEndTran ou trabalhando no modo de confirmação automática, pode fazer com que a fonte de dados exclua os planos de acesso para todas as instruções em uma conexão. Para obter mais informações, consulte os tipos de informações SQL_CURSOR_COMMIT_BEHAVIOR e SQL_CURSOR_ROLLBACK_BEHAVIOR em SQLGetInfo e Efeito de transações em cursores e instruções preparadas.

Exemplo de código

Consulte SQLBindParameter, SQLPutData e SQLSetPos.

Para obter informações sobre Consulte
Alocando um identificador de instrução Função SQLAllocHandle
Associando um buffer a uma coluna em um conjunto de resultados Função SQLBindCol
Associando um buffer a um parâmetro Função SQLBindParameter
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 Função SQLExecDirect
Executando uma instrução SQL preparada Função SQLExecute
Retornando o número de linhas afetadas por uma instrução Função SQLRowCount
Definindo um nome de cursor Função SQLSetCursorName

Confira também

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