# RBNB DataTurbine

# JavaBean / ActiveX User Guide

## November 2007

## Copyright Creare, Inc.

## Table of Contents

- Introduction
- Objects
  - ChannelMap
  - Client
  - Sink
  - Source
  - PlugIn
- Installation
- Examples

## Introduction

The JavaBean interface to the RBNB Simple API (SAPI) provides a persistent control which may be included in any container application to provide RBNB support. Most of the methods which are visible to the Java developer via the SAPI are also exported through the JavaBean interface. This document assumes familiarity with the SAPI.

Via the JavaBean to ActiveX bridge provided by Sun Microsystems, it is possible to use this JavaBean anywhere one might use an ActiveX control. Now any ActiveX container may be used as an RBNB client: Microsoft Word, Microsoft Access, DataViews, LabVIEW, MATLAB, etc. The interface for the ActiveX control is identical to the JavaBean interface in the method names and number of parameters, but the data types involved vary depending on the interface used. Please consult your container's documentation for specifics on how to include ActiveX components, and Sun's ActiveX bridge user guide and FAQ for more information.

## Objects

All of the classes available in the Simple API can be created as JavaBeans or ActiveX objects. There are some differences in available methods, because the JavaBean brdige does not support method overloading. The following notes describe what those differences are.

JavaBeans and ActiveX objects always use the default constructor for an object. Each object has methods for specifying any constructor parameters (if any exist) after the object has been created.

### ChannelMap

The ChannelMap object stores channel names and their associated data for posting to or retrieval from a server. See the SAPI ChannelMap JavaDoc.

Method | Difference from SAPI
--- | ---
PutData | The overloaded version which takes the byte order argument is not available. Local byte order is assumed.
toString | This method, and the other Object methods, are not exported.

### Client

Although instances of the Client object cannot be created, it serves as the base class for the Sink, Source, and PlugIn objects. See the SAPI Client JavaDoc.

Method | Difference from SAPI
--- | ---
OpenRBNBConnection | The versions of this method with zero and two parameters are not available.
CloseRBNBConnection | The version of this method with zero parameters is not available.
SetRingBuffer | This method exists to allow the cache size, archive mode, and archive size to be specified after the object has been created.

### Sink

In addition to the changes listed above to its base object, a few other methods have been affected. Note that since the constructor takes no parameters in the JavaBean/ActiveX world, the SetRingBuffer method should be used. See the SAPI Sink JavaDoc.

Method | Difference from SAPI
--- | ---
Fetch | Only the version with two parameters has been exported. Since the JavaBean bridge to ActiveX does not allow objects to be returned, you must pass a valid ChannelMap object to this method, which will be filled with the result.
Request | Only the version with four parameters is available.

### Source

In addition to the changes listed in Client, the Flush method is changed. Note that since the constructor takes no parameters in the JavaBean/ActiveX world, the SetRingBuffer method should be used. See the SAPI Sink JavaDoc.

Method | Difference from SAPI
--- | ---
Flush | Only the version with two parameters has been exported.

### PlugIn

In addition to the changes listed for Client, above, a few other methods have been affected. See the SAPI Sink JavaDoc.

Method | Difference from SAPI
--- | ---
SetRingBuffer | This method is unsupported for PlugIns, and therefore is not exported.
Fetch | Only the version with two parameters has been exported. Since the JavaBean bridge to ActiveX does not allow objects to be returned, you must pass a valid PlugInChannelMap object to this method, which will be filled with the result.
Flush | The version with one parameter is not available.

### PlugInChannelMap

Other than the changes to its base class, the ChannelMap class, the JavaBean/ActiveX interface for the PlugInChannelMap is identical to the SAPI interface. See the SAPI Sink JavaDoc.

## Installation

1. You will need a Microsoft compatible compiler, V 6.0 or later. Run VCVARS32.bat. If you don't have one, have someone who does execute steps 1 and 2, and give you the results. Then skip to step 3.
2. Run pack.bat. It should output 5 DLLs in the current directory.
3. Run:

   reg.bat [path to your JRE]

   Note that the JRE should be the PUBLIC jre, not the one hidden inside a JDK installation.

You should now be able to see the controls with any ActiveX control client or COM browser.

## Examples

In this section we will provide some examples of the usage of the JavaBean and the corresponding ActiveX control. The exact syntax for your application will vary depending on the container used, so these examples can only serve as a guide.

### ActiveX via Visual Basic for Applications: Microsoft Excel™

In this example, one second's worth of data and its corresponding time values will be pulled from an RBNB server and placed in two columns of an Excel™ spreadsheet. The worksheet appears as below.

#### Creating the example

The first step is to create a button to perform the task. This is most easily done using the Control Toolbar. You can change the button text by right clicking and selecting "Properties", then changing the "Name" property. To associate code with the button, right click and select "View Code". This will open up Visual Basic for Applications™. The code below performs the task we seek to perform.

    Private Sub FetchButton_Click()
        Dim index As Long, ii As Long
        Set Sink1 = CreateObject("Sink.Bean")
        Set ChannelMap1 = CreateObject("ChannelMap.Bean")
        Set ChannelMap2 = CreateObject("ChannelMap.Bean")

        Sink1.OpenRBNBConnection "localhost:3333", "ExcelDemo", "", ""
        Sheet1.Cells(1, 1) = "Times"
        Sheet1.Cells(1, 2) = "rbnbSource/c0"
        ChannelMap1.Clear
        ChannelMap1.Add ("rbnbSource/c0")
        Sink1.Request ChannelMap1, 0, 1, "newest"
        Sink1.Fetch -1, ChannelMap2
        If (ChannelMap2.NumberOfChannels > 0) Then
            times = ChannelMap2.GetTimes(0)
            result = ChannelMap2.GetDataAsFloat32(0)
            For ii = 1 To UBound(result)
                Sheet1.Cells(ii + 1, 1) = times(ii - 1) - times(0)
                Sheet1.Cells(ii + 1, 2) = result(ii - 1)
            Next ii
        Else
            MsgBox "No data."
        End If
        Sink1.CloseRBNBConnection

        ' Clean up objects:
        Set Sink1 = Nothing
        Set ChannelMap1 = Nothing
        Set ChannelMap2 = Nothing
    End Sub

Now exit Design Mode by pressing the icon in the Control Toolbar which contains a ruler, a square, and a pencil. You need to start an RBNB server and RBNB source. If everything has been set up correctly, pressing the "Fetch Data" button should now fill the first two columns with time values and data, from the channel "rbnbSource/c0". The plot may be added using the Chart Wizard.