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.
Funções relacionadas
| 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 |