R (D)COM Server V1.35

Overview

This package contains a COM server used to connect a client application (e.g. Microsoft Excel) with R.

An Add-In for Microsoft Excel is provided as well as Active X controls to be included in your applications.

• major bugfixes in error handling (R parse errors)
• more Active X Controls for Text Output Device
• Installation/Uninstallation
• Repository for R instances for shared and exclusive access
• Many Samples
• Excel Add-In

Features

• data-transfer both from R to the client-application and vice versa, currently supporting scalars (booleans, integers, doubles and strings) and arrays of these.
• "console" device (Active X control) for local/remote R server output.
• graphics device (Active X control) for local/remote R graphics output
• multiple local/remote server applications ("R processes") accessible by single client
• multiple local/remote clients per R server process
• Add-In for Microsoft Excel to use R as the computational backend
• centralized repository for managing multiple R processes including shared and exclusive access from multiple machines
• remote access to R possible without any local installation

Archives

RSrv135.exe

setup program for server and sample code (including runtime libraries)

RSrv135S.zip

VC++ 6.0 and VB sources for server and controls, CVS access is in work

Installation

• Install the latest R release (>= R 1.6.0). R 1.9.0 or higher is recommended.
• Start the setup program
• If a previous version has been installed, don't forget to remove this one
  • close all client applications using the COM server
  • unregister the COM server

    %R_HOME%\bin\StatConnectorSrv /UnRegServer

  • delete old binaries
• R (D)COM Server installation
  • Which Package should I Install?

    RSrv135.exe is a full installer and provides all required components including runtime libraries for Visual Basic and Visual C++. Previous versions provided an installer without the runtime libraries, too. This isn't supported any more.

    If you don't want to make changes to the server software you won't have to download and install the sources either. All information required for creating a client application using the COM server is included in the documentation and the sample code installed with the COM server.

  • install RSrv135.exe.

    Installation allows you to choose between various default types of installation.

    • If you want to develop client applications, you should choose a "Development installation". This will install binaries for running local and remote servers, test and sample applications, including source code. An installation of R is required on this machine, too.

      When deploying your own client application to some machine, you have to install R (D)COM Server on this machine, too.

    • If running R locally on this machine, choose "Local Server Installation". This will install binaries for the local COM servers and a simple test application used for testing the basic functionality of R and the R (D)COM Server installation. A local installation of R is required, too. This machine can be used for running client applications using a local R server and for providing R server objects for remote clients, too.
    • For running a client application locally and accessing R objects installed on a remote server, choose "Remote Server Files" as your setup option. This will set up necessary binaries for accessing an installation of R and R (D)COM server on a remote machine. R is not required on this machine
• start 01 - Basic Test from the R (D)COM Server program group in the start menu and press "Start".

Troubleshooting

If anything goes wrong when calling .Init() of the COM object for the first time, retrieve error information using .GetErrorText():

"installation problem: unable to load connector"

R proxy library could not be loaded. The cause of this common failure can be:

• the environment variable %R_HOME% points to a directory where R is not installed and
• the registry key corresponding to your R installation does not point to the installation folder of R and
• rproxy.dll and R.dll cannot be found in the %PATH%

In case you have downloaded precompiled binaries from CRAN and installed them, something went wrong there. Please try to reinstall R using the setup program. Download "dbgview" (see section "Resources") to find out what's going wrong.

If you have compiled R yourself, check %R_HOME%\bin\rproxy.dll and the registry key HKEY_LOCAL_MACHINE\Software\R-core\R\InstallPath if this one points to your R installation folder.

"installation problem: invalid connector library"

possibly damaged R proxy library. This version of the COM server requires R >= 1.6.

"installation problem: interpreter interface version mismatch"

wrong version of R proxy library. This version of the COM server requires R >= 1.6.

"installation problem: interpreter version mismatch"

wrong version of R. This version of the COM server requires R >= 1.6.

If a message box shows up on your call to .Init(), which tells you that the base library could not be found, you probably should set R_HOME to your installation folder. This should rarely be necessary.

