NOTAS GERAIS:
- Este artigo se aplica ao Elipse E3, versões 4.0 ou inferior.
- A biblioteca E3DataAccess apresenta um erro ao ser utilizada em linguagens sem tipos (typeless), como o VBScript ou o JavaScript.
- Este componente é compatível apenas com aplicações 32 bits.
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 ilustra 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 a comunicação com o E3Server.
Com o E3Studio, Microsoft Excel e VBA devidamente instalados, acesse a interface VBA da aplicação Excel. Na interface do VBA, adicione a biblioteca E3DataAccess na lista de referências do projeto. Para isto, entre na opção References, localizada no menu Tools:
Figura 1: Acessando lista de referências do projeto
Na lista de referências disponíveis, procure pela biblioteca E3DataAccess e habilite-a através da caixa de seleção.
Figura 2: Lista de referências disponíveis no projeto
Caso a biblioteca não esteja disponível na lista de referências, é preciso registrá-la. Para isto, clique no botão Browse, e uma caixa de seleção para a determinação da biblioteca será exibida.
Figura 3: Caixa de seleção da biblioteca
Procure pelo arquivo .dll chamado E3DataAccess. Ele vem juntamente no pacote do E3 versão 3.0, e encontra-se dentro do seu diretório de instalação, 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; então, siga o passo anterior novamente. Confirme a modificação clicando no botão OK.
3) Instanciando um novo objeto E3DataAccess no projeto
Após a biblioteca E3DataAccess ter sido adicionada ao projeto, é possível utilizá-la. 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 via Project Explorer, e selecionar a opção Insert–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, que deve ser renomeado como E3ServerCOM.
Clique 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, criamos 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: *quando um novo objeto E3DataAccess é instanciado, também é consumido um produto de Viewer do Hardkey. Isso pode ser visualizado na opção de Licenças, disponível no menu do E3Server. Portanto, deve-se prestar atenção redobrada para que não sejam consumidos mais produtos do que o necessário.
*A partir da versão 4.5.208 o E3Server suporta conexões do E3DataAccess e do E3AccessLayer ilimitadas, sem consumo de Viewer ou de qualquer outro tipo de produto.
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 chamado Hist1 com dois campos: E3TimeStamp e TagHist, que armazenam os valores gerados pelo TagDemo2:
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. O objeto Histórico foi associado ao BancoDados1 através de sua propriedade DBServer. Tudo isto foi feito para utilizar a função de acesso ao Banco de Dados do E3DataAccess.
Figura 6: Banco de Dados da aplicação E3
Atribua um nome qualquer a tabela do Histórico pela propriedade TableName, e ela será gerada clicando no botão Gerar estrutura no BD do menu.
Crie um novo objeto Consulta dentro do Servidor de Dados. Configure-o 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, crie uma consulta que retorne todos os dados da tabela do Histórico.
Figura 7: Tela de definição da consulta
5) Leitura e escrita de dados com o E3DataAccess
Com a aplicação E3 pronta, retorne ao Excel. Selecione sua tela e crie dois Botões de Comando; neste exemplo, faça 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 a opção View–Toolbars–Control Toolbox:
Figura 8: Habilitando a barra Control Toolbox no Excel
O componente CommandButton estará disponível na barra Control Toolbox; selecione-o e adicione os dois botões. Clique com o botão direito do mouse no primeiro CommandButton e acesse suas propriedades. Na propriedade Caption, mude seu conteúdo para “Ler valor” e faça o mesmo com o outro botão, mas mudando seu conteúdo para “Escrever valor”. Isto mudará o texto dos botões. Mude também a propriedade Name dos botões de leitura e escrita para: readValueButton e writeValueButton, respectivamente.
Agora, acesse o código do botão encarregado de ler o valor do tag da aplicação E3 (readValueButton). Clique 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, adicione 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 instanciado 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 o 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 clicar o botão Ler valor, teremos uma resposta conforme 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, acesse o código do evento de clique do botão writeValueButton, como foi feito com o primeiro botão. Clique duas vezes com o mouse em cima dele e será aberto o código do evento no VBA.
Dentro dele, adicione 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, utilize 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 método GetValue, e 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 o 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 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.
Obs: Nas versões 4.5 ou superiores, foram adicionados dois novos métodos: ReadValue e WriteValue. Eles substituem GetValue e o SetValue, que consequentemente devem ser evitados.
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 alguma mudança nele.
Crie um novo botão com a propriedade Name com o valor “onEventsButton” e Caption com o valor “Ativar evento”. Após isto, acesse o VBA.
Dentro do VBA, crie um novo módulo classe, clicando no menu Insert e escolhendo a opção Class Module.
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; mude 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: Lista de seleção de Objetos do VBA
Ao selecionar 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, coloque o código que será executado quando ocorrer esta mudança. Neste caso, faça 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 descobrir 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. Acesse o código dele e insira 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, é possível 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.
É possível 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: Resposta do botão “Ativar evento”
Agora é possível monitorar os eventos de TagDemo1, mas como fazer para encerrar 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”, insira 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. Substitua 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.
No mesmo exemplo, adicione um novo botão na planilha com Name “queryButton” e Caption “Consultar BD”. Acesse o código do evento de clique deste botão e complemente-o 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) Considerações Finais
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.
Anexos:
