Elipse Knowledgebase :: Conectando uma aplicação VBA a um E3Server com a biblioteca de comunicação E3DataAccess

Knowledgebase Home

Search the Knowledgebase

Browse by Category

Knowledgebase Home > Português > Elipse E3 > Scripts

Conectando uma aplicação VBA a um E3Server com a biblioteca de comunicação E3DataAccess

1) Introdução

A biblioteca E3DataAccess fornece ao usuário uma nova maneira de conexão com o E3Server. Agora, qualquer aplicação desenvolvida em VB, Delphi, .NET ou outra linguagem com suporte a COM consegue se comunicar com o E3Server com a utilização das funções fornecidas por ela.

Este artigo se manterá em esclarecer o funcionamento do E3Server com uma aplicação desenvolvida em um ambiente VBA, através do Microsoft Excel. O mesmo procedimento também pode ser aplicado em outros ambientes de desenvolvimento, adequando seu código de acordo com a sintaxe da linguagem utilizada.

2) Habilitando a biblioteca E3DataAccess para uso no VBA

Antes de criar a aplicação pelo VBA, é preciso habilitar a biblioteca E3DataAccess para uso no ambiente de desenvolvimento. Após isto, ficarão disponíveis todas as funções necessárias para conseguir se comunicar com o E3Server.

Com o E3 Studio, Microsoft Excel e VBA devidamente instalados, acessamos a interface VBA da aplicação Excel. Na interface do VBA, adicionamos a biblioteca E3DataAccess na lista de referências do projeto. Para fazer isto, entre na opção References, localizada no menu Tools, conforme a figura abaixo:

Figura 1: Acessando lista de referências do projeto.

Na lista de referências disponíveis, procurar pela biblioteca E3DataAccess e habilitá-la através da caixa de seleção.

Figura 2: Lista de referências disponíveis no projeto.

No caso da biblioteca não estar disponível na lista de referências, é preciso registrar ela antes. Para registrar a biblioteca, clique no botão [Browse...], uma caixa de seleção para a determinação da biblioteca será exibida (Figura 3).

Figura 3: Caixa de seleção da biblioteca.

Procure pelo arquivo .dll de nome E3DataAccess. Ele vem junto no pacote do E3 versão 3.0 e encontra-se dentro do diretório de instalação dele, na subpasta Bin (Exemplo: C:/Program Files/Elipse E3/Bin). Após abrir o arquivo .dll, a biblioteca E3DataAccess ficará disponível na lista de referências e, então, siga o passo anterior novamente. Confirme a modificação clicando no botão [OK].

3) Instanciando um novo objeto E3DataAccess no projeto

Com a biblioteca E3DataAccess adicionada ao projeto, agora podemos fazer uso dela. Neste exemplo, vamos adicionar um novo módulo ao projeto e instanciar um objeto do tipo E3DataAccess dentro dele.

Para criar um novo módulo, uma das alternativas é clicar com o botão direito do mouse em cima do nome do projeto, disponível pelo Project Explorer (Figura 4). Selecionar a opção Insert e Module.

Figura 4: Inserindo um novo Módulo pelo VBA.

Feito isto, será adicionado um novo módulo ao projeto com o nome default de "Module1". Vamos renomear o nome dele para "E3ServerCOM".

Clicamos duas vezes em cima do módulo "E3ServerCOM" criado para acessar seu código. Neste momento, não existe nenhum código dentro do módulo. É nele que vamos inserir a seguinte linha para a instanciação do objeto E3DataAccess, conforme abaixo:

Public E3 As New E3DATAACCESSLib.E3DataAccessManager

Com esta linha de código, estamos criando um novo objeto chamado "E3" derivado da classe "E3DATAACCESSLib.E3WebLinkMan". Esta classe contém todas as funções necessárias para realizar a conexão com o E3Server. O objeto também foi instanciado como público, sendo, portanto, acessível em qualquer lugar do projeto.

