All public functions provided by the FLAM record interface. More...

Functions
int	siFmrVersion (const int siSize, char *pcBuffer)
	Retrieves version information.
int	siFmrAbout (const int siSize, char *pcBuffer)
	Retrieves about information.
int	siFmrLicense (const int siSize, char *pcBuffer)
	Retrieves the license text.
int	siFmrHelp (char pcErr, const int siWhat, const int siDepth, const char pcPath, int piOut, char *ppOut)
	Retrieves help text for an archive or format string parameter.
int	siFmrSyntax (char pcErr, const int siWhat, const int siDepth, const char pcPath, int piOut, char *ppOut)
	Retrieves syntax information for an archive or format string.
int	siFmrCheck (char pcErr, const int siWhat, const char pcString, int piOut, char *ppOut)
	Validates an archive or format string.
int	siFmrOpen (char pcErr, void ppGbl, const int isSys, const int isStd, const char pcEnv, const char *pcLog)
	Opens a global session with optional in-memory logging.
int	siFmrClose (void *pvGbl)
	Closes a global session.
int	siFmrGetLog (void pvGbl, const char *ppLog)
	Retrieves in-memory log messages.
int	siFmrClearLog (void *pvGbl)
	Clears the in-memory log buffer.
void	vdFmrDeactivateLog (void *pvGbl)
	Deactivates in-memory logging.
void	vdFmrReactivateLog (void *pvGbl)
	Reactivates in-memory logging.
int	siFmrOpenArchive (char pcErr, void pvGbl, void *ppHdl, const char pcArchive, const char *pcFormat, const int siNumber)
	Opens a FLAM5 archive for read or write access.
int	siFmrNextMember (char pcErr, void pvHdl, const char *pcFormat)
	Advances to the next matching member (read mode).
int	siFmrLocate (char pcErr, void pvHdl, int piLen, const unsigned char ppRec, const int siSkip, void pvCnv)
	Locates the next record without copying (zero-copy read).
int	siFmrGet (char pcErr, void pvHdl, int piLen, unsigned char pcRec, const int siSkip, void *pvCnv)
	Reads the next record into a caller-supplied buffer (read mode).
int	siFmrNewMember (char pcErr, void pvHdl, const char pcFormat, const int siStaFmt, int piStaSiz, char **ppStaBuf)
	Starts a new member in an open archive (write mode).
int	siFmrPut (char pcErr, void pvHdl, const int siLen, const unsigned char pcRec, void pvCnv)
	Writes a record or element to the current member (write mode).
int	siFmrFlush (char pcErr, void pvHdl, const int isFinal, const int isForce)
	Flushes buffered records to the archive (write mode).
const char *	pcFmrGetArcName (void *pvHdl)
	Returns the current archive file name.
const char *	pcFmrGetMbrName (void *pvHdl)
	Returns the name of the current archive member.
const char *	pcFmrGetTabName (void *pvHdl)
	Returns the current table name.
const char *	pcFmrGetMbrState (void *pvHdl, const int isCurrent)
	Returns the member state string.
const char *	pcFmrGetArcComment (void *pvHdl)
	Returns the archive comment string.
const unsigned char *	pcFmrGetArcHeader (void pvHdl, unsigned int puiLen)
	Returns the binary user header from the archive.
unsigned int	uiFmrGetArcType (void *pvHdl)
	Returns the archive type identifier.
unsigned int	uiFmrGetArcMbrCount (void *pvHdl)
	Returns the number of members in the archive.
unsigned int	uiFmrGetArcVersion (void *pvHdl)
	Returns the archive format version.
unsigned int	uiFmrGetArcSaveMode (void *pvHdl)
	Returns the archive save mode.
const char *	pcFmrGetFtrName (void *pvHdl)
	Returns the filter name for the current member (DECO path).
const char *	pcFmrGetMbrComment (void *pvHdl)
	Returns the user comment of the last read member.
const unsigned char *	pcFmrGetMbrHeader (void pvHdl, unsigned int puiLen)
	Returns the binary user header of the last read member.
int	siFmrSetArcComment (char pcErr, void pvHdl, const char *pcCmt)
	Sets the archive comment (write mode).
int	siFmrSetMbrComment (char pcErr, void pvHdl, const char *pcCmt)
	Sets the member comment (write mode).
int	siFmrSetArcHeader (char pcErr, void pvHdl, const unsigned char *pcHdr, unsigned int uiLen)
	Sets the archive-level binary user header (write mode).
int	siFmrSetMbrHeader (char pcErr, void pvHdl, const unsigned char *pcHdr, unsigned int uiLen)
	Sets the member-level binary user header (write mode).
int	siFmrSetTabName (char pcErr, void pvHdl, const char *pcName)
	Sets the current table name (write mode).
int	siFmrSetMbrName (char pcErr, void pvHdl, const char *pcName)
	Sets the current member name (write mode).
int	siFmrSetMbrState (char pcErr, void pvHdl, const char *pcState)
	Sets member state attributes (write mode).
int	siFmrCloseArchive (char pcErr, void pvHdl, const int isSuccess, const int siStaFmt, int piStaSiz, char *ppStaBuf)
	Closes a FLAM5 archive and releases all resources.
const char *	pcFmrGetArcInfo (void pvHdl, char pcBuf, unsigned int uiSiz)
	Returns a human-readable description string for an open archive.
int	siFmrCheckArchive (char pcErr, void pvHdl, const int siLev, TsFmrChkResult *psResult)
	Performs an integrity check on the open archive.
int	siFmrGetMbrStatistics (void pvHdl, TsFmrMbrSta psSta)
	Returns member statistics for the currently open member.
const char *	pcFmrErrorMessage (const int siRtc)
	Maps a FLAM return code to a short English message.

Detailed Description

All public functions provided by the FLAM record interface.

Function Documentation

◆ siFmrVersion()

int siFmrVersion	(	const int	siSize,
		char *	pcBuffer )

