Función SQLSetCursorName

  • Artículo

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

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 el primer carácter del 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.
34000 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 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 aynchronous 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 la instrucciónHandle 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 acceder 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 que SQL_NTS.
HY117 La conexión se suspende debido a un 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 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, 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, 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 no 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 un nombre de cursor debe tratarse de una manera que distingue mayúsculas de 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 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, consulte 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
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