NOTA: É importante destacar que quando instanciamos um novo objeto E3DataAccess, é consumida também uma licença de Viewer do Hardkey. Isso pode ser visualizado acessando a opção de Licenças, disponível no menu do E3Server. Portanto, é necessário um pouco de atenção para não serem consumidas licenças a mais do que o necessário.

4) Aplicação E3

A aplicação E3 utilizada para este exemplo é uma aplicação padrão com dois objetos TagDemo e um TagInterno dentro do Servidor de Dados para demonstração dos métodos de leitura e escrita do E3DataAccess. Além deles, também foi criado um Histórico de nome "Hist1" com dois campos: E3TimeStamp e TagHist que armazena os valores gerados por "TagDemo2", conforme ilustrado na figura abaixo:

Figura 5: Histórico da aplicação E3

Foi criado um objeto Banco de Dados do tipo Access chamado "BancoDados1" que guarda todos os dados no arquivo Teste.mdb. Associamos o objeto "Histórico" ao "BancoDados1" através de sua propriedade DBServer. Tudo isto foi feito para podermos fazer uso da função de acesso ao Banco de Dados do E3DataAccess.

Figura 6: Bando de Dados da aplicação E3

Atribuímos um nome qualquer a tabela do Histórico pela propriedade TableName e geramos ela clicando no botão "Gerar estrutura no BD" do menu.

Criamos um novo objeto Consulta dentro do Servidor de Dados. Configuramos ele para se conectar ao Banco de Dados "BancoDados1" recém criado e acessar a tabela do Histórico gerada. Na janela de definição de consultas, criamos uma consulta que retorne todos os dados da tabela do Histórico (Figura 7).

Figura 7: Tela de definição da consulta

5) Leitura e escrita de dados com o E3DataAccess

Com a aplicação E3 pronta, retornamos ao Excel. Selecionamos sua tela e criamos dois Botões de Comando, neste exemplo faremos com que um deles leia o valor do "TagDemo1" e o outro escreva um valor em "TagInterno1". Para adicionar os botões, é aconselhável deixar visualizável a barra de ferramentas Control Toolbox, isso pode ser feito acessando View, Toolbars e Control Toolbox, conforme a figura abaixo:

Figura 8: Habilitando a barra Control Toolbox no Excel

Na barra Control Toolbox estará disponível o componente CommandButton, selecione-o e adicione os dois botões. Clicamos com o botão direito do mouse no primeiro CommandButton e acessamos suas propriedades. Na propriedade Caption, mudamos seu conteúdo para "Ler valor" e fazemos o mesmo com o outro botão, mas mudando seu conteúdo para "Escrever valor". Isto mudará o texto dos botões (Figura 8). Vamos mudar também a propriedade Name dos botões de leitura e escrita para: "readValueButton" e "writeValueButton", respectivamente.

Agora, acessamos o código do botão encarregado de ler o valor do tag da aplicação E3 (readValueButton). Clicamos duas vezes em cima do botão e o VBA será aberto automaticamente dentro do código do evento de clique do botão. Dentro do evento, adicionamos as seguintes linhas de código:

Private Sub readValueButton_Click()
Dim timestamp As Variant
Dim quality As Integer
Dim value As Variant

E3.Server = "E3Server_HostName"

If E3.GetValue("Dados.TagDemo1.Value", timestamp, quality, value) Then
Range("D4") = value
Range("E4") = quality
Range("F4") = timestamp
Else
MsgBox "Ocorreu uma falha na conexão!"
End If
End Sub

O objeto E3 neste código é o mesmo objeto público que instanciamos no módulo "E3ServerCOM". Este objeto trata de todas as operações e conexões com o E3Server, portanto, ele é a "chave" de todo o código. Após a declaração das variáveis de rotina, estamos atribuindo um valor a propriedade Server do objeto E3. Através da propriedade Server, informamos o nome do servidor E3Server (tipo string) ao qual queremos obter conexão. Isto deve ser feito antes de realizar qualquer operação no domínio.

Método GetValue(Link, TimeStamp, Qualidade, Valor)

Para ler o valor do tag, utilizamos o método GetValue, este método recebe os seguintes parâmetros de entrada e saída:

