SQLPrepare--Preparar una sentencia

Finalidad

Especificación:

CLI de DB2 1.1

ODBC 1.0

ISO CLI

SQLPrepare() asocia una sentencia de SQL con el descriptor de sentencia de entrada y envía la sentencia al DBMS para que se prepare. La aplicación puede hacer referencia a esta sentencia preparada pasando el descriptor de sentencia a otras funciones.

Si previamente se utiliza el descriptor de contexto de sentencia con una sentencia de consulta (o cualquier función que devuelva un conjunto resultante), se debe llamar a SQLFreeStmt() antes de llamar a SQLPrepare().

Sintaxis

SQLRETURN   SQLPrepare       (SQLHSTMT          StatementHandle,   /* hstmt */
                              SQLCHAR      FAR  *StatementText,    /* szSqlStr */
                              SQLINTEGER        TextLength);       /* cbSqlStr */

Argumentos de la función

Tabla 74. Argumentos de SQLPrepare

Tipo de datos	Argumento	Uso	Descripción
SQLHSTMT	`StatementHandle`	entrada	Descriptor de contexto de sentencia.
SQLCHAR	`StatementText`	entrada	Serie de la sentencia de SQL
SQLINTEGER	`TextLength`	entrada	Longitud del contenido del argumento `StatementText`. Se debe establecer en la longitud exacta de la sentencia de SQL contenida en `szSqlstr`, o en SQL_NTS si el texto de la sentencia termina en nulo.

Uso

Después de preparar una sentencia utilizando SQLPrepare(), la aplicación puede solicitar información sobre el formato del conjunto resultante (si la sentencia es una consulta), llamando a una de estas funciones:

SQLNumResultCols()
SQLDescribeCol()

La serie de la sentencia de SQL puede contener marcadores de parámetros. Un marcador de parámetro se representa mediante un símbolo ? y se utiliza para indicar una posición en la sentencia donde se colocará un valor proporcionado por la aplicación cuando se llame a SQLExecute(). La función de enlace de parámetros, SQLBindParameter(), enlaza (asocia) valores de la aplicación con cada marcador de parámetro e indica si se debe realizar alguna conversión de datos al transferir los datos.

Se deben enlazar todos los parámetros antes de invocar SQLExecute(). Si desea obtener más información, consulte el apartado SQLExecute--Ejecutar una sentencia.

Consulte la sección sobre la sentencia PREPARE del manual DB2 Universal Database Consulta de SQL para obtener información sobre reglas referentes a marcadores de parámetros.

Después de procesar los resultados de la llamada a SQLExecute(), la aplicación puede ejecutar de nuevo la sentencia con valores de parámetros nuevos (o los mismos).

Códigos de retorno

SQL_SUCCESS
SQL_SUCCESS_WITH_INFO
SQL_ERROR
SQL_INVALID_HANDLE

Diagnósticos

Tabla 75. SQLSTATE de SQLPrepare

SQLSTATE	Descripción	Explicación
42nnn	Error de sintaxis.	Los SQLSTATE 42nnn indican que hay varios problemas de sintaxis o de acceso en la sentencia. Los caracteres nnn representan cualquier SQLSTATE con ese código de clase. Ejemplo: 42nnn representa cualquier SQLSTATE perteneciente a la clase 42.
58004	Error inesperado del sistema.	Error no recuperable del sistema.
HY001	Error de asignación de memoria.	DB2 CLI no puede asignar la memoria necesaria para ejecutar o finalizar la función.
HY009	Valor no válido de argumento.	`StatementText` es un puntero nulo.
HY013	Error inesperado de gestión de la memoria.	DB2 CLI no puede acceder a la memoria necesaria para ejecutar o finalizar la función.
HY014	No hay más descriptores de contexto.	DB2 CLI no puede asignar un descriptor de contexto debido a los recursos internos.
HY090	Longitud no válida de la serie de caracteres o del almacenamiento intermedio.	El argumento `TextLength` es menor que uno pero no igual a SQL_NTS.

Restricciones

Ninguna.

Consulta relacionada