Functions
const char *	pcFl4RecVersion (const int l, const int s, char *b)

const char *	pcFl4RecAbout (const int l, const int s, char *b)

void	flmopn (C08 *flmid, I32 rc, I32 lstpar, I32 opmode, C08 ddname, I32 statis)
	Open a FLAMFILE.

void	flmopd (C08 *flmid, I32 rc, I32 lstpar, I32 namelen, C08 dsname, I32 org, I32 recf, I32 recs, U08 recdel, FKD keydesc, I32 blks, I32 cldisp, I32 *dev)
	Set/Get FLAMFILE organisation attributes.

void	flmopf (C08 *flmid, I32 rc, I32 version, I32 flcode, I32 modus, I32 maxbuf, I32 header, I32 maxrec, FKD keydesc, I32 blkmode, U08 exk20, U08 exd20)
	Set/Get FLAMFILE attributes.

void	flmflu (C08 *flmid, I32 rc, U32 cputime, U32 recin, U32 bytin, U32 bytoflin, U32 recout, U32 bytout, U32 *bytoflout)
	Flush FLAMFILE.

void	flmeme (C08 *flmid, I32 rc, U32 cputime, U32 recin, U32 bytin, U32 bytoflin, U32 recout, U32 bytout, U32 bytoflout, U08 membermac)
	End member in a FLAMFILE (only z/OS)

void	flmdel (C08 *flmid, I32 rc)
	Delete last record (only z/OS)

void	flmfky (C08 *flmid, I32 rc, I32 keylen, U08 record, I32 *checkmod)
	Find record using a key (only z/OS)

void	flmfrn (C08 *flmid, I32 rc, I32 recno, I32 checkmod)
	Find record number (only z/OS)

void	flmgky (C08 *flmid, I32 rc, I32 reclen, U08 record, I32 *buflen)
	Get record addressed by key (only z/OS).

void	flmgrn (C08 *flmid, I32 rc, I32 reclen, U08 record, I32 buflen, I32 recno)
	Get record by number (only z/OS)

void	flmgtr (C08 *flmid, I32 rc, I32 reclen, U08 record, I32 *buflen)
	Get previous record (only z/OS)

void	flmiky (C08 *flmid, I32 rc, I32 reclen, U08 record)
	Insert record with key (only z/OS)

void	flmlcr (C08 *flmid, I32 rc, I32 reclen, U08 *recptr)
	Locate previous record (only z/OS)

void	flmpky (C08 *flmid, I32 rc, I32 reclen, U08 record)
	Put record by key (only z/OS)

void	flmupd (C08 *flmid, I32 rc, I32 reclen, U08 record)
	Update record (only z/OS)

void	flmcls (C08 *flmid, I32 rc, U32 cputime, U32 recin, U32 bytin, U32 bytoflin, U32 recout, U32 bytout, U32 *bytoflout)
	Close FLAMFILE.

void	flmghd (C08 *flmid, I32 rc, I32 namelen, C08 filename, I32 org, I32 recf, I32 recs, U08 recdel, FKD keydesc, I32 blks, I32 prnctr, C08 system)
	Get file header.

void	flmphd (C08 *flmid, I32 rc, I32 namelen, C08 filename, I32 org, I32 recf, I32 recs, U08 recdel, FKD keydesc, I32 blks, I32 prnctr, C08 system, I32 *cont)
	Put file header.

void	flmguh (C08 *flmid, I32 rc, I32 hdrlen, C08 header)
	Get user header.

void	flmpuh (C08 *flmid, I32 rc, I32 hdrlen, C08 header)
	Put user header.

void	flmpwd (C08 *flmid, I32 rc, U32 pwdlen, C08 passwd)
	Sets a password for encryption/decryption while compressing/decompressing.

void	flmkme (C08 *flmid, I32 rc, U32 kmclen, U08 kmc, const U32 liblen, const C08 lib, const U32 fuclen, const C08 fuc, const U32 parlen, const C08 par, U32 msglen, C08 msg, U32 inflen, C08 inf)
	Load and use FKME.

void	flmpos (C08 *flmid, I32 rc, I32 *pos)
	Set read position.

void	flmget (C08 *flmid, I32 rc, I32 reclength, U08 record, I32 *buflength)
	Get next record.

void	flmloc (C08 *flmid, I32 rc, I32 reclength, U08 *record)
	Locate record.

void	flmput (C08 *flmid, I32 rc, I32 reclength, U08 record)
	Put record.

void	flmerr (I32 rc, I32 msglen, const C08 **errmsg)
	Provides an error message.

void	flmqry (C08 *flmid, I32 rc, I32 parameter, void value)
	Query extended FLAMFILE attributes.

void	flmset (C08 *flmid, I32 rc, I32 parameter, void value)
	Set extended FLAMFILE attributes.

Detailed Description

Function Documentation

◆ pcFl4RecVersion()

const char * pcFl4RecVersion	(	const int	l,
		const int	s,
		char *	b )

extern

Adds version information to buffer

Parameters

[in]	l	Level for indentation
[in]	s	Size of about buffer
[in,out]	b	Pointer to about buffer

Returns: Pointer to version buffer

◆ pcFl4RecAbout()

const char * pcFl4RecAbout	(	const int	l,
		const int	s,
		char *	b )

extern

Adds about information to buffer

Parameters

[in]	l	Level for indentation
[in]	s	Size of about buffer
[in,out]	b	Pointer to about buffer

Returns: Pointer to about buffer

◆ flmopn()

void flmopn	(	C08 **	flmid,
		I32 *	rc,
		I32 *	lstpar,
		I32 *	opmode,
		C08 *	ddname,
		I32 *	statis )

extern

Open a FLAMFILE.

The flmopn() function opens a FLAMFILE. It can be followed by a flmopd() and/or flmopf() call, in order to set or query the attributes of the FLAMFILE or the FLAM settings.

Parameters

