Tutorial de ADO.

Este tutorial ilustra como utilizar el modelo de programacin de ADO para hacer peticiones (queries) y actualizar una fuente de datos. Primero describe los pasos necesarios para realizar esta tarea. Luego el tutorial es repetido en Microsoft Visual Basic; Microsoft Visual C++ con Extensiones Visual C++ y Microsoft Visual J++, con ADO for Windows Foundation Classes (ADO/WFC).

Este tutorial est codificado en diferentes lenguajes por dos razones:

La documentacin de ADO asume que el lector codifica en Visual Basic. Esto hace la documentacin conveniente para los programadores de Visual Basic, pero menos til para los programadores que utilizan otros lenguajes.

Si Usted tiene alguna duda acerca de una funcin de ADO en particular y conoce un poco de otros lenguajes, puede ser capaz de resolver su duda al solo ver la misma funcin expresada en otro lenguaje.

Cmo se presenta el tutorial.

Este tutorial est dividido en pasos que corresponden al modelo de programacin ADO. Cada paso es discutido e ilustrado con un fragmento de cdigo de Visual Basic. Al final de este tutorial, todos los fragmentos de cdigo son integrados en un ejemplo de Visual Basic.

El ejemplo integrado es luego repetido en otros lenguajes de programacin. Cada paso en cada lenguaje de programacin esta numerado. Utilice el nmero del paso para referirse a la discusin correspondiente en este tutorial descriptivo.

El modelo de programacin ADO est enunciado ms abajo. Utilcelo como un mapa al avanzar a lo largo de este tutorial.

El modelo de programacin ADO con objetos.

Haga una conexin a una fuente de datos (Connection). Opcionalmente, comience una transaccin.

Opcionalmente, puede crear un objeto para representar un comando SQL (Command). Opcionalmente, especifique columnas, tablas y valores dentro del comando SQL con parmetros variables (Parameter). Ejecute el comando (Command, Connection o Recordset). Si el comando regresa filas, almacene las filas en un objeto de almacenamiento (Recordset). Opcionalmente, puede crear una vista del objeto de almacenamiento de forma que pueda navegar, ordenar y filtrar los datos (Recordset). Edite los datos, ya sea aadiendo, eliminando o cambiando filas o columnas (Recordset).

Si es apropiado, actualice la fuente de datos con los cambios desde el objeto de almacenamiento (Recordset). Si se utiliz una transaccin, acepte o rechace los cambios hechos durante la transaccin. Finalice la transaccin (Connection).

Paso 1: Abra una conexin.

Usted requiere de medios para establecer las condiciones necesarias para intercambiar datos, es decir, una conexin (connection). La fuente de datos a la que se conecte, esta especificada en una cadena de conexin, aunque los parmetros especificados en una cadena de conexin pueden diferir para cada proveedor y fuente de datos.

La manera principal en la que ADO abre una conexin es con el mtodo Connection.Open. Alternativamente, Usted puede invocar el mtodo abreviado, Recordset.Open, tanto para abrir una conexin como para enviar un comando sobre esa conexin en una sola operacin. La siguiente es la sintaxis para cada mtodo en Visual Basic:

connection.Open CadenaDeConexin, IDUsuario, Contrasea, OpcionesDeApertura recordset.Open Fuente, ConexinActiva, TipoDeCursor, TipoDeBloqueo, Opciones
El comparar estos dos mtodos se hacen notables algunas caractersticas tiles de los parmetros de los mtodos ADO en general.

Un parmetro de mtodo puede ser especificado de varias maneras. Por ejemplo, Recordset.Open utiliza un parmetro ConexinActiva, el cual podra ser una cadena de literales, una variable que representa una cadena o un objeto Connection que representa una conexin abierta.

Este tutorial utiliza la cadena de literales de conexin, "DSN=pubs;uid=sa;pwd=;". (Las fuentes de datos son indirectamente especificadas por la palabra clave "DSN=". Vea la seccin de "Cadenas de conexin tpicas" en "Microsoft OLE DB Provider for ODBC" para ms informacin).

