Función SQLNativeSql

  • Artículo

Conformidad
Versión introducida: Cumplimiento de estándares ODBC 1.0: ODBC

Resumen
SQLNativeSql devuelve la cadena SQL modificada por el controlador. SQLNativeSql no ejecuta la instrucción SQL.

Sintaxis

  
SQLRETURN SQLNativeSql(  
     SQLHDBC        ConnectionHandle,  
     SQLCHAR *      InStatementText,  
     SQLINTEGER     TextLength1,  
     SQLCHAR *      OutStatementText,  
     SQLINTEGER     BufferLength,  
     SQLINTEGER *   TextLength2Ptr);

Argumentos

ConnectionHandle
[Entrada] Identificador de conexión.

InStatementText
[Entrada] Cadena de texto SQL que se va a traducir.

TextLength1
[Entrada] Longitud en caracteres de la cadena de texto *InStatementText .

OutStatementText
[Salida] Puntero a un búfer en el que se va a devolver la cadena SQL traducida.

Si OutStatementText es NULL, TextLength2Ptr seguirá devolviendo el número total de caracteres (excepto el carácter de terminación NULL para los datos de caracteres) disponible para devolver en el búfer al que apunta OutStatementText.

BufferLength
[Entrada] Número de caracteres en el búfer *OutStatementText . Las versiones anteriores de esta documentación implicaban erróneamente que este recuento de caracteres debe ser incluso si el valor devuelto en *InStatementText es una cadena Unicode (al llamar a SQLNativeSqlW). No hay ninguna restricción de este tipo. Para lograr una interoperabilidad óptima, los escritores de controladores deben esperar que se pase cualquier recuento de caracteres a esta función, mientras que se recomienda que los escritores de aplicaciones siempre usen un recuento par.

TextLength2Ptr
[Salida] Puntero a un búfer en el que devolver el número total de caracteres (excepto la terminación null) disponible para devolver en *OutStatementText. Si el número de caracteres disponibles para devolver es mayor o igual que BufferLength, la cadena SQL traducida en *OutStatementText se trunca en BufferLength menos la longitud de un carácter de terminación NULL.

Devoluciones

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR o SQL_INVALID_HANDLE.

Diagnóstico

Cuando SQLNativeSql devuelve SQL_ERROR o SQL_SUCCESS_WITH_INFO, se puede obtener un valor SQLSTATE asociado llamando a SQLGetDiagRec con un HandleType de SQL_HANDLE_DBC y un identificador de ConnectionHandle. En la tabla siguiente se enumeran los valores SQLSTATE devueltos normalmente por SQLNativeSql 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).
01004 Datos de cadena, truncados a la derecha El búfer *OutStatementText no era lo suficientemente grande como para devolver toda la cadena SQL, por lo que la cadena SQL se truncaba. La longitud de la cadena SQL notruncada se devuelve en *TextLength2Ptr. (Function devuelve SQL_SUCCESS_WITH_INFO).
08003 Conexión no abierta ConnectionHandle no estaba en estado conectado.
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.
22007 Formato datetime no válido *InStatementText contenía una cláusula de escape con un valor de fecha, hora o marca de tiempo no válidos.
24000 Estado de cursor no válido El cursor al que se hace referencia en la instrucción se colocó antes del inicio del conjunto de resultados o después del final del conjunto de resultados. Es posible que un controlador no devuelva este error que tenga una implementación nativa del cursor de DBMS.
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.
HY009 Uso no válido del puntero nulo (DM) *InStatementText era un puntero nulo.
HY010 Error de secuencia de funciones (DM) Se llamó a una función de ejecución asincrónica para ConnectionHandle y todavía se estaba ejecutando cuando se llamó a esta funció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 TextLength1 era menor que 0, pero no igual a SQL_NTS.
(DM) El argumento BufferLength era menor que 0 y el argumento OutStatementText no era un puntero nulo.
HY109 Posición del cursor no válida Se ha eliminado o no se ha capturado la fila actual del cursor. Es posible que un controlador no devuelva este error que tenga una implementación nativa del cursor de DBMS.
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.
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 ConnectionHandle no admite la función .

Comentarios

A continuación se muestran ejemplos de lo que SQLNativeSql podría devolver para la siguiente cadena SQL de entrada que contiene la función escalar CONVERT. Supongamos que el empid de columna es de tipo INTEGER en el origen de datos:

SELECT { fn CONVERT (empid, SQL_SMALLINT) } FROM employee

Un controlador para Microsoft SQL Server podría devolver la siguiente cadena SQL traducida:

SELECT convert (smallint, empid) FROM employee

Un controlador para ORACLE Server podría devolver la siguiente cadena SQL traducida:

SELECT to_number (empid) FROM employee

Un controlador para Entrada podría devolver la siguiente cadena SQL traducida:

SELECT int2 (empid) FROM employee

Para obtener más información, consulte Ejecución directa y Ejecución preparada.

Ninguno.

Consulte también

Referencia de API ODBC
Archivos de encabezado de ODBC