[out]	flmid	POINTER The contents of flmid is a pointer to a character string. This argument identifies the FLAMFILE for which the function is being executed. It is set by the flmopn() function and must not be changed until calling flmcls().
[out]	rc	INTEGER Return code (mainframe: 0=No error, 1=Error during memory request, 10=File is not a FLAMFILE, 1=FLAMFILE format error, 12=Record length error, 13=File length error, 14=Checksum error, 20=Invalid OPENMODE, 21=Invalid size of matrix buffer, 22=Invalid compression mode, 23=Invalid code in FLAMFILE, 24=24 Invalid BLOCKMODE, 25=Invalid record length, 30=FLAMFILE is empty, 37=Invalid key position (unequal 1), 40=Module or table cannot be loaded, 41=Module cannot be called, 42=Module cannot be unloaded, 43-49=Abort by user exit, 52=Invalid duplicate keys in the FLAMFILE, 57=Invalid partially compressed data length, x'F00000XX'=FLAM error code from FLAMFIO for FLAMFILE, x' 1F'=31 FLAMFILE no assigned, x' 20'=32 Invalid OPENMODE, x' 21'=33 Invalid file type, x' 22‘=34 Invalid record format, x’ 23'=35 Invalid record length, x' 24'=36 Invalid block length, x' 26'=38 Invalid key length, x' 27'=39 Invalid file name, x' 28'=40 I/O-module not loaded (e.g. missing STEPLIB in JCL), x'FFXXXXXX'=DMS error code from FLAMFIO for FLAMFILE
[in]	lstpar	INTEGER Set to a non-zero value if you will call flmopd() and/or flmopf() afterwards
[in]	opmode	INTEGER 0=INPUT(read), 1=OUTPUT(write), 2=INOUT(read/write, Host-only)
[in]	ddname	STRING Zero-terminated filename of file to open (or DD name (STRING8) on mainframes)
[in]	statis	INTEGER Indicates whether to collect statistical data that is returned on flmcls() or flmflu() (0=disable, other=enable)

◆ flmopd()

void flmopd	(	C08 **	flmid,
		I32 *	rc,
		I32 *	lstpar,
		I32 *	namelen,
		C08 *	dsname,
		I32 *	org,
		I32 *	recf,
		I32 *	recs,
		U08 *	recdel,
		FKD *	keydesc,
		I32 *	blks,
		I32 *	cldisp,
		I32 *	dev )

extern

Set/Get FLAMFILE organisation attributes.

flmopd() allows to set and/or get file organistation attributes of the FLAMFILE. Use of flmopd() is optional but has to be done after flmopn() and before flmopf(). To create a VSAM-KSDS as FLAMFILE FLAM needs the key position and key length of the original VSAM dataset, to build it own key position and key length. If you access an existing FLAM-VSAM-FILE then the key description structure contains the calculated key length and key position of the FLAMFILE.

Parameters

[in]	flmid	POINTER Identifies the FLAMFILE for which the function is executed. It is set by the flmopn() function and must not be changed until calling flmcls().
[out]	rc	INTEGER Return code (mainframe: 0= no error, -1=invalid identification or invalid call (e.g. LASTPAR=0 for FLMOPN), etc.)
[in]	lstpar	INTEGER Set to a non-zero value if you will call flmopf() afterwards
[in,out]	namelen	INTEGER Pass the length of the `filename` buffer; contains the filename length after this call (max. 54 Bytes on mainframe)
[in,out]	dsname	String Buffer used to output the filename of the file to be opened (on mainframes the file name (max. 54 Bytes) allocated to the DD name)
[in,out]	org	INTEGER organisation of FLAMFILE (0,8,16=sequential(PS,ESDS) 1,9,17=index-sequential(IS,KSDS) 2,10=RRDS 3,11=LDS)
[in,out]	recf	INTEGER Record format for FLAMFILE (0,8,16=variable 1,9,17=fixed(default) 2,3,10,18=undefined (on mainframe: 0=V,8=VB,16=VBS 1=F,9=FB,17=FBS 2,10,18=undefined)
[in,out]	recs	INTEGER maximum record length for FLAMFILE 80 - 32760, 512=default (for CX7 the maximum is 4095)
[in,out]	recdel	STRING4 Record delimiter for FLAMFILE records (only for CX7 on WIN/UNIX). On mainframe not supported.
[in,out]	keydesc	POINTER Pointer to key description (32 bytes) for the original records at write and from the FLAMFILE at read see FKD (mainframe only)
[in,out]	blks	INTEGER Blocksize for the FLAMFILE (only for mainframes) 0=unblocked or 80-32760
[in,out]	cldisp	INTEGER Close disposition (only for mainframes) 0=rewind(default) 1=unload 2=leave/retain
[in,out]	dev	INTEGER Device type 0=disc(default) 7=user defined I/O functions are used (for mainframes: 0,8,16=disc or unkown(default) 1,9,17=tape 2,10,18=floppy 3,11,19=streamer 7,15,23=user defined I/O functions are used)

◆ flmopf()

void flmopf	(	C08 **	flmid,
		I32 *	rc,
		I32 *	version,
		I32 *	flcode,
		I32 *	modus,
		I32 *	maxbuf,
		I32 *	header,
		I32 *	maxrec,
		FKD *	keydesc,
		I32 *	blkmode,
		U08 *	exk20,
		U08 *	exd20 )

extern

Set/Get FLAMFILE attributes.

Can be used to define (when compressing) or retrieve (when decompressing) the attributes of the compressed file. flmopf() can be called as second function after flmopn(), when flmopd() is not used, or as third function after flmopd(). For encrypted FLAMFILES on mainframes the function FLMSET() must be used, other platforms use bit 4 and 5 of the modus parameter to specify the encryption method: FLAM and AES

Parameters

[in]	flmid	POINTER Identifies the FLAMFILE for which the function is executed. It is set by the flmopn() function and must not be changed until calling flmcls().
[out]	rc	INTEGER Return code (mainframe: 0= no error, -1=invalid identification, 40=Load of user exit failed, 43-49=abort by user exit, etc.)
[in,out]	version	INTEGER of FLAMFILE: always 2 (UNIX only) (on mainframe: 100= Version 1/6020, 101=Version 1/6035, 200=Version 2, 300=Version 3, 400=Version 4)
[out]	flcode	INTEGER During compression, specifies the character set to use to write to the FLAMFILE. This information is returned during the decompression procedure. 0=EBCDIC, 1=ASCII(default)
[in,out]	modus	INTEGER compression method: 0=CX8 1=CX7 2=VR8 3=ADC 5=NDC
[in,out]	maxbuf	INTEGER size of matrix buffer in bytes or kbytes, possible values 1 - 2.621.440, Implicit value (at compression): 32 Kbytes (mainframe: Size of matrix buffer in BYTES)
[in,out]	header	INTEGER option flag for header generation/existence: 0=no 1=yes
[in]	maxrec	INTEGER maximum number of records in matrix: limits are 255 for CX8,CX7,VR8 and 4095 for ADC
[in,out]	keydesc	POINTER pointer to key description (32 bytes) for the original records see FKD (mainframe only)
[in]	blkmode	method of matrix storage: 0=unblocked (one compressed record from one matrix) 1=blocked (default, data from more than 1 matrix might be in 1 block)
[in]	exk20	STRING8 name of user exit (8 bytes) for output of compressed data (unused / z/OS only)
[in,out]	exd20	STRING8 name of user exit (8 bytes) for input of compressed data (unused / z/OS only)

◆ flmflu()

void flmflu	(	C08 **	flmid,
		I32 *	rc,
		U32 *	cputime,
		U32 *	recin,
		U32 *	bytin,
		U32 *	bytoflin,
		U32 *	recout,
		U32 *	bytout,
		U32 *	bytoflout )

extern

Flush FLAMFILE.

flmflu() finishes the current FLAM matrix and finalizes the compression procedure for a file. The remaining records in the block are compressed and the last FLAM record is padded where necessary. The compressed file is not closed after flmflu() and the statistics counters are not reset, i.e. another piece of compressed data can be appended. With Secure FLAMFILEs, a member trailer is appended.

Statistical information is returned if it has been requested at the corresponding flmopn() call (statis != 0).

When compressing Secure FLAMFILEs, flmflu() is permitted only after flmpuh() or flmput(). When decompressing Secure FLAMFILEs, flmflu() must be preceded by either flmget(), flmghd(), or flmguh().

Parameters

[in]	flmid	POINTER Identifies the FLAMFILE for which the function is executed. It is set by the flmopn() function and must not be changed until calling flmcls().
[out]	rc	INTEGER Return code (mainframe: 0= no error, -1=invalid identification, 43-49=abort by user exit, x'FFXXXXXX'=DMS error code)
[out]	cputime	INTEGER Consumed CPU time in units of time as returned by clock() (UNIX in seconds, MAINFRAME: used CPU in milliseconds)
[out]	recin	INTEGER If flmopn() was called with `statis` != 0, this argument returns the number of decompressed records which have been processed by flmput() or flmget(). The accumulated values of this counter are only significant if complete files are processed.
[out]	bytin	INTEGER If flmopn() was called with `statis` != 0, this argument returns the number of bytes of the decompressed records which have been transferred with flmput() or flmget(). The accumulated value of this counter is only significant if complete files are processed.
[out]	bytoflin	INTEGER UNIX: If the accumulated value of the `bytin` argument exceeds 2,000,000,000, this counter is used for multiples of 2,000,000,000. MAINFRAME: Overflow counter for original bytes. With extremely big compressed files (greater 4 gigabytes) one word byte counter are not sufficient. For this purpose the overflow counters are provided. They allow to extend the counter to a double word.
[out]	recout	INTEGER If flmopn() was called with `statis` != 0, this argument returns the number of compressed records which were created during the compression procedure or read during the decompression procedure. This value is only significant if complete files are processed (MAINFRAME: Number of compressed records).
[out]	bytout	INTEGER If flmopn() was called with `statis` != 0, this argument returns the number of bytes which were created during the compression procedure or read during the decompression procedure. This value is only significant if complete files are processed (MAINFRAME: Number of compressed bytes).
[out]	bytoflout	INTEGER UNIX: If the accumulated value of the `bytout` argument exceeds 2,000,000,000, this counter is used for multiples of 2,000,000,000. MAINFRAME: Overflow counter for compressed bytes. With extremely big compressed files (greater 4 gigabytes) one word byte counter are not sufficient. For this purpose the overflow counters are provided. They allow to extend the counter to a double word.

◆ flmeme()

void flmeme	(	C08 **	flmid,
		I32 *	rc,
		U32 *	cputime,
		U32 *	recin,
		U32 *	bytin,
		U32 *	bytoflin,
		U32 *	recout,
		U32 *	bytout,
		U32 *	bytoflout,
		U08 *	membermac )

extern

End member in a FLAMFILE (only z/OS)

The function FLMEME finishes the current data as member of a Group-FLAMFILE (end member). During compression, the content of the matrix is compressed and written immediately, enlarged with some security information (e.g. byte- and record counter), if required (SECUREINFO=YES); during decompression, the next matrix is decompressed. On AES encryption, a member MAC is created and written into the end member. The MAC is returned. On AES decryption, the member MAC is returned. Statistical values are returned. To end only a matrix and not the entire member, function * flmflu() is provided.

Parameters

[in]	flmid	POINTER Identifies the FLAMFILE for which the function is executed. It is set by the flmopn() function and must not be changed until calling flmcls().
[out]	rc	INTEGER Return code (mainframe: 0=no error, -1=invalid identification, 43-49=abort by user exit, x'FFXXXXXX'=DMS error code)
[out]	cputime	INTEGER Consumed CPU time in units of time as returned by clock() in milliseconds.
[out]	recin	INTEGER Number of original records
[out]	bytin	INTEGER Number of original bytes
[out]	bytoflin	INTEGER Overflow counter for original bytes. With extremely big compressed files (greater 4 gigabytes) one word byte counters are not sufficient. For this purpose the overflow counters are provided. They allow to extend the counter to a double word.)
[out]	recout	INTEGER Number of compressed records
[out]	bytout	INTEGER Number of compressed bytesrecords
[out]	bytoflout	INTEGER Overflow counter for compressed bytes. With extremely big compressed files (greater 4 gigabytes) one word byte counters are not sufficient. For this purpose the overflow counters are provided. They allow to extend the counter to a double word.
[out]	membermac	STRING8 pointer to a 8 byte string field where the member mac is returned.

◆ flmdel()

void flmdel	(	C08 **	flmid,
		I32 *	rc )

extern

Delete last record (only z/OS)

With function FLMDEL it is possible to delete the last read original record from an index sequential FLAMFILE.

Parameters

[in]	flmid	POINTER Identifies the FLAMFILE for which the function is executed. It is set by the flmopn() function and must not be changed until calling flmcls().
[out]	rc	INTEGER Return code (Mainframe: 0=no error, -1=invalid identification for function invalid, 5=no active record found, 43-49=abort by user exit, x'FFXXXXXX'= DMS)

◆ flmfky()

void flmfky	(	C08 **	flmid,
		I32 *	rc,
		I32 *	keylen,
		U08 *	record,
		I32 *	checkmod )

extern

Find record using a key (only z/OS)

The function FLMFKY (Find Key) can be used to search in an index sequential FLAMFILE for a record of the original file, whose key is equal to or greater than a specified key value. The specified value can be generic, i.e. not all of the positions of the key value have to be specified uniquely. The record found is the next record to be processed. If FLMFKY does not find a record, the old position is retained.

Parameters

[in]	flmid	POINTER Identifies the FLAMFILE for which the function is executed. It is set by the flmopn() function and must not be changed until calling flmcls().
[out]	rc	INTEGER Return code (Mainframe: 0=no error, -1=invalid identification or function, 5=Key not found, otherwise=see function FLMGET)
[in]	keylen	INTEGER Key length: This contains the number of significant bytes in the specified key value. It can be less than the key length. In this case, only the length passed here is taken into account in the logical relation specified in the argument checkmod.
[in]	record	POINTER Record buffer with search key
[in]	checkmod	INTEGER Type of relation (0 - equal, 1 - greater than or equal, 2 - greater than)

◆ flmfrn()

void flmfrn	(	C08 **	flmid,
		I32 *	rc,
		I32 *	recno,
		I32 *	checkmod )

extern

Find record number (only z/OS)

The function FLMFRN (Find Record Number) positions the record pointer to a record with a specified number in an index sequential FLAMFILE. This number corresponds to the record number of the sequential or relative original file. The record is the next record to be processed. Specifying checkmod=1 or 2 allows gaps and empty records to be skipped. If FLMFRN does not find a record, the old position isretained.

Parameters

[in]	flmid	POINTER Identifies the FLAMFILE for which the function is executed. It is set by the flmopn() function and must not be changed until calling flmcls().
[out]	rc	INTEGER Return code (0=no error, -1=invalid identification or function, 5=invalid position, otherwise=see function FLMGET)
[in,out]	recno	INTEGER Record number (1 = File start. With checkmod=1,2 the true record number is returned)
[out]	checkmod	INTEGER Type of relation (0 - Record with specified number, 1 - Record with specified number, skip gaps and empty records, 2 - Record with next number, skip gaps and empty records)

◆ flmgky()

void flmgky	(	C08 **	flmid,
		I32 *	rc,
		I32 *	reclen,
		U08 *	record,
		I32 *	buflen )

extern

Get record addressed by key (only z/OS).

The user can obtain an original record from an index sequential FLAMFILE via a key by using the function FLMGKY. The search key must be placed at the key position within the record area.

Parameters

[in]	flmid	POINTER Identifies the FLAMFILE for which the function is executed. It is set by the flmopn() function and must not be changed until calling flmcls().
[out]	rc	INTEGER Return code (0=no error, -1=invalid identification or function, 5=Key not found, otherwise=see function FLMGET)
[out]	reclen	INTEGER Length of passed record in bytes
[out]	record	STRING Original record (Data with key)
[in]	buflen	INTEGER Length of available record buffer in byte

◆ flmgrn()

void flmgrn	(	C08 **	flmid,
		I32 *	rc,
		I32 *	reclen,
		U08 *	record,
		I32 *	buflen,
		I32 *	recno )

extern

Get record by number (only z/OS)

The function FLMGRN (Get Record Number) reads the original record of a sequential or relative file from an index sequential FLAMFILE as specified by the record number. If FLMGRN does not find a valid record, the new position moved to is the next record or the end of the file.

Parameters

[in]	flmid	POINTER Identifies the FLAMFILE for which the function is executed. It is set by the flmopn() function and must not be changed until calling flmcls().
[out]	rc	INTEGER Return code (0=no error, -1=invalid identification or function, 1=Record was truncated because original record was larger than BUFLEN, 2=END-OF-FILE found, 3=Gap in relative file found, 5=Invalid record number (0 or negative), 6=New file starts, eventually the new file header can be read, otherwise=see function FLMGET)
[out]	reclen	INTEGER Record length in bytes of the passed record
[out]	record	STRING Original record (data)
[in]	buflen	INTEGER Length of available record buffer in bytes
[in]	recno	INTEGER Record number (1 = file start)

With return codes 2, 6 and 7 no record is passed. With return code 3 a record of length =0 is passed.

◆ flmgtr()

void flmgtr	(	C08 **	flmid,
		I32 *	rc,
		I32 *	reclen,
		U08 *	record,
		I32 *	buflen )

extern

Get previous record (only z/OS)

With function FLMGTR (Get reverse) the previous original record is read in sequential order. It is possible to position to a certain record in the compressed file using FLMGKY or FLMPOS and then to read backward sequentially. Data is transferred from the record buffer to the calling program (MOVE mode).

Parameters

[in]	flmid	POINTER Identifies the FLAMFILE for which the function is executed. It is set by the flmopn() function and must not be changed until calling flmcls().
[out]	rc	INTEGER Return code (0=no error, -1=invalid identification or function, 1=Record was truncated because original record was larger than BUFLEN, 2=END-OF-FILE found, 3=Gap in relative file found, 6=New file starts, eventually the new file header can be read, otherwise=see function FLMGET).
[out]	reclen	INTEGER Record length in bytes of the passed record.
[out]	record	STRING Original record (data).
[in]	buflen	INTEGER Length of available record buffer in bytes.

With return codes 2 and 6 no record is passed. With return code 3 a record of length 0 is passed.

◆ flmiky()

void flmiky	(	C08 **	flmid,
		I32 *	rc,
		I32 *	reclen,
		U08 *	record )

extern

Insert record with key (only z/OS)

The function FLMIKY allows to insert records with a key to an index sequential FLAMFILE (VSAM-KSDS).

Parameters

[in]	flmid	POINTER Identifies the FLAMFILE for which the function is executed. It is set by the flmopn() function and must not be changed until calling flmcls().
[out]	rc	INTEGER Return code (0=no error, -1=invalid identification or function, 5=Key exists already, 15=Original record is larger than 32763 bytes, 16=Original record is larger than matrix - 4, 43-49=Abort by user exit, 52=Too many) or invalid duplicate keys, x'FFXXXXXX'=DMS error code)
[in]	reclen	INTEGER Record length (data length) in bytes without record length field
[in]	record	STRING Original record (data with key)