extern

Retrieves version information.

Returns a null-terminated version string for this library and all internal components. Use this output in support cases.

Parameters

[in]	siSize	Size of the provided buffer in bytes
[out]	pcBuffer	Buffer for the null-terminated version string

Returns: FLMRTC_OK on success, FLMRTC_LEN if the buffer was too small (the string is truncated but null-terminated)

◆ siFmrAbout()

int siFmrAbout	(	const int	siSize,
		char *	pcBuffer )

extern

Retrieves about information.

Returns a null-terminated about string with library description and license information for all integrated third-party components.

Parameters

[in]	siSize	Size of the provided buffer in bytes
[out]	pcBuffer	Buffer for the null-terminated about string

Returns: FLMRTC_OK on success, FLMRTC_LEN if the buffer was too small (the string is truncated but null-terminated)

◆ siFmrLicense()

int siFmrLicense	(	const int	siSize,
		char *	pcBuffer )

extern

Retrieves the license text.

Returns the current license text as a null-terminated, multi-line string. The license text defines the permissible use of this library.

Parameters

[in]	siSize	Size of the provided buffer in bytes
[out]	pcBuffer	Buffer for the null-terminated license string

Returns: FLMRTC_OK on success, FLMRTC_LEN if the buffer was too small (the string is truncated but null-terminated)

◆ siFmrHelp()

int siFmrHelp	(	char *	pcErr,
		const int	siWhat,
		const int	siDepth,
		const char *	pcPath,
		int *	piOut,
		char **	ppOut )

extern

Retrieves help text for an archive or format string parameter.

Returns a human-readable help description for the specified parameter type. The output is written to a dynamically allocated buffer that must be freed by the caller.

To select the parameter string for which to retrieve help, pass one of the following constants as siWhat:

FMR_DECO_ARC / FMR_READ_ARC (1) – DECO archive string (FROM/READ)
FMR_READ_FORMAT (2) – format string in read/DECO mode
FMR_COMP_ARC / FMR_WRITE_ARC (3) – COMP archive string (TO/WRITE)
FMR_WRITE_FORMAT (4) – format string in write/COMP mode
FMR_STATE (11) – state string (member metadata)
FMR_LOG (12) – memory log string

Parameters

[in]	pcErr	Optional error trace buffer (FLMERR_SIZ bytes) or NULL to suppress the trace
[in]	siWhat	Parameter type constant (see list above)
[in]	siDepth	Depth of the help hierarchy to display (0 = all)
[in]	pcPath	Optional null-terminated path within the parameter tree (e.g. "comp.lzip") or NULL
[in,out]	piOut	Pre-allocated buffer size on input; final buffer size on output (may be NULL)
[in,out]	ppOut	Pointer to a pointer to a dynamically allocated help text buffer (must be freed by caller)

Returns: FLMRTC_OK on success, non-zero on error

◆ siFmrSyntax()

int siFmrSyntax	(	char *	pcErr,
		const int	siWhat,
		const int	siDepth,
		const char *	pcPath,
		int *	piOut,
		char **	ppOut )

extern

Retrieves syntax information for an archive or format string.

Returns the formal syntax for the specified parameter type in a compact, machine-parseable format. The output is written to a dynamically allocated buffer that must be freed by the caller.

To select the parameter string for which to retrieve syntax, pass one of the following constants as siWhat:

FMR_DECO_ARC / FMR_READ_ARC (1) – DECO archive string (FROM/READ)
FMR_READ_FORMAT (2) – format string in read/DECO mode
FMR_COMP_ARC / FMR_WRITE_ARC (3) – COMP archive string (TO/WRITE)
FMR_WRITE_FORMAT (4) – format string in write/COMP mode
FMR_STATE (11) – state string (member metadata)
FMR_LOG (12) – memory log string

Parameters

[in]	pcErr	Optional error trace buffer (FLMERR_SIZ bytes) or NULL to suppress the trace
[in]	siWhat	Parameter type constant (see list above)
[in]	siDepth	Depth of the syntax hierarchy to display
[in]	pcPath	Optional null-terminated path within the parameter tree or NULL
[in,out]	piOut	Pre-allocated buffer size on input; final buffer size on output (may be NULL)
[in,out]	ppOut	Pointer to a pointer to a dynamically allocated syntax buffer (must be freed by caller)

Returns: FLMRTC_OK on success, non-zero on error

◆ siFmrCheck()

int siFmrCheck	(	char *	pcErr,
		const int	siWhat,
		const char *	pcString,
		int *	piOut,
		char **	ppOut )

extern

Validates an archive or format string.

Parses and validates the supplied parameter string against the grammar for the specified parameter type. Returns detailed diagnostic output when the string is invalid.

To select the grammar against which to validate, pass one of the following constants as siWhat:

FMR_DECO_ARC / FMR_READ_ARC (1) – DECO archive string (FROM/READ)
FMR_READ_FORMAT (2) – format string in read/DECO mode
FMR_COMP_ARC / FMR_WRITE_ARC (3) – COMP archive string (TO/WRITE)
FMR_WRITE_FORMAT (4) – format string in write/COMP mode
FMR_STATE (11) – state string (member metadata)
FMR_LOG (12) – memory log string

Parameters

[in]	pcErr	Optional error trace buffer (FLMERR_SIZ bytes) or NULL to suppress the trace
[in]	siWhat	Parameter type constant (see list above)
[in]	pcString	Null-terminated string to validate
[in,out]	piOut	Pre-allocated buffer size on input; final buffer size on output (may be NULL)
[in,out]	ppOut	Pointer to a pointer to a dynamically allocated output buffer with check results (freed by caller)

Returns: FLMRTC_OK if the string is valid, non-zero otherwise

◆ siFmrOpen()

int siFmrOpen	(	char *	pcErr,
		void **	ppGbl,
		const int	isSys,
		const int	isStd,
		const char *	pcEnv,
		const char *	pcLog )

