Función SQLSetCursorName
Conformidad
Versión introducida: Cumplimiento de estándares ODBC 1.0: ISO 92
Resumen
SQLSetCursorName asocia un nombre de cursor a una instrucción activa. Si una aplicación no llama a SQLSetCursorName, el controlador genera nombres de cursor según sea necesario para el procesamiento de instrucciones SQL.
Sintaxis
SQLRETURN SQLSetCursorName(
SQLHSTMT StatementHandle,
SQLCHAR * CursorName,
SQLSMALLINT NameLength);
Argumentos
StatementHandle
[Entrada] Identificador de instrucciones.
CursorName
[Entrada] Nombre del cursor. Para un procesamiento eficaz, el nombre del cursor no debe incluir ningún espacio inicial o final en el nombre del cursor y, si el nombre del cursor incluye un identificador delimitado, el delimitador debe colocarse como primer carácter en el nombre del cursor.
NameLength
[Entrada] Longitud en caracteres de *CursorName.
Devoluciones
SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR o SQL_INVALID_HANDLE.
Diagnóstico
Cuando SQLSetCursorName 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 SQLSetCursorName 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 nombre del cursor superó el límite máximo, por lo que solo se usó el número máximo permitido de caracteres. |
| 24000 | Estado de cursor no válido | La instrucción correspondiente a StatementHandle ya estaba en estado ejecutado o colocado en cursor. |
| 34 000 | Nombre de cursor no válido | El nombre del cursor especificado en *CursorName no era válido porque superó la longitud máxima definida por el controlador, o se inició con "SQLCUR" o "SQL_CUR". |
| 3C000 | Nombre de cursor duplicado | El nombre del cursor especificado en *CursorName ya existe. |
| 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) El argumento CursorName era un puntero nulo. |
| 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 ayncrónica todavía se estaba ejecutando cuando se llamó a la función SQLSetCursorName . (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. |
| HY090 | Longitud de búfer o cadena no válida | (DM) El argumento NameLength era menor que 0, pero no igual a SQL_NTS. |
| 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, al ejecutar una instrucción de consulta, el controlador genera un nombre que comienza con las letras SQL_CUR y no supera los 18 caracteres de longitud.
Todos los nombres de cursor dentro de la conexión deben ser únicos. El controlador define la longitud máxima de un nombre de cursor. Para obtener la interoperabilidad máxima, se recomienda que las aplicaciones limiten los nombres de cursor a más de 18 caracteres. En ODBC 3*.x*, si un nombre de cursor es un identificador entre comillas, se trata de manera que distingue mayúsculas de minúsculas y puede contener caracteres que la sintaxis de SQL no permitiría o trataría especialmente, como espacios en blanco o palabras clave reservadas. Si se debe tratar un nombre de cursor de una manera que distingue mayúsculas de minúsculas, debe pasarse como un identificador entre comillas.
Un nombre de cursor que se establece explícita o implícitamente permanece establecido hasta que se quita la instrucción con la que está asociada, mediante SQLFreeHandle. 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.
Ejemplo de código
En el ejemplo siguiente, una aplicación usa SQLSetCursorName para establecer un nombre de cursor para una instrucción. A continuación, usa esa instrucción para recuperar los resultados de la tabla CUSTOMERS. Por último, realiza una actualización posicionada para cambiar el número de teléfono de John Smith. Tenga en cuenta que la aplicación usa diferentes identificadores de instrucción para las instrucciones SELECT y UPDATE .
Para obtener otro ejemplo de código, vea SQLSetPos.
#define NAME_LEN 50
#define PHONE_LEN 10
SQLHSTMT hstmtSelect,
SQLHSTMT hstmtUpdate;
SQLRETURN retcode;
SQLHDBC hdbc;
SQLCHAR szName[NAME_LEN], szPhone[PHONE_LEN];
SQLINTEGER cbName, cbPhone;
/* Allocate the statements and set the cursor name. */
SQLAllocHandle(SQL_HANDLE_STMT, hdbc, &hstmtSelect);
SQLAllocHandle(SQL_HANDLE_STMT, hdbc, &hstmtUpdate);
SQLSetCursorName(hstmtSelect, "C1", SQL_NTS);
/* SELECT the result set and bind its columns to local buffers. */
SQLExecDirect(hstmtSelect,
"SELECT NAME, PHONE FROM CUSTOMERS",
SQL_NTS);
SQLBindCol(hstmtSelect, 1, SQL_C_CHAR, szName, NAME_LEN, &cbName);
SQLBindCol(hstmtSelect, 2, SQL_C_CHAR, szPhone, PHONE_LEN, &cbPhone);
/* Read through the result set until the cursor is */
/* positioned on the row for John Smith. */
do
retcode = SQLFetch(hstmtSelect);
while ((retcode == SQL_SUCCESS || retcode == SQL_SUCCESS_WITH_INFO) &&
(strcmp(szName, "Smith, John") != 0));
/* Perform a positioned update of John Smith's name. */
if (retcode == SQL_SUCCESS || retcode == SQL_SUCCESS_WITH_INFO) {
SQLExecDirect(hstmtUpdate,
"UPDATE EMPLOYEE SET PHONE=\"2064890154\" WHERE CURRENT OF C1",
SQL_NTS);
}
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 |
| Devolver un nombre de cursor | Función SQLGetCursorName |
| Configuración de las opciones de desplazamiento del cursor | Función SQLSetScrollOptions |