### STATE

#### Synopsis

    HELP:   State string for FLUC byte, stream and record interfaces
    TYPE:   OBJECT
    SYNTAX: > flcbyt STATE(ORGF='str'/STREAM/DUMMY,FILE='str'/STREAM/DUMMY,MEMBER='str',COMMENT='str',CHRSET=NONE/SYSTEM/ASCII/UCS1/UTF8/EBCDIC/UCS2BE/UTF16BE/UCS2LE/UTF16LE/UCS4BE/UTF32BE/UCS4LE/UTF32LE/LOCAL,CCSID='str',SPACE=num,BLKSIZE=num,RECFORMAT=NONE/BIN/TXT/TXT-ASA/TXT-MCC/DLM/DLM-ASA/DLM-MCC/VAR/VAR-ASA/VAR-MCC/FIX/FIX-ASA/FIX-MCC/VAR-REL/VAR-REL-ASA/VAR-REL-MCC/FIX-REL/FIX-REL-ASA/FIX-REL-MCC/F/FA/FM/FS/FSA/FSM/FB/FBA/FBM/FBS/FBSA/FBSM/FE/FEA/FEM/FK/FKA/FKM/FR/FRA/FRM/U/UA/UM/V/VA/VM/VS/VSA/VSM/VB/VBA/VBM/VBS/VBSA/VBSM/VE/VEA/VEM/VK/VKA/VKM/VR/VRA/VRM/ORG,RECLENGTH=num,KEYPOSITION=num,KEYLENGTH=num,DATFMT=NONE/BLOCK/RECORD/ELEMENT,DATTYP=NONE/BINARY/RECORD/RECTXT/CHAR/TEXT/XML/TABLE,MATRIX=NONE/DATBLK/STDREC/STDASAREC/STDMCCREC/RELREC/RELASAREC/RELMCCREC/TXTREC/TXTDLM/TXTRST/XMLELM,REDUNDANT,NOTREDUNDANT,ATTRIB())

#### Description

The state string contains some metadata representing the internal state of FLUC. When opening a file for reading (fcbopen2("read."/"input()")), this state string is returned. It can be passed to a successive file open call for writing (fcbopen2("write."/"output()") or FCROPN("write."/"output()")) to give FLUC additional hints about the data that is to be written. The state string contains mainly file attributes which must be known to fill header information for archives (GZIP, FLAM) correctly, but also some information about elements when working in element formatting mode.

On C/C++ interfaces, the parameter is a pointer to a pointer to a string. In read mode, if you pass a non-null pointer, the pointer target will be a pointer to a null-terminated string dynamically allocated in heap memory (i.e. you must free() it!) containing the state string after the opening function returns. In write mode, if you pass a non-null pointer to a pointer to a state string, this state string is used to set the internal state. Otherwise, the state is initialized with default values.

On the record interface, the application must provide the memory and a length error is returned if the buffer is too small.

#### Example:

       "state(member='test.txt' recf=FBA recl=120)"

The state mainly contains file attributes which describe the source. This information is important for example to store the right values in GZIP or FLAM headers. The status object can be used to pass the source's characteristics to the write operation.

#### Arguments

- `STRING: ORGF='str'/STREAM/DUMMY - Original name of the file (used for defined mappings, if empty then FILE is used)`
  - `STREAM - Read from stdin or write to stdout`
  - `DUMMY - Read EOF or write nothing`
- `STRING: FILE='str'/STREAM/DUMMY - Current name of the file (with appended extensions, if empty then ORGF is used)`
  - `STREAM - Read from stdin or write to stdout`
  - `DUMMY - Read EOF or write nothing`
- `STRING: MEMBER='str' - Name or Index of the member`
- `STRING: COMMENT='str' - Comment for headers`
- `NUMBER: CHRSET=NONE/SYSTEM/ASCII/UCS1/UTF8/EBCDIC/UCS2BE/UTF16BE/UCS2LE/UTF16LE/UCS4BE/UTF32BE/UCS4LE/UTF32LE/LOCAL - Character set`
  - `NONE - No character set defined`
  - `SYSTEM - SYSTEM (environment specific (on mainframe EBCDIC else ASCII))`
  - `ASCII - ASCII (mainly used in the for open system)`
  - `UCS1 - UCS-1 (for text formatting identical to ASCII < 64k)`
  - `UTF8 - UTF-8 (for text formatting identical to ASCII < 2M)`
  - `EBCDIC - EBCDIC (mainly used on IBM mainframe)`
  - `UCS2BE - UCS-2 Big Endian (multibyte character set < 64k)`
  - `UTF16BE - UTF-16 Big Endian (multibyte character set < 2M)`
  - `UCS2LE - UCS-2 Little Endian (multibyte character set < 64k)`
  - `UTF16LE - UTF-16 Little Endian (multibyte character set < 2M)`
  - `UCS4BE - UCS-4 Big Endian (multibyte character set < 64k)`
  - `UTF32BE - UTF-32 Big Endian (multibyte character set < 2M)`
  - `UCS4LE - UCS-4 Little Endian (multibyte character set < 64k)`
  - `UTF32LE - UTF-32 Little Endian (multibyte character set < 2M)`
  - `LOCAL - LOCAL (platform specific (on mainframe EBCDIC else ASCII))`
