Función SQLNativeSql
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.
Funciones relacionadas
Ninguno.