Função SQLPrepare
Conformidade
Versão introduzida: Conformidade de padrões do ODBC 1.0: ISO 92
Resumo
SQLPrepare prepara uma cadeia de caracteres SQL para execução.
Sintaxe
SQLRETURN SQLPrepare(
SQLHSTMT StatementHandle,
SQLCHAR * StatementText,
SQLINTEGER TextLength);
Argumentos
StatementHandle
[Entrada] Identificador de instrução.
StatementText
[Entrada] Cadeia de caracteres de texto SQL.
Textlength
[Entrada] Comprimento de *StatementText em caracteres.
Retornos
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 Identificador de StatementHandle. A tabela a seguir lista os valores SQLSTATE normalmente 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 o contrário.
| 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 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. 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 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 o número de nomes especificados não é o mesmo grau que a tabela derivada definida pela especificação de 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 de 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 "CARACTERE de escapeESCAPE do valor de padrão LIKE" na cláusula WHERE e o caractere após o caractere de escape no valor padrão não era "%" nem "_". |
| 24.000 | Estado de cursor inválido | (DM) Um cursor foi aberto no StatementHandle e SQLFetch ou SQLFetchScroll foram chamados. Um cursor foi aberto no StatementHandle, mas SQLFetch ou SQLFetchScroll não foram chamados. |
| 34000 | Nome de cursor inválido | *StatementText continha um DELETE posicionado ou um UPDATE posicionado, e o cursor referenciado pela instrução que estava 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 preparavel 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 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 o 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 (fazendo referência a uma tabela diferente daquela 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 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 daquela que está sendo criada) não existia. |
| 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 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çõ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 SQLPrepare 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. |
| 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 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 | Tempo limite esgotado | O período de tempo limite 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 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 enviá-la à fonte de dados para preparação. Em particular, o driver modifica as sequências de escape usadas para definir a sintaxe do SQL para determinados recursos. (Para obter uma descrição da gramática da instrução SQL, consulte Sequências de escape no ODBC e apêndice C: Gramática do 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) poderão ser verificadas quando a instrução for preparada (se todos os parâmetros tiverem sido associados) ou quando elas forem executadas (se todos os parâmetros não tiverem sido associados). Para a interoperabilidade máxima, um aplicativo deve desassociar todos os parâmetros aplicados a uma instrução SQL antiga antes de preparar uma nova instrução SQL na mesma instrução. Isso impede erros devido a informações de parâmetro antigas que estão sendo aplicadas à nova instrução.
Importante
A confirmação de 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 |
| Associar um buffer a uma coluna em um conjunto de resultados | Função SQLBindCol |
| Associar 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 |
Consulte 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