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.

  1. Inicia um novo projeto ActiveX DLL no Visual Basic.

  2. 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.
  3. No menu Projeto, clique em Propriedades do Project1. Altere o Nome do Projeto para ExcelRTD e, em seguida, clique em OK.

  4. 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
    
    
  5. 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
    
  6. 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
    
  7. No menu Ficheiro, clique em Tornar ExcelRTD.dll criar o componente.

Utilizar o Servidor RTD no Excel

  1. Inicia um novo livro no Microsoft Excel.

  2. 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.

  3. 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.

  4. 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.

  5. 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:

  1. Saia do Microsoft Excel e mude para o projeto no Visual Basic.
  2. 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.
  3. 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.