This service provider interface (SPI) allows customers to connect an arbitrary storage backend to the FLAM5 segment store layer. Any key/value or block-addressable storage system can be used as the physical archive medium. FLAM handles all member management, versioning, and compression; the provider only needs to implement a small set of operations on an integer-keyed blob store.

The SPI is activated by the CLEP qualifier:

store.seguser(
    LIBRARY='libfsse',
    FUNC='FSEGUSR',
    PARAMETER='...',
    TRACE)

FLAM ships a reference implementation (libfsse / FSEGUSR) that wraps the built-in flat-file segment store. The corresponding source file (FSSE.c) is an internal implementation and is not delivered as source to customers.

The customer-facing sample implementation is CSRC/SAMPLE/FSEGODB.c. It demonstrates how to back the FSEG SPI with an ODBC-accessible relational database (PostgreSQL, MySQL, SQL Server, DB2, SQLite) and can be used as a coding template for custom providers.

Lifecycle

The provider handle and the storage connection are managed separately:

State: EMPTY (ppHdl == NULL)
  |
  | FSEG_FUNC_NEW  -- allocate handle; store name + params
  v
State: NEW (handle allocated, storage not connected)
  |                        |
  | FSEG_FUNC_OPN          | FSEG_FUNC_EXS / DAR / PRN
  v                        | (stateless; provider self-manages connection)
State: OPEN                v
  |                    State: NEW  (unchanged after stateless op)
  | FSEG_FUNC_PUT/GET/DEL/GMN/SMN/CBF/FLB/VLS/DVS
  |
  | FSEG_FUNC_CLS  -- disconnect; handle stays in NEW state
  v
State: NEW  (may re-open with OPN)
  |
  | FSEG_FUNC_FRE  -- free handle; ppHdl = NULL
  v
State: EMPTY

Stateless operations (EXS, DAR, PRN) are called in NEW state. The provider opens a temporary connection internally, executes the operation, and closes it before returning. VLS and DVS require OPEN state and operate on the open version index.

FSEG_FUNC_CLS closes the storage connection but does not free the handle. Every session must be terminated with FSEG_FUNC_FRE after the final FSEG_FUNC_CLS.

Threading model

Each open handle is used by a single thread only. The provider does not need to implement internal locking per handle. Multiple handles to the same archive namespace may be active simultaneously; the provider is responsible for namespace-level concurrency control.

Interface standards

All function parameters are passed by reference (pointer). The function has no return value; the return code is the second parameter.

Parameter widths are fixed and architecture-independent:

32-bit unsigned integer: unsigned int
64-bit signed integer: long long
64-bit unsigned integer: unsigned long long
Byte pointer: unsigned char*
String pointer: char*

Alignment rule: 32-bit fields that immediately precede a pointer must be paired so that together they fill one 64-bit slot, keeping the pointer on a 64-bit boundary. This prevents bus errors on strict-alignment architectures (SPARC, RISC-V, z/Architecture). When only one 32-bit field naturally precedes a pointer, a reserved dummy field is added as the second element of the pair (see e.g. TsFsegDel).

All strings passed to the provider are null-terminated; the matching length field contains the byte count without the null character.

Return code handling

The provider must set *piRetco to 0 for success or to a provider-defined non-zero value to signal an error. The provider must not use or depend on FLMRTC_* values from FLMRTC.h. The bridge layer (SEGSSE) translates any non-zero provider return code to the dedicated FLAM reason code FLMRTC_FSG and includes the provider RC and the message written to pcMsg in the FLAM error trace.

Coding example

The reference implementation FSSE.c wraps the built-in SEGFILE backend and demonstrates the complete SPI lifecycle including version management and batch buffers. The compiled provider is shipped as libfsse.