rgma.h File Reference

Go to the source code of this file.

Data Structures

struct  RGMAResourceEndpoint
struct  RGMAException
struct  RGMAStorageLocation
struct  RGMAStringList
struct  RGMARow
struct  RGMAResultSet
struct  RGMATupleStore
struct  RGMATupleStoreList
struct  RGMAProducerTableEntry
struct  RGMAProducerTableEntryList
struct  RGMAIndex
struct  RGMAIndexList
struct  RGMAColumnDefinition
struct  RGMATableDefinition
struct  RGMAException_S
struct  RGMAStorageLocation_S
struct  RGMAResultSet_S
struct  RGMATableAuthorization_S

Typedefs

typedef RGMAResource_S RGMAResource
typedef RGMAException_S RGMAException
typedef RGMAStorageLocation_S RGMAStorageLocation
typedef RGMAResultSet_S RGMAResultSet
typedef RGMATableAuthorization_S RGMATableAuthorization

Functions

int RGMA_createConsumer (int terminationInterval, const char *selectStatement, int queryType, int timeInterval, RGMAResource **resourcePP)
int RGMA_createPrimaryProducer (int terminationInterval, int properties, int storageType, RGMAStorageLocation *storageLocation, RGMAResource **resourcePP)
int RGMA_createSecondaryProducer (int terminationInterval, int properties, int storageType, RGMAStorageLocation *storageLocation, RGMAResource **resourcePP)
int RGMA_createOnDemandProducer (int terminationInterval, const char *uri, RGMAResource **resourcePP)
int RGMA_reconnect (RGMAResourceEndpoint *endpointP, int resourceType, RGMAResource **resourcePP)
int RGMAPrimaryProducer_declareTable (RGMAResource *resourceP, const char *tableName, const char *predicate, int hrpSec, int lrpSec)
int RGMAPrimaryProducer_insert (RGMAResource *resourceP, const char *insertStatement, int lrpSec)
int RGMAPrimaryProducer_insertList (RGMAResource *resourceP, int numInserts, char **insertStatements, int lrpSec)
RGMATupleStoreListRGMAPrimaryProducer_listTupleStores (RGMAException *exceptionP)
int RGMAPrimaryProducer_dropTupleStore (const char *logicalName, RGMAException *exceptionP)
int RGMAPrimaryProducer_getHistoryRetentionPeriod (RGMAResource *resourceP, const char *tableName)
int RGMAPrimaryProducer_getLatestRetentionPeriod (RGMAResource *resourceP, const char *tableName)
int RGMASecondaryProducer_declareTable (RGMAResource *resourceP, const char *tableName, const char *predicate, int hrpSec)
RGMATupleStoreListRGMASecondaryProducer_listTupleStores (RGMAException *exceptionP)
int RGMASecondaryProducer_dropTupleStore (const char *logicalName, RGMAException *exceptionP)
int RGMASecondaryProducer_getHistoryRetentionPeriod (RGMAResource *resourceP, const char *tableName)
int RGMAOnDemandProducer_declareStaticTable (RGMAResource *resourceP, const char *tableName, const char *predicate)
int RGMAConsumer_start (RGMAResource *resourceP, int timeoutSec)
int RGMAConsumer_startDirected (RGMAResource *resourceP, int timeoutSec, int numProducers, RGMAResourceEndpoint *producers)
int RGMAConsumer_abort (RGMAResource *resourceP)
int RGMAConsumer_hasAborted (RGMAResource *resourceP)
RGMAResultSetRGMAConsumer_pop (RGMAResource *resourceP, int maxCount)
int RGMA_getTerminationInterval (RGMAResource *resourceP)
int RGMA_showSignOfLife (RGMAResource *resourceP)
int RGMA_close (RGMAResource *resourceP)
int RGMA_destroy (RGMAResource *resourceP)
int RGMARegistry_createRegistry (const char *vdbName, const char *registryService, RGMAException *exceptionP)
int RGMARegistry_destroyRegistry (const char *vdbName, const char *registryService, RGMAException *exceptionP)
RGMAProducerTableEntryListRGMARegistry_getAllProducersForTable (const char *vdbName, const char *tableName, RGMAException *exceptionP)
int RGMASchema_createSchema (const char *vdbName, const char *schemaService, RGMAException *exceptionP)
int RGMASchema_destroySchema (const char *vdbName, const char *schemaService, RGMAException *exceptionP)
int RGMASchema_createTable (const char *vdbName, const char *createTableStatement, int numRules, char **rules, RGMAException *exceptionP)
int RGMASchema_dropTable (const char *vdbName, const char *tableName, RGMAException *exceptionP)
int RGMASchema_createIndex (const char *vdbName, const char *createIndexStatement, RGMAException *exceptionP)
int RGMASchema_dropIndex (const char *vdbName, const char *indexName, RGMAException *exceptionP)
int RGMASchema_createView (const char *vdbName, const char *createViewStatement, int numRules, char **rules, RGMAException *exceptionP)
int RGMASchema_dropView (const char *vdbName, const char *viewName, RGMAException *exceptionP)
RGMAStringListRGMASchema_getAllTables (const char *vdbName, RGMAException *exceptionP)
RGMATableDefinitionRGMASchema_getTableDefinition (const char *vdbName, const char *tableName, RGMAException *exceptionP)
RGMAIndexListRGMASchema_getTableIndexes (const char *vdbName, const char *tableName, RGMAException *exceptionP)
int RGMASchema_setAuthorizationRules (const char *vdbName, const char *tableName, int numRules, char **rules, RGMAException *exceptionP)
RGMAStringListRGMASchema_getAuthorizationRules (const char *vdbName, const char *tableName, RGMAException *exceptionP)
int RGMA_setProperty (int service, const char *name, const char *parameter, const char *value, RGMAException *exceptionP)
char * RGMA_getProperty (int service, const char *name, const char *parameter, RGMAException *exceptionP)
char * RGMA_getVersion (int service, RGMAException *exceptionP)
RGMAResourceEndpointRGMA_getEndpoint (RGMAResource *resourceP)
const RGMAExceptionRGMA_getException (RGMAResource *resourceP)
char * RGMA_getResultSetValue (RGMAResultSet *rs, int rowNum, int colNum, const char *colName)
void RGMA_printResultSet (FILE *stream, RGMAResultSet *rs)
void RGMA_freeResource (RGMAResource *resourceP)
void RGMA_freeEndpoint (RGMAResourceEndpoint *endpointP)
void RGMA_freeException (RGMAException *exceptionP)
void RGMA_freeStringList (RGMAStringList *stringListP)
void RGMA_freeResultSet (RGMAResultSet *resultSetP)
void RGMA_freeTupleStoreList (RGMATupleStoreList *tupleStoreListP)
void RGMA_freeProducerTableEntryList (RGMAProducerTableEntryList *producerTableEntryListP)
void RGMA_freeIndexList (RGMAIndexList *indexListP)
void RGMA_freeTableDefinition (RGMATableDefinition *tableDefinitionP)
int RGMA_createPrimaryProducer (int terminationInterval, int properties, int storageType, RGMAStorageLocation *storageLocation, int numVOs, char **voNames, RGMAResource **resourcePP)
int RGMA_createSecondaryProducer (int terminationInterval, int properties, int storageType, RGMAStorageLocation *storageLocation, int numVOs, char **voNames, RGMAResource **resourcePP)
int RGMA_createOnDemandProducer (int terminationInterval, const char *uri, int numVOs, char **voNames, RGMAResource **resourcePP)
int RGMAPrimaryProducer_insert (RGMAResource *resourceP, const char *insertStatement)
int RGMAPrimaryProducer_insertList (RGMAResource *resourceP, int numInserts, char **insertStatements)
int RGMAConsumer_isExecuting (RGMAResource *resourceP)
int RGMAConsumer_count (RGMAResource *resourceP)


