Método DataRecordsets.Add (Visio)

Agrega un objeto DataRecordset a la colección DataRecordsets mediante la conexión y recuperación de datos de un origen de datos OLEDB o ODBC.

Nota:

Este objeto o miembro Visio solo se encuentra disponible para los usuarios con licencia de Visio Professional 2013.

Sintaxis

expresión. Add (ConnectionIDOrString, CommandString, AddOptions, Name)

Expresión Variable que representa un objeto DataRecordsets .

Parameters

Nombre	Obligatorio/opcional	Tipo de datos	Descripción
ConnectionIDOrString	Obligatorio	Variant	Identificador de un objeto DataConnection existente o la cadena de conexión para especificar una nueva conexión de origen de datos.
CommandString	Obligatorio	String	Cadena de consulta que especifica la tabla de base de datos o la hoja de cálculo de Excel y los campos (columnas) de la tabla o de la hoja que contienen los datos sobre los que desea realizar la consulta.
AddOptions	Necesario	Long	Opciones que determinan propiedades del conjunto de registros de datos que se agrega. Combinación de uno o varios valores enumerados de VisDataRecordsetAddOptions. Para obtener más información, vea la sección de comentarios.
Name	Opcional	Cadena	Asigna un nombre para mostrar al objeto DataRecordset que se va a agregar.

Valor devuelto

DataRecordset

Comentarios

Puede determinar una cadena de conexión apropiada para pasar al parámetro ConnectionIDOrString utilizando primero el Asistente para selector de datos en la interfaz del usuario (IU) de Visio con el fin de realizar la misma conexión, grabando después una macro durante la ejecución del asistente y, por último, copiando la cadena de conexión del código de la macro.

Una manera sencilla de reutilizar una conexión de datos existente es pasar el valor de la propiedad DataConnection de un objeto DataRecordset existente para el parámetro ConnectionIDOrString. Utilice la siguiente sintaxis:

NewDataRecordset  = DataRecordsets.Add(ExistingDataRecordset .DataConnection.ID, CommandString, AddOptions, Name)

En el caso del parámetro ConnectionIDOrString, si pasa el identificador de un objeto DataConnection existente que está siendo usado por uno o más conjuntos de registros de datos, todos los conjuntos de registros de datos se convierten en un conjunto de registros del grupo de la transacción. Todos los conjuntos de registros de datos del grupo se actualizan cada vez que se produce una operación de actualización de datos.

El parámetro AddOptions puede ser una combinación de uno o más de los valores siguientes de la enumeración VisDataRecordsetAddOptions declarada en la biblioteca de tipos de Visio. El valor predeterminado es cero (0), que especifica que no se establece ninguna de las opciones.

Constante	Valor	Descripción
visDataRecordsetNoExternalDataUI	1	Impide que los datos del nuevo conjunto de registros de datos se muestren en la ventana Datos externos.
visDataRecordsetNoRefreshUI	2	Impide que el conjunto de registros de datos se muestre en el cuadro de diálogo Actualizar datos.
visDataRecordsetNoAdvConfig	4	Impide que el conjunto de registros de datos se muestre en el cuadro de diálogo Configurar actualización.
visDataRecordsetDelayQuery	8	Agrega un conjunto de registros de datos, pero no ejecuta la consulta CommandString hasta la siguiente vez que se llama al método Refresh.
visDataRecordsetDontCopyLinks	16	Agrega un conjunto de registros de datos, pero los vínculos de datos de formas no se copian en el Portapapeles cuando se copian o cortan formas.

Una vez asignados estos valores, no se pueden cambiar durante la existencia del objeto DataRecordset.

El parámetro Name es una cadena opcional que permite asignar un nombre para mostrar al conjunto de registros de datos. Si se especifica que se muestre la ventana Datos externos en la UI de Visio, el nombre que se pase para este argumento aparecerá en la ficha de la ventana Datos externos correspondiente al conjunto de registros de datos agregado.