Link – parâmetro de entrada que fornece o caminho do objeto a ser lido.
Timestamp – parâmetro de saída que recebe o timestamp do Link referenciado.
Qualidade – parâmetro de saída que recebe a qualidade do Link referenciado.
Valor – parâmetro de saída que recebe o valor do Link referenciado.

Este método, quando chamado, retorna o valor booleano TRUE se obter sucesso na operação ou FALSE caso contrário. No código acima estamos lendo o dado de "TagDemo1" e guardando seu valor, qualidade e timestamp nas variáveis: value, quality e timestamp.

Se não ocorrer nenhum problema com a leitura dos dados (retorna TRUE), escrevemos seus valores nas células D4, E4 e F4 da planilha do Excel. Portanto, ao clicarmos no botão "Ler valor", teríamos uma resposta como a da figura abaixo:

Figura 9: Resposta do botão "Ler valor"

Os valores foram armazenados nas respectivas células da planilha, conforme especificado no código. Com o valor lido, o próximo passo agora é escrever um valor no "TagInterno1", o que será abordado a seguir.

Primeiro, acessamos o código do evento de clique do botão "writeValueButton", como fizemos com o primeiro botão. Clicamos duas vezes com o mouse em cima dele e será aberto o código do evento no VBA.

Dentro dele, vamos adicionar as seguintes linhas de código:

Private Sub writeValueButton_Click()
Dim timestamp As Variant
Dim quality As Integer
Dim value As Variant

value = CDbl(Range("D7"))
quality = Range("E7")
timestamp = DateTime.Now

E3.Server = "E3Server_HostName"

If E3.SetValue("Dados.TagInterno1.Value", timestamp, quality, value) Then
Range("G7") = "Sucesso!"
Else
Range("G7") = "Falha!"
End If
End Sub

De forma semelhante ao código anterior, vamos utilizar as células D7, E7 e G7. A célula D7 será utilizada para armazenar qual o valor a escrever no "TagInterno1", este valor é atribuído à variável value convertida para o tipo double, que é o formato do dado. A célula E7 receberá o valor da qualidade do "TagInterno1" e será atribuído à variável Quality. A variável timestamp receberá a data e tempo atual do sistema e a célula G7 será utilizada para retornar o sucesso ou não da operação de escrita.

Após feito todos os preparos, é feita a conexão no E3Server através da propriedade Server do objeto E3 e chamamos o método para escrever o valor.

Método SetValue(Link, TimeStamp, Qualidade, Valor)

Este método é sintaticamente idêntico ao outro método GetValue, possui os seguintes parâmetros de entrada:

Link – parâmetro de entrada que fornece o caminho do objeto a ser escrito.
Timestamp – parâmetro de entrada que fornece o timestamp do Link referenciado.
Qualidade – parâmetro de entrada que fornece a qualidade do Link referenciado.
Valor – parâmetro de entrada que fornece o valor do Link referenciado.

Assim como o método GetValue, ele retorna um valor booleano TRUE quando a escrita for realizada com sucesso e FALSE caso contrário. O evento acima escreve um valor obtido na célula D7 com uma qualidade obtida na célula E7 e um timestamp com a data e hora atual obtidas do sistema. Estes dados são utilizados para a escrita no Link "Dados.TagInterno1.Value", endereço onde está localizado o "TagInterno1" dentro da aplicação E3.

Então, para realizar o teste de escrita, antes de clicarmos no botão "Escrever valor", fornecemos o valor e qualidade dele nas respectivas células (D7 e E7) da planilha, isto resultará em uma saída conforme a da figura abaixo.

Figura 10: Resposta do botão "Escrever valor"

Para confirmarmos que o valor foi realmente escrito em "TagInterno1", uma forma seria ver na ferramenta WatchWindow disponível no próprio Studio. Outra maneira é criar um novo botão para ler o valor de "TagInterno1" da mesma forma que fizemos com "TagDemo1", apenas mudando o valor do parâmetro Link na chamada do método de leitura.

6) Como receber eventos com o E3DataAccess