If you cannot solve the installation problem by yourself, please try to find help on the R COM mailing list (see "Resources"). Subscribing to this list is recommended if you want to use/are using the R COM server (or any other part of R's COM connectivity modules).

Using the COM server (Example code in Visual Basic)

1. get a server object

   dim x as StatConnector
set x = new StatConnector

   and install an error handler

   on error goto error_handler

2. fire up R

   x.Init ("R")

3. use R

   x.SetSymbol ("symname",value)

   or

   y = x.GetSymbol ("symname")

   or

   y = x.Evaluate ("expression")

   or

   x.EvaluateNoReturn ("expression")

4. shut down R

   x.Close

5. error handler

   error_handler:
MsgBox x.GetErrorText,"R Server Error"

   You can retrieve Information about the COM Server by calling x.GetServerInformation passing the requested information identifier (see enum InformationType in StatConnectorSrv.idl). Get information about the proxy dll calling x.GetConnectorInformation or the R interpreter itself with x.GetInterpreterInformation.

Using the COM server (Example code in Python)

To use COM with Python, the Python for Windows extensions (available from http://starship.python.net/crew/mhammond/) have to be installed.

Thanks to Dominic Barraclough (mailto:Dominic_Barraclough@urmc.rochester.edu) for the following piece of code:

After firing up the python interpreter, if one enters the following we can see that -python can talk to R and get stuff back!

>>> from win32com.client import Dispatch
>>> sc=Dispatch("StatConnectorSrv.StatConnector")
>>> sc.Init("R")
>>> sc.Evaluate("2+2")
4.0 # COMMENT- R can do arithmetic and can tell python about it!
>>>

RServerManager: A Short Introduction

R (D)COM server provides a mechanism for standard applications like Microsoft Excel or custom applications written in any language serving as a COM client (e.g. Visual Basic, Perl) to use the R as a powerful computational engine and renderer for graphics and text output.

The current implementation of the R server package puts every single R interpreter used in a client application into a separate address space, allowing different code and data segments for multiple instances of the interpreter even in a single client instance.

On the other hand, using COM/DCOM to expose R's functionality to client applications even makes it possible to share a single instance of an R interpreter between multiple client applications, both running on the same or even on different machines in the network. Sharing an interpreter instance also implies a shared data and code segment for R.

The implementation using COM takes care of synchronizing access to the interpreter, so only one client can use the server's functionality at the same time.

Using these COM/DCOM features to share a single interpreter requires some level of "intelligence" in the client applications and cooperation between these. One client has to create the interpreter instance and all clients have to gain access to this object in some way, by using some kind of data exchange.

This is the situation where a generic concept for managing and sharing interpreters is required: the R Server Manager.

RServerManager: Using the Server Manager

The core of the server manager is the COM object RServerManager.ServerPool. Every client application has to use an instance of this CoClass to gain access to some shared interpreter. The object itself provides a collection-like interface to a shared collection of COM objects each of them representing an R interpreter.

To share server objects between client applications on different machines, the RServerManager.ServerPool objects must run on a single machine in the network managing all server instances. While all server objects are managed on a centralized server machine, this does not necessarily mean, that the R interpreters themselves have to be instantiated on the same machine, too. The server manager only provides a mechanism for managing shared R servers and gaining access to these.

As long as RServerManager lives, it can manage R servers. Either provide your own startup script or use the sample "InitServers" for this purpose. As soon as the last program which uses RServerManager terminates the server manager will close, too and all R instances in the repository will be released. In case any application still has a reference to one of the R processes, this process will stay alive.

The sample application InitServers will provide means to add a new R server to the server manager interactively. Deleting is not possible. The list will show the currently known R servers and (in braces) the number of servers available with the shown key.

RServerManager: Shared Use Scenario

Just get elements from the server manager (take care, you will get "Item" elements) and use them for "shared" use.

Shared use means that everyone can access the same elements.

E.g. app1 can get a server with key "R" and app2 can get access to the same server. This results in shared data space!

See SharedUse sample for more info

RServerManager: Exclusive Use

One can get a R server from the server manager and request exclusive use for this server (this is an atomic operation!). Other apps also requesting exclusive use will not get access to the server.

Please take care to release the lock afterwards. It will not be released automatically for you when your app terminates.

See ExclusiveUse sample.

Shared use can interfer with exclusive use. E.g. apps requesting shared use won't honor a lock set by an exclusive use app. Never use a mixed model for access to the same COM server.

RServerManager: Server Groups

You can add multiple servers with the same name. This will create groups in the server manager. Exclusively requesting a server with a specific name will just return one server (the first one) from a group sharing the same name.

This is a good mechanism for server-pooling.

RServerManager: Future

GUI (InitServers) doesn't provide means for deleting a server. No GUI for releasing locked servers, too.

Enhancements could be:

• GUI for deleting
• config-file for InitServers (auto-start of servers)
• managing locks (viewing, deleting)...

BUGS

• dim attribute lost when transferring an array to R. fixed in 0.91
• arrays of strings could not be transferred. fixed in 0.91
• server didn't start automatically when requested. fixed in 0.91
• only a single instance of the server could be used. fixed in 0.91
• server crashes when released and graphics window open. fixed in 0.91
• server quits when evaluating an incompete expression. fixed in 1.0
• returning boolean values for TRUE caused confusion in some clients because 1 was returned instead of VARIANT_TRUE. fixed in 1.1
• exception/stack overflow when transferring large arrays of strings. fixed in 1.35
• problems transferring large arrays of any data type. fixed in rproxy.dll since R 1.9.0
• drawings using StatConnectorGraphicsDevice didn't honor NULL background and foreground color for circles, polygons and rectangles. fixed in 1.35
• rectangle sometimes drawn around StatConnectorGraphicsDevice. fixed in 1.35
• multiple Active X graphics devices not supported. fixed in 1.35

Thanks

We would like to thank the following people for their contributions to the R COM services:

• Greg Hood (mailto:G.HOOD@CGIAR.ORG) for his support on the installation of the Excel Add-In
• Dominic Barraclough (mailto:Dominic_Barraclough@urmc.rochester.edu) for the sample code for Python
• Paul A. Larsen (mailto:palarsen@bevo.che.wisc.edu) for information on how to use the R COM server with LabVIEW
• John Swan-Stone for his contributions for the VARIANT-support.

And of course we would like to thank our users who have contributed many new ideas and have helped in continously improving this project.

Resources

http://cran.r-project.org/

CRAN - the major site for R and associated software/documentation.

http://cran.r-project.org/contrib/extra/dcom/

Download location on CRAN for the R COM server. This is the last officially released version.

http://sunsite.univie.ac.at/rcom/

The home of the R COM server and clients. You can find latest snapshots and additional documentation there.

http://bugzilla.csd.univie.ac.at/

Bug-Tracking system and feature database for R COM services. Please add problem reports and enhancement ideas there. This will ensure that the information doesn't get lost and will help other users, too.

http://mailman.csd.univie.ac.at/mailman/listinfo/rcom-l

The mailing list for all R COM services. Discusses all topics related to the R COM servers and the R COM client package. See this page for information about the list, subscription etc.

See the R FAQ for information about general mailing lists concerning R.

http://www.sysinternals.com/ntw2k/freeware/debugview.shtml

Download site for dbgview.exe.

Contact and Support

For support on installation, operation etc. please direct your questions to the mailing list hostet at http://mailman.csd.univie.ac.at/mailman/listinfo/rcom-l. You can find the archives of the mailing list there, too. The list is members-only, so please subscribe to the list first. Posts by non-members will be rejected automatically.

The mailing list provides archives of all postings. Please browse the archives to find an answer to your questions first!

Directing your questions to the mailing list will reach all members of the list and increases the probability to quickly get the answer you expect.

Please honor the fact that the authors of this software package are doing the work in their spare time. Because of this, time for answering questions is limited. We are doing our best to read all postings at the mailing list and try to help as soon as possible, but we will not answer private mail sent to us concerning help for the COM server. So please post your questions to the mailing list.

If you have any ideas for enhancement of this software please let us know. It is best to discuss topics on the mailing list and then add the topic as agreed by all on the list to the feature database at http://bugzilla.csd.univie.ac.at/. We will do our best to implement features or future releases.

In case you need direct support, e.g. for a commercial product, or if your project requires additional features to be implemented in our software, don't hesitate to contact us. We will be glad to find a solution for you.

• Thomas Baier (mailto:thomas.baier@ci.tuwien.ac.at)
• Erich Neuwirth (mailto:erich.neuwirth@univie.ac.at)

License

This software is distributed under the GNU LESSER GENERAL PUBLIC LICENSE Version 2.1.

Parts can be distributed under different licenses. This is noted in the file itself.

The binaries of the COM server and its associated parts are all distributed under the GNU LESSER GENERAL PUBLIC LICENSE Version 2.1.

See COPYING.LIB for the full text of the license (or COPYING for the GNU GENERAL PUBLIC LICENSE)

Please subscribe to the mailing list dedicated to R COM services at http://mailman.csd.univie.ac.at/mailman/listinfo/rcom-l.

Author(s)

Thomas Baier and Erich Neuwirth