Typedef Documentation

typedef struct RGMAResource_S RGMAResource
 

The RGMAResource structure represents a single producer or consumer resource, and holds all API settings related to the resource. This includes the resource-endpoint, the handle to the gSOAP environment, the resource type and any errors associated with the resource. It is an opaque structure and you are not expected to read or change its contents. You should free it when no longer required by calling RGMA_freeResource.

typedef struct RGMAException_S RGMAException
 

Deprecated:
Use the new version of this structure.

typedef struct RGMAStorageLocation_S RGMAStorageLocation
 

Deprecated:
Use the new version of this structure.

typedef struct RGMAResultSet_S RGMAResultSet
 

Deprecated:
Use the new version of this structure.

typedef struct RGMATableAuthorization_S RGMATableAuthorization
 

Deprecated:
This structure was never used.


Function Documentation

int RGMA_createConsumer int  terminationInterval,
const char *  selectStatement,
int  queryType,
int  timeInterval,
RGMAResource **  resourcePP
 

Creates a new Consumer resource.

Extracts the URL of the Consumer Service from the R-GMA configuration file $RGMA_HOME/etc/rgma/rgma.conf. Both the environment variable, and the file, must exist.

Continuous, latest and history queries may optionally take a time interval to limit the age of tuples returned. This is indicated by combining the query type with the RGMAQueryType_INTERVAL qualifier, for example: (RGMAQueryType_CONTINUOUS | RGMAQueryType_INTERVAL).

