Función SQLPrepare
Conformidad
Versión introducida: Cumplimiento de estándares ODBC 1.0: ISO 92
Resumen
SQLPrepare prepara una cadena SQL para su ejecución.
Sintaxis
SQLRETURN SQLPrepare(
SQLHSTMT StatementHandle,
SQLCHAR * StatementText,
SQLINTEGER TextLength);
Argumentos
StatementHandle
[Entrada] Identificador de instrucciones.
StatementText
[Entrada] Cadena de texto SQL.
TextLength
[Entrada] Longitud de *StatementText en caracteres.
Devoluciones
SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_STILL_EXECUTING, SQL_ERROR o SQL_INVALID_HANDLE.
Diagnóstico
Cuando SQLPrepare devuelve SQL_ERROR o SQL_SUCCESS_WITH_INFO, se puede obtener un valor SQLSTATE asociado llamando a SQLGetDiagRec con un HandleType de SQL_HANDLE_STMT y un identificador de StatementHandle. En la tabla siguiente se enumeran los valores SQLSTATE devueltos normalmente por SQLPrepare y se explica cada uno en el contexto de esta función; la notación "(DM)" precede a las descripciones de SQLSTATEs devueltas por el Administrador de controladores. El código de retorno asociado a cada valor SQLSTATE es SQL_ERROR, a menos que se indique lo contrario.
| SQLSTATE | Error | Descripción |
|---|---|---|
| 01000 | Advertencia general | Mensaje informativo específico del controlador. (Function devuelve SQL_SUCCESS_WITH_INFO). |
| 01S02 | Valor de opción cambiado | Un atributo de instrucción especificado no era válido debido a las condiciones de trabajo de implementación, por lo que se sustituyó temporalmente un valor similar. (Se puede llamar a SQLGetStmtAttr para determinar cuál es el valor sustituido temporalmente). El valor sustituto es válido para StatementHandle hasta que se cierra el cursor. Los atributos de instrucción que se pueden cambiar son: 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 (Function devuelve SQL_SUCCESS_WITH_INFO). |
| 08S01 | Error de vínculo de comunicación | Se produjo un error en el vínculo de comunicación entre el controlador y el origen de datos al que se conectó el controlador antes de que la función completara el procesamiento. |
| 21S01 | La lista de valores de inserción no coincide con la lista de columnas | *StatementText contenía una instrucción INSERT y el número de valores que se van a insertar no coincidía con el grado de la tabla derivada. |
| 21S02 | El grado de tabla derivada no coincide con la lista de columnas | *StatementText contenía una instrucción CREATE VIEW y el número de nombres especificados no es el mismo grado que la tabla derivada definida por la especificación de consulta. |
| 22018 | Valor de carácter no válido para la especificación de conversión | *StatementText contenía una instrucción SQL que contenía un literal o parámetro, y el valor era incompatible con el tipo de datos de la columna de tabla asociada. |
| 22019 | Carácter de escape no válido | El argumento StatementText contenía un predicado LIKE con un ESCAPE en la cláusula WHERE y la longitud del carácter de escape que sigue a ESCAPE no era igual a 1. |
| 22025 | Secuencia de escape no válida | El argumento StatementText contenía "LIKE pattern value ESCAPE escape character" en la cláusula WHERE y el carácter que sigue al carácter de escape en el valor de patrón no era "%" ni "_". |
| 24000 | Estado de cursor no válido | (DM) Se ha abierto un cursor en StatementHandle y se ha llamado a SQLFetch o SQLFetchScroll. Se ha abierto un cursor en StatementHandle, pero no se ha llamado a SQLFetch o SQLFetchScroll. |
| 34 000 | Nombre de cursor no válido | *StatementText contenía una INSTRUCCIÓN DELETE posicionada o una UPDATE posicionada, y el cursor al que hace referencia la instrucción que se está preparando no estaba abierto. |
| 3D000 | Nombre de catálogo no válido | El nombre de catálogo especificado en StatementText no era válido. |
| 3F000 | Nombre de esquema no válido | El nombre de esquema especificado en StatementText no era válido. |
| 42000 | Error de sintaxis o infracción de acceso | *StatementText contenía una instrucción SQL que no era preparable o contenía un error de sintaxis. *StatementText contenía una instrucción para la que el usuario no tenía los privilegios necesarios. |
| 42S01 | Ya existe una tabla base o vista | *StatementText contenía una instrucción CREATE TABLE o CREATE VIEW y el nombre de la tabla o el nombre de vista especificados ya existe. |
| 42S02 | Tabla base o vista no encontrada | *StatementText contenía una instrucción DROP TABLE o DROP VIEW y el nombre de tabla o vista especificados no existían. *StatementText contenía una instrucción ALTER TABLE y el nombre de tabla especificado no existía. *StatementText contenía una instrucción CREATE VIEW y no existía un nombre de tabla o nombre de vista definido por la especificación de consulta. *StatementText contenía una instrucción CREATE INDEX y el nombre de tabla especificado no existía. *StatementText contenía una instrucción GRANT o REVOKE y el nombre de la tabla o el nombre de vista especificados no existían. *StatementText contenía una instrucción SELECT y no existía un nombre de tabla o un nombre de vista especificados. *StatementText contenía una instrucción DELETE, INSERT o UPDATE y el nombre de tabla especificado no existía. *StatementText contenía una instrucción CREATE TABLE y una tabla especificada en una restricción (que hace referencia a una tabla distinta de la que se está creando) no existía. |
| 42S11 | El índice ya existe | *StatementText contenía una instrucción CREATE INDEX y el nombre de índice especificado ya existía. |
| 42S12 | No se encontró el índice | *StatementText contenía una instrucción DROP INDEX y el nombre de índice especificado no existía. |
| 42S21 | La columna ya existe | *StatementText contenía una instrucción ALTER TABLE y la columna especificada en la cláusula ADD no es única ni identifica una columna existente en la tabla base. |
| 42S22 | No se encontró la columna. | *StatementText contenía una instrucción CREATE INDEX y uno o varios de los nombres de columna especificados en la lista de columnas no existían. *StatementText contenía una instrucción GRANT o REVOKE y no existía un nombre de columna especificado. *StatementText contenía una instrucción SELECT, DELETE, INSERT o UPDATE y no existía un nombre de columna especificado. *StatementText contenía una instrucción CREATE TABLE y una columna especificada en una restricción (que hace referencia a una tabla distinta de la que se está creando) no existía. |
| HY000 | Error general | Se produjo un error para el que no había ningún SQLSTATE específico y para el que no se definió SQLSTATE específico de la implementación. El mensaje de error devuelto por SQLGetDiagRec en el búfer *MessageText describe el error y su causa. |
| HY001 | Error de asignación de memoria | El controlador no pudo asignar memoria necesaria para admitir la ejecución o finalización de la función. |
| HY008 | Operación cancelada | El procesamiento asincrónico se ha habilitado para StatementHandle. Se llamó a la función y antes de completar la ejecución, se llamó a SQLCancel o SQLCancelHandle en StatementHandle y, a continuación, se llamó a la función de nuevo en StatementHandle. Se llamó a la función y antes de completar la ejecución, se llamó a SQLCancel o SQLCancelHandle en statementHandle desde un subproceso diferente en una aplicación multiproceso. |
| HY009 | Uso no válido del puntero nulo | (DM) StatementText era un puntero nulo. |
| HY010 | Error de secuencia de funciones | (DM) Se llamó a una función de ejecución asincrónica para el identificador de conexión asociado a StatementHandle. Esta función asincrónica todavía se estaba ejecutando cuando se llamó a la función SQLPrepare . (DM) SQLExecute, SQLExecDirect o SQLMoreResults se llamó a para statementHandle y devolvió SQL_PARAM_DATA_AVAILABLE. Se llamó a esta función antes de recuperar los datos para todos los parámetros transmitidos. (DM) Se llamó a una función que ejecuta de forma asincrónica (no esta) para statementHandle y todavía se estaba ejecutando cuando se llamó a esta función. (DM) SE llamó a SQLExecute, SQLExecDirect, SQLBulkOperations o SQLSetPos para el statementHandle y devolvió SQL_NEED_DATA. Se llamó a esta función antes de enviar datos para todos los parámetros o columnas de datos en ejecución. |
| HY013 | Error de administración de memoria | No se pudo procesar la llamada de función porque no se pudo tener acceso a los objetos de memoria subyacentes, posiblemente debido a condiciones de memoria baja. |
| HY090 | Longitud de búfer o cadena no válida | (DM) El argumento TextLength era menor o igual que 0, pero no igual a SQL_NTS. |
| HY117 | La conexión se suspende debido al estado de transacción desconocido. Solo se permiten las funciones de desconexión y solo lectura. | (DM) Para obtener más información sobre el estado suspendido, vea Función SQLEndTran. |
| HYC00 | Característica opcional no implementada | La configuración de simultaneidad no era válida para el tipo de cursor definido. El atributo de instrucción SQL_ATTR_USE_BOOKMARKS se estableció en SQL_UB_VARIABLE y el atributo de instrucción SQL_ATTR_CURSOR_TYPE se estableció en un tipo de cursor para el que el controlador no admite marcadores. |
| HYT00 | Se ha agotado el tiempo de espera | El período de tiempo de espera expirado antes de que el origen de datos devuelva el conjunto de resultados. El período de tiempo de espera se establece mediante SQLSetStmtAttr, SQL_ATTR_QUERY_TIMEOUT. |
| HYT01 | Se ha agotado el tiempo de espera de la conexión. | El período de tiempo de espera de conexión expiró antes de que el origen de datos respondiera a la solicitud. El período de tiempo de espera de conexión se establece a través de SQLSetConnectAttr, SQL_ATTR_CONNECTION_TIMEOUT. |
| IM001 | El controlador no admite esta función | (DM) El controlador asociado a StatementHandle no admite la función . |
| IM017 | El sondeo está deshabilitado en modo de notificación asincrónica | Cada vez que se usa el modelo de notificación, el sondeo está deshabilitado. |
| IM018 | No se ha llamado a SQLCompleteAsync para completar la operación asincrónica anterior en este identificador. | Si la llamada de función anterior en el identificador devuelve SQL_STILL_EXECUTING y si el modo de notificación está habilitado, se debe llamar a SQLCompleteAsync en el identificador para realizar el procesamiento posterior y completar la operación. |
Comentarios
La aplicación llama a SQLPrepare para enviar una instrucción SQL al origen de datos para su preparación. Para obtener más información sobre la ejecución preparada, consulte Ejecución preparada. La aplicación puede incluir uno o varios marcadores de parámetro en la instrucción SQL. Para incluir un marcador de parámetro, la aplicación inserta un signo de interrogación (?) en la cadena SQL en la posición adecuada. Para obtener información sobre los parámetros, vea Parámetros de instrucción.
Nota:
Si una aplicación usa SQLPrepare para preparar y SQLExecute para enviar una instrucción COMMIT o ROLLBACK , no será interoperable entre productos DBMS. Para confirmar o revertir una transacción, llame a SQLEndTran.
El controlador puede modificar la instrucción para usar la forma de SQL que usa el origen de datos y, a continuación, enviarla al origen de datos para su preparación. En concreto, el controlador modifica las secuencias de escape usadas para definir la sintaxis SQL para determinadas características. (Para obtener una descripción de la gramática de instrucciones SQL, consulte Secuencias de escape en ODBC y apéndice C: Gramática SQL). Para el controlador, un identificador de instrucción es similar a un identificador de instrucción en el código SQL incrustado. Si el origen de datos admite identificadores de instrucción, el controlador puede enviar un identificador de instrucción y valores de parámetro al origen de datos.
Una vez preparada una instrucción, la aplicación usa el identificador de instrucción para hacer referencia a la instrucción en llamadas de función posteriores. La instrucción preparada asociada al identificador de instrucción se puede volver a ejecutar mediante una llamada a SQLExecute hasta que la aplicación libere la instrucción con una llamada a SQLFreeStmt con la opción SQL_DROP o hasta que se use el identificador de instrucción en una llamada a SQLPrepare, SQLExecDirect o una de las funciones de catálogo (SQLColumns, SQLTables, etc.). Una vez que la aplicación prepare una instrucción, puede solicitar información sobre el formato del conjunto de resultados. En algunas implementaciones, llamar a SQLDescribeCol o SQLDescribeParam después de SQLPrepare podría no ser tan eficaz como llamar a la función después de SQLExecute o SQLExecDirect.
Algunos controladores no pueden devolver errores de sintaxis ni infracciones de acceso cuando la aplicación llama a SQLPrepare. Un controlador puede controlar errores de sintaxis y infracciones de acceso, solo errores de sintaxis o ni errores de sintaxis ni infracciones de acceso. Por lo tanto, una aplicación debe poder controlar estas condiciones al llamar a funciones relacionadas posteriores, como SQLNumResultCols, SQLDescribeCol, SQLColAttribute y SQLExecute.
En función de las funcionalidades del controlador y del origen de datos, la información de parámetros (como los tipos de datos) se puede comprobar cuando se prepara la instrucción (si se han enlazado todos los parámetros) o cuando se ejecuta (si no se han enlazado todos los parámetros). Para obtener la interoperabilidad máxima, una aplicación debe desenlatar todos los parámetros que se aplicaron a una instrucción SQL anterior antes de preparar una nueva instrucción SQL en la misma instrucción. Esto evita errores que se deben a que se aplica información antigua de parámetros a la nueva instrucción.
Importante
Confirmar una transacción, ya sea llamando explícitamente a SQLEndTran o trabajando en modo de confirmación automática, puede hacer que el origen de datos elimine los planes de acceso de todas las instrucciones de una conexión. Para obtener más información, vea los tipos de información de SQL_CURSOR_COMMIT_BEHAVIOR y SQL_CURSOR_ROLLBACK_BEHAVIOR en SQLGetInfo y Effect of Transactions on Cursors and Prepared Statements (Efectos de transacciones en cursores e instrucciones preparadas).
Ejemplo de código
Consulte SQLBindParameter, SQLPutData y SQLSetPos.
Funciones relacionadas
| Para obtener información sobre | Vea |
|---|---|
| Asignar un identificador de instrucción | Función SQLAllocHandle |
| Enlazar un búfer a una columna de un conjunto de resultados | Función SQLBindCol |
| Enlace de un búfer a un parámetro | Función SQLBindParameter |
| Cancelación del procesamiento de instrucciones | Función SQLCancel |
| Ejecución de una operación de confirmación o reversión | Función SQLEndTran |
| Ejecución de una instrucción SQL | Función SQLExecDirect |
| Ejecución de una instrucción SQL preparada | Función SQLExecute |
| Devolver el número de filas afectadas por una instrucción | Función SQLRowCount |
| Establecimiento de un nombre de cursor | Función SQLSetCursorName |