Función SQLGetCursorName
Conformidad
Versión introducida: Cumplimiento de estándares ODBC 1.0: ISO 92
Resumen
SQLGetCursorName devuelve el nombre del cursor asociado a una instrucción especificada.
Sintaxis
SQLRETURN SQLGetCursorName(
SQLHSTMT StatementHandle,
SQLCHAR * CursorName,
SQLSMALLINT BufferLength,
SQLSMALLINT * NameLengthPtr);
Argumentos
StatementHandle
[Entrada] Identificador de instrucciones.
CursorName
[Salida] Puntero a un búfer en el que se va a devolver el nombre del cursor.
Si CursorName es NULL, NameLengthPtr 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 CursorName.
BufferLength
[Entrada] Longitud de *CursorName, en caracteres.
NameLengthPtr
[Salida] Puntero a la memoria en la que se devuelve el número total de caracteres (excepto el carácter de terminación NULL) disponible para devolver en *CursorName. Si el número de caracteres disponibles para devolver es mayor o igual que BufferLength, el nombre del cursor de *CursorName 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 SQLGetCursorName 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 SQLGetCursorName 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 *CursorName no era lo suficientemente grande como para devolver todo el nombre del cursor, por lo que el nombre del cursor se truncaba. La longitud del nombre del cursor sintruir se devuelve en *NameLengthPtr. (Function devuelve SQL_SUCCESS_WITH_INFO). |
| 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. |
| 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 SQLGetCursorName . (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 de ejecución asincrónica 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. |
| HY015 | No hay ningún nombre de cursor disponible | (DM) El controlador era un controlador ODBC 2*.x*, no había ningún cursor abierto en la instrucción y no se había establecido ningún nombre de cursor con SQLSetCursorName. |
| HY090 | Longitud de búfer o cadena no válida | (DM) El valor especificado en el argumento BufferLength era menor que 0. |
| 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 StatementHandle no admite la función . |
Comentarios
Los nombres de cursor solo se usan en instrucciones update y delete posicionadas (por ejemplo, UPDATE table-name ...WHERE CURRENT OF cursor-name). Para obtener más información, vea Instrucciones de actualización y eliminación posicionadas. Si la aplicación no llama a SQLSetCursorName para definir un nombre de cursor, el controlador genera un nombre. Este nombre comienza con las letras SQL_CUR.
Nota:
En ODBC 2*.x*, cuando no había ningún cursor abierto y no se había establecido ningún nombre mediante una llamada a SQLSetCursorName, una llamada a SQLGetCursorName devolvió SQLSTATE HY015 (no hay ningún nombre de cursor disponible). En ODBC 3*.x*, esto ya no es cierto; independientemente de cuándo se llame a SQLGetCursorName , el controlador devuelve el nombre del cursor.
SQLGetCursorName devuelve el nombre de un cursor si el nombre se creó explícita o implícitamente. Se genera implícitamente un nombre de cursor si no se llama a SQLSetCursorName . Se puede llamar a SQLSetCursorName para cambiar el nombre de un cursor en una instrucción siempre que el cursor esté en un estado asignado o preparado.
Un nombre de cursor que se establece explícita o implícitamente permanece establecido hasta que se quita statementHandle con el que está asociado, mediante SQLFreeHandle con un HandleType de SQL_HANDLE_STMT.
Funciones relacionadas
| Para obtener información sobre | Vea |
|---|---|
| Ejecución de una instrucción SQL | Función SQLExecDirect |
| Ejecución de una instrucción SQL preparada | Función SQLExecute |
| Preparación de una instrucción para su ejecución | Función SQLPrepare |
| Establecimiento de un nombre de cursor | Función SQLSetCursorName |