Outra das possibilidades da biblioteca E3DataAccess é a recepção de eventos provenientes da aplicação E3. Ela possui um evento chamado OnValueChanged que pode ser capturado por qualquer aplicação que o instancie. Com isto é possível a recepção dos valores em tempo real, ao contrário do método GetValue que retorna o valor apenas quando requisitado.

O exemplo feito até este momento faz a leitura do valor de "TagDemo1" sempre que clicamos no botão correspondente. Vamos criar agora outro botão que ativa o evento OnValueChanged para o "TagDemo1", fazendo com que o valor do tag seja enviado a uma célula da planilha sempre que ocorrer mudanças nele.

Vamos criar um novo botão com a propriedade Name com o valor "onEventsButton" e Caption com o valor "Ativar evento". Após isto, acessamos o VBA.

Dentro do VBA, criamos um novo módulo classe, clicando no menu Insert e escolhendo a opção Class Module (Figura 11).

Figura 11: Inserindo um novo Módulo Classe pelo VBA

Será criado um novo módulo classe de nome "Class1" dentro da pasta "Class Modules", vamos mudar o nome da classe para "E3ServerEvents" pelas propriedades dela. Dentro do código desta classe, inserimos a linha abaixo:

Public WithEvents E3EVT As E3DATAACCESSLib.E3DataAccessManager

Com isto estamos instanciando um novo objeto E3DataAccess de nome "E3EVT". O parâmetro WithEvents indica que o objeto "E3EVT" está apto a receber eventos. Selecionamos o objeto criado pela lista de seleção dos objetos e o evento OnValueChanged na lista de declarações ao lado (Figura 12).

Figura 12: Lista de seleção de Objetos do VBA

Ao selecionarmos o objeto, será criado automaticamente a declaração do evento OnValueChanged no código da classe. Ou seja, depois de realizado isto, teríamos o seguinte código.

Public WithEvents E3EVT As E3DATAACCESSLib.E3DataAccessManager

'Linhas geradas automaticamente
Private Sub E3EVT_OnValueChanged(ByVal Path As String, ByVal Timestamp As Variant, ByVal Quality As Integer, ByVal Value As Variant)

End Sub

Este evento será gerado toda vez que ocorrer uma mudança nos valores dos dados da aplicação E3. Dentro dele, colocamos o código que será executado quando ocorrer esta mudança. Neste caso, faremos com que as células D10, E10 e F10 da planilha recebam os dados dos valores, qualidades e timestamps de "TagDemo1", respectivamente. O código abaixo trata de fazer isto:

Public WithEvents E3EVT As E3DATAACCESSLib.E3DataAccessManager

'Linhas geradas

Private Sub E3EVT_OnValueChanged(ByVal Path As String, ByVal Timestamp As Variant, ByVal Quality As Integer, ByVal Value As Variant)
Range("D10") = Value
Range("E10") = Quality
Range("F10") = Timestamp

End Sub

Os parâmetros Value, Quality e Timestamp do evento recebem todos os dados atualizados quando gerado o evento do objeto monitorado. A variável Path recebe qual o caminho do objeto que ativou o evento. No caso de estarmos monitorando mais de um objeto ao mesmo tempo, conhecer a variável Path é importante para descobrirmos qual a origem da chamada do evento. Como neste exemplo só estaremos monitorando "TagDemo1", dispensaremos o uso desta variável.

Após isto, voltamos ao código do módulo E3ServerCOM e instanciamos um novo objeto da classe recém criada E3ServerEvents. O nome utilizado é "E3Evt1".

Public E3Evt1 As New E3ServerEvents 'Linha criada
Public E3 As New E3DATAACCESSLib.E3DataAccessManager

O que resta a fazer agora é adicionar o código ao evento clique do botão "onEventsButton". Acessamos o código dele e inserimos as seguintes linhas:

Private Sub onEventButton_Click()
Set E3Evt1.E3EVT = E3

E3.Server = "E3Server_HostName"

If Not (E3.RegisterCallback("Dados.TagDemo1.Value")) Then
MsgBox "Não foi possível registrar o Link passado!"
End If

End Sub