extern

Opens a global session with optional in-memory logging.

This function initializes a global session handle that can be shared across multiple siFmrOpenArchive() calls. It loads the FLAM environment (system variables, STDENV) and optionally enables in-memory logging.

Calling this function is optional. If siFmrOpenArchive() is called with pvGbl == NULL, an internal global session is created and released automatically on siFmrCloseArchive().

When in-memory logging is enabled, diagnostic messages that would normally be printed to the console are collected in a buffer that can be queried with siFmrGetLog() and cleared with siFmrClearLog(). Logging can be temporarily suspended with vdFmrDeactivateLog() and resumed with vdFmrReactivateLog().

Parameters

[in]	pcErr	Optional error trace buffer (FLMERR_SIZ bytes) or NULL to suppress the trace
[out]	ppGbl	Receives the global session handle on success
[in]	isSys	Non-zero to load system variables (z/OS only)
[in]	isStd	Non-zero to load the standard environment (.stdenv file or DD:STDENV on z/OS)
[in]	pcEnv	Optional null-terminated list of additional environment variable assignments (KEY=VALUE separated by newline or semicolon), or NULL
[in]	pcLog	Optional null-terminated CLP log string for configuring in-memory logging (e.g. "LOG(FORMAT=STANDARD MESSAGE(WARN))"), or NULL to use defaults

Returns: FLMRTC_OK on success, non-zero on error

◆ siFmrClose()

int siFmrClose ( void * pvGbl )

extern

Closes a global session.

Releases all resources allocated by siFmrOpen(). All archive handles opened with this global session must be closed with siFmrCloseArchive() before calling this function.

Parameters

[in] pvGbl Global session handle from siFmrOpen()

Returns: FLMRTC_OK on success, non-zero on error

◆ siFmrGetLog()

int siFmrGetLog	(	void *	pvGbl,
		const char **	ppLog )

extern

Retrieves in-memory log messages.

Returns the maximum error code observed since the last call to siFmrOpen() or siFmrClearLog(). Optionally, a read-only pointer to the log buffer is returned via ppLog. The returned pointer is valid until the next call to any FLMREC function on the same session.

Parameters

[in]	pvGbl	Global session handle from siFmrOpen()
[out]	ppLog	Receives a read-only pointer to the null-terminated log string, or NULL if not needed

Returns: Maximum error code recorded since last clear, or 0 if none

◆ siFmrClearLog()

int siFmrClearLog ( void * pvGbl )

extern

Clears the in-memory log buffer.

Resets the log buffer and the maximum error code counter to zero. After this call siFmrGetLog() will return 0 and an empty string.

Parameters

[in] pvGbl Global session handle from siFmrOpen()

Returns: FLMRTC_OK on success, non-zero on error

◆ vdFmrDeactivateLog()

void vdFmrDeactivateLog ( void * pvGbl )

extern

Deactivates in-memory logging.

Suspends collection of log messages for the given session. While deactivated, messages are discarded. Use vdFmrReactivateLog() to resume. This is useful to suppress expected warnings for specific operations.

Parameters

[in] pvGbl Global session handle from siFmrOpen()

◆ vdFmrReactivateLog()

void vdFmrReactivateLog ( void * pvGbl )

extern

Reactivates in-memory logging.

Resumes collection of log messages after a prior call to vdFmrDeactivateLog().

Parameters

[in] pvGbl Global session handle from siFmrOpen()

◆ siFmrOpenArchive()

int siFmrOpenArchive	(	char *	pcErr,
		void *	pvGbl,
		void **	ppHdl,
		const char *	pcArchive,
		const char *	pcFormat,
		const int	siNumber )

extern

Opens a FLAM5 archive for read or write access.

This is the central function of the FLAM record interface. It opens a FLAM5 archive and returns a handle used for all subsequent record operations on that archive.

The archive string determines the access mode and location of the archive (see Archive string). The format string controls how the member data is presented as records or elements (see Format string). If pcFormat is NULL, FORMAT.RECORD() is assumed.

When reading, the first matching member in the archive directory is opened automatically. Use siFmrNextMember() to advance to the next matching member.

When writing, the archive is set up to receive records. The first member is not finalized until records are flushed via siFmrFlush() or the archive is closed via siFmrCloseArchive(). Use siFmrSetMbrName() or siFmrSetMbrState() to attach metadata to the member before writing the first record.

pvGbl is an optional shared global session handle from siFmrOpen(). If NULL is passed, a private session is created internally and released when the handle is closed. Passing a shared handle enables log sharing and environment reuse across multiple archive operations.

The siNumber parameter overrides the I/O batch size for the active format mode. It is only relevant when writing (to(...)) and is ignored for reading. The same value can also be set via the archive string (e.g. to.new(...).maxrec(count=N)); a non-zero siNumber takes precedence. The interpretation depends on the format mode:

format.record(), format.fl4(), format.table(): maximum number of records per matrix. By default FLMARC determines this value dynamically to keep approximately 1 MiB of data per matrix, based on the actual record length, column count, and I/O buffer size. The result is clamped to a minimum of 4 and a maximum of approximately 1 million records. siNumber overrides this dynamic calculation.
format.element(): number of element rows flushed per batch (default: 1024 rows).
All other formats (block, binary, stream): I/O buffer size in bytes (default: 1 MB = 1048576 bytes). Pass 0 to use the built-in default for the active format mode.

Parameters

[in]	pcErr	Optional error trace buffer (FLMERR_SIZ bytes) or NULL to suppress the trace
[in]	pvGbl	Optional shared global session handle from siFmrOpen(), or NULL for a private session
[out]	ppHdl	Receives the new archive handle on success
[in]	pcArchive	Null-terminated archive string (see Archive string)
[in]	pcFormat	Null-terminated format string (see Format string), or NULL for FORMAT.RECORD() default
[in]	siNumber	Write-only batch size override: max records per matrix (REC/FL4/TAB; default is ~1 MiB/matrix, min 4, max ~1M), element rows per flush (ELM; default 1024), or I/O buffer bytes (other formats; default 1 MB); 0 = use default; ignored when reading