Si el método Add se realiza correctamente, realiza las siguientes acciones:

• Crea un objeto DataRecordset y le asigna el nombre especificado en el parámetro Name. Si no especifica un nombre, Visio asigna al conjunto de registros de datos el nombre de la tabla de base de datos que es el origen de los datos.

• Asocia un objeto DataConnection nuevo o existente al objeto DataRecordset.

• Abre la ventana Datos externos en la UI de Visio, a menos que se establezca visDataRecordsetNoExternalDataUI.

Si no se pasa visDataRecordsetDelayQuery como parte del parámetro AddOptions, el método Add realiza también las acciones siguientes:

• Ejecuta la cadena de consulta especificada en el parámetro CommandString y recupera los datos resultantes.

• Asigna los tipos de datos de las columnas del origen de datos a tipos de datos de Visio equivalentes, y filtra los resultados para quitar las columnas del origen de datos que no se pueden vincular a formas de Visio porque no tienen tipos de datos de Visio equivalentes. En particular, no se pueden importar tipos de datos esotéricos ni binarios como UserDefined, Chapter y IDispatch.

• Asigna un identificador de fila a cada una de las filas del conjunto de registros de datos. Para obtener más información sobre los identificadores de fila, vea el tema DataRecordset.GetDataRowIDs .

Nota:

El método Add no se ejecuta correctamente y devuelve una excepción si encuentra errores de conexión de red, tiempos de espera de red o errores de permiso de base de datos. Si se establece la opción visDataRecordsetDelayQuery, en las mismas circunstancias, Add puede agregar correctamente un nuevo conjunto de registros de datos, pero la actualización puede sufrir errores.

Ejemplo:

La macro siguiente de Microsoft Visual Basic para Aplicaciones (VBA) muestra la forma de usar el método Add para conectar un dibujo de Visio a datos en ORGDATA.XLS, un libro de Microsoft Office Excel que está instalado en C:\Archivos de programa\Microsoft Office\OFFICE12\SAMPLES\1033\ cuando se instala Visio en la ruta de archivo predeterminada.

En este ejemplo, no hay ninguna conexión de datos existente, por lo que para el primer parámetro del método Add , se pasa strConnection , la cadena de conexión. Para el segundo parámetro, se pasa strCommand , la cadena de comando, que indica a Visio que seleccione todas las columnas de la hoja de cálculo que especifiquemos. Para el tercer parámetro del método Add , pasamos cero para especificar el comportamiento predeterminado del conjunto de registros de datos y, para el último parámetro, pasamos "Org Data" , el nombre para mostrar que queremos asignar al conjunto de registros de datos.

Public Sub AddDataRecordset_Example() 
 
    Dim strConnection As String 
    Dim strCommand As String 
    Dim strOfficePath As String 
    Dim vsoDataRecordset As Visio.DataRecordset 
 
    strOfficePath = Visio.Application.Path     
    strConnection = "Provider=Microsoft.ACE.OLEDB.12.0;" _ 
                       & "User ID=Admin;" _ 
                       & "Data Source=" + strOfficePath + "SAMPLES\1033\ORGDATA.XLS;" _ 
                       & "Mode=Read;" _ 
                       & "Extended Properties=""HDR=YES;IMEX=1;MaxScanRows=0;Excel 12.0;"";" _ 
                       & "Jet OLEDB:Engine Type=34;" 
 
    strCommand = "SELECT * FROM [Sheet1$]" 
 
    Set vsoDataRecordset = ActiveDocument.DataRecordsets.Add(strConnection, strCommand, 0, "Org Data") 
 
End Sub

Soporte técnico y comentarios

¿Tiene preguntas o comentarios sobre VBA para Office o esta documentación? Vea Soporte técnico y comentarios sobre VBA para Office para obtener ayuda sobre las formas en las que puede recibir soporte técnico y enviar comentarios.