◆ flmlcr()

void flmlcr	(	C08 **	flmid,
		I32 *	rc,
		I32 *	reclen,
		U08 **	recptr )

extern

Locate previous record (only z/OS)

The function FLMLCR is equivalent to FLMGTR (Get reverse). The data will not be transmitted but only a pointer on the record is provided (locate Mode).

Parameters

[in]	flmid	POINTER Identifies the FLAMFILE for which the function is executed. It is set by the flmopn() function and must not be changed until calling flmcls().
[out]	rc	INTEGER Return code (0=no error, -1=invalid identification or function, 2=Beginning of file found, otherwise=see FLMGET)
[out]	reclen	INTEGER Record length in bytes of the passed record
[out]	recptr	POINTER Record address (data address)

With return codes 2 and 6 no record address is passed. With return code 3 the length 0 is passed.

◆ flmpky()

void flmpky	(	C08 **	flmid,
		I32 *	rc,
		I32 *	reclen,
		U08 *	record )

extern

Put record by key (only z/OS)

The function FLMPKY allows to insert records into an index sequential FLAMFILE or to update records within such a file via a key.

Parameters

[in]	flmid	POINTER Identifies the FLAMFILE for which the function is executed. It is set by the flmopn() function and must not be changed until calling flmcls().
[out]	rc	INTEGER Return code (0=no error, -1=invalid identification or function, 5=Key not allowed, 15=Original record greater than 32763 bytes, 16=Original record greater than matrix - 4, 43=Abort by user exit, x'FFXXXXXX'= DMS error code)
[in]	reclen	INTEGER Record length (data length) in bytes without record length field (exclusive length)
[in]	record	STRING Original record (Data with key)