Parameters:
terminationInterval The interval (in seconds) after which this Consumer resource will be destroyed by the Consumer Service, if there has been no contact from the API.
selectStatement The SQL SELECT statement for this Consumer.
queryType The type of query. Exactly one of:
RGMAQueryType_CONTINUOUS,
RGMAQueryType_LATEST,
RGMAQueryType_HISTORY or
RGMAQueryType_STATIC.
The first three types may also be combined with RGMAQueryType_INTERVAL (see above).
timeInterval Optional time-interval (in seconds) limiting the age of tuples returned by the query.
resourcePP On output, will contain pointer to new Consumer.
Returns:
0 on success, -1 on error.

int RGMA_createPrimaryProducer int  terminationInterval,
int  properties,
int  storageType,
RGMAStorageLocation storageLocation,
RGMAResource **  resourcePP
 

Creates a new Primary Producer resource.

Extracts the URL of the Primary Producer Service from the R-GMA configuration file $RGMA_HOME/etc/rgma/rgma.conf. Both the environment variable, and the file, must exist.

Parameters:
terminationInterval The interval (in seconds) after which this Primary Producer resource will be destroyed by Primary Producer Service, if there has been no contact from the API.
properties Optional properties for the new producer. Zero, or a combination (bitwise OR) of:
RGMAProducerProps_LATEST and
RGMAProducerProps_HISTORY
storageType The tuple storage type for the new producer. One of:
RGMAStorageType_MEMORY,
RGMAStorageType_DATABASE.
storageLocation Details of permanent tuple store. May be NULL if using temporary storage. Usually NULL.
resourcePP On output, will contain pointer to new Primary Producer.
Returns:
0 on success, -1 on error.

int RGMA_createSecondaryProducer int  terminationInterval,
int  properties,
int  storageType,
RGMAStorageLocation storageLocation,
RGMAResource **  resourcePP
 

Creates a new Secondary Producer resource.

Extracts the URL of the Secondary Producer Service from the R-GMA configuration file $RGMA_HOME/etc/rgma/rgma.conf. Both the environment variable, and the file, must exist.

Parameters:
terminationInterval The interval (in seconds) after which this Secondary Producer resource will be destroyed by Secondary Producer Service, if there has been no contact from the API.
properties Optional properties for the new producer. Zero, or a combination (bitwise OR) of:
RGMAProducerProps_LATEST and
RGMAProducerProps_HISTORY.
storageType The tuple storage type for the new producer. One of:
RGMAStorageType_MEMORY,
RGMAStorageType_DATABASE.
storageLocation Details of permanent tuple store. May be NULL if using temporary storage. Usually NULL.
resourcePP On output, will contain pointer to new Secondary Producer.
Returns:
0 on success, -1 on error.

int RGMA_createOnDemandProducer int  terminationInterval,
const char *  uri,
RGMAResource **  resourcePP
 

Creates a new On-demand Producer resource.

Extracts the URL of the On-demand Producer Service from the R-GMA configuration file $RGMA_HOME/etc/rgma/rgma.conf. Both the environment variable, and the file, must exist.

Parameters:
terminationInterval The interval (in seconds) after which this On-demand Producer resource will be destroyed by On-demand Producer Service, if there has been no contact from the API.
uri The URI of the system that will respond to queries (the form "socket://hostname:port").
resourcePP On output, will contain pointer to new On-demand Producer.
Returns:
0 on success, -1 on error.

int RGMA_reconnect RGMAResourceEndpoint endpointP,
int  resourceType,
RGMAResource **  resourcePP
 

Re-connects the API to the remote resource at a given resource-endpoint, i.e. it creates and initialises a local resource structure to interface to the given resource-endpoint. Does not contact the server - you should call RGMA_showSignOfLife() after reconnect() if you want to keep the resource alive.

This function is useful to re-attach to a remote resource following termination of the program that originally it. The behviour of the system is undefined if you make multiple connections to the same resource.

Parameters:
endpointP Pointer to resource-endpoint of remote resource.
resourceType R-GMA resource type: one of RGMAResourceType_CONSUMER, RGMAResourceType_PRIMARYPRODUCER, RGMAResourceType_SECONDARYPRODUCER, RGMAResourceType_ONDEMANDPRODUCER.
resourcePP On output, will contain pointer to new resource.
Returns:
0 on success, -1 on error.
See also:
RGMA_getEndpoint().

int RGMAPrimaryProducer_declareTable RGMAResource resourceP,
const char *  tableName,
const char *  predicate,
int  hrpSec,
int  lrpSec
 

Registers a Primary Producer in the Registry, as a producer for the specified table.

