Como criar um servidor RealTimeData para o Excel
Resumo
O Microsoft Excel fornece uma nova função de livro, RTD, que lhe permite chamar servidor de automatização COM (Component Object Model) com o objetivo de obter dados em tempo real. Este artigo descreve como utilizar o Visual Basic para criar um Servidor RealTimeData para utilizar com a função RTD do Excel.
Mais Informações
A função da mesma tem a seguinte sintaxe:
=RTD(ProgID,Server,String1,[String2],...)
O primeiro argumento, ProgID, representa o Identificador Programático (ProgID) do servidor RealTimeData. O argumento Servidor indica o nome do aparelho no qual o servidor RealTimeData é executado; este argumento pode ser uma cadeia nula ou omitido se o servidor RealTimeData for executado localmente. Os argumentos restantes representam simplesmente parâmetros para enviar para o servidor RealTimeData; cada combinação exclusiva destes parâmetros representa um "tópico", que tem um "ID de tópico" associado. Os parâmetros são sensíveis às caixas de dados. Por exemplo, a seguinte ilustra as chamadas para o servidor RTD que resultariam em três IDs de tópico separados:
=RTD("ExcelRTD.RTDFunctions",,"AAA", "10")
=RTD("ExcelRTD.RTDFunctions",,"AAA", "5")
=RTD("ExcelRTD.RTDFunctions",,"aaa", "5")
Para que um Servidor de Automatização COM seja um Servidor RealTimeData para ser utilizado com a função RTD do Excel, tem de implementar a interface do IRTDServer. O servidor tem de implementar todos os métodos do IRTDServer:
ServerStart: chamada quando o Excel pede o primeiro tópico RTD para o servidor. ServerStart deve devolver um 1 no sucesso e um valor negativo ou 0 na falha. O primeiro parâmetro do método ServerStart é um objeto de chamadas que o servidor RealTimeData utiliza para notificar o Excel quando deve recolher atualizações do servidor RealTimeData.
ServerTerminate: ligou quando o Excel já não necessita de tópicos RTD do servidor RealTimeData.
ConnectData: Ligou-se sempre que o Excel pede um novo tópico RTD a partir do servidor RealTimeData.
DisconnectData: Ligou sempre que o Excel já não necessitar de um tópico específico.
HeartBeat: chamado pelo Excel se um determinado intervalo tiver decorrido desde a última vez que o Excel foi notificado das atualizações a partir do servidor RealTimeData.
RefreshData: chamada quando o Excel está a pedir uma atualização sobre tópicos. A atualizaçãoData é chamada após o servidor notificar o Excel de que existem atualizações e devolve uma contagem dos tópicos a atualizar juntamente com o ID de tópico e o valor de cada tópico.
Criar um Servidor RealTimeData de Exemplo
O exemplo seguinte demonstra como criar e utilizar um servidor RealTimeData com o Microsoft Excel 2002. Este servidor fornece simplesmente um contador que é atualizado a cada 10 segundos numa base de dados. O servidor aceita até duas cadeias de tópicos. A primeira cadeia de tópico pode ser AAA, BBB e CCC; qualquer outra cadeia de tópico é considerada inválida e o servidor devolve #VALUE! à função RTD. A segunda cadeia é um valor numérico que representa a forma como o valor devolvo deve ser incrementado. Se a segunda cadeia for omitida, o valor de incremento é predefinido para 1. Se a segunda cadeia não for numérica, o servidor devolve #NUM! à função RTD.
Inicia um novo projeto ActiveX DLL no Visual Basic.
No menu Projeto , clique em Referências, selecione a Biblioteca de Objetos da sua versão do Excel e, em seguida, clique em OK. Por exemplo, selecione uma das seguintes ações:
- Para o Microsoft Office Excel 2007, selecione Biblioteca de Objetos do Microsoft Excel 12.0.
- Para o Microsoft Office Excel 2003, selecione Biblioteca de Objetos do Microsoft Excel 11.0.
- Para o Microsoft Excel 2002, selecione Biblioteca de Objetos do Microsoft Excel 10.0.
No menu Projeto, clique em Propriedades do Project1. Altere o Nome do Projeto para ExcelRTD e, em seguida, clique em OK.
Altere a propriedade Nome do módulo de classe Classe1 para RTDFunções. Adicione o seguinte código a RTDFunções:
Option Explicit Implements IRtdServer 'Interface allows Excel to contact this RealTimeData server Private m_colTopics As Collection Private Function IRtdServer_ConnectData(ByVal TopicID As Long, Strings() As Variant, GetNewValues As Boolean) As Variant '** ConnectData is called whenever a new RTD topic is requested 'Create a new topic class with the given TopicId and string and add it to the 'm_colTopics collection Dim oTopic As New Topic m_colTopics.Add oTopic, CStr(TopicID) oTopic.TopicID = TopicID oTopic.TopicString = Strings(0) If UBound(Strings) >= 1 Then oTopic.SetIncrement Strings(1) 'For this example, the initial value for a new topic is always 0 IRtdServer_ConnectData = oTopic.TopicValue Debug.Print "ConnectData", TopicID End Function Private Sub IRtdServer_DisconnectData(ByVal TopicID As Long) '** DisconnectData is called whenever a specific topic is not longer needed 'Remove the topic from the collection m_colTopics.Remove CStr(TopicID) Debug.Print "DisconnectData", TopicID End Sub Private Function IRtdServer_Heartbeat() As Long '** Called by Excel if the heartbeat interval has elapsed since the last time ' Excel was called with UpdateNotify. Debug.Print "HeartBeat" End Function Private Function IRtdServer_RefreshData(TopicCount As Long) As Variant() '** Called when Excel is requesting a refresh on topics. RefreshData will be called ' after an UpdateNotify has been issued by the server. This event should: ' - supply a value for TopicCount (number of topics to update) ' - return a two dimensional variant array containing the topic ids and the ' new values of each. Dim oTopic As Topic, n As Integer ReDim aUpdates(0 To 1, 0 To m_colTopics.Count - 1) As Variant For Each oTopic In m_colTopics oTopic.Update aUpdates(0, n) = oTopic.TopicID aUpdates(1, n) = oTopic.TopicValue n = n + 1 Next TopicCount = m_colTopics.Count IRtdServer_RefreshData = aUpdates Debug.Print "RefreshData", TopicCount & " topics updated" End Function Private Function IRtdServer_ServerStart(ByVal CallbackObject As Excel.IRTDUpdateEvent) As Long '** ServerStart is called when the first RTD topic is requested Set oCallBack = CallbackObject Set m_colTopics = New Collection g_TimerID = SetTimer(0, 0, TIMER_INTERVAL, AddressOf TimerCallback) If g_TimerID > 0 Then IRtdServer_ServerStart = 1 'Any value <1 indicates failure. Debug.Print "ServerStart" End Function Private Sub IRtdServer_ServerTerminate() '** ServerTerminate is called when no more topics are needed by Excel. KillTimer 0, g_TimerID '** Cleanup any remaining topics. This is done here since ' IRtdServer_DisconnectData is only called if a topic is disconnected ' while the book is open. Items left in the collection when we terminate ' are those topics left running when the workbook was closed. Dim oTopic As Topic For Each oTopic In m_colTopics m_colTopics.Remove CStr(oTopic.TopicID) Set oTopic = Nothing Next Debug.Print "ServerTerminate" End Sub
No menu Projeto, clique em Adicionar Módulo de Classe. Altere a propriedade Nome do módulo de classe para Tópico e altere a propriedade Instancing para Privado. Adicione o seguinte código ao módulo de classe Tópico:
Option Explicit Private m_TopicID As Long Private m_TopicString As String Private m_Value As Variant Private m_IncrementVal As Long Private Sub Class_Initialize() m_Value = 0 m_IncrementVal = 1 End Sub Friend Property Let TopicID(ID As Long) m_TopicID = ID End Property Friend Property Get TopicID() As Long TopicID = m_TopicID End Property Friend Property Let TopicString(s As String) s = UCase(s) If s = "AAA" Or s = "BBB" Or s = "CCC" Then m_TopicString = s Else m_Value = CVErr(xlErrValue) 'Return #VALUE if not one of the listed topics End If End Property Friend Sub Update() On Error Resume Next 'the next operation will fail if m_Value is an error (like #NUM or #VALUE) m_Value = m_Value + m_IncrementVal End Sub Friend Sub SetIncrement(v As Variant) On Error Resume Next m_IncrementVal = CLng(v) If Err <> 0 Then m_Value = CVErr(xlErrNum) 'Return #NUM if Increment value is not numeric End If End Sub Friend Property Get TopicValue() As Variant If Not (IsError(m_Value)) Then TopicValue = m_TopicString & ": " & m_Value Else TopicValue = m_Value End If End Property
No menu Projeto, selecione Adicionar Módulo. Adicione o seguinte código ao novo módulo:
Public Declare Function SetTimer Lib "user32" (ByVal hWnd As Long, _ ByVal nIDEvent As Long, ByVal uElapse As Long, ByVal lpTimerFunc As Long) As Long Public Declare Function KillTimer Lib "user32" (ByVal hWnd As Long, ByVal nIDEvent As Long) As Long Public Const TIMER_INTERVAL = 5000 Public oCallBack As Excel.IRTDUpdateEvent Public g_TimerID As Long Public Sub TimerCallback(ByVal hWnd As Long, ByVal uMsg As Long, ByVal idEvent As Long, ByVal dwTime As Long) oCallBack.UpdateNotify End Sub
No menu Ficheiro, clique em Tornar ExcelRTD.dll criar o componente.
Utilizar o Servidor RTD no Excel
Inicia um novo livro no Microsoft Excel.
Na célula A1, introduza a seguinte fórmula e, em seguida, prima a tecla ENTER:
=RTD("ExcelRTD.RTDFunções";"AAA"; 5)
O valor de retorno inicial é "AAA: 0". Após cinco segundos, o valor é atualizado para "AAA: 10" e, após 10 segundos, o valor é atualizado para "AAA:15" e assim por cima.
Na célula A2, introduza a seguinte fórmula e prima ENTER:
=RTD("ExcelRTD.RTDFunções";"BBB"; 3)
O valor de retorno inicial é "BBB: 0". A cada cinco segundos, o valor da célula incrementa 3.
Na célula A3, introduza a seguinte fórmula e prima ENTER:
=RTD("ExcelRTD.RTDFunções";"AAA"; 5)
O valor de retorno inicial corresponde aos conteúdos da célula A1, uma vez que este é o mesmo "tópico" utilizado na célula A1.
Na célula A4, introduza a seguinte fórmula e prima Enter: =RTD("ExcelRTD.RTDFunções";"AAA"; 10)
O valor de retorno inicial é "AAA: 0". A cada cinco segundos, o valor da célula é incrementado, tal como as outras células. Tenha em atenção que o valor devolto não corresponde aos conteúdos da célula A1 ou A3 porque a combinação de parâmetros transmitido para o servidor é diferente.
Para esta ilustração, o servidor RTD foi compilado e o Excel estava a utilizar a versão em tempo de executar do componente. Para fins de depuração, os servidores RTD podem ser executados a partir do Visual Basic IDE.
Para executar no modo de depuração:
- Saia do Microsoft Excel e mude para o projeto no Visual Basic.
- Prima F5 para iniciar o componente. Se for exibida a caixa de diálogo Propriedades do Projeto, clique em OK para selecionar a opção predefinida aguardar pela criação dos componentes.
- Certifique-se de que a janela Immediate no Visual Basic é apresentada. À medida que introduza fórmulas nas células e à medida que as células são atualizadas, examine os conteúdos da janela Imediato no Visual Basic para ver que ações acionam os diferentes eventos.
Nota
Sobre o Evento DisconnectData
Embora o Excel seja um subscritor do seu servidor RTD, aciona o evento DisconnectData quando já não necessita de um tópico (por exemplo, quando elimina ou limpa uma fórmula RTD numa célula). No entanto, o Excel não liga para DisconnectData em cada tópico do servidor RTD quando o livro é fechado ou o Excel fecha; Em vez disso, o Excel chama apenas ServerTerminate. Quando estiver a criar um servidor RTD, deve criar código para qualquer limpeza necessária de tópicos ou outros objetos quando o evento ServerTerminate for ateado.
(c) Microsoft Corporation 2001, Todos os Direitos Reservados. Contribuições de Lori B. Turner, Microsoft Corporation.