|
Purpose |
Bind a field string variable to a random file buffer or a dynamic string variable. |
|
Syntax |
FIELD # filenum,
nSize AS fieldvar,
[FROM] nStart TO nEnd
AS fieldvar [, ...] |
|
Remarks |
A field variable is a special form of
By default, a field variable mimics a dynamic string variable, and may be considered a virtual replacement. Then, at any time, the FIELD statement can be used to declare that the field variable now refers to a specific portion of a random file buffer or a dynamic string. FIELD RESET is used to change it back to a nul (zero-length) dynamic string. FIELD STRING also changes it back to a dynamic string, but first assigns the current sub-section data to it. This last action is particularly useful in the case where the sub-section data might be lost when the bound random file is closed. In the first form, FIELD binds a field string variable to a specific sub-section of a random-access file buffer. In the second form, FIELD binds a field string variable to a specific sub-section of a dynamic string variable .If the sub-section extends beyond the actual size of the file buffer or string, that portion of the FIELD is empty. Otherwise, it represents a fixed size string, and may be referenced as any other string variable. When used with a file: A random-access file buffer is automatically created for use when GET or PUT are used without a target variable. In this case, the file data is read or written using this buffer, which is accessed with one or many field variables. If a field is defined by a single field (size) 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 as it is placed into the file buffer. There is no requirement to use LSET for assignment. Finally, it should be noted that FIELD statements are tied to an open file, i.e. they are valid only as long as the file is open. Once the file is closed, any field strings that had been defined for the file will return nul (empty), not a string of the previously specified length. LOCAL sFirst AS FIELD, sSecond AS FIELD OPEN "ABC.TXT" FOR RANDOM AS #1 LEN=20 FIELD #1, 10 AS sFirst, 10 AS sSecond sFirst = "0123456789" sSecond = "9876543210" Put #1 ' creates a record of: 01234567899876543210 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.). LOCAL x$, sFirst AS FIELD, sSecond AS FIELD FIELD x$, 3 AS sFirst, 3 AS sSecond x$ = SPACE$(6) ' Allocate the space for the field SFirst = "111" sSecond = "222" ? x$ ' Displays 111222 x$ = "abcd" ? sFirst ' Displays abc ? sSecond ' Displays d |
|
Restrictions |
Field string variables must be explicitly declared using DIM, INSTANCE, LOCAL, STATIC, GLOBAL, or THREADED. Attempting to bind a variable other than a declared field variable results in a compile-time Error 544 ("Field variable expected"). Field strings cannot be used in UDT or UNION structures. Attempting to do so results in a compile-time Error 485 ("Dynamic/Field strings not allowed"). |
|
See also |
Field Strings, GET, PUT, TYPE/END TYPE, User-Defined Types, Unions, UNION/END UNION |