Parameters:
resourceP Pointer to the Primary Producer resource to register.
tableName The name of the table to declare.
predicate An SQL WHERE clause defining the subset of the table that this producer will publish. May an empty string.
hrpSec Retention period (in seconds). Tuples older than this will be removed from the history tuple storage.
lrpSec Retention period (in seconds). Tuples older than this will never be returned in latest queries and will be removed from the latest tuple storage.
Returns:
0 on success or -1 on error.

int RGMAPrimaryProducer_insert RGMAResource resourceP,
const char *  insertStatement,
int  lrpSec
 

Publishes data for a single tuple (row) into a table, using an SQL INSERT statement.

Parameters:
resourceP Pointer to the Primary Producer resource through which to publish data.
insertStatement An SQL INSERT statement.
lrpSec Retention period (in seconds). Set this to 0 to use the default set in RGMAPrimaryProducer_declareTable().
Returns:
0 on success or -1 on error.

int RGMAPrimaryProducer_insertList RGMAResource resourceP,
int  numInserts,
char **  insertStatements,
int  lrpSec
 

Publishes data for multiple tuples (rows) into a table, using SQL INSERT statements.

Parameters:
resourceP Pointer to the Primary Producer resource through which to publish data.
numInserts The number of tuples to insert.
insertStatements List of insert statements, one for each tuple.
lrpSec Retention period (in seconds). Set this to 0 to use the default set in RGMAPrimaryProducer_declareTable().
Returns:
0 on success or -1 on error.

RGMATupleStoreList* RGMAPrimaryProducer_listTupleStores RGMAException exceptionP  ) 
 

Returns a list of names and database parameters of all permanent tuple stores belonging to the user (or all tuple stores in the service if it is running insecurely).

You should free the list when no longer required, by calling RGMA_freeTupleStoreList().

Parameters:
exceptionP Pointer to exception (filled in on failure).
Returns:
RGMATupleStoreList containing zero or more tuple store definitions, or NULL on error.

int RGMAPrimaryProducer_dropTupleStore const char *  logicalName,
RGMAException exceptionP
 

Drops one of user's permanent tuple stores. Tuple stores that are currently being used by a producer cannot be dropped.

Parameters:
logicalName Logical name of tuple store to be dropped.
exceptionP Pointer to exception (filled in on failure).
Returns:
0 on success or -1 on error.

int RGMAPrimaryProducer_getHistoryRetentionPeriod RGMAResource resourceP,
const char *  tableName
 

Queries Primary Producer's retention period for history tuples in specified table.

Parameters:
resourceP Pointer to the Primary Producer resource to query.
tableName Table name to query.
Returns:
Retention period (in seconds) or -1 on error.

int RGMAPrimaryProducer_getLatestRetentionPeriod RGMAResource resourceP,
const char *  tableName
 

Queries Primary Producer's retention period for latest tuples in specified table.

Parameters:
resourceP Pointer to the Primary Producer resource to query.
tableName Table name to query.
Returns:
Retention period (in seconds) or -1 on error.

int RGMASecondaryProducer_declareTable RGMAResource resourceP,
const char *  tableName,
const char *  predicate,
int  hrpSec
 

Registers a Secondary Producer in the Registry, as a producer for the specified table.

Parameters:
resourceP Pointer to the Secondary Producer resource to register.
tableName The name of the table to declare.
predicate An SQL WHERE clause defining the subset of the table that this producer will publish. May an empty string.
hrpSec Retention period (in seconds). Tuples older than this will be removed from the history tuple storage.
Returns:
0 on success or -1 on error.

RGMATupleStoreList* RGMASecondaryProducer_listTupleStores RGMAException exceptionP  ) 
 

Returns a list of names and database parameters of all permanent tuple stores belonging to the user (or all tuple stores in the service if it is running insecurely).

You should free the list when no longer required, by calling RGMA_freeTupleStoreList().

Parameters:
exceptionP Pointer to exception (filled in on failure).
Returns:
RGMATupleStoreList containing zero or more tuple store definitions, or NULL on error.

int RGMASecondaryProducer_dropTupleStore const char *  logicalName,
RGMAException exceptionP
 

Drops one of user's permanent tuple stores. Tuple stores that are currently being used by a producer cannot be dropped.

Parameters:
logicalName Logical name of tuple store to be dropped.
exceptionP Pointer to exception (filled in on failure).
Returns:
0 on success or -1 on error.

int RGMASecondaryProducer_getHistoryRetentionPeriod RGMAResource resourceP,
const char *  tableName
 

Queries Secondary Producer's retention period for history tuples in specified table.

Parameters:
resourceP Pointer to the Secondary Producer resource to query.
tableName Table name to query.
Returns:
Retention period (in seconds) or -1 on error.

int RGMAOnDemandProducer_declareStaticTable RGMAResource resourceP,
const char *  tableName,
const char *  predicate
 

