OBJUSER

Synopsis

HELP:   User-defined object store SPI backend (store.objuser())
TYPE:   OBJECT
SYNTAX: OBJUSER(NAMESPACE='str',LIBRARY='str',FUNCTION='str',PARAMETER='str',TRACE,LOGGING,DEBUG)

Description

Use user-defined FOBJ object store SPI backend for archive read.

The FOBJ SPI (Object Store Exit) lets a user-supplied shared library handle object-level storage I/O. The library exports a single entry point conforming to the TfFobjExit signature and processes the 7 FOBJ function codes defined in FOBJ.h.

The NAME parameter identifies the archive namespace passed to the provider as pcNamStr during open. LIBRARY and FUNCTION select the shared library and its entry point (defaults: libfsse / FOBJUSR). An optional PARAMETER string is forwarded as pcParStr for provider-specific configuration. The TRACE switch enables diagnostic output from the provider.

LOGGING enables info-level log messages from the OBJSSE bridge and the FOBJ provider (sets FOBJ_FLAG_LOG in the OPN call). DEBUG adds per-operation detail to the log output (sets FOBJ_FLAG_DEBUG; requires LOGGING to be set).

FOBJ SPI -- Object Store Provider Interface

A FOBJ provider is a shared library that exports one C function conforming to the TfFobjExit signature defined in FOBJ.h. The provider receives all storage requests from FL5 through this single entry point and must implement the 7 FOBJ function codes listed below.

FL5 ships a reference provider (libfsse / entry point FOBJUSR) that maps the FOBJ SPI to the built-in OBJFLDR folder-based object store backend. Custom providers can target any storage backend (cloud blob storage, relational database, key-value store, etc.) by implementing the same interface.

The FOBJ SPI is the object-level counterpart to the FSEG SPI. While FSEG operates on integer-keyed binary segments, FOBJ operates on string-keyed binary objects. FL5 uses FOBJ internally to store the segment-store index objects (directory, member descriptors) on top of arbitrary object backends.

Entry Point

The provider library must export a function with this C signature:

void FOBJUSR(
    void*               pvGbl,
    void**              ppHdl,
    int*                piRetco,
    unsigned int        uiVersion,
    const unsigned int* piFunc,
    TuFobjPar*          puPara,
    unsigned int        uiMsgSiz,
    char*               pcMsg);

The name FOBJUSR is the default; it can be overridden with the FUNCTION CLEP parameter. The arguments are:

• pvGbl -- FL5 global context handle (struct Fl5Gbl*); may be NULL in probe calls; pass to FLM_LOG() for log output.
• ppHdl -- pointer to the provider's own handle; NULL on first OPN call; provider allocates and stores its handle here.
• piRetco -- output return code: 0 = success, non-zero = error; use FOBJ_RTC_NFD (1) for "object not found" in GET.
• uiVersion -- interface version (FOBJ_VERSION, currently 0x0100); provider must accept if compatible.
• piFunc -- function code (see FOBJ Function Codes below).
• puPara -- parameter union; access the member matching *piFunc.
• uiMsgSiz -- capacity of pcMsg buffer in bytes.
• pcMsg -- null-terminated diagnostic message written by provider.

The provider must set *piRetco = 0 on success. For GET when the object does not exist the provider must set *piRetco = FOBJ_RTC_NFD (1) -- this code has a specific meaning in the OBJSSE bridge and must not be used for other error conditions. All other errors are represented by any non-zero value other than FOBJ_RTC_NFD.

Interface Version

The current interface version is FOBJ_VERSION = 0x0100. A provider must check uiVersion at OPN time and reject versions it does not support.

FOBJ Function Codes

The *piFunc argument selects the operation.

• FOBJ_FUNC_OPN (1) [stOpn] -- Open or connect to the archive namespace. Called once before any data operation. Provider allocates its handle.
• FOBJ_FUNC_CLS (2) [stCls] -- Close and release resources. isCommit=1 commits pending writes; isCommit=0 rolls back.
• FOBJ_FUNC_GET (3) [stGet] -- Retrieve an object by string key. Provider returns a locate pointer; the data must remain valid until the next SPI call. If the object does not exist, set *piRetco = FOBJ_RTC_NFD.
• FOBJ_FUNC_PUT (4) [stPut] -- Store an object by string key. Overwrites any existing object with the same key.
• FOBJ_FUNC_DEL (5) [stDel] -- Delete an object by string key.
• FOBJ_FUNC_CHK (6) [stChk] -- Check whether an object exists and meets a minimum size. Provider sets isExists=1 if the object exists and uiDatLen >= uiMinLen.
• FOBJ_FUNC_DST (7) [stDst] -- Delete the entire store namespace for the currently open version.

Open Parameters (TsFobjOpn)

Fields set by the caller before OPN:

• uiFlg -- flag word (see FOBJ Flags below).
• siVerId -- always -1; version is embedded in the object key prefix by the OBJSSE bridge; providers may ignore this field.
• pcNamStr / uiNamLen -- archive namespace (from CLEP NAME).
• pcParStr / uiParLen -- provider parameter string (from CLEP PARAMETER).

Fields written by the provider at OPN:

