Oninit UDR / Informix DataBlade engineering
Talk to an expert →

Oninit® UDR — TimeSeries API: Install

Building and registering the TimeSeries API's UDRs against a real Informix instance — shown here as it's actually deployed for the tsapi project. Once it's installed, the Configuration guide covers loading a YAML mapping and the Read API covers using it.

Download

There is no packaged source distribution for the TimeSeries API yet — the Download page's tarball is ONI UDR Debug's own release, and does not include these modules. Build from the tsapi project's own source tree directly until a TimeSeries API release exists.

Requirements

  • An IBM Informix Dynamic Server instance with the TimeSeries DataBlade installed, and its SDK headers available ($INFORMIXDIR/incl/public) plus the blade's own headers ($INFORMIXDIR/extend/TimeSeries.<ver>/lib).
  • A C compiler (cc/gcc) — each UDR builds as a plain cc -shared object.
  • Enough DBA privilege on the target database to run CREATE FUNCTION / CREATE PROCEDURE / CREATE ROW TYPE.

1. Build

One .bld module holds every TimeSeries UDR (oni_ts_read, oni_ts_write, oni_ts_write_file, oni_ts_resolve_metrics, oni_ts_start, oni_ts_status, oni_ts_abort, oni_ts_yaml_reload, oni_ts_yaml_validate). Every module reads and writes the same shared-memory block, and a single module means no two of them can disagree about its layout:

make udr-ts-combined-build \
     IDS_INCL=$INFORMIXDIR/incl/public \
     TS_BLADE_INCL=$INFORMIXDIR/extend/TimeSeries.<ver>/lib

# which runs:
cc -O2 -std=c11 -fPIC -fvisibility=hidden -shared \
   -Iinclude -I$INFORMIXDIR/incl/public -I<TimeSeries lib dir> \
   -Wl,--exclude-libs=tsbeapi.a \
   <the sources listed as TS_COMBINED_SRC in the Makefile> \
   <TimeSeries lib dir>/tsbeapi.a -o oni_ts_combined.bld

-fvisibility=hidden and --exclude-libs are required: the blade's own tsbeapi.a carries several hundred symbols that would otherwise collide with other loaded modules. The module links tsbeapi.a because the real ts_* symbols aren't resolvable from the base server process the way mi_* symbols are.

2. Deploy

Put each build in its own version-numbered directory under your instance's extend/ tree:

mkdir -p $INFORMIXDIR/extend/oni_ts_combined.3.0
cp oni_ts_combined.bld $INFORMIXDIR/extend/oni_ts_combined.3.0/

As with ONI UDR Debug, use a fresh version directory for every rebuild rather than overwriting a file a running server process has already loaded.

3. Register

Run the registration scripts in each database that uses the API, with the external name in each pointing at the combined module ($INFORMIXDIR/extend/oni_ts_combined.<n>.0/oni_ts_combined.bld). Registering needs the EXTEND role:

dbaccess <database> - < scripts/register_ts_read.sql
dbaccess <database> - < scripts/register_ts_write.sql
dbaccess <database> - < scripts/register_ts_write_file.sql
dbaccess <database> - < scripts/register_ts_resolve_metrics.sql
dbaccess <database> - < scripts/register_ts_start.sql
dbaccess <database> - < scripts/register_ts_status.sql
dbaccess <database> - < scripts/register_ts_abort.sql
dbaccess <database> - < scripts/register_ts_yaml_reload.sql
dbaccess <database> - < scripts/register_ts_yaml_validate.sql

Feed the script on standard input as shown. When dbaccess runs as another operating-system user (for example sudo -u informix), that user can't read a script in a private directory. Don't register old per-module builds and the combined module in the same database.

Each database that uses the API gets its own YAML file and its own cache slot (see the Configuration guide). The shared-memory block is named oni_ts_block, so a database still on an older module layout keeps using its own separate block until you re-register it.

oni_ts_read() deliberately does not lazily build a cache from an unspecified YAML source — run oni_ts_start() first (see the Configuration guide) or every read call raises a clear, hard error telling you to.

Verified against a real instance

The combined module has been built, deployed, and exercised against a live, running IBM Informix Dynamic Server instance, end to end — not just checked against the SDK headers.