Tutorial

Environments

An Environment is a collection of multiple Databases. An Environment is the “root entity” of upscaledb. You need to create or open an Environment to start working with Databases.

An Environment can either be file-based or in-memory based (but not both at the same time).

Databases in an Environment are identified by an unsigned 16 bit wide number. The values 0 and everything above 0xf000 are reserved.

The following chapter shows how to create or open Environments, how to create, open, rename or delete Databases from Environment files, and anything else you should learn in order to work with Environments.

For simple samples on how to use Environments see the file samples/db1.c. For more complex samples see samples/env1.c (and samples/env3.cpp if you prefer C++). These samples creates two Databases - one for customers, one for orders. It fills them, and then prints a list of all customers and their orders.

Creating a new Environment

The function ups_env_create is used to create a new Environment. It allocates an Environment handle (of type ups_env_t). All functions are declared in include/ups/upscaledb.h as follows:

ups_status_t
ups_env_create (ups_env_t **env, const char *filename, uint32_t flags,
            uint32_t mode, const ups_parameter_t *param);

API reference for ups_env_create

The parameter param is a variable length parameter list; the parameters UPS_PARAM_PAGE_SIZE, UPS_PARAM_CACHE_SIZE and UPS_PARAM_LOG_DIRECTORY are supported. These parameters are all explained in the header file or the API reference. If you do not want to specify any of these parameters then simply pass NULL.

The mode specifies the file access rights for the newly created file. On Linux and Unix, they are identical to the parameter you would give to the chmod command to change the access rights. If you do not know what to specify, an (octal) 0664 might be ok for you - this gives read/write-rights to your own user and all users in the same group, and read-only rights to anyone else. On Microsoft Windows, the mode parameter is ignored.

Here’s the code for creating an upscaledb Environment:

#include <stdio.h> // for printf
#include <stdlib.h> // for exit
#include <ups/upscaledb.h>

int main (int argc, char **argv) {
  ups_status_t st;
  ups_env_t *env;

  if ((st = ups_env_create (env, “test.db”, 0, 0664, 0)) != UPS_SUCCESS) {
    printf ("error %d (%s)\n", st, ups_strerror (st));
    exit (–1);
  }
  // …
}

Creating In-Memory Environments

Environments do not have to be file-based, they can also reside in RAM.

While you gain better performance, it is not possible to open existing Databases in an Environment (with ups_env_open), and as soon as you close the Environment it is gone and there is no way to restore it.

To create an In-Memory Environment, call ups_env_create with the flag UPS*IN*MEMORY. Since In-Memory Databases are not written to disk, the filename parameter is ignored and can be NULL.

Here is a code snippet creating an In-Memory Environment:

if ((st = ups_env_create (env, NULL, UPS_IN_MEMORY, 0, 0)) != UPS_SUCCESS) {
  printf ("error %d (%s)\n", st, ups_strerror (st));
  exit (–1);
}

Opening an Environment

The procedure of opening an Environment is again quite similar to creating an Environment. The file is opened with ups_env_open.

ups_status_t
ups_env_open (ups_env_t **env, const char *filename,
            uint32_t flags, ups_parameter_t *param);

API reference for ups_env_open

param is a variable parameter list. Usually you can set this parameter to NULL. See the section “Creating an Environment” for more information about parameter lists.

You can specify the flag UPS_READ_ONLY to open the Environment in read-only mode. In this mode it is not possible to create new Databases or to rename existing Databases in this Environment. All write modifications will fail with error UPS_READ_ONLY.