Registers an On-demand Producer in the Registry, as a producer for the specified static table. A static table only supports static queries and has no time-stamps associated with its tuples.

Parameters:
resourceP Pointer to the On-demand Producer resource to register.
tableName The name of the table to declare.
predicate An SQL WHERE clause defining the subset of the table that this producer will publish. May an empty string.
Returns:
0 on success or -1 on error.

int RGMAConsumer_start RGMAResource resourceP,
int  timeoutSec
 

Starts this consumer's query, using the mediator to find relevant producers to contact. The query will automatically abort after the specified time interval. You cannot prevent the query from timing out, but you can set a very large time interval. The query is run asynchronously. You should keep poping tuples from the consumer by calling RGMAConsumer_pop() repeatedly until it returns a result set with its endOfResults flag set to 1 (true). You can stop a query's execution by calling RGMAConsumer_abort(). Any un-popped tuples will be lost if a query is restarted.

Parameters:
resourceP Pointer to the Consumer resource whose query is to be started.
timeoutSec Query timeout (in seconds).
Returns:
0 on success or -1 on error.
See also:
RGMAConsumer_abort() and RGMAConsumer_startDirected().

int RGMAConsumer_startDirected RGMAResource resourceP,
int  timeoutSec,
int  numProducers,
RGMAResourceEndpoint producers
 

Starts this consumer's query, contacting all producers in a list provided by the user. In all other respects, this function is identical to RGMAConsumer_start(). Since the mediator is not used, it is up to the user to ensure that the producers in the list can, taken together, give a complete and correct answer to the query.

Parameters:
resourceP Pointer to the Consumer resource whose query is to be started.
timeoutSec Query timeout (in seconds).
numProducers Number of producers to contact (at least 1).
producers List of producer resource-endpoints to contact.
Returns:
0 on success or -1 on error.
See also:
RGMAConsumer_start().

int RGMAConsumer_abort RGMAResource resourceP  ) 
 

Aborts a running query, after a call to start() or startDirected()). Does nothing if the query has already finished. Any tuples which had already been delivered to the consumer service may still be retrieved via pop.

Parameters:
resourceP Pointer to the Consumer resource which started the query.
Returns:
0 on success or -1 on error.

int RGMAConsumer_hasAborted RGMAResource resourceP  ) 
 

Determines whether a Consumer's query has aborted (either following a call to abort(), or because its query has timed out).

Note that as this involves a remote call, you should be careful to check for errors.

Parameters:
resourceP Pointer to the Consumer resource to query.
Returns:
1 if it has, 0 if it has not; -1 if an error occurred.

RGMAResultSet* RGMAConsumer_pop RGMAResource resourceP,
int  maxCount
 

Retrieves at most maxCount tuples from a Consumer which have been returned by producers. The returned list will be empty if there are no tuples currently available. The final result set for a query will have its endOfResults flag set to 1 (true).

You should free the result set when no longer required, by calling RGMA_freeResultSet().

Parameters:
resourceP Pointer to the Consumer resource to query.
maxCount The maximum number of tuples to retrieve.
Returns:
Pointer to new result set, or NULL on error.
See also:
RGMAResultSet, RGMA_printResultSet(), RGMA_freeResultSet().

int RGMA_getTerminationInterval RGMAResource resourceP  ) 
 

Queries the termination interval for a resource.

Parameters:
resourceP Pointer to the resource to query.
Returns:
Termination interval (in seconds) or -1 on error.

int RGMA_showSignOfLife RGMAResource resourceP  ) 
 

Indicates to a service that a resource should be kept alive. This method should be called periodically if there is no other contact with the resource through another API function.

Parameters:
resourceP Pointer to the resource to keep alive.
Returns:
0 on success or -1 on error.

int RGMA_close RGMAResource resourceP  ) 
 

Schedules a (remote) resource for destruction. The resource will no longer be available through this API and will be destroyed by the service once it has finished interacting with other components. You should also free up any local memory associated with the resource using RGMA_freeResource().

Parameters:
resourceP Pointer to the resource to close.
Returns:
0 on success or -1 on error.

int RGMA_destroy RGMAResource resourceP  ) 
 

Destroys a (remote) resource immediately. The resource will no longer be available to any component. You should also free up any local memory associated with the resource by calling RGMA_freeResource().

Parameters:
resourceP Pointer to the resource to destroy.
Returns:
0 on success or -1 on error.

int RGMARegistry_createRegistry const char *  vdbName,
const char *  registryService,
RGMAException exceptionP
 

Creates a new instance (replica) of a Registry for a specified virtual database in a Registry Service. This function would only normally be used by system administrators.

Parameters:
vdbName Virtual database name.
registryService URL of registry service in which to create the registry instance.
exceptionP Pointer to exception (filled in on failure).
Returns:
0 on success or -1 on error.