Na primeira linha, estamos fazendo com que a propriedade "E3EVT" do objeto "E3Evt1" aponte para o objeto já instanciado "E3". Desta forma, podemos trabalhar tanto com o objeto "E3EVT" ou "E3" que o efeito será o mesmo. Logo após, conectamos ao E3Server desejado através da propriedade Server.

Método RegisterCallback(Link)

Este método é chamado quando desejamos monitorar os eventos de um determinado objeto da aplicação E3. Neste caso, queremos monitorar o objeto "TagDemo1". Ele possui apenas um parâmetro de entrada:

Link – parâmetro de entrada que fornece o caminho do objeto a ser monitorado.

Poderíamos monitorar mais do que um objeto, chamando este método para cada um deles. Todas as mudanças de valores desses objetos ativariam o mesmo evento OnValueChanged presente no módulo classe "E3ServerEvents". No caso da monitoração de mais de um objeto, talvez seja necessário o devido tratamento do parâmetro Path do evento para realizarmos ações diferentes dependendo da origem da mudança.

Terminado a implementação, agora podemos receber eventos de "TagDemo1" quando clicarmos no botão "Ativar evento" (Figura 13).

Figura 13: Resposta do botão "Ativar evento"

Certo, agora conseguimos monitorar os eventos de "TagDemo1", mas como fazer para encerrarmos sua monitoração? Esta é a função do método UnregisterCallback.

Método UnregisterCallback(Link)

Assim como o método RegisterCallback, este também possui apenas um parâmetro:

Link – parâmetro de entrada que fornece o caminho do objeto a deixar de ser monitorado.

Quando o método é chamado, ele "desregistra" o objeto da aplicação E3 passado por parâmetro. É retornado o valor booleano TRUE no sucesso da operação.

Para deixarmos de monitorar o objeto "TagDemo1", vamos criar um novo botão na planilha abaixo do "Ativar evento". Pelas propriedades dele, atribuímos "offEventButton" para a propriedade Name e "Desativar evento" para Caption.

No código do evento de clique do novo botão "offEventButton", inserimos o código abaixo:

Private Sub offEventButton_Click()
Set E3Evt1.E3EVT = E3

E3.Server = "E3Server_HostName"

If Not (E3.UnregisterCallback("Dados.TagDemo1.Value")) Then
MsgBox "Não foi possível desregistrar o Link passado!"
End If
End Sub

O código é idêntico ao do botão anterior, com exceção da chamada do método. Substituimos o método RegisterCallback por UnregisterCallback para "desregistrar" o objeto "TagDemo1" e, desta forma, encerrarmos a monitoração do mesmo.

Agora conseguimos ativar e desativar o recebimento de eventos provenientes de "TagDemo1" através dos botões "Ativar evento" e "Desativar evento".

7) Como realizar consultas ao objeto Banco de Dados com o E3DataAccess

A biblioteca E3DataAccess também nos permite realizar consultas ao objeto Banco de Dados do E3. Logo, torna-se necessário a existência de um objeto Banco de Dados devidamente configurado na aplicação E3 e um objeto Consulta conectado a este banco. O E3DataAccess trata de realizar a consulta através do objeto Consulta da aplicação E3.

Continuamos com o mesmo exemplo e adicionamos um novo botão na planilha com Name "queryButton" e Caption "Consultar BD". Acessamos o código do evento de clique deste botão e complementamos ele com o código abaixo:

Private Sub queryButton_Click()
Dim Resposta As Variant
Dim Names As Variant
Dim Values As Variant
Dim rnum As Integer

Resposta = Array()

E3.Server = "E3Server_HostName"

If E3.GetE3QueryRows("Dados.Consulta1", Names, Values, Resposta) Then
  Range("G16") = "Sucesso!"
rnum = 16
  For i = 0 To 20
   Range("F" + CStr(rnum)) = Resposta(0, i)
   Range("D" + CStr(rnum)) = Resposta(1, i)
   Range("E" + CStr(rnum)) = Resposta(2, i)
   rnum = rnum + 1
Next
Else
Range("G16") = "Falha!"
End If
End Sub

