Método DataRecordsets.Add (Visio)

Adiciona um objeto DataRecordset à coleção DataRecordsets conectando-se e recuperando dados de uma fonte de dados OLEDB ou ODBC.

Observação

This Visio object or member is available only to licensed users of Visio Professional 2013.

Sintaxe

expressão. Adicionar (ConnectionIDOrString, CommandString, AddOptions, Name)

Expressão Uma variável que representa um objeto DataRecordsets .

Parâmetros

Nome	Obrigatório/Opcional	Tipo de dados	Descrição
ConnectionIDOrString	Obrigatório	Variantes	A ID de um objeto DataConnection existente ou a cadeia de conexão para especificar uma nova conexão de fonte de dados.
CommandString	Obrigatório	String	Cadeia de caracteres de consulta que especifica a tabela de banco de dados ou planilha do Excel e os campos (colunas) na tabela ou planilha que contém os dados que se quer consultar.
AddOptions	Obrigatório	Long	Opções que determinam as propriedades do conjunto de registro de dados a ser adicionado. Uma combinação de um ou mais valores enumerados de VisDataRecordsetAddOptions. Para obter mais informações, consulte Comentários.
Name	Opcional	String	Atribui ao objeto DataRecordset adicionado um nome para exibição.

Valor de retorno

DataRecordset

Comentários

Você pode determinar uma cadeia de caracteres de conexão adequada para passar ao parâmetro ConnectionIDOrString usando primeiramente o Assistente do Seletor de Dados da interface do usuário do Visio para criar a mesma conexão, gravando uma macro durante a execução do assistente e, então, copiando a cadeia de caracteres de conexão do código da macro.

Uma maneira fácil de reutilizar uma conexão de dados existente é passar o valor da propriedade DataConnection de um objeto DataRecordset existente para o parâmetro ConnectionIDOrString. Use a seguinte sintaxe:

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

No parâmetro ConnectionIDOrString, se você passar a identificação de um objeto DataConnection existente que esteja sendo usado no momento por um ou mais conjuntos de registros de dados, todos os conjuntos de registros de dados se tornarão um conjunto de registros de grupo transacionado. Todos os conjuntos de registros de dados no grupo serão atualizados sempre que ocorrer uma operação de atualização de dados.

O parâmetro AddOptions pode ser uma combinação de um ou mais dos valores a seguir, contidos na enumeração VisDataRecordsetAddOptions, que é declarada na biblioteca de tipos do Visio. O padrão é zero (0), o que especifica que nenhuma das opções seja definida.

Constant	Valor	Descrição
visDataRecordsetNoExternalDataUI	1	Impede que os dados de um novo conjunto de registros de dados sejam exibidos na janela Dados Externos.
visDataRecordsetNoRefreshUI	2	Impede que o conjunto de registros de dados seja exibido na caixa de diálogo Atualizar Dados.
visDataRecordsetNoAdvConfig	4	Impede que o conjunto de registros de dados seja exibido na caixa de diálogo Configurar Atualização.
visDataRecordsetDelayQuery	8	Adiciona um conjunto de registros de dados, mas não executa a consulta CommandString até a próxima vez em que se chame o método Refresh.
visDataRecordsetDontCopyLinks	16	Adiciona um conjunto de registros de dados, mas os links de dados de forma não são copiados para a Área de Transferência quando as formas são copiadas ou cortadas.

Depois de atribuir esses valores, você não pode alterá-los durante a existência do objeto DataRecordset.

O parâmetro Name é uma cadeia de caracteres opcional que permite atribuir ao conjunto de registros de dados um nome para exibição. Caso você especifique que a janela Dados Externos seja exibida na interface do usuário do Visio, o nome que você passar para esse argumento aparecerá na guia da janela Dados Externos correspondente ao conjunto de registros de dados adicionado.

Se o método Add for bem-sucedido, ele executará as seguintes ações:

• Cria um objeto DataRecordset e atribui a ele o nome especificado no parâmetro Name. Se você não especificar um nome, o Visio atribuirá o conjunto de registros de dados ao nome da tabela de banco de dados que é a fonte dos dados.

• Associa um objeto DataConnection novo ou existente ao objeto DataRecordset.

• Abre a janela Dados Externos da interface do usuário do Visio, a menos que visDataRecordsetNoExternalDataUI esteja definido.

A não ser que você passe visDataRecordsetDelayQuery como parte do parâmetro AddOptions, o método Add também faz o seguinte:

• Executa a cadeia de caracteres de consulta especificada no parâmetro CommandString e recupera os dados resultantes.

• Mapeia os tipos de dados das colunas da fonte de dados para os tipos de dados do Visio equivalentes, enquanto filtra o resultado para remover as colunas dados-fonte que não possam ser vinculadas a formas do Visio por não existir equivalência com um tipo de dado do Visio. Particularmente, você não pode importar dados binários ou tipos de dados secretos como UserDefined, Chapter e IDispatch.

• Atribui uma identificação de linha a cada linha do conjunto de registros de dados. Para obter mais informações sobre IDs de linha, consulte Tópico DataRecordset.GetDataRowIDs .

Observação

O método Add falha e retorna uma exceção caso encontre erros de conexão de rede, problemas de tempo limite de rede ou erros de permissões de banco de dados. Se a opção visDataRecordsetDelayQuery estiver definida, o método Add, nas mesma circunstâncias, poderá adicionar um novo conjunto de registros de dados com êxito, mas a atualização talvez falhe.

Exemplo

A macro VBA (Microsoft Visual Basic for Applications) a seguir mostra como você deve usar o método Add para conectar um desenho do Visio a dados de ORGDATA.XLS, uma pasta de trabalho do Microsoft Office Excel que é instalada em C:\Arquivos de Programas\Microsoft Office\OFFICE12\SAMPLES\1033\ quando se instala o Visio como caminho padrão de arquivos.

Neste exemplo, não há nenhuma conexão de dados existente, portanto, para o primeiro parâmetro do método Add , passamos strConnection , a cadeia de conexão. Para o segundo parâmetro, passamos strCommand , a cadeia de caracteres de comando, que orienta o Visio a selecionar todas as colunas na planilha especificada. Para o terceiro parâmetro do método Add , passamos zero para especificar o comportamento padrão do conjunto de registros de dados e, para o último parâmetro, passamos "Org Data", o nome de exibição que queremos atribuir ao conjunto de registros de dados.

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

Suporte e comentários

Tem dúvidas ou quer enviar comentários sobre o VBA para Office ou sobre esta documentação? Confira Suporte e comentários sobre o VBA para Office a fim de obter orientação sobre as maneiras pelas quais você pode receber suporte e fornecer comentários.