Función SQLGetCursorName

  • Artículo

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

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 a 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 el nombre completo del cursor, por lo que el nombre del cursor se truncaba. La longitud del nombre del cursor notruncado 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 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 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 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 funciones de desconexión y de 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 responda 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, UPDATEtable-name ... WHERE CURRENT OFcursor-name). Para obtener más información, vea Instrucciones Update y Delete 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 (sin 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.

Para información acerca de 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

Consulte también

Referencia de API ODBC
Archivos de encabezado de ODBC