- `STRING: CCSID='str' - CCSID / Character encoding`
- `NUMBER: SPACE=num - Required space for the target in byte`
- `NUMBER: BLKSIZE=num - Block size`
- `NUMBER: RECFORMAT=NONE/BIN/TXT/TXT-ASA/TXT-MCC/DLM/DLM-ASA/DLM-MCC/VAR/VAR-ASA/VAR-MCC/FIX/FIX-ASA/FIX-MCC/VAR-REL/VAR-REL-ASA/VAR-REL-MCC/FIX-REL/FIX-REL-ASA/FIX-REL-MCC/F/FA/FM/FS/FSA/FSM/FB/FBA/FBM/FBS/FBSA/FBSM/FE/FEA/FEM/FK/FKA/FKM/FR/FRA/FRM/U/UA/UM/V/VA/VM/VS/VSA/VSM/VB/VBA/VBM/VBS/VBSA/VBSM/VE/VEA/VEM/VK/VKA/VKM/VR/VRA/VRM/ORG - Record format`
  - `NONE - No format defined`
  - `BIN - Open - Binary (undefined) data (only the last record are shorter then record length)`
  - `TXT - Open - Text data with standard delimiter (result is a stripped variable length records)`
  - `TXT-ASA - Open - Text data with standard delimiter and ASA byte in front (result variable length records with ASA attribute)`
  - `TXT-MCC - Open - Text data with standard delimiter and MCC byte in front (result variable length records with MCC attribute)`
  - `DLM - Open - Records separated by a special delimiter with the result of variable length records`
  - `DLM-ASA - Open - ASA records separated by a special delimiter with the result of variable length records`
  - `DLM-MCC - Open - MCC records separated by a special delimiter with the result of variable length records`
  - `VAR - Open - Variable length record (if necessary define length format)`
  - `VAR-ASA - Open - Variable length record with ASA print control character (if necessary define length format)`
  - `VAR-MCC - Open - Variable length record with machine print control codes (if necessary define length format)`
  - `FIX - Open - Fixed-length record (file size = N * record length)`
  - `FIX-ASA - Open - Fixed-length record with ASA print control character (file size = N * (record length + 1))`
  - `FIX-MCC - Open - Fixed-length record with machine print control codes (file size = N * (record length + 1))`
  - `VAR-REL - Open - Variable relative record (if necessary define length format)`
  - `VAR-REL-ASA - Open - Variable relative record with ASA print control character (if necessary define length format)`
  - `VAR-REL-MCC - Open - Variable relative record with machine print control codes (if necessary define length format)`
  - `FIX-REL - Open - Fix relative record (file size = N * (record length + 8))`
  - `FIX-REL-ASA - Open - Fix relative record with ASA print control character (file size = N * (record length + 9))`
  - `FIX-REL-MCC - Open - Fix relative record with machine print control codes (file size = N * (record length + 9))`
  - `F - Host - Fixed-length, unblocked`
  - `FA - Host - Fixed-length, unblocked, ASA print control characters`
  - `FM - Host - Fixed-length, unblocked, machine print control codes`
  - `FS - Host - Fixed-length, standard`
  - `FSA - Host - Fixed-length, standard, ASA print control characters`
  - `FSM - Host - Fixed-length, standard, machine print control codes`
  - `FB - Host - Fixed-length, blocked`
  - `FBA - Host - Fixed-length, blocked, ASA print control characters`
  - `FBM - Host - Fixed-length, blocked, machine print control codes`
  - `FBS - Host - Fixed-length, blocked, standard`
  - `FBSA - Host - Fixed-length, blocked, standard, ASA print control characters`
  - `FBSM - Host - Fixed-length, blocked, standard, machine print control codes`
  - `FE - Host - Fixed-length, ESDS`
  - `FEA - Host - Fixed-length, ESDS, ASA print control characters`
  - `FEM - Host - Fixed-length, ESDS, machine print control codes`
  - `FK - Host - Fixed-length, KSDS`
  - `FKA - Host - Fixed-length, KSDS, ASA print control characters`
  - `FKM - Host - Fixed-length, KSDS, machine print control codes`
  - `FR - Host - Fixed-length, RRDS`
  - `FRA - Host - Fixed-length, RRDS, ASA print control characters`
  - `FRM - Host - Fixed-length, RRDS, machine print control codes`
  - `U - Host - Undefined-length`
  - `UA - Host - Undefined-length, ASA print control characters`
  - `UM - Host - Undefined-length, machine print control codes`
  - `V - Host - Variable`
  - `VA - Host - Variable, ASA print control characters`
  - `VM - Host - Variable, machine print control codes`
  - `VS - Host - Variable, spanned`
  - `VSA - Host - Variable, spanned, ASA print control characters`
  - `VSM - Host - Variable, spanned, machine print control codes`
  - `VB - Host - Variable, blocked`
  - `VBA - Host - Variable, blocked, ASA print control characters`
  - `VBM - Host - Variable, blocked, machine print control codes`
  - `VBS - Host - Variable, blocked, spanned`
  - `VBSA - Host - Variable, blocked, spanned, ASA print control characters`
  - `VBSM - Host - Variable, blocked, spanned, machine print control codes`
  - `VE - Host - Variable, ESDS`
  - `VEA - Host - Variable, ESDS, ASA print control characters`
  - `VEM - Host - Variable, ESDS, machine print control codes`
  - `VK - Host - Variable, KSDS`
  - `VKA - Host - Variable, KSDS, ASA print control characters`
  - `VKM - Host - Variable, KSDS, machine print control codes`
  - `VR - Host - Variable, RRDS`
  - `VRA - Host - Variable, RRDS, ASA print control characters`
  - `VRM - Host - Variable, RRDS, machine print control codes`
  - `ORG - Use original record format as default (like none)`