int RGMARegistry_destroyRegistry const char *  vdbName,
const char *  registryService,
RGMAException exceptionP
 

Destroys an instance (replica) of a Registry of a specified virtual database from a Registry Service. The Registry database is wiped. This function would only normally be used by system administrators.

Parameters:
vdbName Virtual database name.
registryService URL of registry service from which to drop the registry instance.
exceptionP Pointer to exception (filled in on failure).
Returns:
0 on success or -1 on error.

RGMAProducerTableEntryList* RGMARegistry_getAllProducersForTable const char *  vdbName,
const char *  tableName,
RGMAException exceptionP
 

Returns details of all producers that are registered for a specified table in a specified virtual database.

Parameters:
vdbName Virtual database name.
tableName Table name.
exceptionP Pointer to exception (filled in on failure).
Returns:
List of producers (may be empty) or NULL on error.

int RGMASchema_createSchema const char *  vdbName,
const char *  schemaService,
RGMAException exceptionP
 

Creates a new instance (replica) of a Schema for a specified virtual database in a Schema Service. This function would only normally be used by system administrators.

Parameters:
vdbName Virtual database name.
schemaService URL of schema service in which to create the schema instance.
exceptionP Pointer to exception (filled in on failure).
Returns:
0 on success or -1 on error.

int RGMASchema_destroySchema const char *  vdbName,
const char *  schemaService,
RGMAException exceptionP
 

Destroys an instance (replica) of a Schema of a specified virtual database from a Schema Service. The Schema database is wiped. This function would only normally be used by system administrators.

Parameters:
vdbName Virtual database name.
schemaService URL of schema service from which to drop the schema instance.
exceptionP Pointer to exception (filled in on failure).
Returns:
0 on success or -1 on error.

int RGMASchema_createTable const char *  vdbName,
const char *  createTableStatement,
int  numRules,
char **  rules,
RGMAException exceptionP
 

Creates a new table in the schema of a specified virtual database. The table name, column names and column types must conform to the rules in the User Guide. A set of initial authorization rules for the table may also be specified. The format of the rules is described in the User Guide.

Parameters:
vdbName Virtual database name.
createTableStatement SQL CREATE TABLE statement.
numRules Number of authorization rules (may be 0).
rules Authorization rules (may be NULL).
exceptionP Pointer to exception (filled in on failure).
Returns:
0 on success or -1 on error.

int RGMASchema_dropTable const char *  vdbName,
const char *  tableName,
RGMAException exceptionP
 

Drops a table from the schema of a specified virtual database.

Parameters:
vdbName Virtual database name.
tableName Table to drop.
exceptionP Pointer to exception (filled in on failure).
Returns:
0 on success or -1 on error.

int RGMASchema_createIndex const char *  vdbName,
const char *  createIndexStatement,
RGMAException exceptionP
 

Creates a new index definition for a table in the schema of a specified virtual database. The index name and index definition must conform to the rules in the User Guide.

Parameters:
vdbName Virtual database name.
createIndexStatement SQL CREATE INDEX statement.
exceptionP Pointer to exception (filled in on failure).
Returns:
0 on success or -1 on error.

int RGMASchema_dropIndex const char *  vdbName,
const char *  indexName,
RGMAException exceptionP
 

Drops an index from the schema of a specified virtual database.

Parameters:
vdbName Virtual database name.
indexName Index to drop.
exceptionP Pointer to exception (filled in on failure).
Returns:
0 on success or -1 on error.

int RGMASchema_createView const char *  vdbName,
const char *  createViewStatement,
int  numRules,
char **  rules,
RGMAException exceptionP
 

Creates a new view in the schema of a specified virtual database. The view name and view definition must conform to the rules in the User Guide. A set of initial authorization rules for the view may also be specified. The format of the rules is described in the User Guide.

Parameters:
vdbName Virtual database name.
createViewStatement SQL CREATE VIEW statement.
numRules Number of authorization rules (may be 0).
rules Authorization rules (may be NULL).
exceptionP Pointer to exception (filled in on failure).
Returns:
0 on success or -1 on error.

int RGMASchema_dropView const char *  vdbName,
const char *  viewName,
RGMAException exceptionP
 

Drops a view from the schema of a specified virtual database.

Parameters:
vdbName Virtual database name.
viewName View to drop.
exceptionP Pointer to exception (filled in on failure).
Returns:
0 on success or -1 on error.

RGMAStringList* RGMASchema_getAllTables const char *  vdbName,
RGMAException exceptionP
 

Returns a list of all tables and views in the schema of a specified virtual database.

You should free the list returned by calling RGMA_freeStringList when it is no longer required.

