Función SQLPrepare

  • Artículo

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 instrucción.

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 Insertar lista de valores 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 no era compatible 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 "LIKEpattern valueESCAPEescape character" en la cláusula WHERE y el carácter que sigue al carácter de escape en el valor del 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 .
34000 Nombre de cursor no válido *StatementText contenía una 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 o vista base *StatementText contenía una instrucción CREATE TABLE o CREATE VIEW , y el nombre de tabla o nombre de vista especificado 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 el nombre de 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 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 Columna no encontrada *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 función (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) SE llamó a SQLExecute, SQLExecDirect o SQLMoreResults para la instrucciónHandle 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 de ejecución 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 la instrucciónHandle 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 acceder 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 que SQL_NTS.
HY117 La conexión se suspende debido a un estado de transacción desconocido. Solo se permiten funciones de desconexión y de 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 Tiempo de espera agotado 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 a través de 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ámetros 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 los productos de 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, vea 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 llamando 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 prepara 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.

Según las funcionalidades del controlador y el 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 desenlazar 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 de parámetro antigua 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 SQL_CURSOR_COMMIT_BEHAVIOR y SQL_CURSOR_ROLLBACK_BEHAVIOR en SQLGetInfo y El efecto de las transacciones en cursores e instrucciones preparadas.

Ejemplo de código

Consulte SQLBindParameter, SQLPutData y SQLSetPos.

Para información acerca de Vea
Asignar un identificador de instrucción Función SQLAllocHandle
Enlace de un búfer a una columna de un conjunto de resultados SQLBindCol (función)
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

Consulte también

Referencia de API ODBC
Archivos de encabezado de ODBC