Muchos objetos tienen propiedades que pueden proporcionar un argumento si un parmetro de mtodo es omitido. Por ejemplo, provea la informacin de la cadena de conexin para el mtodo Connection.Open al establecer la propiedad CadenaDeConexin (ConnectionString) del objeto Connection, luego omita el parmetro CadenaDeConexin del mtodo Open.

Este tutorial utiliza la siguiente declaracin del objeto Connection y el mtodo Open:

Dim cnn As New ADODB.Connection cnn.Open "DSN=pubs;uid=sa;pwd=;"

Paso 2: Creando un comando.

Un comando es una instruccin entendida por el proveedor de datos que modificar, administrar o manipular la fuente de datos. Los comandos son tpicamente escritos en SQL, aunque no se requiere un lenguaje en particular. Un comando de peticin (query) requiere que el proveedor de datos regrese un objeto Recordset que contiene filas de informacin.

Especifique un comando como cualquiera de los siguientes:

Texto comando, esto es, una cadena de literales o una variable que representa la cadena. Un objeto que representa al comando. En este caso, es el valor de una propiedad Comando (Command) de un objeto CommandText establecido como el texto del comando.

Este tutorial hace peticiones de toda la informacin en la tabla de authors en la base de datos pubs. El objeto Command es declarado, establecido con el objeto abrir Connection y el texto de comando. El cdigo luce como este:

Dim cmd As New ADODB.Command Set cmd.ActiveConnection = cnn cmd.CommandText = "SELECT * from authors"
Comandos parametrizados.
Los comandos pueden ser parametrizados. Un comando parametrizado consiste de un texto de comando que puede ser modificado con un valor especificado por el usuario cada vez que el comando es invocado.

Un comodn ("?") indica la parte del texto de comando que ser modificada. Cada comodn en el texto de comando ser reemplazado con el valor del objeto Parameter correspondiente en la coleccin Parameters cuando el comando sea ejecutado.

Hay dos maneras de crear un objeto Parameter y agregarlo a la coleccin Parameters del objeto Command. La primera manera es crear un objeto Parameter, establecer sus propiedades Nombre (Name), Tipo (Type), Direccin (Direction), Tamao (Size) y Valor (Value) individualmente, y luego agregarlo a la coleccin Parameters. La segunda manera es crear y establecer las propiedades del objeto Parameter con el mtodo CreateParameters del objeto Command, y luego agregar el objeto Parameter recin creado; todo en un solo estatuto.

Finalmente, llame a los mtodos Command.Execute o Recordset.Open para sustituir los parmetros por los comodines y obtener un Recordset. Cambie la propiedad Value del objeto Parameter por otro nombre. Entonces llame al mtodo Execute o a los mtodos Recordset.Close y Open de nuevo para obtener un nuevo Recordset de otro autor.

Optimice el desempeo del comando parametrizado con la propiedad Prepared. Note que el mtodo

Execute no puede especificar las propiedades CursorType o LockType del objeto recordset.

Aqu hay un breve ejemplo:

Public Sub main() Dim cnn As New ADODB.Connection Dim cmd As New ADODB.Command Dim prm As ADODB.Parameter Dim strCmd As String strCmd = "SELECT * FROM authors WHERE au_lname = ?" cmd.CommandText = strCmd cmd.Parameters.Append _ cmd.CreateParameter("last name", adVarChar, adParamInput, 40, "") cnn.Open "dsn=pubs;uid=sa;pwd=;" cmd.ActiveConnection = cnn cmd.Parameters("last name") = "Ringer" DisplayRst cmd.Execute cmd.Parameters("last name") = "Karsen" DisplayRst cmd.Execute cnn.Close End Sub Private Sub DisplayRst(rst As ADODB.Recordset) If rst.EOF = True Then Debug.Print "No recordset returned for Name = '";_ rst.ActiveCommand.Parameters(0); "'" End If While rst.EOF = False Debug.Print "Name = '"; rst!au_fname; " "; rst!au_lname; "'" rst.MoveNext Wend

End Sub

Paso 3: Ejecute el comando.

Los tres mtodos que regresan un Recordset son Connection.Execute, Command.Execute y Recordset.open. Esta es su sintxis en Visual Basic:

