R-GMA C API

Introduction

This is the detailed function documentation for the prototype R-GMA C API. The API has been extensively redesigned in anticipation of the new Web Services version of R-GMA, and the purpose of this prototype is to give users a first chance to experiment with the new API and feed back any comments to the development team.

This version of the prototype is designed to interface to the old servlets- based R-GMA services, so if you have access to an existing R-GMA servlet implementation (MON box), you can use this API with it. The API is almost fully functional, except where it has not been possible to map new functionality to the old servlets implementation.

The API consists of a single header file (rgma.h) and a library (libglite-rgma-c.a). It is a pure C implementation, and has no external software dependencies. The library provided in the binary distribution is for Red Hat Linux systems, but you can easily re-compile the source files for other systems (including Win32, by linking with a Winsock implementation such as wsock32.dll): just compile all of the source files together.

This document provides a brief introduction to the API, together with detailed function documentation (autogenerated from rgma.h). The C-API User Guide is the best starting point for using the API. For a full description of how R-GMA works, see the R-GMA specification document.


Configuration

You need a copy of the header file (rgma.h) and library file (libglite-rgma-c.a) somewhere accessible to your code. The library also extracts the URLs of the R-GMA servlets you wish to connect to from a file called "rgma.conf". The standard configuration puts the library file in $RGMA_HOME/lib, the header file in $RGMA_HOME/include and the configuration file in $RGMA_HOME/etc/rgma/rgma.conf, where $RGMA_HOME is usually "/opt/glite". The enviroment variable "RGMA_HOME" must be defined, and the file "rgma.conf" must exist. This file is shared by all R-GMA APIs, so you may have an existing one (it used to be called rgma.props). See here if you need to create one from scratch.

If you need to use a proxy server to access the servlets, set the environment variable http_proxy to contain the URL (including port number) of the proxy server.


Using the library

See the new C-API User Guide for an introduction and worked examples.


Configuration File (rgma.conf)

The configuration file should contain lines for each of the servlets to which the API will connect. If you are running the services on the same machines as the API, it will look like this:

LatestProducer=http://localhost:8080/R-GMA/LatestProducerServlet
DataBaseProducer=http://localhost:8080/R-GMA/DataBaseProducerServlet
StreamProducer=http://localhost:8080/R-GMA/StreamProducerServlet
Archiver=http://localhost:8080/R-GMA/ArchiverServlet
CanonicalProducer=http://localhost:8080/R-GMA/CanonicalProducerServlet
Consumer=http://localhost:8080/R-GMA/ConsumerServlet

Limitations of prototype

The following functionality is not yet implemented in this prototype (because the servlets don't support it):

More information