Apéndice B: Tablas de transición de estado de ODBC

Las tablas de este apéndice muestran cómo las funciones ODBC provocan transiciones del entorno, la conexión, la instrucción y los estados descriptores. El estado del entorno, la conexión, la instrucción o el descriptor normalmente dicta cuándo se pueden llamar a las funciones que usan el tipo de identificador correspondiente (entorno, conexión, instrucción o descriptor). Los estados de entorno, conexión, instrucción y descriptor se superponen aproximadamente, como se muestra en las ilustraciones siguientes. Por ejemplo, la superposición exacta de los estados de conexión C5 y C6 y los estados de instrucción S1 a S12 depende del origen de datos, ya que las transacciones comienzan en momentos diferentes en orígenes de datos diferentes y el estado de descriptor D1i (descriptor asignado implícitamente) depende del estado de la instrucción con la que está asociado el descriptor, mientras que el estado D1e (descriptor asignado explícitamente) es independiente del estado de cualquier instrucción. Para obtener una descripción de cada estado, vea Transiciones de entorno, Transiciones de conexión, Transiciones de instrucción y Transiciones de descriptor, más adelante en este apéndice.

El entorno y los estados de conexión se superponen de la siguiente manera:

Los estados de conexión y instrucción se superponen de la siguiente manera:

Los estados de instrucción y descriptor se superponen de la siguiente manera:

Los estados de conexión y descriptor se superponen de la siguiente manera:

Cada entrada de una tabla de transición puede ser uno de los siguientes valores:

• -- -El estado no cambia después de ejecutar la función.

• E

  n , C_n_, S_n_ o D_n_ : el entorno, la conexión, la instrucción o el estado del descriptor se mueve al estado especificado.

• (IH): se pasó un identificador no válido a la función. Si el identificador era un identificador nulo o era un identificador válido del tipo incorrecto (por ejemplo, se pasó un identificador de conexión cuando se requería un identificador de instrucción), la función devuelve SQL_INVALID_HANDLE; de lo contrario, el comportamiento no está definido y probablemente fatal. Este error solo se muestra cuando es el único resultado posible de llamar a la función en el estado especificado. Este error no cambia el estado y siempre lo detecta el Administrador de controladores, como se indica entre paréntesis.

• NS : siguiente estado. La transición de la instrucción es la misma que si la instrucción no hubiera pasado por los estados asincrónicos. Por ejemplo, supongamos que una instrucción que crea un conjunto de resultados entra en el estado S11 a partir del estado S1 porque SQLExecDirect devolvió SQL_STILL_EXECUTING. La notación NS en el estado S11 significa que las transiciones de la instrucción son las mismas que las de una instrucción en el estado S1 que crea un conjunto de resultados. Si SQLExecDirect devuelve un error, la instrucción permanece en el estado S1; si se realiza correctamente, la instrucción se mueve al estado S5; si necesita datos, la instrucción pasa al estado S8; y si todavía se está ejecutando, permanece en el estado S11.

• XXXXX o (XXXXX): SQLSTATE relacionado con la tabla de transición; Los SQLSTATEs detectados por el Administrador de controladores se incluyen entre paréntesis. La función devolvió SQL_ERROR y sqlSTATE especificado, pero el estado no cambia. Por ejemplo, si se llama a SQLExecute antes de SQLPrepare, devuelve SQLSTATE HY010 (error de secuencia de función).

Nota

Las tablas no muestran errores no relacionados con las tablas de transición que no cambian el estado. Por ejemplo, cuando se llama a SQLAllocHandle en el estado de entorno E1 y devuelve SQLSTATE HY001 (error de asignación de memoria), el entorno permanece en el estado E1; Esto no se muestra en la tabla de transición del entorno para SQLAllocHandle.

Si el entorno, la conexión, la instrucción o el descriptor pueden moverse a más de un estado, se muestra cada estado posible y una o varias notas al pie explican las condiciones en las que tiene lugar cada transición. Las notas al pie siguientes pueden aparecer en cualquier tabla.

