Compartir vía


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);  
}  
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

Consulte también

Referencia de API ODBC
Archivos de encabezado de ODBC