3. Building GCI Applications

This chapter explains how to use GemBuilder for C to build your C application. Your application will provide the main program and API. When linking your compiled code, you will link the GemBuilder for C libraries that allow you to make GemBuilder function calls.

3.1 Environment

Anyone who runs a GemStone application or process is responsible for setting the following environment variables:

GEMSTONE — A full pathname to your GemStone installation directory.

PATH — Add the GemStone bin directory to your path.

There are a number of other GemStone configuration parameters and environment variables that affect your session. In particular, GemStone allows many ways to configure processes to be distributed over multiple hosts, which require specific details in the login parameters. Also, there are a number of configuration parameters that affect your session, such as the amount of memory it can use.

Defaults are provided, so in the most simple case, with all processes running on a single machine, you do not need any further configuration.

Refer to the System Administration Guide for GemStone/S 64 Bit for details on both how to use Network Resource String syntax in login parameters, and how to setup configuration files for use by Gems.

3.2 RPC and Linked applications

The GemBuilder for C interface provide two versions: Remote Procedure Call (RPC) and linked.

In an RPC application, your application exists in a process separate from the Gem. The two processes communicate through remote procedure calls. This interprocess communication requires a small overhead associated with each GemBuilder call, independent of whatever object access is performed or Smalltalk code is executed.
In a linked application, your application and Gem (the GemStone session) exist as a single process. Your application is expected to provide the main entry point.

A linked application can also run RPC Gems, in addition to its linked Gem. An RPC application cannot have a linked Gem.

The function GciIsRemote reports whether your application was linked with the RPC version or Linked version of the GemBuilder interface.

RPC for Debugging

When debugging a new application, you must use the RPC interface. You should use GciLnk only after your application has been completely debugged and thoroughly tested, to avoid the risk of errors corrupting your repository.

When using an RPC Gem, you may achieve better performance by using functions such as GciTraverseObjs, GciStoreTrav, and GciFetchPaths. Those functions are designed to reduce the number of network round-trips by combining functions that are commonly used in sequence.

Linked for Performance

You can use a linked, single-Gem configuration to enhance performance. In a linked application, a GemBuilder function call is a machine-instruction procedure call rather than a remote call over the network to a different process.

WARNING!
Before using GciLnk, debug your C code in a process that does not include a Gem! For more information, see section Risk of Database Corruption.

In a linked application, you may achieve better performance by using the simple GciFetch... and GciStore... functions instead of the complex object traversal functions. This has the advantage of making the application easier to write, depending on your requirements. However, if your application will login to GemStone multiple times, any sessions after the first will be RPC gems and you should design your application accordingly.

The GemBuilder for C Shared Libraries

The two versions of GemBuilder are provided as a set of shared libraries. A shared library is a collection of object modules that can be bound to an executable, usually at run time. The contents of a shared library are not copied into the executable. Instead, the library’s main function loads all of its functions. Only one copy is loaded into memory, even if multiple client processes use the library at the same time. Thus, they “share” the library.

The GemBuilder library files libgcilnk.* and libgcirpc.*, and other required files, are provided in the GemStone distribution under $GEMSTONE/lib.

3.3 GemBuilder Applications that load Shared Libraries

Most applications will load shared libraries at run time. The binding is done by code that is part of the application. If that code is not executed, the shared library is not loaded. With this type of binding, applications can decide at run time which GemBuilder library to use. They can also unbind at run time and rebind to the same or different shared libraries. The code is free to handle a run-time-bind error however it sees fit.

Building the Application

To build an application that loads GemBuilder shared libraries:

1. Include gci.ht and gcirtl.hf in the C source code.

#include "gci.hf"

#include "gcirtl.hf"

However, applications are free to use their own run-time-bind interface instead of gcirtl, which is meant to be used from C. For example, a Smalltalk application would use the mechanism provided by the Smalltalk vendor to call a shared library.

2. Call GciRtlLoad to load the RPC GemBuilder.

To load the RPC version, pass true as the first argument; to load the linked version, pass in false.

Call GciRtlLoad before any other GemBuilder calls. To unload the GemBuilder libraries, call GciRtlUnload. The GciRtlIsLoaded function can be used to determine if an interface is loaded or not.

3. When linking, include gcirtlobj.o, not one of the GemBuilder libraries (libgcirpc.* and libgcilnk.*).

Chapter 5, “Compiling and Linking” tells how to compile and link your application, and provides specific details for what should be included in the compile and link operations.

Searching for the Library

At run time the gcirtl code searches for the GemBuilder library in the following places:

1. Any directories specified by the application in the argument to GciRtlLoad.

2. The $GEMSTONE/lib directory.

3. The normal operating system search, as described in the following sections.

How UNIX Matches Search Names with Shared Library Files

The UNIX operating system loader searches the following directories for matching file names, in this order:

1. Any path specified by the environment variable LD_LIBRARY_PATH.

2. Any path recorded in the executable when it was built.

3. The global directory /usr/lib.

3.4 Building Statically Linked Applications

Normally, applications will load shared libraries at runtime. However, it is also possible to statically link GemBuilder applications, which in some cases may improve performance.

In a statically linked application, the executable is linked to the GemBuilder library archive file when the executable is built. When the executable runs, it automatically loads the library. Unlike when loading a shared library, your code cannot programmatically determine which library to load. For example, with run-time loading, your code can determine which version of the GemBuilder libraries to load, but this must be determined ahead of time for a statically linked application.

Static linking is only possible with the RPC shared libraries.

To build an application that build-time-binds to GemBuilder:

1. Include gci.hf in the C source code.

2. When linking, include the RPC GemBuilder library (libgcirpc.*).

GemBuilder finds build-time-bound shared libraries by using the normal operating system searches described in “Searching for the Library” here. If a library cannot be found, the operating system returns an error.