connection.Execute(TextoComando, RegistrosAfectados, Opciones) command.Execute(RegistrosAfectados, Parmetros, Opciones) recordset.Open Fuente, ConexinActiva, TipoDeCursor, TipoDeBloqueo, Opciones
Estos mtodos estn optimizados para aprovechar las ventajas de sus objetos particulares.

Antes de que Usted enve un comando debe, implcita o explcitamente, abrir una conexin. Cada mtodo que enva un comando representa la conexin de manera diferente:

El mtodo Connection.Execute utiliza la conexin expresado por el objeto Connection en s mismo.

El mtodo Command.Execute utiliza el objeto Connection establecido en su propiedad ConexinActiva (ActiveConnection). El mtodo Recordset.Open utiliza una cadena de conexin, su parmetro ConexinActiva o el objeto Connection establecido en su propiedad ConexinActiva.

Otra diferencia es la manera en que el comando es especificado en los tres mtodos:

En el mtodo Connection.Execute, el comando es texto de comando. En el mtodo Command.Execute, el comando no es visible, est especificado en la propiedad Command.CommandText. Adems, el comando puede ser parametrizado. En el mtodo Recordset.Open, el comando es el argumento Fuente, el cual puede ser texto de comando o un objeto Command. (El argumento Fuente puede ser tambin una cadena que especifique un nombre de tabla, un procedimiento almacenado o el nombre de archivo de un Recordset persistido.)

Cada mtodo tiene un balance diferente entre funcionalidad y desempeo:

El mtodo Execute est hecho para, pero no limitado para, ejecutar comandos que no regresan datos.

Ambos mtodos Execute regresan objetos de solo lectura y unidireccionales Recordset.

