HELP: Default format for variable length data fields [PFLGLENPTR] TYPE: NUMBER SYNTAX: VARFMT=PLENPTR/ALENPTR/PPTRLEN/APTRLEN/PFLGLENPTR/PPTRLENFLG
The format for variable length data allows to write the length and a pointer to the value instead of the value itself to your data stream/ structure. This is useful to reduce memory utilization for variable length data. The pointer is in native/usable format (incl. bit width) and valid up to the next read operation. When writing, the data the pointer points to is copied and the data needs to only be valid for the duration of this operation.
On a 32 bit system, the pointer requires 4 bytes. On a 64 bit system, the pointer requires 8 bytes. The length is always a 32 bit unsigned integer in local endianness.
It is mandatory to specify the field order of length and pointer and padding (if applicable). The field order can be set to length-pointer or pointer-length. It is also possible to pad the fields so that they can be directly written to C structs, which are stored unpacked by default (i.e. fields are aligned to offsets that are a multiple of the field's length). Both can be controlled by setting the METHOD to one of:
The example below shows a type definition in C for a few tables as union. To read from or write to them, the APTRLEN format must be used.
typedef struct PtrLen {
uint8_t* pcDat;
uint32_t uiLen;
} TsPtrLen;
typedef struct Row42 {
TsPtrLen asCol[42];
} TsRow42;
typedef struct Row07 {
TsPtrLen asCol[ 7];
} TsRow07;
typedef struct Row13 {
TsPtrLen asCol[13];
} TsRow13;
typedef union Tables {
TsRow42 stRow42;
TsRow07 stRow07;
TsRow13 stRow13;
} TuTables;
int main() {
TuTables unMyTables;
uint32_t uiLen=unMyTable.stRow07.asCol[0].uiLen;
uint8_t* pcDat=unMyTable.stRow07.asCol[0].pcDat;
}
When writing to memory, the space for the data is allocated and managed by FLAM. When reading from memory, the application must provide the pointer and is responsible for it. The length of a length-pointer pair is determined by the system's architecture (32/64 bit) and selected METHOD (8, 12 or 16 bytes). Therefore it does not have to be provided.
For example, in COBOL the packed form (PLENPTR/PPTRLEN) and for C the aligned form (ALENPTR/APTRLEN) must be used to be in sync with the structures of these programming languages. If you need alignment of these length-pointer pairs in a complex structure, the normal alignment for the whole element can be used.
To determine null/empty indication and other additional information, a flag, length and pointer format can be used. The 32 bit flag word, contains the null indication bit as least significant bit of the high order half word (FLMELM_TYPTAB_FLAG_NULLID). No other flag bits are defined, yet.
PLENPTR - Buffer length as 32 bit (system endian) integer followed by pointer in architecture-specific length; no padding (packed) (8/12 bytes on 32/64 bit systems)ALENPTR - Buffer length as 32 bit (system endian) integer followed by pointer in architecture-specific length; with memory alignment (unpacked) (8/16 bytes on 32/64 bit systems)PPTRLEN - Pointer in architecture-specific length followed by buffer length as 32 bit (system endian) integer; no padding (packed) (8/12 bytes on 32/64 bit systems)APTRLEN - Pointer in architecture-specific length followed by buffer length as 32 bit (system endian) integer; with memory alignment (unpacked) (8/12 bytes on 32/64 bit systems)PFLGLENPTR - 32 bit flag word (system endian), buffer length as 32 bit (system endian) integer followed by pointer in architecture-specific length (12/16 bytes on 32/64 bit systems)PPTRLENFLG - Pointer in architecture-specific length, buffer length as 32 bit (system endian) integer followed by 32 bit flag word (system endian) (12/16 bytes on 32/64 bit systems)