Returns: FLMRTC_OK on success, non-zero on error

◆ siFmrNextMember()

int siFmrNextMember	(	char *	pcErr,
		void *	pvHdl,
		const char *	pcFormat )

extern

Advances to the next matching member (read mode).

When a FLAM5 archive contains multiple members and the archive string used in siFmrOpenArchive() includes a filter (e.g. filter.member(name='*.txt')), this function advances to the next member that matches the filter. Without a filter it iterates over all members in the archive directory in order.

An optional format string pcFormat allows changing the record format for the new member. If NULL is passed, the format specified at siFmrOpenArchive() is retained.

After a successful call, pcFmrGetMbrName() and pcFmrGetMbrState() return the metadata of the newly opened member.

Parameters

[in]	pcErr	Optional error trace buffer (FLMERR_SIZ bytes) or NULL to suppress the trace
[in]	pvHdl	Archive handle from siFmrOpenArchive() (read mode)
[in]	pcFormat	Null-terminated format string for this member, or NULL to retain the current format

Returns: FLMRTC_OK on success, FLMRTC_EOF when no more matching members exist, other non-zero value on error

◆ siFmrLocate()

int siFmrLocate	(	char *	pcErr,
		void *	pvHdl,
		int *	piLen,
		const unsigned char **	ppRec,
		const int	siSkip,
		void *	pvCnv )

extern

Locates the next record without copying (zero-copy read).

Returns a pointer directly into the internal read buffer. No copy is performed. The pointed-to data is valid until the next call to siFmrLocate(), siFmrGet(), siFmrNextMember(), or siFmrCloseArchive() on the same handle.

When the format mode is format.element(), elements of the type given by siSkip are silently skipped. Pass FLMELM_NOSKIP to receive all elements without skipping.

pvCnv is an optional element converter handle opened with the FLCBYT converter API. It is only relevant when using format.element() and allows on-the-fly type conversion of individual element values. Pass NULL when not needed.

Parameters

[in]	pcErr	Optional error trace buffer (FLMERR_SIZ bytes) or NULL to suppress the trace
[in]	pvHdl	Archive handle from siFmrOpenArchive() (read mode)
[out]	piLen	Receives the length of the located record in bytes
[out]	ppRec	Receives a pointer into the internal buffer; may be NULL if only the length is needed
[in]	siSkip	Element type to skip, or FLMELM_NOSKIP
[in]	pvCnv	Optional element converter handle, or NULL

Returns: FLMRTC_OK on success, FLMRTC_EOF at end of member data, FLMRTC_EOM at end of member (call siFmrNextMember() to continue), FLMRTC_EOT at end of table (with table-formatted data), other non-zero value on error

◆ siFmrGet()

int siFmrGet	(	char *	pcErr,
		void *	pvHdl,
		int *	piLen,
		unsigned char *	pcRec,
		const int	siSkip,
		void *	pvCnv )

extern

Reads the next record into a caller-supplied buffer (read mode).

Copies the next record from the archive into the buffer pointed to by pcRec. This is a copying variant of siFmrLocate(). On entry, piLen must point to the size of the provided buffer. If the record is longer than the buffer, FLMRTC_LEN is returned and piLen is updated to the required size – no data is copied in that case.

If pcRec is NULL, no copy is performed and piLen receives the length of the current record without consuming it.

Parameters

[in]	pcErr	Optional error trace buffer (FLMERR_SIZ bytes) or NULL to suppress the trace
[in]	pvHdl	Archive handle from siFmrOpenArchive() (read mode)
[in,out]	piLen	Buffer size on entry; actual record length on exit (set to required size on FLMRTC_LEN)
[out]	pcRec	Caller-supplied buffer for the record data, or NULL to query the record length only
[in]	siSkip	Element type to skip, or FLMELM_NOSKIP
[in]	pvCnv	Optional element converter handle, or NULL

Returns: FLMRTC_OK on success, FLMRTC_LEN if the buffer is too small (piLen set to the required size), FLMRTC_EOF at end of member data, FLMRTC_EOM at end of member, FLMRTC_EOT at end of table, other non-zero value on error

◆ siFmrNewMember()

int siFmrNewMember	(	char *	pcErr,
		void *	pvHdl,
		const char *	pcFormat,
		const int	siStaFmt,
		int *	piStaSiz,
		char **	ppStaBuf )

extern

Starts a new member in an open archive (write mode).

Finalizes the current member and starts a new empty member within the same archive handle. Use this function to write multiple members to a FLAM5 archive without closing and reopening it (see Writing multiple members).

An optional format string pcFormat can be supplied to change the record format for the new member. If NULL is passed, the format of the previous member is retained.

Optional statistics for the member just finalized can be retrieved via ppStaBuf. The buffer is dynamically allocated and must be freed by the caller. Pass NULL for piStaSiz and ppStaBuf if statistics are not needed.

After a successful call, set the new member's metadata with siFmrSetMbrName() or siFmrSetMbrState() before calling siFmrPut().

Parameters

[in]	pcErr	Optional error trace buffer (FLMERR_SIZ bytes) or NULL to suppress the trace
[in]	pvHdl	Archive handle from siFmrOpenArchive() (write mode)
[in]	pcFormat	Null-terminated format string for the new member, or NULL to retain the current format
[in]	siStaFmt	Format constant for statistics output (FLMOUT_FORMAT_*)
[in,out]	piStaSiz	Pre-allocated statistics buffer size on input; final size on output (may be NULL)
[in,out]	ppStaBuf	Pointer to pointer to a dynamically allocated statistics buffer (must be freed by caller; may be NULL)

Returns: FLMRTC_OK on success, FLMRTC_CHK or FLMRTC_VRS as non-fatal integrity warnings, other non-zero value on error

