SEGUSER

Synopsis

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

Description

Use user-defined FSEG segment store SPI backend for archive read.

The FSEG SPI (Segment Store Exit) lets a user-supplied shared library handle segment-level storage I/O. The library exports a single entry point conforming to the TfFsegExit signature and processes the 14 FSEG function codes defined in FSEG.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 / FSEGUSR). 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 SEGSSE bridge and the FSEG provider (sets FSEG_FLAG_LOG in the OPN call). DEBUG adds per-operation detail to the log output (sets FSEG_FLAG_DEBUG; requires LOGGING to be set).

FSEG SPI -- Segment Store Provider Interface

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

FL5 ships a reference provider (libfsse / entry point FSEGUSR) that maps the FSEG SPI to the built-in SEGFILE flat-file backend. Custom providers can target any storage backend (relational database, key-value store, cloud object storage, etc.) by implementing the same interface.

Entry Point

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

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

The name FSEGUSR 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.
• uiVersion -- interface version (FSEG_VERSION, currently 0x0102); provider must accept if compatible.
• piFunc -- function code (see FSEG 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 and write a human-readable error description to pcMsg on failure.

Interface Version

The current interface version is FSEG_VERSION = 0x0102. The major byte (0x01) identifies the function-code set; the minor byte (0x02) identifies backward-compatible additions (such as the uiDelLen output field in TsFsegDel and the uiSegCnt field in TsFsegFlb added in version 0x0102). A provider must check uiVersion at OPN time and reject versions it does not support.

FSEG Function Codes

The *piFunc argument selects the operation. The union member to use in puPara is shown in brackets.

• FSEG_FUNC_OPN (1) [stOpn] -- Open or connect to the archive namespace. Called once before any data operation. Provider allocates its handle.
• FSEG_FUNC_CLS (2) [stCls] -- Close and release resources. isCommit=1 commits pending writes; isCommit=0 rolls back.
• FSEG_FUNC_PUT (3) [stPut] -- Store one segment. Provider assigns a 64-bit integer index returned in siSegInd.
• FSEG_FUNC_GET (4) [stGet] -- Retrieve a segment by index. Provider returns a locate pointer; the data must remain valid until the next SPI call.
• FSEG_FUNC_DEL (5) [stDel] -- Delete a segment by index. Provider returns the size of the deleted segment in uiDelLen (0 if unknown).
• FSEG_FUNC_EXS (6) [stExs] -- Check whether a segment exists. Provider sets isExists to 1 if found, 0 if not.
• FSEG_FUNC_GMN (7) [stGmn] -- Get the main (root) segment index. Provider returns FSEG_IDX_INI if not set.
• FSEG_FUNC_SMN (8) [stSmn] -- Persist the main segment index.
• FSEG_FUNC_VLS (9) [stVls] -- List all versions. Provider allocates a TsFsegVsnEnt array and sets uiVsnCnt; the caller frees the array with free().
• FSEG_FUNC_DVS (10) [stDvs] -- Delete one version by ID. Provider sets uiVerDel to the number of versions deleted.
• FSEG_FUNC_DAR (11) [stDar] -- Delete the entire archive. Provider sets uiVerDel to the number of versions deleted.
• FSEG_FUNC_PRN (12) [stPrn] -- Prune old versions. Provider retains uiKeepCnt most-recent versions and sets uiVerDel.
• FSEG_FUNC_CBF (13) [stCbf] -- Create a write buffer (batch hint). Provider assigns a buffer ID in uiBufId.
• FSEG_FUNC_FLB (14) [stFlb] -- Flush a write buffer to permanent storage. uiSegCnt reports the number of PUT calls issued since the matching CBF call.

Open Parameters (TsFsegOpn)

Fields set by the caller before OPN:

• uiFlg -- flag word (see FSEG Flags below).
• siVerId -- version to open; -1 = latest (read) or create new (write).
• 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.
• siOpenedVerId -- actual version ID opened.

Close Parameters (TsFsegCls)

• isCommit [INPUT] -- 1 = commit, 0 = rollback/abort.
• uiTotalBytesWritten [OUTPUT] -- total bytes written including overhead (used for FLAM statistics).
• uiSegmentBytesWritten [OUTPUT] -- pure payload bytes written.

FSEG Flags (TsFsegOpn.uiFlg)

• FSEG_FLAG_WRITE (0x01) -- write access; 0 = read-only.
• FSEG_FLAG_OVERWRITE (0x02) -- overwrite existing archive.
• FSEG_FLAG_LOG (0x04) -- enable INFO-level log output.
• FSEG_FLAG_DEBUG (0x08) -- enable DEBUG-level log output (requires LOG).
• FSEG_FLAG_TRACE (0x10) -- enable provider trace output.
• FSEG_FLAG_ACCESS (0x40) -- SAF checks were performed.
• FSEG_FLAG_STRONG (0x80) -- strict RACF mode; namespace and parameter were explicitly approved.
• FSEG_FLAG_VERSIONED (0x100) -- archive uses versioning; enables VLS / DVS / DAR / PRN.

Segment Types (TsFsegPut.uiSegTyp)

• FSEG_SEGTYP_DAT (1) -- raw compressed member data.
• FSEG_SEGTYP_MBR (2) -- member descriptor (metadata).
• FSEG_SEGTYP_DIR (3) -- directory segment (archive index).

Special Segment Index Values

• FSEG_IDX_INI (-1) -- index not yet initialized / no main segment set.
• FSEG_IDX_EMPTY (-2) -- represents a zero-length member.

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 archive file. The provider appends /<namespace> to obtain the full 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.

Logging

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

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

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

z/OS SAF Resource Groups

On z/OS with GLOBAL.SGU.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):

• FSEGLIB.<library-name> -- authorizes the provider shared library. If defined with NONE, the library may not be loaded. A READ permit sets FSEG_FLAG_ACCESS in the OPN flag word.
• FSEGFUC.<function-name> -- authorizes the entry point name. A READ permit sets FSEG_FLAG_ACCESS.
• FSEGPTH.<namespace> -- authorizes the archive namespace. A READ permit sets FSEG_FLAG_STRONG (strict mode).
• FSEGPAR.<parameter-string> -- authorizes the parameter string (which may contain credentials). A READ permit sets FSEG_FLAG_STRONG.

FSEG_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).

The provider can inspect these flags to decide whether to enforce additional access controls on its own resources.

See Also

• FOBJ SPI reference: doc/include/man_fl5_spi_fobj.txt
• Reference implementation: CSRC/SEGSTOR/FSSE.c (FSEGUSR)
• SPI bridge: CSRC/SEGSTOR/SEGSSE.c
• Interface header: CINC/FSEG.h
• z/OS installation: doc/install.zos.txt (FSEGLIB./FSEGFUC./ FSEGPTH./FSEGPAR. resource groups)

Arguments

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