- `NUMBER: RECLENGTH=num - Record length`
- `NUMBER: KEYPOSITION=num - Key position (>=1)`
- `NUMBER: KEYLENGTH=num - Key length (>=1)`
- `NUMBER: DATFMT=NONE/BLOCK/RECORD/ELEMENT - Data format (not required at write)`
  - `NONE - Unknown data format`
  - `BLOCK - Block oriented data`
  - `RECORD - Record oriented data`
  - `ELEMENT - Element oriented data`
- `NUMBER: DATTYP=NONE/BINARY/RECORD/RECTXT/CHAR/TEXT/XML/TABLE - Data type (not required at write)`
  - `NONE - Unknown data type`
  - `BINARY - Binary data (not printable)`
  - `RECORD - Binary record (not printable)`
  - `RECTXT - Text record (printable)`
  - `CHAR - Character data (no delimiter)`
  - `TEXT - Text data (with delimiter)`
  - `XML - XML data (like CHAR)`
  - `TABLE - Table (various elements per record)`
- `NUMBER: MATRIX=NONE/DATBLK/STDREC/STDASAREC/STDMCCREC/RELREC/RELASAREC/RELMCCREC/TXTREC/TXTDLM/TXTRST/XMLELM - Matrix type of the elements list`
  - `NONE - Unknown matrix type`
  - `DATBLK - Simple data block (no attributes)`
  - `STDREC - Simple standard record (no attributes)`
  - `STDASAREC - Standard record with ASA control characters (1 byte) as attributes`
  - `STDMCCREC - Standard record with machine control characters (1 byte) as attributes`
  - `RELREC - Relative record with 8 byte slot number as attribute`
  - `RELASAREC - Relative record with slot number (8 byte) and ASA control character (1 byte) as attribute`
  - `RELMCCREC - Relative record with slot number (8 byte) and machine control character (1 byte) as attribute`
  - `TXTREC - Standard text record (no attributes)`
  - `TXTDLM - Record with text delimiter at the end (no attributes)`
  - `TXTRST - Text records with data and rest element (no attributes)`
  - `XMLELM - XML elements (no attributes)`
- `SWITCH: REDUNDANT - Data is known as redundant`
- `SWITCH: NOTREDUNDANT - Data is known as not redundant`