◆ siFmrPut()

int siFmrPut	(	char *	pcErr,
		void *	pvHdl,
		const int	siLen,
		const unsigned char *	pcRec,
		void *	pvCnv )

extern

Writes a record or element to the current member (write mode).

Submits a single record (or element) to the internal write buffer. Data is not immediately written to the archive file; use siFmrFlush() to force a flush, or rely on the automatic flush at siFmrNewMember() or siFmrCloseArchive().

Record and binary modes (format.record(), format.text(), format.bin()): pcRec points to the raw record data, siLen is its byte length. Records are buffered and written in batches.

Element mode (format.element()): pcRec must point to a serialized FlmElmRec0 structure and siLen must equal FLMELMREC0_LENGTH(psElm). Each call submits exactly one element. The rules below apply depending on the matrix type (uiMat) of the element:

Standard formats (matrix type < FLMMAT_TYP_TABELM): The column count per logical row is fixed by the matrix type (e.g. 1 for most record types, 2 for FLMMAT_TYP_TXTRST). No header element is required; elements may be submitted one by one.
Table formats (matrix type >= FLMMAT_TYP_TABELM, i.e. isMatTypTab() is true): A header element with uiTyp = FLMELM_TYPTAB_HEADER | (uiColCnt << 8) MUST be the first element submitted, and before every format change. After the header, data elements must be submitted in exact multiples of uiColCnt (one logical row = uiColCnt consecutive calls). A new header triggers an implicit flush of pending complete rows and updates uiColCnt for subsequent rows.

At siFmrFlush(), siFmrNewMember(), and siFmrCloseArchive() the pending element count must be a complete multiple of uiColCnt; a partial row returns FLMRTC_ITF.

pvCnv is an optional element converter handle for on-the-fly type conversion in element mode. Pass NULL when not needed.

Parameters

[in]	pcErr	Optional error trace buffer (FLMERR_SIZ bytes) or NULL to suppress the trace
[in]	pvHdl	Archive handle from siFmrOpenArchive() (write mode)
[in]	siLen	Length of the record or element structure in bytes
[in]	pcRec	Pointer to the record data or FlmElmRec0 structure
[in]	pvCnv	Optional element converter handle, or NULL

Returns: FLMRTC_OK on success, non-zero on error

◆ siFmrFlush()

int siFmrFlush	(	char *	pcErr,
		void *	pvHdl,
		const int	isFinal,
		const int	isForce )

extern

Flushes buffered records to the archive (write mode).

Forces all records accumulated in the internal write buffer to be processed and written towards the archive file. In normal operation this is called automatically by siFmrNewMember() and siFmrCloseArchive(). Use this function explicitly when you want to commit data without closing the archive.

When isFinal is TRUE, the current member is finalized (footer, checksums and metadata are written). A subsequent siFmrPut() would then implicitly start a new member.

When isForce is TRUE, the flush is performed even if no data is pending in the buffer.

In format.element() mode with table formats (matrix type >= FLMMAT_TYP_TABELM): the pending element count must be a complete multiple of the current column count (uiColCnt). If a partial row is pending, complete rows are written first and then FLMRTC_ITF is returned.

Parameters

[in]	pcErr	Optional error trace buffer (FLMERR_SIZ bytes) or NULL to suppress the trace
[in]	pvHdl	Archive handle from siFmrOpenArchive() (write mode)
[in]	isFinal	Non-zero to finalize the current member after flush
[in]	isForce	Non-zero to force flush even if no data is pending

Returns: FLMRTC_OK on success, non-zero on error

◆ pcFmrGetArcName()

const char * pcFmrGetArcName ( void * pvHdl )

extern

Returns the current archive file name.

Returns a read-only pointer to the null-terminated path of the currently open FLAM5 archive file. The pointer is valid until the handle is closed.

Parameters

[in] pvHdl Archive handle from siFmrOpenArchive()

Returns: Pointer to the archive file name string, or NULL on error

◆ pcFmrGetMbrName()

const char * pcFmrGetMbrName ( void * pvHdl )

extern

Returns the name of the current archive member.

Returns a read-only pointer to the null-terminated member name of the member currently open for reading or writing. The pointer is valid until the next call to siFmrNextMember(), siFmrNewMember(), or siFmrCloseArchive() on the same handle.

Parameters

[in] pvHdl Archive handle from siFmrOpenArchive()

Returns: Pointer to the member name string, or NULL if no member is currently open

◆ pcFmrGetTabName()

const char * pcFmrGetTabName ( void * pvHdl )

extern

Returns the current table name.

When table-formatted data is being processed, this function returns the name of the current table (defined in the row specification). The name changes at the start of a new table (when siFmrGet() returns FLMRTC_EOT on a table boundary, or when siFmrSetTabName() is called on write).

Parameters

[in] pvHdl Archive handle from siFmrOpenArchive()

Returns: Pointer to the null-terminated table name, or NULL if no table name is active

◆ pcFmrGetMbrState()

const char * pcFmrGetMbrState	(	void *	pvHdl,
		const int	isCurrent )

extern

Returns the member state string.

Returns a read-only pointer to the null-terminated member state string. The state string encodes member metadata (original file name, record format, record length, character set, etc.) in CLP syntax, for example:

"STATE(ORGF='data.txt' RECF=FB RECL=80 CCSID=IBM-1141)"

The pointer is valid until the next call that modifies member state on the same handle.

Parameters

[in]	pvHdl	Archive handle from siFmrOpenArchive()
[in]	isCurrent	Non-zero to return the current (possibly modified) state; zero to return the original state as stored in the archive directory entry

Returns: Pointer to the null-terminated state string, or NULL on error

◆ pcFmrGetArcComment()

const char * pcFmrGetArcComment ( void * pvHdl )

extern

Returns the archive comment string.

