Como criar um servidor RealTimeData para Excel

  • Artigo
  • Aplica-se a:
    Microsoft Excel

Resumo

O Microsoft Excel fornece uma nova função de planilha, RTD, que permite chamar um servidor de Automação do COM (Component Object Model) com a finalidade de recuperar dados em tempo real. Este artigo descreve como usar o Visual Basic para criar um Servidor RealTimeData para uso com a função RTD do Excel.

Informações adicionais

A função de planilha RTD tem a seguinte sintaxe:

=RTD(ProgID,Server,String1,[String2],...)

O primeiro argumento, ProgID, representa o ProgID (Identificador Programático) do servidor RealTimeData. O argumento Server indica o nome do computador no qual o servidor RealTimeData é executado; esse argumento pode ser uma cadeia de caracteres nula ou omitido se o servidor RealTimeData deve ser executado localmente. Os argumentos restantes simplesmente representam parâmetros a serem enviados para o servidor RealTimeData; cada combinação exclusiva desses parâmetros representa um "tópico", que tem uma "ID de tópico" associada. Os parâmetros diferenciam maiúsculas de minúsculas. Por exemplo, o seguinte ilustra as chamadas para o servidor RTD que resultariam em três IDs de tópico separadas:

=RTD("ExcelRTD.RTDFunctions",,"AAA", "10")

=RTD("ExcelRTD.RTDFunctions",,"AAA", "5")

=RTD("ExcelRTD.RTDFunctions",,"aaa", "5")

Para que um Servidor de Automação COM seja um Servidor RealTimeData para uso com a função RTD do Excel, ele deve implementar a interface IRTDServer. O servidor deve implementar todos os métodos de IRTDServer:

  • ServerStart: chamado quando o Excel solicita o primeiro tópico RTD para o servidor. ServerStart deve retornar um 1 em caso de êxito e um valor negativo ou 0 em caso de falha. O primeiro parâmetro do método ServerStart é um objeto de retorno de chamada que o servidor RealTimeData usa para notificar o Excel quando deve coletar atualizações do servidor RealTimeData.

  • ServerTerminate: chamado quando o Excel não requer mais tópicos RTD do servidor RealTimeData.

  • ConnectData: chamado sempre que o Excel solicita um novo tópico RTD do servidor RealTimeData.

  • DisconnectData: chamado sempre que o Excel não exigir mais um tópico específico.

  • HeartBeat: chamado pelo Excel se um determinado intervalo tiver decorrido desde a última vez em que o Excel foi notificado sobre atualizações do servidor RealTimeData.

  • RefreshData: chamado quando o Excel está solicitando uma atualização sobre tópicos. RefreshData é chamado depois que o servidor notifica o Excel de que existem atualizações e retorna uma contagem dos tópicos a serem atualizados junto com a ID do tópico e o valor de cada tópico.

Criar um servidor RealTimeData de exemplo

O exemplo a seguir demonstra como criar e usar um servidor RealTimeData com o Microsoft Excel 2002. Esse servidor simplesmente fornece um contador que é atualizado a cada 10 segundos em uma planilha. O servidor aceita até duas cadeias de caracteres de tópico. A primeira cadeia de caracteres de tópico pode ser AAA, BBB e CCC; qualquer outra cadeia de caracteres de tópico é considerada inválida e o servidor retorna #VALUE! para a função RTD. A segunda cadeia de caracteres é um valor numérico que representa como o valor retornado deve ser incrementado. Se a segunda cadeia de caracteres for omitida, o valor de incremento será o padrão 1. Se a segunda cadeia de caracteres não for numérica, o servidor retornará #NUM! para a função RTD.

  1. Inicie um novo projeto de DLL do ActiveX no Visual Basic.

  2. No menu Projeto , clique em Referências, selecione a Biblioteca de Objetos para sua versão do Excel e clique em OK. Por exemplo, selecione um dos seguintes:

    • 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 clique em OK.

  4. Altere a propriedade Name do módulo de classe Class1 para RTDFunctions. Adicione o seguinte código a RTDFunctions:

    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 Privada. Adicione o seguinte código ao módulo de classe Topic:

    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 Arquivo, clique em Criar ExcelRTD.dll para compilar o componente.

Usar o servidor RTD no Excel

  1. Inicie uma nova pasta de trabalho no Microsoft Excel.

  2. Na célula A1, insira a seguinte fórmula e pressione a tecla ENTER:

    =RTD("ExcelRTD.RTDFunctions",,"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 diante.

  3. Na célula A2, insira a seguinte fórmula e pressione ENTER:

    =RTD("ExcelRTD.RTDFunctions",,"BBB", 3)

    O valor de retorno inicial é "BBB: 0". A cada cinco segundos, o valor da célula é incrementado em 3.

  4. Na célula A3, insira a seguinte fórmula e pressione ENTER:

    =RTD("ExcelRTD.RTDFunctions",,"AAA", 5)

    O valor de retorno inicial corresponde ao conteúdo da célula A1 porque esse é o mesmo "tópico" usado em A1.

  5. Na célula A4, insira a seguinte fórmula e pressione Enter: =RTD("ExcelRTD.RTDFunctions","AAA", 10)

    O valor de retorno inicial é "AAA: 0". A cada cinco segundos, o valor da célula é incrementado da mesma forma que as outras células. Observe que o valor retornado não corresponde ao conteúdo da célula A1 ou A3 porque a combinação de parâmetros passados para o servidor é diferente.

Para esta ilustração, o servidor RTD foi compilado e o Excel estava usando a versão em tempo de execução do componente. Para fins de depuração, os servidores RTD podem ser executados no IDE do Visual Basic.

Para executar no modo de depuração:

  1. Saia do Microsoft Excel e alterne para o projeto no Visual Basic.
  2. Pressione F5 para iniciar o componente. Se a caixa de diálogo Propriedades do Projeto for exibida, clique em OK para selecionar a opção padrão de Aguardar componentes a serem criados.
  3. Verifique se a janela Imediata no Visual Basic é exibida. Conforme você insere fórmulas nas células e conforme as células são atualizadas, examine o conteúdo da janela Imediata no Visual Basic para ver quais ações estão disparando os diferentes eventos.

Observação

Sobre o evento DisconnectData

Embora o Excel seja um assinante do servidor RTD, ele dispara o evento DisconnectData quando ele não precisa mais de um tópico (por exemplo, quando você exclui ou desmarca uma fórmula RTD em uma célula). No entanto, o Excel não chama DisconnectData em cada tópico para o servidor RTD quando a pasta de trabalho é fechada ou o Excel é encerrado; Em vez disso, o Excel chama apenas ServerTerminate. Ao criar um servidor RTD, você deve codificar qualquer limpeza necessária de tópicos ou outros objetos quando o evento ServerTerminate for acionado.

(c) Microsoft Corporation 2001, Todos os Direitos Reservados. Contribuições de Lori B. Turner, Microsoft Corporation.