◆ flmupd()

void flmupd	(	C08 **	flmid,
		I32 *	rc,
		I32 *	reclen,
		U08 *	record )

extern

Update record (only z/OS)

The function FLMUPD updates the original record last read from a VSAM-KSDS FLAMFILE.

Parameters

[in]	flmid	POINTER Identifies the FLAMFILE for which the function is executed. It is set by the flmopn() function and must not be changed until calling flmcls().
[out]	rc	INTEGER Return code (0=no error, -1=invalid identification or function, 5=No current record, 15=Original record greater than 32764 bytes, 16=Original record greater than matrix - 4, 43=Abort by user exit, x'FFXXXXXX'= DMS error code).
[in]	reclen	INTEGER Record length (data length) in bytes without record lengthfield.
[in]	record	STRING Original record (data).

◆ flmcls()

void flmcls	(	C08 **	flmid,
		I32 *	rc,
		U32 *	cputime,
		U32 *	recin,
		U32 *	bytin,
		U32 *	bytoflin,
		U32 *	recout,
		U32 *	bytout,
		U32 *	bytoflout )

extern

Close FLAMFILE.

The flmcls() function finalizes the record interface.

If compression is closed, the last matrix is compressed and the compressed data is written to the FLAMFILE. Additional information (byte-, record counter, MACs) are stored as an 'ending record', if required (SECUREINFO=YES). Then the FLAMFILE is closed.