Returns a read-only pointer to the null-terminated comment string stored in the archive header. The pointer is valid until the handle is closed. Returns NULL if no comment is present.

Parameters

[in] pvHdl Archive handle from siFmrOpenArchive()

Returns: Pointer to the archive comment string, or NULL if not present

◆ pcFmrGetArcHeader()

const unsigned char * pcFmrGetArcHeader	(	void *	pvHdl,
		unsigned int *	puiLen )

extern

Returns the binary user header from the archive.

Returns a read-only pointer to the raw user header bytes stored in the archive directory entry, and sets puiLen to the header length in bytes. The pointer is valid until the handle is closed. Returns NULL if no user header is present; in that case puiLen is set to 0.

Parameters

[in]	pvHdl	Archive handle from siFmrOpenArchive()
[out]	puiLen	Receives the user header length in bytes, or 0

Returns: Pointer to the user header bytes, or NULL if not present

◆ uiFmrGetArcType()

unsigned int uiFmrGetArcType ( void * pvHdl )

extern

Returns the archive type identifier.

Returns the archive type constant (e.g. FLMARC_TYPE_COMPLETE) set when the archive was created. Compare the result against the FLMARC_TYPE_* constants defined in FLMDEF.h. Returns FLMARC_TYPE_NONE (0) if the handle is invalid or no archive is open.

Parameters

[in] pvHdl Archive handle from siFmrOpenArchive()

Returns: Archive type constant (FLMARC_TYPE_COMPLETE, FLMARC_TYPE_SUBSET_SEG, etc.), or FLMARC_TYPE_NONE (0) on error

◆ uiFmrGetArcMbrCount()

unsigned int uiFmrGetArcMbrCount ( void * pvHdl )

extern

Returns the number of members in the archive.

Returns the total member count stored in the archive directory. Returns 0 if the handle is invalid or no archive is open.

Parameters

[in] pvHdl Archive handle from siFmrOpenArchive()

Returns: Member count, or 0 on error

◆ uiFmrGetArcVersion()

unsigned int uiFmrGetArcVersion ( void * pvHdl )

extern

Returns the archive format version.

Returns the FLAM5 archive format version number. Returns 0 if the handle is invalid or no archive is open.

Parameters

[in] pvHdl Archive handle from siFmrOpenArchive()

Returns: Archive version number, or 0 on error

◆ uiFmrGetArcSaveMode()

unsigned int uiFmrGetArcSaveMode ( void * pvHdl )

extern

Returns the archive save mode.

Returns the save mode constant (e.g. FLMSAV_MODE_FIL) that describes the storage topology in which the archive was originally created. Returns 0 (FLMSAV_MODE_NON) if the handle is invalid or no archive is open. Compare the result against the FLMSAV_MODE_* constants defined in FLMDEF.h.

Parameters

[in] pvHdl Archive handle from siFmrOpenArchive()

Returns: Save mode constant (FLMSAV_MODE_FIL, FLMSAV_MODE_FOL, etc.), or FLMSAV_MODE_NON (0) on error

◆ pcFmrGetFtrName()

const char * pcFmrGetFtrName ( void * pvHdl )

extern

Returns the filter name for the current member (DECO path).

When reading a DECO-format archive, returns the null-terminated name of the filter associated with the current member, obtained via the filter callback registered at open time. Returns NULL for non-DECO archives or if no filter callback is registered.

The pointer is valid until the next call to siFmrNextMember() or siFmrCloseArchive() on the same handle.

Parameters

[in] pvHdl Archive handle from siFmrOpenArchive()

Returns: Pointer to the null-terminated filter name, or NULL

◆ pcFmrGetMbrComment()

const char * pcFmrGetMbrComment ( void * pvHdl )

extern

Returns the user comment of the last read member.

Returns the member-level user comment string stored in the directory entry of the most recently read member. The string is in the system locale character set (converted from UTF-8 by the FLMARC layer on read). The pointer remains valid until the next siFmrGet() or siFmrLocate() call.

Parameters

[in] pvHdl Archive handle from siFmrOpenArchive()

Returns: Pointer to the member comment string, or NULL if not present

◆ pcFmrGetMbrHeader()

const unsigned char * pcFmrGetMbrHeader	(	void *	pvHdl,
		unsigned int *	puiLen )

extern

Returns the binary user header of the last read member.

Returns the member-level binary user header stored in the directory entry of the most recently read member. The pointer remains valid until the next siFmrGet() or siFmrLocate() call.

Parameters

[in]	pvHdl	Archive handle from siFmrOpenArchive()
[out]	puiLen	Receives the user header length in bytes, or 0

Returns: Pointer to the user header bytes, or NULL if not present

◆ siFmrSetArcComment()

int siFmrSetArcComment	(	char *	pcErr,
		void *	pvHdl,
		const char *	pcCmt )

extern

Sets the archive comment (write mode).

Stores a null-terminated comment string as the archive-level comment. Must be called before the first siFmrPut() so that the comment is passed to the underlying archive open call.

Parameters

[in]	pcErr	Optional error trace buffer (FLMERR_SIZ bytes) or NULL to suppress the trace
[in]	pvHdl	Archive handle from siFmrOpenArchive() (write mode)
[in]	pcCmt	Null-terminated comment string (copied internally)

Returns: FLMRTC_OK on success, non-zero on error

◆ siFmrSetMbrComment()

int siFmrSetMbrComment	(	char *	pcErr,
		void *	pvHdl,
		const char *	pcCmt )

extern

Sets the member comment (write mode).

Stores a null-terminated comment string as the comment for the current member. May be called before or after the first siFmrPut(). If the archive member handle is already open (after the first Put), the comment is applied directly via the FLMARC layer. Otherwise it is stored internally and applied when the member is opened. The string is copied internally; the caller does not need to keep the buffer alive after the call returns.

Parameters

[in]	pcErr	Optional error trace buffer (FLMERR_SIZ bytes) or NULL to suppress the trace
[in]	pvHdl	Archive handle from siFmrOpenArchive() (write mode)
[in]	pcCmt	Null-terminated comment string (copied internally)