• ppcName -- points to a null-terminated canonical archive identifier inside the provider's handle; valid until CLS.

Close Parameters (TsFobjCls)

• isCommit [INPUT] -- 1 = commit, 0 = rollback/abort.

Get Parameters (TsFobjGet)

• pcKeyStr / uiKeyLen [INPUT] -- object key string.
• ppDatPtr [OUTPUT] -- locate pointer to object data (provider-owned; valid until next SPI call).
• uiDatLen [OUTPUT] -- object data length in bytes.

Put Parameters (TsFobjPut)

• pcKeyStr / uiKeyLen [INPUT] -- object key string.
• pcDatPtr [INPUT] -- object data (valid for this call only).
• uiDatLen [INPUT] -- object data length in bytes.

Check Parameters (TsFobjChk)

• pcKeyStr / uiKeyLen [INPUT] -- object key string.
• uiMinLen [INPUT] -- minimum required data length (0 = any).
• isExists [OUTPUT] -- 1 if object exists with length >= uiMinLen.

FOBJ Flags (TsFobjOpn.uiFlg)

• FOBJ_FLAG_WRITE (0x01) -- write access; 0 = read-only.
• FOBJ_FLAG_OVERWRITE (0x02) -- overwrite existing archive.
• FOBJ_FLAG_LOG (0x04) -- enable INFO-level log output.
• FOBJ_FLAG_DEBUG (0x08) -- enable DEBUG-level log output (requires LOG).
• FOBJ_FLAG_TRACE (0x10) -- enable provider trace output.
• FOBJ_FLAG_ACCESS (0x40) -- SAF checks were performed.
• FOBJ_FLAG_STRONG (0x80) -- strict RACF mode; namespace and parameter were explicitly approved.

Provider Parameter String

The built-in reference provider (libfsse) parses the PARAMETER string as a semicolon-separated list of key=value pairs:

• path=<directory> -- base directory for the object folder. The provider appends /<namespace> to obtain the full folder path. Default: current directory (.).

Custom providers may define their own parameter string format. The string is passed verbatim as pcParStr and is not interpreted by FL5.

Object Key Format

The OBJSSE bridge prefixes every object key with the version ID to allow multiple archive versions to coexist in the same namespace. Key format: <version-id>/<object-name>. A provider that stores objects in a flat namespace does not need to parse or interpret the key format.

Logging

When FOBJ_FLAG_LOG is set in uiFlg, the provider may call FLM_LOG(FLMLOG_TYP_INFO, ...) with message tags starting with FSSE-OBJ- (reference provider) or any provider-specific prefix. Messages are routed through the FL5 log framework.

When FOBJ_FLAG_DEBUG is additionally set, the provider may emit FLMLOG_TYP_DEBUG messages for per-operation detail.

The OBJSSE bridge itself logs with the OBJSSE- prefix regardless of provider flags.

z/OS SAF Resource Groups

On z/OS with GLOBAL.OBU.CONTROL defined in the $FLAM RACF class, FL5 performs authorization checks before loading the provider. Four resource groups are used (all checked at READ attribute level):

• FOBJLIB.<library-name> -- authorizes the provider shared library. If defined with NONE, the library may not be loaded. A READ permit sets FOBJ_FLAG_ACCESS in the OPN flag word.
• FOBJFUC.<function-name> -- authorizes the entry point name. A READ permit sets FOBJ_FLAG_ACCESS.
• FOBJPTH.<namespace> -- authorizes the archive namespace. A READ permit sets FOBJ_FLAG_STRONG (strict mode).
• FOBJPAR.<parameter-string> -- authorizes the parameter string (which may contain credentials). A READ permit sets FOBJ_FLAG_STRONG.

FOBJ_FLAG_STRONG is set when uiSafLevel < 8, meaning RACF is in strict mode (GLOBAL.MUSTDEF=UPDATE or lower). With STRONG set, both the namespace and the parameter string were explicitly approved. Without STRONG (permissive mode), SAF accepted RC=4 (not defined).

See Also

• FSEG SPI reference: doc/include/man_fl5_spi_fseg.txt
• Reference implementation: CSRC/SEGSTOR/FSSE.c (FOBJUSR)
• SPI bridge: CSRC/SEGSTOR/OBJSSE.c
• Interface header: CINC/FOBJ.h
• z/OS installation: doc/install.zos.txt (FOBJLIB./FOBJFUC./ FOBJPTH./FOBJPAR. resource groups)

Arguments

• STRING: NAMESPACE='str' - Archive namespace identifier passed to the FOBJ provider [required]
• STRING: LIBRARY='str' - FOBJ provider shared library name [default: libfsse]
• STRING: FUNCTION='str' - FOBJ provider entry point name [default: FOBJUSR]
• STRING: PARAMETER='str' - Provider-specific parameter string passed as pcParStr [default: empty]
• SWITCH: TRACE - Enable provider-level SPI trace output (FOBJ_FLAG_TRACE)
• SWITCH: LOGGING - Enable info logging from the OBJSSE bridge and FOBJ provider (FOBJ_FLAG_LOG)
• SWITCH: DEBUG - Enable debug logging from the OBJSSE bridge and FOBJ provider (FOBJ_FLAG_DEBUG; requires LOGGING)