NAME

field - allocate space for variables in random file buffer

SYNOPSIS

field [#]FileNum, Width as StrVar[, Width as StrVar]... 

DESCRIPTION

The field statement is used to extract data from a packed file record read by get into variables that can be accessed at program level.  Specifically, it declares an association between file record fields and string variables that causes each string variable to reference data from its related field, each time a record is read by get

FileNum is the number under which the file was opened.  Width is a numeric expression that specifies the width of the record field to be associated with StrVar.  StrVar is a string variable that will reference the unpacked field.  Successive width+variable pairs map the file record fields, in sequence, into associated string variables. 

For example, the statement

	field 1, 15 as a$, 10 as b$, 20 as c$
defines a mapping between three file record fields and three string variables that maps the first 15 characters of the record into a$, the next 10 characters into b$, and the next 20 characters into c$.  This mapping is in effect for records read on file number 1. 

Note - Field does not move any data into or out of the random file buffer used by get.  It only changes the internal definitions for the StrVar arguments so that they reference the buffer locations for the associated fields.  This association is broken by using a fielded variable on the left hand side of an equal sign in a subsequent input or let statement, as this moves the variable to string space and it no longer points to the file buffer. 

Multiple field statements may be executed for the same file number.  Each of them is in effect simultaneously and each one defines a field mapping starting from the beginning of the record.  This may be used to obtain multiple field definitions for the same data. 

EXAMPLE

The program
	   open "R", 1, "addrph", 40
	   field #1, 12 as phone$
	30 rset phone$ = a$
	40 put #1
	   close #1
opens a file named addrph as a random file.  The variable phone$ is assigned to the first 12 positions in each record.  Line 30 puts information into the buffer, and the put statement in line 40 writes the buffer to the file. 

SEE ALSO

lset, put, rset

DIAGNOSTICS

A "Field overflow" error occurs if the total number of bytes allocated in a field statement exceeds the record length given when the file was opened. 

A "Bad file number" error occurs if FileNum is less than 1 or greater than the maximum number of files permitted or if FileNum is not open. 

If FileNum is a random access file, a "Bad file mode" error occurs. 

If Width is less than 0, an "Illegal function call" error occurs. 

from The Basmark QuickBASIC Programmerís Manual by Lawrence Leinweber