Función SQLSetCursorName

Conformidad
Versión introducida: compatibilidad con estándares de 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
Entradas Identificador de instrucción.

CursorName
Entradas 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 el primer carácter del nombre del cursor.

NameLength
Entradas 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 de SQLSTATE que devuelve normalmente SQLSetCursorName y se explica cada uno de ellos 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. (La función 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 de caracteres permitido.
24000 Estado de cursor no válido La instrucción correspondiente a StatementHandle ya estaba en un estado ejecutado o situado en el cursor.
34000 Nombre de cursor no válido El nombre de cursor especificado en *CursorName no era válido porque superó la longitud máxima tal como la define el controlador o comenzó con "SQLCUR" o "SQL_CUR".
3C000 Nombre de cursor duplicado El nombre de 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ó ningún 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 la memoria necesaria para admitir la ejecución o la finalización de la función.
HY009 Uso no válido de puntero nulo (DM) el argumento CursorName era un puntero nulo.
HY010 Error de secuencia de función (DM) se llamó a una función que se ejecuta de forma asincrónica para el identificador de conexión que está asociado a StatementHandle. Esta función aynchronous todavía se estaba ejecutando cuando se llamó a la función SQLSetCursorName .

(DM) se llamó a una función que se ejecuta de forma asincrónica para StatementHandle y que todavía se estaba ejecutando cuando se llamó a esta función.

Se llamó a SQLExecute, SQLExecDirect, SQLBulkOperations o SQLSetPos para StatementHandle y se devolvió SQL_NEED_DATA. Se llamó a esta función antes de enviar los 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 insuficientes.
HY090 Longitud de búfer o cadena no válida (DM) el argumento NameLength era menor que 0 pero no es igual a SQL_NTS.
HY117 La conexión se suspendió debido a un estado de transacción desconocido. Solo se permiten las funciones de desconexión y de solo lectura. (DM) para obtener más información sobre el estado suspendido, consulte función SQLEndTran.
HYT01 Tiempo de espera de conexión agotado Expiró el tiempo de espera de conexión antes de que el origen de datos respondiera a la solicitud. El período de tiempo de espera de la conexión se establece mediante 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 las instrucciones Update y DELETE posicionadas (por ejemplo, Update TABLE-Name ... Donde Current of cursor-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, en la ejecución de 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 máxima interoperabilidad, se recomienda que las aplicaciones limiten los nombres de cursor a un máximo de 18 caracteres. En ODBC 3 . x, si un nombre de cursor es un identificador entre comillas, se trata de manera que distingue entre mayúsculas y 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 un nombre de cursor se debe tratar de manera que distinga entre mayúsculas y minúsculas, se debe pasar 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 a 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, utiliza 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 utiliza identificadores de instrucciones diferentes 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 información acerca de Vea
Ejecutar una instrucción SQL Función SQLExecDirect
Ejecutar una instrucción SQL preparada Función SQLExecute
Devolver un nombre de cursor Función SQLGetCursorName
Establecer opciones de desplazamiento del cursor Función SQLSetScrollOptions

Consulte también

Referencia de la API de ODBC
Archivos de encabezado de ODBC