When decompression is closed, only the FLAMFILE is closed. Additional records not yet read from the FLAMFILE are discarded.

Statistical information are returned if it has been requested at the corresponding flmopn() call (statis != 0). Mainframe: The parameters cputime until bytoflout are only used if the statistics are switched on in FLMOPN.

With Secure FLAMFILEs, flmcls() may only be invoked immediately after flmflu() or flmpos().

Parameters

[in,out]	flmid	POINTER The contents of flmid is a pointer to a character string. This argument identifies the FLAMFILE for which the function is being executed. It is set by the flmopn() function and must not be changed until calling flmcls().
[out]	rc	INTEGER Return code (mainframe: 0=no error, -1=Invalid identification (e.g. FLMCLS already done ?), 43-49=Abort by user exit, x'FFXXXXXX'=DMS- error code)
[out]	cputime	INTEGER Consumed CPU time in units of time as returned by clock() (Mainframe: CPU time in milliseconds, UNIX: in seconds).
[out]	recin	INTEGER If flmopn() was called with `statis` != 0, this argument returns the number of original records which have been processed by flmput() or flmget(). The accumulated values of this counter are only significant if complete files are processed.
[out]	bytin	INTEGER If flmopn() was called with `statis` != 0, this argument returns the number of bytes of the original records which have been transferred with flmput() or flmget(). The accumulated value of this counter is only significant if complete files are processed.
[out]	bytoflin	INTEGER UNIX: If the accumulated value of the `bytin` argument exceeds 2,000,000,000, this counter is used for multiples of 2,000,000,000. MAINFRAME: Overflow counter for original bytes. With extremely big compressed files (greater 4 gigabytes) one word byte counters are not sufficient. For this purpose the overflow counters are provided. They allow to extend the counter to a double word.
[out]	recout	INTEGER If flmopn() was called with `statis` != 0, this argument returns the number of compressed records which were created during the compression procedure or read during the decompression procedure. This value is only significant if complete files are processed.
[out]	bytout	INTEGER If flmopn() was called with `statis` != 0, this argument returns the number of bytes which were created during the compression procedure or read during the decompression procedure. This value is only significant if complete files are processed.
[out]	bytoflout	INTEGER UNIX: If the accumulated value of the `bytout` argument exceeds 2,000,000,000, this counter is used for multiples of 2,000,000,000. MAINFRAME: Overflow counter for compressed bytes. With extremely big compressed files (greater 4 gigabytes) one word byte counter are not sufficient. For this purpose the overflow counters are provided. They allow to extend the counter to a double word.