Este código faz uma consulta ao Banco de Dados e preenche na planilha os vinte primeiros resultados dela a partir das células D16, E16 e F16 até as vinte células subsequentes. Como sempre, antes de chamar o método da consulta, é preciso obter a conexão com o E3Server em questão.

NOTA: Na aplicação E3 utilizada, a execução da consulta retorna mais do que vinte registros. Porém, caso sua consulta retorne menos do que vinte registros, apenas ajuste a cláusula For do código para ficar de acordo e evitar erros na execução do código.

Método GetE3QueryRows(Link, Names, Values, Rows)

Através deste método, realizamos consultas ao Banco de Dados da aplicação E3. Ele recebe quatro variáveis como parâmetros:

Link – parâmetro de entrada que fornece o caminho do objeto Consulta a ser executado no servidor E3.
Names – parâmetro de entrada que fornece uma lista (tipo array) dos nomes das variáveis a serem utilizadas na execução da consulta, caso sejam necessários.
Values – parâmetro de entrada que fornece uma lista (tipo array) dos valores das variáveis, passadas pelo parâmetro Names, a serem utilizadas na execução da consulta, caso sejam necessários.
Rows – parâmetro de saída que recebe uma matriz com o resultado da consulta executada, no caso da consulta devolver algum resultado.

Na chamada do método, estamos referenciando a consulta "Dados.Consulta1" pelo parâmetro Link, ou seja, será executada esta consulta de acordo com o conteúdo de sua propriedade SQL. Como em nossa consulta não existem variáveis sendo utilizadas, apenas passamos duas listas sem conteúdo pelos parâmetros Names e Values. Da mesma forma, a variável Resposta só será utilizada para receber o retorno dos registros da consulta pelo parâmetro Rows.

Os índices da matriz Resposta de retorno possuem a seguinte divisão: [coluna][linha], onde a coluna corresponde ao campo e linha ao registro retornados de acordo com o que foi requisitado pela consulta. A tabela consultada no exemplo possui três campos: E3TimeStamp, TagHist e TagHis_Quality. Então, o primeiro registro da matriz Resposta estaria dividido da seguinte forma:

Resposta[0][0] - onde está armazenado o valor do campo E3TimeStamp do primeiro registro resultante.
Resposta[1][0] - onde está armazenado o valor do campo TagHist do primeiro registro resultante.
Resposta[2][0] - onde está armazenado o valor do campo TagHist_Quality do primeiro registro resultante.

Logo:

Resposta[i][j] – é onde está armazenado o valor do campo i do registro j resultante.

Dentro da cláusula For do código são preenchidas as células da planilha de acordo com os valores dos registros retornados pela consulta. Com o código pronto, quando clicamos no botão "Consultar BD", obtemos o resultado a seguir:

Figura 14: Resposta do botão "Consultar BD"

Após esta última etapa, foram demonstrados todos os tipos de operações possíveis de se realizar com a biblioteca E3DataAccess. Com a aplicação exemplo criada pelo VBA, conseguimos ler e escrever valores, receber eventos e realizar consultas com os objetos de uma aplicação E3.

8) Como conectar uma aplicação C++ ao E3DataAccess

O E3DataAccess é uma biblioteca managed, então apenas linguagens .NET conseguem se comunicar com ela: C#, VB.NET, C++/CLI... ou algum meio que permita código nativo (C++) comunicar-se com assemblies managed. Existem formas de fazer isso, uma delas permite a utilização de código nativo e managed dentro de um mesmo assembly. Segue o link para uma documentação da Microsoft sobre esse assunto:

http://msdn.microsoft.com/en-us/library/x0w2664k(VS.80).aspx

9) Conclusão

Com este artigo foi possível entender melhor o funcionamento da biblioteca E3DataAccess. Suas funções de interação com o E3Server são de simples entendimento e nos permitem realizar operações fundamentais em aplicações E3.

Além disso, ela aumentou as opções de desenvolvimento de aplicações com o E3. A biblioteca oferece ao desenvolvedor a opção de desenvolver aplicações em ambientes com os quais esteja mais familiarizado.