FLD(

General Form:

FLD(alpha-variable.field-variable [.fieldvariable ...])
FLD(ptrvar.field-variable [.fieldvariable ...])

Where:

ptrvar = a numeric variable holding a PTR value from NEW or PTROF()

The FLD( function defines a substring within the alpha variable or array to which it is applied. The specifications of the substring, its start byte and length, are held in a special form of variable called a field variable which is distinguished by having a period as its first character.

Field variables can be initialised in records using DEFRECORD and FLD, in LET statements or they can be READ from DATA statements, for example:

DEFRECORD ExampleRec
    FLD lockbyte$1
    FLD description$
END RECORD
.description$ = (2,16)
READ .description$
DATA (2,16)

all define a string field .description$ which starts in byte 2 and is 16 bytes long. The parentheses are required. This field variable can then be applied to any alpha variable provided it is big enough to hold the substring. Thus for the field variable defined above

Result$ = FLD(buffer$.description$)
Result$ = STR(buffer$,2,16)

have the same effect. Using FLD( instead of STR( not only improves the readability of programs, it will also execute faster in most circumstances.

Numeric field variables allow the substring to be considered as a number. The length parameter must give information about how the number is encoded in the string. This can be achieved by specifying a $FORMAT numeric field specification. The length of the field is implied by the image. When used as a numeric expression FLD( will extract the substring and $UNPACK the number. For backward compatibility, numeric fields can also be specified by supplying a PACK image but this usage is now deprecated.

Multiple nested FLD() functions can be replaced by an extended FLD() function as a shortcut. Thus the following are equivalent:

    FLD(FLD(a$.b$).c)
    FLD(a$.b$.c)

The FLD() function can also be used to dereference a pointer to a dynamically allocated object such as a structure. In this case the first argument in the FLD() is not an alpha variable but the numeric handle referencing the object as returned by NEW when it was created or by PTROF(). For example:

DEFSTRUCT myRec
    FLD name$ AS PTR
END STRUCT
pRec = NEW _myRec
REDIM FLD(pRec.name$) = "Peter"

Individual elements of an occurs can be access used an array notation e.g.

DEFRECORD ExampleRec
    FLD n(2)
    FLD description$(2)16
END RECORD
DIM a$_ExampleRec
FLD(a$.n<1>) = 1.5
FLD(a$.n<2>) = 3.4
FLD(a$.decsription$<1>) = "red"
FLD(a$.decsription$<2>) = "cold"

The array index inside the brackets is counted from 1.

The starting position of a field and the size of a field may be found with the POS( and LEN( functions respectively, i.e.

FieldStart = POS(.description$)

FieldLength = LEN(.description$)

The packing format can be found using the PACK( function.

Field variables cannot currently be used as a receiver variable in CALL and DATA LOAD statements.

Note: Using postfix and prefix operators with a numeric field should be avoided as it will have an effect on performance as the field will need to be unpacked, changed and repacked.

Compatibility

The shortcut notation with multiple field specifiers was introduced in KCML 6.20.

Fields using dynamic memory pointers were introduced with KCML 7.00.