◆ flmghd()

void flmghd	(	C08 **	flmid,
		I32 *	rc,
		I32 *	namelen,
		C08 *	filename,
		I32 *	org,
		I32 *	recf,
		I32 *	recs,
		U08 *	recdel,
		FKD *	keydesc,
		I32 *	blks,
		I32 *	prnctr,
		C08 *	system )

extern

Get file header.

flmghd() allows retrieving the file attributes of the original file during decompression if they were stored in the FLAMFILE during compression. If the FLAMFILE contains several file headers (see flmphd()), the last file header found by FLAM is returned. It is possible to request the file header information with function# FLMGHD at any time between FLAM-OPEN (FLMOPN, FLMOPD, FLMOPF) and FLAM-CLOSE (FLMCLS).

The first file header is usually available immediately after flmopn() (see flmopf() header=1). When FLAM recognizes additional file headers, it will inform the user via the return code (RETCO=6) of flmget() or flmloc().

Parameters

[in]	flmid	POINTER Pointer to a character string of 8 bytes. Identifies the FLAMFILE. It is set by the flmopn() function and must not be changed until calling flmcls().
[out]	rc	INTEGER Return code (mainframe: 0=no error, -1=Invalid identification or function)
[in,out]	namelen	INTEGER Pass the length of the `filename` buffer in which the name of the original file will be returned. Is set to the actual length when function returns (Mainframe: 0=File name not known).
[in,out]	filename	STRING Buffer area in which to store the original filename. If the buffer is too small, the filename will be truncated to the length of the buffer.
[in,out]	org	INTEGER returns a value for the organization of the original file. Possible values (not all are supported on Unix): 0=sequential, 1=index-sequential, 2=relative, 3=random/direct access, 4=no record structure, 5=library 6=physical
[out]	recf	INTEGER returns a value for the record format of the original file. Possible values (not all are supported on Unix): 0/8/16/24 = variable / blocked / blocked/spanned / VFC; 1/9/17 = fix / blocked / blocked/Standard; 2/10/18 = undefined (U)/ EAF; 3/11/19 = stream (S)/ text delimiter / length fields
[out]	recs	INTEGER This argument returns the record size of the original file. For variable record sizes and the stream record format, the value is 0 (Mainframe= 0-32760).
[out]	recdel	STRING4 This argument specifies the record delimiter for the stream record format.
[out]	keydesc	POINTER Key description structure, 32 bytes (mainframe only)
[out]	blks	INTEGER Block length of original file (0=unblocked), Mainframe = 0-32760).
[out]	prnctr	INTEGER Printer control characters (0=none, 1=ASA, 2=Machine specific)
[out]	system	STRING2 This argument consists of two bytes and is used to return a code for the operating system in which the FLAMFILE was created: = x'0000' unknown = x'0080' MS-DOS = x'0101' IBM MVS, z/OS = x'0102' IBM VSE/SP, zVSE = x'0103' IBM VM/SP VM/XA = x'0104' IBM DPPX/8100 = x'0105' IBM DPPX/370 = x'02XX' UNISYS = x'0301' DEC VMS = x'0302' DEC ULTRIX = x'0401' SIEMENS BS2000 = x'0402' SIEMENS SINIX = x'0403' SIEMENS SYSTEM V = x'0501' NIXDORF 886X = x'0502' NIXDORF TARGON = x'06XX' WANG = x'07XX' PHILLIPS = x'08XX' OLIVETTI = x'11XX' INTEL 80286 = x'12XX' INTEL 80386 = x'13XX' INTEL 80486

◆ flmphd()

void flmphd	(	C08 **	flmid,
		I32 *	rc,
		I32 *	namelen,
		C08 *	filename,
		I32 *	org,
		I32 *	recf,
		I32 *	recs,
		U08 *	recdel,
		FKD *	keydesc,
		I32 *	blks,
		I32 *	prnctr,
		C08 *	system,
		I32 *	cont )

extern

Put file header.

The flmphd() function is only allowed during compression and if header=1 was set with flmopf(). It generates a common file header, which describes the file format of the original records that are transferred subsequently. If several different files are compressed into a single FLAMFILE, a separate file header can be generated for each file with the flmphd() function. FLAM returns this file header information during the decompression procedure if it has been requested to do so (flmghd()).

Calls to flmphd() with continue_param!=0 or after flmpwd() must be followed immediately by flmpuh().

Using SECUREINFO=YES, function flmphd() is mandatory!

Note: The parameters in flmphd() also control the construction of an index-sequential FLAMFILE. On DSORG=0 (sequential data), a record number is created and used as a record key; on DSORG=1 (index-sequential) the original key is used.

Parameters

[in]	flmid	POINTER Identifies the FLAMFILE for which the function is executed. It is set by the flmopn() function and must not be changed until calling flmcls().
[out]	rc	INTEGER Return code (mainframe: 0=no error, -1=Invalid identification or function)
[in]	namelen	INTEGER Length of the `filename` (mainframe: 0 = no use of filename)
[in]	filename	STRING Buffer containing the original filename
[in]	org	INTEGER Code for the organization of the original file. For permissible values, see the flmghd() function.
[in]	recf	INTEGER Code for the record format of the original file. For permissible values, see the flmghd() function.
[in]	recs	INTEGER The maximum record size of the original file (mainframe: 0-32760)
[in]	recdel	STRING4 Record delimiter
[in]	keydesc	POINTER Key description structure, 32 bytes (for mainframes only)
[in]	blks	INTEGER Block length of original file (UNIX: 0=unblocked, 0-32767, MAINFRAME: 0-32760)
[in]	prnctr	INTEGER Printer control characters for mainframe only (0=none, 1=ASA, 2=Machine specific)
[in]	system	STRING2 This argument consists of two bytes and is used to return a code for the operating system in which the FLAMFILE was created. For a list of valid values, see flmghd().
[in]	cont	INTEGER Indicates whether a call to flmpuh() will follow (0=no more parameter, otherwise=a user header is to be transferred with FLMPUH)

◆ flmguh()

void flmguh	(	C08 **	flmid,
		I32 *	rc,
		I32 *	hdrlen,
		C08 *	header )

extern

Get user header.