Parameters:
vdbName Virtual database name.
exceptionP Pointer to exception (filled in on failure).
Returns:
List of tables and views (may be empty) or NULL on error.

RGMATableDefinition* RGMASchema_getTableDefinition const char *  vdbName,
const char *  tableName,
RGMAException exceptionP
 

Returns the column definitions of a table or view in the schema of a specified virtual database.

You should free the structure returned by calling RGMA_freeTableDefinition when it is no longer required.

Parameters:
vdbName Virtual database name.
tableName Table or view to query.
exceptionP Pointer to exception (filled in on failure).
Returns:
Table definition or NULL on error.

RGMAIndexList* RGMASchema_getTableIndexes const char *  vdbName,
const char *  tableName,
RGMAException exceptionP
 

Returns the list of indexes defined on a table in the schema of a specified virtual database.

You should free the list returned by calling RGMA_freeIndexList when it is no longer required.

Parameters:
vdbName Virtual database name.
tableName Table to query.
exceptionP Pointer to exception (filled in on failure).
Returns:
List of indexes (may be empty) or NULL on error.

int RGMASchema_setAuthorizationRules const char *  vdbName,
const char *  tableName,
int  numRules,
char **  rules,
RGMAException exceptionP
 

Replaces the authorization rules on a table or view in the schema of a specified virtual database. The format of the rules is described in the User Guide.

Parameters:
vdbName Virtual database name.
tableName Table or view to update.
numRules Number of authorization rules (may be 0 to remove all existing rules).
rules Authorization rules (may be NULL).
exceptionP Pointer to exception (filled in on failure).
Returns:
0 on success or -1 on error.

RGMAStringList* RGMASchema_getAuthorizationRules const char *  vdbName,
const char *  tableName,
RGMAException exceptionP
 

Returns the authorization rules on a table or view in the schema of a specified virtual database. The format of the rules is described in the User Guide.

You should free the list returned by calling RGMA_freeStringList when it is no longer required.

Parameters:
vdbName Virtual database name.
tableName Table or view to update.
exceptionP Pointer to exception (filled in on failure).
Returns:
List of authorization rules (may be empty) or NULL on error.

int RGMA_setProperty int  service,
const char *  name,
const char *  parameter,
const char *  value,
RGMAException exceptionP
 

Sets the value of a service property - see the User Guide for a list of properties that can be set.

Parameters:
service Service (see getVersion()).
name Property name.
parameter Property parameter (may be NULL).
value New value for property.
exceptionP Pointer to exception (filled in on failure).
Returns:
0 on success, or -1 on error.

char* RGMA_getProperty int  service,
const char *  name,
const char *  parameter,
RGMAException exceptionP
 

Returns the value of a service property - see the User Guide for a list of properties that can be queried and the values that they return.

You should free the string returned (by calling free()) when it is no longer required.

Parameters:
service Service (see getVersion()).
name Property name.
parameter Property parameter (may be NULL).
exceptionP Pointer to exception (filled in on failure).
Returns:
Requested property string or NULL on error.

char* RGMA_getVersion int  service,
RGMAException exceptionP
 

Returns a string representing the version number of an R-GMA service.

You should free the string returned (by calling free()) when it is no longer required.

Parameters:
service Service - one of:
RGMAService_PRIMARYPRODUCER
RGMAService_SECONDARYPRODUCER
RGMAService_ONDEMANDPRODUCER
RGMAService_CONSUMER
RGMAService_REGISTRY
RGMAService_SCHEMA
exceptionP Pointer to exception (filled in on failure).
Returns:
Version number string or NULL on error.

RGMAResourceEndpoint* RGMA_getEndpoint RGMAResource resourceP  ) 
 

Gets the resource-endpoint (URL and id) for a resource, in an RGMAResourceEndpoint structure. You should free the memory associated with it (using RGMA_freeEndpoint()) when you are done with it.

Parameters:
resourceP Pointer to the resource to query.
Returns:
Pointer to new resource-endpoint, or NULL on error.
See also:
RGMAResourceEndpoint

const RGMAException* RGMA_getException RGMAResource resourceP  ) 
 

Returns a pointer to the most recent exception which occurred in a given resource. The pointer is only valid until the resource is freed.

Parameters:
resourceP Pointer to the resource to query.
Returns:
Pointer to exception, or NULL if (and only if) no exception has occurred in the resource.
See also:
RGMAException

char* RGMA_getResultSetValue RGMAResultSet rs,
int  rowNum,
int  colNum,
const char *  colName
 

Convenience function: returns a pointer to the requested value (as a string) from a result set. You must specify a row number and either a column name or column number (if you specify both, the column name will be used).