Returns: FLMRTC_OK on success, non-zero on error

◆ siFmrSetArcHeader()

int siFmrSetArcHeader	(	char *	pcErr,
		void *	pvHdl,
		const unsigned char *	pcHdr,
		unsigned int	uiLen )

extern

Sets the archive-level binary user header (write mode).

Sets the binary user header stored in the archive segment. The data is copied internally by the underlying FLMARC layer, so the caller does not need to keep the buffer alive after the call returns. May be called at any point after siFmrOpenArchive() and before siFmrCloseArchive().

Parameters

[in]	pcErr	Optional error trace buffer (FLMERR_SIZ bytes) or NULL to suppress the trace
[in]	pvHdl	Archive handle from siFmrOpenArchive() (write mode)
[in]	pcHdr	Pointer to the binary header data
[in]	uiLen	Length of the header data in bytes

Returns: FLMRTC_OK on success, non-zero on error

◆ siFmrSetMbrHeader()

int siFmrSetMbrHeader	(	char *	pcErr,
		void *	pvHdl,
		const unsigned char *	pcHdr,
		unsigned int	uiLen )

extern

Sets the member-level binary user header (write mode).

Sets the binary user header for the current member. May be called before or after the first siFmrPut(). If the archive member handle is already open (after the first Put), the header is applied directly via the FLMARC layer. Otherwise it is stored internally and applied when the member is opened. The data is copied internally; the caller does not need to keep the buffer alive after the call returns. Pass uiLen = 0 to clear any previously set member user header.

Parameters

[in]	pcErr	Optional error trace buffer (FLMERR_SIZ bytes) or NULL to suppress the trace
[in]	pvHdl	Archive handle from siFmrOpenArchive() (write mode)
[in]	pcHdr	Pointer to the binary header data, or NULL if `uiLen` is 0
[in]	uiLen	Length of the header data in bytes, or 0 to clear

Returns: FLMRTC_OK on success, non-zero on error

◆ siFmrSetTabName()

int siFmrSetTabName	(	char *	pcErr,
		void *	pvHdl,
		const char *	pcName )

extern

Sets the current table name (write mode).

Specifies the table name for the records that follow. All records written after this call belong to the named table until another call to siFmrSetTabName(). Only meaningful when the format string references a table schema.

Must be called at a clean table boundary, i.e. when no unflushed records are pending in the write buffer.

Parameters

[in]	pcErr	Optional error trace buffer (FLMERR_SIZ bytes) or NULL to suppress the trace
[in]	pvHdl	Archive handle from siFmrOpenArchive() (write mode)
[in]	pcName	Null-terminated table name string

Returns: FLMRTC_OK on success, non-zero on error

◆ siFmrSetMbrName()

int siFmrSetMbrName	(	char *	pcErr,
		void *	pvHdl,
		const char *	pcName )

extern

Sets the current member name (write mode).

Convenience wrapper around siFmrSetMbrState() that sets the original file name (ORGF) and file name (FILE) attributes of the next member being written. Equivalent to:

siFmrSetMbrState(pcErr, pvHdl, "STATE(ORGF='name' FILE='name')");

Must be called before writing the first record of a member (before the first siFmrPut() or after siFmrNewMember()).

Parameters

[in]	pcErr	Optional error trace buffer (FLMERR_SIZ bytes) or NULL to suppress the trace
[in]	pvHdl	Archive handle from siFmrOpenArchive() (write mode)
[in]	pcName	Null-terminated member (file) name string

Returns: FLMRTC_OK on success, non-zero on error

◆ siFmrSetMbrState()

int siFmrSetMbrState	(	char *	pcErr,
		void *	pvHdl,
		const char *	pcState )

extern

Sets member state attributes (write mode).