Retrieves the data from the user-specific FLAM file header. Calling this function is only allowed during decompression and immediately following an flmghd() call.

Parameters

[in]	flmid	POINTER Identifies the FLAMFILE for which the function is executed. It is set by the flmopn() function and must not be changed until calling flmcls().
[out]	rc	INTEGER Return code (mainframe: 0=no error, -1=Invalid identification or function) *
[in,out]	hdrlen	INTEGER Pass the length of the buffer in which the user-specific file header will be returned. Is set to the actual length when function returns. (Mainframe: 0=no data, 1-3500=8-bit compressed data for CX8 or VR8, -1750=7-bit compressed data for CX7)
[out]	header	STRING Buffer containing user header with user data. The user data is reproduced exactly as it is written, i.e. converting the code of a file transfer has no effect here.

◆ flmpuh()

void flmpuh	(	C08 **	flmid,
		I32 *	rc,
		I32 *	hdrlen,
		C08 *	header )

extern

Put user header.

The flmpuh() function adds a user-specific header with information of arbitrary structure to the FLAMFILE. This information is added in binary form and can be retrieved during decompression with flmguh() (the complementary function).

Calling this function is only allowed during compression and immediately following an flmphd() call.

Parameters

[in]	flmid	POINTER Identifies the FLAMFILE for which the function is executed. It is set by the flmopn() function and must not be changed until calling flmcls().
[out]	rc	INTEGER Return code (mainframe: 0=no error, -1=Invalid identification or function)
[in]	hdrlen	INTEGER max. 1750 (Host, 7-bit, CX7), 32732 bytes (other))
[in]	header	STRING User-specific header data In CX7, this data is converted in such a way that the integrity of the FLAMFILE is not corrupted. The user data itself remains in its original code, even during code conversions using heterogeneous data exchange.

◆ flmpwd()

void flmpwd	(	C08 **	flmid,
		I32 *	rc,
		U32 *	pwdlen,
		C08 *	passwd )

extern

Sets a password for encryption/decryption while compressing/decompressing.

It is the first call after the last FLMOPx function during encryption.

The encryption mode is set by the function flmset(). On decryption, the information is read from the FLAMFILE and can be obtained by calling flmqry().

Parameters

[in]	flmid	POINTER Identifies the FLAMFILE for which the function is executed. It is set by the flmopn() function and must not be changed until calling flmcls().
[out]	rc	INTEGER Return code (mainframe: 0=no error, -1=Password function invalid, e.g. for MODE=CX8, VR8, CX7, renewed call up)
[in]	pwdlen	INTEGER The password's length in characters (max. 64)
[in]	passwd	STRING The password string

◆ flmkme()

void flmkme	(	C08 **	flmid,
		I32 *	rc,
		U32 *	kmclen,
		U08 *	kmc,
		const U32 *	liblen,
		const C08 *	lib,
		const U32 *	fuclen,
		const C08 *	fuc,
		const U32 *	parlen,
		const C08 *	par,
		U32 *	msglen,
		C08 *	msg,
		U32 *	inflen,
		C08 *	inf )

extern

Load and use FKME.

Works like SETPWD but use FKME parameters. It dynamically loads the FKME module, runs the function code INFO, if inflen provided and execute function code COMP or DECO with the provided values.

Parameters

[in,out]	flmid	POINTER Identifies the FLAMFILE for which the function is executed. It is set by the flmopn() function and must not be changed until calling flmcls().
[out]	rc	INTEGER Return code
[in,out]	kmclen	length of key management context (user header)
[in,out]	kmc	pointer to key mangement context (user header)
[in]	liblen	length of the library name (not relevant on z/OS)
[in]	lib	pointer to the library name
[in]	fuclen	length of the function name
[in]	fuc	pointer to the function name (for dynamic load)
[in]	parlen	length of the parameter string
[in]	par	pointer to the paramter string
[in,out]	msglen	size/length of return message
[out]	msg	point to the return message
[in,out]	inflen	size/length of return info string (could be 0 to prevent call of function code INFO)
[out]	inf	point to the info string

◆ flmpos()

void flmpos	(	C08 **	flmid,
		I32 *	rc,
		I32 *	pos )

extern

Set read position.

FLMPOS (Position) allows to position the record pointer within compressed files.

With OPEN=INPUT and INOUT or OUTIN the pointer can positioned anywhere, irrespective of whether the original file is index sequential or sequential. With OPEN = OUTPUT it is possible to create gaps in relative files by advancing the write pointer by N records.

FLMPOS (Position) is used for relative positioning in any FLAMFILE and for creating gaps when writing relative files.

The pos parameter is used as follows:

On mainframes: -MAXINT -> Start of file +MAXINT -> End of file -99999999 -> Start of file for Cobol +99999999 -> End of file for Cobol -99999998 -> Start of previous file in a group file +99999998 -> Start of next file in a group file -N -> N records backward +N -> N records forward -99999998 -> Back to the start of the current file or to the start of the previous file in a group file +99999998 -> Start of next file in a group file

ON UNIX: only one relative position is supported: +99999998 -> Start of next file in a group file

Parameters

[in]	flmid	POINTER Identifies the FLAMFILE for which the function is executed. It is set by the flmopn() function and must not be changed until calling flmcls().
[out]	rc	INTEGER Return code (mainframe: 0=no error, -1=Invalid identification or function, 5=Invalid position, 40-78=see function FLMGET, x'FFXXXXXX'=DMS error code)
[in]	pos	INTEGER new position to use on get next read (see above).

◆ flmget()

void flmget	(	C08 **	flmid,
		I32 *	rc,
		I32 *	reclength,
		U08 *	record,
		I32 *	buflength )

extern

Get next record.

flmget() reads the next original record sequentially. The data is transferred to the supplied record buffer. A special return code indicates when a new file header is encountered.

It is possible to position to a certain record in the compressed file using flmgky() or flmpos() and then to continue with sequential reading.

flmget() may only be used at decompression. With encrypted FLAMFILEs, a password must be provided via flmpwd() before the first invocation of flmget().

Parameters