Todo:
Column matching should probably be case-insensitive.
Parameters:
rs Pointer to result set to search.
rowNum Row number (in the range 0 to (rs->numRows - 1))
colNum Column number (in the range 0 to (rs->numCols - 1))
colName Column name (may be NULL).
Returns:
Pointer to requested value, or NULL if not found.
See also:
RGMAResultSet

void RGMA_printResultSet FILE *  stream,
RGMAResultSet rs
 

Convenience function: prints the contents of a result set to a file stream. If you don't specify a stream (i.e. pass NULL), stderr will be used.

Parameters:
stream File stream to which to print result set.
rs Pointer to result set to print.
Returns:
Nothing.
See also:
RGMAResultSet

void RGMA_freeResource RGMAResource resourceP  ) 
 

Frees all memory associated with an RGMAResource structure, but leaves the remote resource intact. If the API never re-connects to the remote resource, it will continue to exist and operate until it exceeds its termination interval.

Parameters:
resourceP Pointer to the RGMAResource to free.
Returns:
Nothing.
See also:
RGMAResource.

void RGMA_freeEndpoint RGMAResourceEndpoint endpointP  ) 
 

Frees all memory associated with an RGMAResourceEndpoint structure.

Parameters:
endpointP Pointer to the RGMAResourceEndpoint to free.
Returns:
Nothing.
See also:
RGMAResourceEndpoint

void RGMA_freeException RGMAException exceptionP  ) 
 

Frees all memory contained within an RGMAException structure (but does not free the exception structure itself). Note that if an API call succeeds, no exception will be written by the API and you should not call this function.

Parameters:
exceptionP Pointer to the RGMAException to free.
Returns:
Nothing.
See also:
RGMAException

void RGMA_freeStringList RGMAStringList stringListP  ) 
 

Frees all memory associated with an RGMAStringList structure.

Parameters:
stringListP Pointer to the RGMAStringList to free.
Returns:
Nothing.
See also:
RGMAStringList

void RGMA_freeResultSet RGMAResultSet resultSetP  ) 
 

Frees all memory associated with an RGMAResultSet structure.

Parameters:
resultSetP Pointer to the RGMAResultSet to free.
Returns:
Nothing.
See also:
RGMAResultSet

void RGMA_freeTupleStoreList RGMATupleStoreList tupleStoreListP  ) 
 

Frees all memory associated with an RGMATupleStoreList structure.

Parameters:
tupleStoreListP Pointer to the RGMATupleStoreList to free.
Returns:
Nothing.
See also:
RGMATupleStoreList

void RGMA_freeProducerTableEntryList RGMAProducerTableEntryList producerTableEntryListP  ) 
 

Frees all memory associated with an RGMAProducerTableEntryList structure.

Parameters:
producerTableEntryListP Pointer to the RGMAProducerTableEntryList to free.
Returns:
Nothing.
See also:
RGMAProducerTableEntryList

void RGMA_freeIndexList RGMAIndexList indexListP  ) 
 

Frees all memory associated with an RGMAIndexList structure.

Parameters:
indexListP Pointer to the RGMAIndexList to free.
Returns:
Nothing.
See also:
RGMAIndexList

void RGMA_freeTableDefinition RGMATableDefinition tableDefinitionP  ) 
 

Frees all memory associated with an RGMATableDefinition structure.

Parameters:
tableDefinitionP Pointer to the RGMATableDefinition to free.
Returns:
Nothing.
See also:
RGMATableDefinition

int RGMA_createPrimaryProducer int  terminationInterval,
int  properties,
int  storageType,
RGMAStorageLocation storageLocation,
int  numVOs,
char **  voNames,
RGMAResource **  resourcePP
 

Deprecated:
Use the new version of this function.

int RGMA_createSecondaryProducer int  terminationInterval,
int  properties,
int  storageType,
RGMAStorageLocation storageLocation,
int  numVOs,
char **  voNames,
RGMAResource **  resourcePP
 

Deprecated:
Use the new version of this function.

int RGMA_createOnDemandProducer int  terminationInterval,
const char *  uri,
int  numVOs,
char **  voNames,
RGMAResource **  resourcePP
 

Deprecated:
Use the new version of this function.

int RGMAPrimaryProducer_insert RGMAResource resourceP,
const char *  insertStatement
 

Deprecated:
Use the new version of this function.

int RGMAPrimaryProducer_insertList RGMAResource resourceP,
int  numInserts,
char **  insertStatements
 

Deprecated:
Use the new version of this function.

int RGMAConsumer_isExecuting RGMAResource resourceP  ) 
 

Deprecated:
Check endOfResults flag on RGMAResultSet instead.

int RGMAConsumer_count RGMAResource resourceP  ) 
 

Deprecated:
Check endOfResults flag on RGMAResultSet instead.


Generated on Thu May 11 19:24:12 2006 for RGMA C API by doxygen 1.3.5