Parses the supplied state string and stores the contained attributes as the metadata for the member currently being written. This overrides any previously set state attributes for this member. The state string uses CLP syntax starting with STATE(.

Common attributes:

ORGF='filename' – original file name stored in the member directory
RECF=FB|VB|FBA|... – record format
RECL=n – logical record length in bytes
CCSID='encoding' – character set identifier

Use siFmrSyntax() with FMR_STATE or siFmrHelp() with FMR_STATE to obtain the complete state string reference.

Must be called before writing the first record of a member (before the first siFmrPut() or after siFmrNewMember()).

Parameters

[in]	pcErr	Optional error trace buffer (FLMERR_SIZ bytes) or NULL to suppress the trace
[in]	pvHdl	Archive handle from siFmrOpenArchive() (write mode)
[in]	pcState	Null-terminated state string, e.g. "STATE(ORGF='a.txt' RECF=FB RECL=80)"

Returns: FLMRTC_OK on success, non-zero on error

◆ siFmrCloseArchive()

int siFmrCloseArchive	(	char *	pcErr,
		void *	pvHdl,
		const int	isSuccess,
		const int	siStaFmt,
		int *	piStaSiz,
		char **	ppStaBuf )

extern

Closes a FLAM5 archive and releases all resources.

Finalizes the current member (if open), closes the archive, and frees the handle. If the archive was opened for write, the archive directory is written and all integrity information is finalized.

The isSuccess flag tells the FLAM5 library whether the calling application considers the operation successful. This affects post-processing commands (if configured in the archive string) and whether incomplete members are marked as invalid.

Optional statistics for the entire operation can be obtained via ppStaBuf. The dynamically allocated buffer must be freed by the caller. Pass NULL for both piStaSiz and ppStaBuf if statistics are not needed.

Parameters

[in]	pcErr	Optional error trace buffer (FLMERR_SIZ bytes) or NULL to suppress the trace
[in]	pvHdl	Archive handle from siFmrOpenArchive()
[in]	isSuccess	Non-zero if the calling application considers the operation successful; zero on error/abort
[in]	siStaFmt	Format constant for statistics output (FLMOUT_FORMAT_*)
[in,out]	piStaSiz	Pre-allocated statistics buffer size on input; final size on output (may be NULL)
[in,out]	ppStaBuf	Pointer to pointer to a dynamically allocated statistics buffer (must be freed by caller; may be NULL)

Returns: FLMRTC_OK on success, FLMRTC_CHK or FLMRTC_VRS as non-fatal integrity warnings, other non-zero value on error

◆ pcFmrGetArcInfo()

const char * pcFmrGetArcInfo	(	void *	pvHdl,
		char *	pcBuf,
		unsigned int	uiSiz )

extern

Returns a human-readable description string for an open archive.

Fills pcBuf with a null-terminated single-line text describing the open archive: type, compression suite, encryption suite, main ID, and FKME ID. Useful for logging and diagnostics.

The function never returns NULL and is safe for direct use inside printf() or snprintf() without a NULL guard:

printf("archive: %s\n", pcFmrGetArcInfo(pvHdl, acBuf, sizeof(acBuf)));

pcFmrGetArcInfo

const char * pcFmrGetArcInfo(void *pvHdl, char *pcBuf, unsigned int uiSiz)

Returns a human-readable description string for an open archive.

If pvHdl is NULL or has no open archive, the sentinel string "--NULL--" is written into pcBuf and returned. If pcBuf is NULL or uiSiz is 0, the static string "--NOBUF--" is returned without touching any buffer.

Parameters

[in]	pvHdl	Archive handle from siFmrOpenArchive()
[out]	pcBuf	Caller-supplied buffer for the null-terminated info string
[in]	uiSiz	Size of `pcBuf` in bytes (including null terminator)

Returns: Always a non-NULL, null-terminated string. Returns pcBuf on success (or when pvHdl is NULL/invalid). Returns the static string "--NOBUF--" when pcBuf is NULL or uiSiz is 0.

◆ siFmrCheckArchive()

int siFmrCheckArchive	(	char *	pcErr,
		void *	pvHdl,
		const int	siLev,
		TsFmrChkResult *	psResult )

extern

Performs an integrity check on the open archive.

Invokes the FLMARC-level archive check on the currently open archive. The check level siLev controls the depth of the verification: level 1 checks directory consistency (all referenced segments present, no orphaned segments); higher levels perform checksum verification of member data. Up to 100 errors are logged per call.

Results are returned in the caller-supplied TsFmrChkResult struct. All fields are zeroed before the check begins. psResult may be NULL if only the return code matters.

Parameters

[in]	pcErr	Optional error trace buffer (FLMERR_SIZ bytes) or NULL
[in]	pvHdl	Archive handle from siFmrOpenArchive() (read or write mode)
[in]	siLev	Check level (1 = directory consistency, 2 = verify data)
[out]	psResult	Receives check counters and last reason code, or NULL

Returns: FLMRTC_OK if the check completed (psResult->siErrors == 0 means archive is clean), non-zero if the check itself could not run

◆ siFmrGetMbrStatistics()

int siFmrGetMbrStatistics	(	void *	pvHdl,
		TsFmrMbrSta *	psSta )

extern

Returns member statistics for the currently open member.

Fills psSta from the nucleus status block stored in the archive directory entry for the member currently positioned on pvHdl. Valid after siFmrOpenArchive() (first member) and after each successful siFmrNextMember().

The values reflect the state at write time. After partial updates, inserts, or deletes via the record-level API the counts may no longer match the actual current content of the member.

Parameters

[in]	pvHdl	Archive handle from siFmrOpenArchive() (read mode)
[out]	psSta	Caller-supplied TsFmrMbrSta struct to receive the statistics

Returns: FLMRTC_OK on success, FLMRTC_ITF if either pointer is NULL

◆ pcFmrErrorMessage()

const char * pcFmrErrorMessage ( const int siRtc )

extern

Maps a FLAM return code to a short English message.

Returns a read-only pointer to a static null-terminated string that describes the given FLAM return code in plain English. Useful for logging and error output when the full error trace (pcErr) is not available or is too verbose.

Parameters

[in] siRtc FLAM return code (see FLMRTC.h)

Returns: Pointer to a static null-terminated message string; never NULL (returns a generic message for unknown codes)

Functions

Detailed Description

Function Documentation

◆ siFmrVersion()

◆ siFmrAbout()

◆ siFmrLicense()

◆ siFmrHelp()

◆ siFmrSyntax()

◆ siFmrCheck()

◆ siFmrOpen()

◆ siFmrClose()

◆ siFmrGetLog()

◆ siFmrClearLog()

◆ vdFmrDeactivateLog()

◆ vdFmrReactivateLog()

◆ siFmrOpenArchive()

◆ siFmrNextMember()

◆ siFmrLocate()

◆ siFmrGet()

◆ siFmrNewMember()

◆ siFmrPut()

◆ siFmrFlush()

◆ pcFmrGetArcName()

◆ pcFmrGetMbrName()

◆ pcFmrGetTabName()

◆ pcFmrGetMbrState()

◆ pcFmrGetArcComment()

◆ pcFmrGetArcHeader()

◆ uiFmrGetArcType()

◆ uiFmrGetArcMbrCount()

◆ uiFmrGetArcVersion()

◆ uiFmrGetArcSaveMode()

◆ pcFmrGetFtrName()

◆ pcFmrGetMbrComment()

◆ pcFmrGetMbrHeader()

◆ siFmrSetArcComment()

◆ siFmrSetMbrComment()

◆ siFmrSetArcHeader()

◆ siFmrSetMbrHeader()

◆ siFmrSetTabName()

◆ siFmrSetMbrName()

◆ siFmrSetMbrState()

◆ siFmrCloseArchive()

◆ pcFmrGetArcInfo()

◆ siFmrCheckArchive()

◆ siFmrGetMbrStatistics()

◆ pcFmrErrorMessage()