[in]	flmid	POINTER Identifies the FLAMFILE for which the function is executed. It is set by the flmopn() function and must not be changed until calling flmcls().
[out]	rc	INTEGER Return code (mainframe: 0=no error, -1=Invalid identification or function, 1=Record was truncated because original record was larger than BUFLEN, 2=END-OF-FILE found, 3=Gap in relative file found, 6=New file starts, eventually the new file header can be read, 7=Password required. Pass it via FLMPWD, 11=FLAMFILE format error, 12=Record length error, 13=File length error, 14=Checksum error, 29=Illegal password, 43-49=Abort by user exit, 52=Too many or invalid duplicate keys, x'FFXXXXXX'=Data management error code, etc.
[out]	reclength	INTEGER Returns the length in bytes of the `record` which has been read
[out]	record	STRING Record buffer used to put record data into
[in]	buflength	INTEGER Length of the `record` buffer in bytes

With return codes 2 , 6 and 7 no record is passed. With return code 3 a record of length 0 is passed.

◆ flmloc()

void flmloc	(	C08 **	flmid,
		I32 *	rc,
		I32 *	reclength,
		U08 **	record )

extern

Locate record.

The function flmloc() is equivalent to flmget(), except that it does not put a read record into a supplied buffer. Instead, a pointer to the record is returned (LOCATE mode).

Parameters

[in]	flmid	POINTER Identifies the FLAMFILE for which the function is executed. It is set by the flmopn() function and must not be changed until calling flmcls().
[out]	rc	INTEGER Return code (mainframe: 0=no error, -1=Invalid identification or function, 1=Record was truncated because original record was)
[out]	reclength	INTEGER Length of the record pointed to by `record`
[out]	record	POINTER Contains pointer to the read record after call

With return codes 2 , 6 and 7 no record is passed. With return code 3 a record of length 0 is passed.

◆ flmput()

void flmput	(	C08 **	flmid,
		I32 *	rc,
		I32 *	reclength,
		U08 *	record )

extern

Put record.

The flmput function compresses one original record at a time.

Parameters

[in]	flmid	POINTER Identifies the FLAMFILE for which the function is executed. It is set by the flmopn() function and must not be changed until calling flmcls().
[out]	rc	INTEGER Return code (mainframe: 0=no error, -1=Invalid identification or function, 2=END-OF-FILE found, 3=Gap in relative file found, 6=New file starts, eventually the new file header can be read, etc.
[in]	reclength	INTEGER Record length in bytes
[in]	record	STRING Buffer containing the buffer with record/data address

◆ flmerr()

void flmerr	(	I32 *	rc,
		I32 *	msglen,
		const C08 **	errmsg )

extern

Provides an error message.

With flmerr() a return code can be translated into a talking error message.

Parameters

[in,out]	rc	INTEGER Return code
	msglen	at input space for the error message, at output length of the error message
	errmsg	pointer to the error message buffer

◆ flmqry()

void flmqry	(	C08 **	flmid,
		I32 *	rc,
		I32 *	parameter,
		void *	value )

extern

Query extended FLAMFILE attributes.

With flmqry() parameters can be obtained during decompression. It may be called at any time after flmopn(), but the results depend on the moment it is called. E.g. SPLIT.. are first known after flmopd(), CRYPTOMODE after flmopf().

Note: In opposite to the other function calls the return code rc was expanded into two words (2 x 4 byte). The first word is still the return code, the second word is the info code. The info code is the parameter in error on return. If the parameter ID unknown the info code 91# will be set.

Besides FLMGET_CRYPTOMODE and FLMGET_SECUREINFO extended attributes are only meaningful on the mainframe.

See also: flmget_parameter and flmset

Parameters

[in]	flmid	POINTER Identifies the FLAMFILE for which the function is executed. It is set by the flmopn() function and must not be changed until calling flmcls().
[out]	rc	INTARY2 Return code and info code
[in]	parameter	INTEGER Identifies the flmget_parameter
[out]	value	POINTER Parameter value read

Note: Only on z/OS multiple parameter/value pairs can be get in one call. It is necessary to mark the end of the parameter list! Most compilers do it automatically, but in Assembler the last parameter address has to be flagged: A(X'80000000')+VALUEn).

It's recommended to make only one call for one parameter to keep the code usable for all platforms.

◆ flmset()

void flmset	(	C08 **	flmid,
		I32 *	rc,
		I32 *	parameter,
		void *	value )

extern

Set extended FLAMFILE attributes.

flmset() sets parameter that open functions do not support. It must be called before flmopd() and/or flmopf(). A later call will fail with return code 90.

Note: In opposite to the other function calls the return code rc was expanded into two words (2 x 4 byte). The first word is still the return code, the second word is the info code. The info code is the parameter in error on return. If the parameter ID unknown the info code 91# will be set.

Besides FLMSET_CRYPTOMODE and FLMSET_SECUREINFO extended attributes are only meaningful on the mainframe.

See also: flmset_parameter and flmqry()

Parameters

[in]	flmid	POINTER Identifies the FLAMFILE for which the function is executed. It is set by the flmopn() function and must not be changed until calling flmcls().
[out]	rc	INTARY2 Return code and info code
[in]	parameter	INTEGER Identifies the flmset_parameter
[in]	value	POINTER Will be used to set the specified `parameter`

Note: Only on z/OS multiple parameter/value pairs can be set in one call. It is necessary to mark the end of the parameter list! Most compilers do it automatically, but in Assembler the last parameter address has to be flagged: A(X'80000000')+VALUEn).

It's recommended to make only one call for one parameter. to keep the code usable for all platforms.

Functions

Detailed Description

Function Documentation

◆ pcFl4RecVersion()

◆ pcFl4RecAbout()

◆ flmopn()

◆ flmopd()

◆ flmopf()

◆ flmflu()

◆ flmeme()

◆ flmdel()

◆ flmfky()

◆ flmfrn()

◆ flmgky()

◆ flmgrn()

◆ flmgtr()

◆ flmiky()

◆ flmlcr()

◆ flmpky()

◆ flmupd()

◆ flmcls()

◆ flmghd()

◆ flmphd()

◆ flmguh()

◆ flmpuh()

◆ flmpwd()

◆ flmkme()

◆ flmpos()

◆ flmget()

◆ flmloc()

◆ flmput()

◆ flmerr()

◆ flmqry()

◆ flmset()