Nota	Significado
b	Antes o después. El cursor se colocaba antes del inicio del conjunto de resultados o después del final del conjunto de resultados.
c	Función actual. La función actual se estaba ejecutando de forma asincrónica.
d	Necesita datos. La función devolvió SQL_NEED_DATA.
e	Error. La función devolvió SQL_ERROR.
i	Fila no válida. El cursor se ha colocado en una fila del conjunto de resultados y se ha eliminado la fila o se ha producido un error en una operación en la fila. Si existía la matriz de estado de fila, el valor de la matriz de estado de fila de la fila se SQL_ROW_DELETED o SQL_ROW_ERROR. (El atributo de instrucción SQL_ATTR_ROW_STATUS_PTR apunta a la matriz de estado de fila).
nf	Not found. La función devolvió SQL_NO_DATA. Esto no se aplica cuando SQLExecDirect, SQLExecute o SQLParamData devuelve SQL_NO_DATA después de ejecutar una instrucción de actualización o eliminación buscada.
np	No está preparado. La instrucción no se preparó.
nr	Especifica que no hay resultados. La instrucción no creará o no creó un conjunto de resultados.
o	Otra función. Otra función se estaba ejecutando de forma asincrónica.
p	Preparado. La instrucción se preparó.
r	Resultados. La instrucción creará o creó un conjunto de resultados (posiblemente vacío).
d	Correcto. La función devolvió SQL_SUCCESS_WITH_INFO o SQL_SUCCESS.
v	Fila válida. El cursor se colocaba en una fila del conjunto de resultados y la fila se había insertado correctamente, actualizado correctamente u otra operación en la fila se había completado correctamente. Si existía la matriz de estado de fila, el valor de la matriz de estado de fila de la fila se SQL_ROW_ADDED, SQL_ROW_SUCCESS o SQL_ROW_UPDATED. (El atributo de instrucción SQL_ATTR_ROW_STATUS_PTR apunta a la matriz de estado de fila).
x	En ejecución. La función devolvió SQL_STILL_EXECUTING.

SQLFreeHandle

En este ejemplo, la fila de la tabla de transición de estado del entorno para SQLFreeHandle cuando HandleType es SQL_HANDLE_ENV es la siguiente.

E0 Sin asignar	E1 Allocated	E2 Conexión
(IH)	E0	(HY010)

Si se llama a SQLFreeHandle en estado de entorno E0 con HandleType establecido en SQL_HANDLE_ENV, el Administrador de controladores devuelve SQL_INVALID_HANDLE. Si se llama en el estado E1 con HandleType establecido en SQL_HANDLE_ENV, el entorno pasa al estado E0 si la función se realiza correctamente y permanece en estado E1 si se produce un error en la función. Si se llama en el estado E2 con HandleType establecido en SQL_HANDLE_ENV, el Administrador de controladores siempre devuelve SQL_ERROR y SQLSTATE HY010 (error de secuencia de función) y el entorno permanece en estado E2.

Para comprender las tablas de transición de estado, es necesario comprender a qué elemento (entorno, conexión, instrucción o descriptor) hacen referencia. Supongamos que una función acepta el identificador de un elemento de tipo X. La tabla de transición de estado X para esa función describe cómo llamar a la función, con el identificador de un elemento de tipo X, afecta a ese elemento. Por ejemplo, SQLDisconnect acepta un identificador de conexión. La tabla de transición de estado de conexión para SQLDisconnect describe cómo SQLDisconnect afecta al estado de la conexión para la que se llama.

Supongamos que una función acepta el identificador de un elemento de tipo Y, donde Y no es igual a X. La tabla de transición de estado X para esa función describe cómo llamar a la función, con un identificador de tipo X asociado al elemento de tipo Y, afecta al elemento de tipo Y. Por ejemplo, la tabla de transición de estado de la instrucción para SQLDisconnect describe cómo SQLDisconnect afecta al estado de una instrucción cuando se llama con el identificador de la conexión con la que está asociada la instrucción.

Este apéndice contiene los temas siguientes.

• Transiciones de entorno

• Transiciones de conexión

• Transiciones de instrucción

• Transiciones de descriptor