El mtodo Command.Execute le permite utilizar comandos parametrizados que pueden ser reutilizados eficientemente. El mtodo Open le permite especificar el TipoDeCursor (estrategia y objeto utilizado para accesar los datos) y el TipoDeBloqueo (especifica el grado de aislamiento de otros usuarios y si el cursor debe de aceptar actualizaciones en los modos inmediato o por lotes (batch) (se discuten en mas detalle ms adelante).

Estudie estas opciones, ellas representan la mayor parte de la funcionalidad de un Recordset.

Este tutorial har cambios al Recordset en modo por lotes; por tanto se especifica un TipoDeBloqueo del tipo adLockBatchOptimistic (bloqueo por lotes optimista). El procesamiento por lotes requiere el Servicio de Cursor, as que la propiedad LocalizacinDeCursor (Cursorlocation) tambin est especificada. Dado que el objeto Command ya est establecido a una conexin abierta, el parmetro ConexinActiva no puede ser especificado en el mtodo Open.

El Recordset es declarado y utilizado como:

Dim rs As New ADODB.Recordset rst.CursorLocation = adUseClient rst.Open cmd, , adOpenStatic, adLockBatchOptimistic

Paso 4: Manipule los datos.
La mayor parte de los mtodos y propiedades del objeto Recordset son dedicados a examinar, navegar y manipular los datos Recordset.

Imagine al Recordset como un arreglo de filas. La fila que Usted puede examinar y manipular en un momento dado es el la fila actual (current row) y su localizacin dentro del Recordset es la posicin de la fila actual (current row position). Cada vez que Usted se mueve a otra fila, esa fila se convierte en la nueva fila actual.

Varios mtodos explcitamente mueven o "navegan" a travs del Recordset (los mtodos Move). Algunos mtodos (el mtodo Find) lo hacen como un efecto colateral de su operacin. Adems, el ajustar ciertas propiedades (la propiedad Bookmark) puede tambin cambiar su posicin de fila. La propiedad TipoDeCursor (CursorType) del objetos Recordset o el parmetro TipoDeCursor del mtodo Open, determinan si Usted puede navegar hacia delante y hacia atrs a travs del Recordset.

La propiedad Filter (filtro) controla los renglones a lo que Usted puede accesar (esto es, cuales renglones le son "visibles"). La propiedad Sort (ordenamiento) controla el orden en el cual Usted navega las filas del Recordset.

Usted puede crear nuevas filas con el mtodo AddNew o eliminar filas existentes con el mtodo Delete.

Un Recordset tiene una coleccin de campos (fields) que es un conjunto de objetos Field que representan cada campo o columna en una fila. Asigne u obtenga los datos de un campo con la propiedad Value del objeto Field. Puede, adems, accesar campos de datos en bloques con el mtodo GetRows. Despus de que Usted ha modificado el Recordset, propage sus cambios a la fuente de datos utilizando los mtodos Update.

En este tutorial, Usted:

Establecer la propiedad Optimize en la coleccin Properties del objeto Field au_lname para mejorar el desempeo del ordenamiento y filtrado.

Ordenar el Recordset por el apellido de cada autor. Filtrar el Recordset de forma que las nicas filas sean aquellas donde el nmero de telfono del autor tengan el cdigo de rea "415" y el conmutador comience con "5". Cambiar los nmeros telefnicos filtrados al mtico cdigo de rea "777."

Utilice los mtodos Move para navegar desde el principio del Recordset filtrado y ordenado hasta el final. Detngase cuando la propiedad EOF del objeto Recordset indique que se ha alcanzado la ltima fila. Al irse moviendo a lo largo del Recordset, visualice el nombre y apellido del autor, el nmero de telfono original y luego cambie el cdigo de rea en el campo del telfono a "777". (Los nmeros telefnicos en el campo de telfono se formatearn como "aaa xxx-yyyy" donde aaa es el cdigo de rea y xxx es el conmutador.)

Al ir cambiando cada fila, ya no cumple el criterio especificado por el filtro, de modo que ya no es visible en el Recordset. Todos los renglones reaparecen cuando el filtro es borrado.

Esquema de la tabla.
El siguiente es el esquema de la tabla authors de la base de datos pubs:

Nombre de columna au_id au_lname au_fname Phone Address

Tipo de dato (Longitud) ID (11) varchar(40) varchar(20) char(12) varchar(40)

Anulable no no no no yes

City State Zip Contract

varchar(20) char(2) char(5) bit

yes yes yes no

El cdigo luce como este:

rst!au_lname.Properties("Optimize") = True rst.Sort = "au_lname" rst.Filter = "phone LIKE '415 5*'" rst.MoveFirst Do While Not rst.EOF Debug.Print "Name = "; rst!au_fname; " "; rst!au_lname;_ ", Phone = "; rst!phone rst!phone = "777" & Mid(rst!phone, 4) rst.MoveNext Loop rst.Filter = adFilterNone
Paso 5: Actualice los datos.
Acaba Usted de cambiar los datos de varias filas del Recordset. ADO utiliza dos nociones bsicas relacionadas con la adicin, eliminacin o modificacin de renglones de datos.

La primera nocin es que los cambios no son inmediatamente hechos al Recordset; en vez de eso, son hechos a una memoria intermedia de copia (copy buffer). Si Usted decide que no desea los cambios, entonces la modificaciones en la memoria intermedia son descartadas. Si decide mantener los cambios, entonces los cambios en la memoria intermedia son aplicados al Recordset.

La segunda nocin es que los cambios pueden ser propagados a la fuente de datos tan pronto como uUsted declare completo el trabajo en una fila, (esto es, modo inmediato). O todos los cambios a un conjunto de renglones son recogidos hasta que Usted declare que el trabajo para el conjunto est completo (esto es, modo por lotes). Estos modos estn gobernados por las propiedades CursorLocation y LockType.

En el modo inmediato, cada invocacin del mtodo Update propaga los cambios a la fuente de datos. En el modo por lotes, cada invocacin de Update o el movimiento de la posicin de fila actual guarda los cambios a la memoria intermedia, pero solo el mtodo Updatebatch propaga los cambios a la fuente de datos. El Recordset fue abierto en modo por lotes (adLockBatchOptimistic) as que las actualizaciones sern hechas en modo por lotes.

Opcionalmente, las actualizaciones pueden ser realizadas en una transaccin. Una transaccin establece un ambiente donde las operaciones dentro de la transaccin son todas exitosas o todos sus efectos son cancelados.

Un ejemplo comn de una transaccin es una aplicacin bancaria, donde una operacin para deducir un cantidad de una cuenta y otra operacin para depositar la misma cantidad en otra cuenta, ambas deben de ser exitosas. Si una falla, entonces la otra debe de ser deshecha; de otra manera las cuentas estarn fuera de balance.

Las transacciones generalmente asignan y mantienen recursos limitados en las fuentes de datos por largos perodos de tiempo. Por esta razn, es recomendable que una transaccin exista por perodos tan cortos como sea posible. (Esta es la razn por la cual este tutorial no comenz la transaccin tan pronto como la conexin fue hecha).

Hablando prcticamente, este tutorial no requiere una transaccin, pero se incluye una para propsitos ilustrativos. El cdigo para comenzar una transaccin y realizar una actualizacin por lotes luce como este:

cnn.BeginTrans rst.UpdateBatch
Paso 6: Concluya la actualizacin.
Imagine que la actualizacin por lotes concluye con errores. El cmo Usted resuelva estos errores depende de la naturaleza y la severidad de los errores y la lgica de su aplicacin. Sin embargo, si la base de datos es compartida con otros usuarios, un error tpico es que alguien ms modific el campo antes de que Usted lo hiciera. Este tipo de error es llamado un conflicto. El ADO detecta esta situacin y reporta un error.

Este paso del tutorial tiene dos partes: Si no hay errores de actualizacin, entonces la fuente de datos refleja los cambios actualizados. La transaccin se ha realizado. Realizar la transaccin finaliza y termina la transaccin.

El cdigo para aceptar la actualizacin luce como este:

cnn.CommitTrans

Si existen errores de actualizacin, sern interceptados en una rutina de manejo de errores. Filtre el Recordset con la constante adFilterConflictingRecords de forma que solo los renglones en conflicto sean visibles. La estrategia de resolucin de errores es meramente imprimir el nombre y apellido del autor (au_fname y au_lname), luego regresar (roll back) (esto es, deshacer) la transaccin. Al regresar la transaccin se descarta cualquiera actualizacin exitosa y finaliza la transaccin.

El cdigo para rechazar la actualizacin luce como este:

rst.Filter = adFilterConflictingRecords rst.MoveFirst Do While Not rst.EOF Debug.Print "Conflict: Name = rst.MoveNext Loop cnn.RollbackTrans
Despus de que concluye la actualizacin, los objetos Recordset y Connection son cerrados y el ejemplo termina de ejecutarse. El cdigo luce como este:

"; rst!au_fname;" "; rst!au_lname

rst.Close cnn.Close
Este es el final del tutorial descriptivo.

Tutorial ADO (Visual Basic).

Este es el tutorial de ADO, escrito en Microsoft Visual Basic. Vea el el Tutorial de ADO para una descripcin del propsito de este tutorial.

Public Sub Main()

' Tutorial in VB

Dim cnn As New ADODB.Connection Dim cmd As New ADODB.Command Dim rst As New ADODB.Recordset

' Step 1 - Open a Connection cnn.Open "DSN=pubs;uid=sa;pwd=;"

' Step 2 - Create a Command Set cmd.ActiveConnection = cnn cmd.CommandText = "SELECT * from authors"

' Step 3 - Execute the Command rst.CursorLocation = adUseClient rst.Open cmd, , adOpenStatic, adLockBatchOptimistic

' Step 4 - Manipulate the Data rst!au_lname.Properties("Optimize") = True rst.Sort = "au_lname" rst.Filter = "phone LIKE '415 5*'" rst.MoveFirst Do While Not rst.EOF Debug.Print "Name = "; rst!au_fname; " "; rst!au_lname; _ ", Phone = "; rst!phone rst!phone = "777" & Mid(rst!phone, 4) rst.MoveNext Loop

rst.Filter = adFilterNone

' Step 5 - Update the Data cnn.BeginTrans On Error GoTo ConflictHandler rst.UpdateBatch

'Step 6, part A - Conclude the Update (Accept changes) cnn.CommitTrans

ExitTutorial: On Error GoTo 0 rst.Close cnn.Close Exit Sub

'Step 6, part B - Conclude the Update (Reject changes) ConflictHandler: rst.Filter = adFilterConflictingRecords rst.MoveFirst Do While Not rst.EOF Debug.Print "Conflict: Name = rst.MoveNext Loop cnn.RollbackTrans Resume ExitTutorial "; rst!au_fname; " "; rst!au_lname

End Sub
Este es el final del tutorial Visual Basic.