FIELD strings

Field strings are a special form of dynamic string, which have all the capabilities of a dynamic string, but may also represent a defined part of a random file buffer or a defined part of a dynamic string.

Field strings must always be declared using DIM, INSTANCE, LOCAL, STATIC, GLOBAL, or THREADED.  They may be used in the same manner as a dynamic string variable, or they can be bound to a file buffer for an open random-access file or a dynamic string using a corresponding FIELD statement.  Each field string occupies sixteen bytes of memory, and requires slightly more general overhead than a regular dynamic string variable.  As with other strings, FIELD variables may be declared as either ANSI characters (FIELD) or wide, Unicode characters (WFIELD).

When used with a file

A random-access file buffer is automatically created for use when GET or PUT statements are used without a target variable.  In this case, the file data is read or written using this file buffer, and the buffer is accessed with one or more field strings.

If a field is defined by a single field (nSize) parameter, it represents the length of the field, with the start position implied by the preceding field within the statement.  If two parameters are used, they represent the start (nStart) and end (nEnd) positions, indexed to one.

If a string value shorter than the declared size is assigned to a field string, it is padded with blank spaces and placed into the file buffer.  There is no requirement to use LSET for assignment.  When used with a file buffer, the field string is only valid when the nominated file is open.  Once the file has been closed, field strings bound to the file buffer will be empty (zero length), rather than a string of the length defined in the FIELD statement.  For example:

LOCAL fld1, fld2, fld3 AS FIELD

OPEN "test.dat" FOR RANDOM AS #1 LEN = 30

FIELD #1, 5 AS fld1, 10 AS fld2, 15 AS fld3

fld1 = "Bob"       ' Stores "Bob  "

CSET fld2 = "Zale" ' Stores "   Zale   "

RSET fld3 = "#1"   ' Stores "             #1"

? STR$(LEN(fld1))  ' Displays 5

? STR$(LEN(fld2))  ' Displays 10

? STR$(LEN(fld3))  ' Displays 15

CLOSE #1

? STR$(LEN(fld1))  ' Displays 0

When used with a dynamic string

A field variable bound to a dynamic string works very much like a pointer, so the programmer must use care in field variable selection.  For example, if you bind a GLOBAL FIELD variable to a LOCAL string variable, then attempt to reference the global string after the local is destroyed (i.e., released when the owning Sub/Function/Method/Property exits), a fatal exception error (GPF) is likely to occur.  The same could happen after an array has been erased, or a REDIM is used to change the memory allocation.  To avoid problems with scope, it is suggested that field variables be bound only with strings within the same scope (LOCAL, GLOBAL, etc.).

In addition, the dynamic string must contain data for the bound field strings to reference the data.  For example:

LOCAL x$, sFirst AS FIELD, sSecond AS FIELD

FIELD x$, 3 AS sFirst, 3 AS sSecond

x$ = ""

? STR$(LEN(sFirst))  ' Displays 0 since x$ is empty

x$ = SPACE$(6)       ' Allocate data to the string

sFirst = "111"

sSecond = "222"

? STR$(LEN(sFirst))  ' Displays 3 as x$ now contains data

Field strings and dynamic strings cannot be part of UDT (User-Defined Type) or UNION structures.

See Also

Nul-Terminated Strings

Dynamic (Variable-length) strings ($)

Fixed-length strings

String expressions