To populate variables and arrays with pre-defined constants.
Restore [label] Read k1[,k2,k3,...] Data k1[,k2,k3,...]
_Data = x% x% = _Data
| label | : user defined label |
| k1, k2,k3... | : numerical and/or string literals |
| x% | : integer |
By using Data statements, it is possible to read in pre-defined numerical, date and string values into variables or arrays in an economical fashion.
The data itself is stored in statements prefaced with the Data command, and this is read into the desired variables by using the Read command, as shown below:
Local a%(2)
Read a%(0), a%(1), a%(2)
Print a%(0), a%(1), a%(2)
Data 1,2,3
Data is added to a data statement separated by commas, and different types of variable types are added in the following way:
Hence, a data statement could look like this:
Data 1,1.456,%1010,$FF,&O12,String,"Another string","String, with a comma","#09/10/1980#","#Null#"
// Integer, Decimal, Integer in Binary, ...in Hex, ...in Octal, String, String, String, Date, Null
When a program is run which contains a data statement, an internal data pointer is set to the first item of data within the whole program. When that item of data is read from a Data statement, the internal data counter is incremented so that the Read command knows the position of the next data item to be read in. The value (or position) of this data pointer can be retrieved using the _Data function like so:
Local a$(2), n%
Print , _Data // Prints the initial position of the data pointer
For n% = 0 To 2
Read a$(n%)
Print a$(n%), // Shows the read data...
Print _Data // ...and the position of the next item of data
Next n%
Data "Record 1","Record 2","Record 3"
_Data can also be used as a command to set the position of the data pointer like this:
Dim a%, dp%(10), n%
For n% = 1 To 10
dp%(n%) = _Data // Store the data pointer
Read a% // Use Read to move the pointer along
Next n%
For n% = 10 DownTo 1 // Run backwards through dp%()...
_Data = dp%(n%) // ...and set the pointer so that...
Read a% : Print a% // ...the data is read backwards
Next n%
Data 1,2,3,4,5,6,7,8,9,10
Generally, data in statements will be grouped together in memory and so, if you know the start position of the first item, you can work out the position of others. To illustrate this: in the last example, all the data was an integer lower than 65536 and thus was stored as a 16-bit integer. With this knowledge, the above example could be shortened to this:
Dim a%, dp%, n%
// Set dp% to the last 16-bit integer which means moving...
// ... past 9 other 16-bit or 2-byte values
dp% = _Data + (9 * 2)
// Now read through the data, decreasing the data pointer by...
// ...2 for each 16-bit integer
For n% = 1 To 10
_Data = dp% : Sub dp%, 2
Read a% : Print a%
Next n%
Data 1,2,3,4,5,6,7,8,9,10
When the Read command has read the last data item in a program, then _Data is set to zero. In this way, it is possible to determine whether the last item has been read, as in the next example:
Local a As Variant
While _Data
Read a : Print a
Wend
Data 1,1.456,%1010,$FF,&O12,String,"Another string"
Data "String, with a comma","#09/10/1980#","#Null#"
Where there are numerous different blocks of data to be read in, it is possible that the data to be passed to a specific variable or array is not the first in the list. In this case, the data pointer can be repositioned using the Restore command. If used with a label, then the data pointer is moved to first data item after that label (the label must be in the same procedure as the Restore command); however, if no label is used, the pointer is moved back to the first item of data in the program listing.
Local a(3) As Variant, b$(3), n%
Restore variants // Jump to the last data group to read in variant values
For n = 0 To 3 : Read a(n%) : Print a(n%) : Next n%
Restore // Place data pointer back at start to read strings.
For n = 0 To 2 : Read b$(n%) : Print b$(n%) : Next n%
strings:
Data "String1",String2,String3
integers:
Data 1,2,3,4,5
variants:
Data "#Null#",String,5,5.6
NOTE: Data statements are NOT procedure-specific but can be read from anywhere within the program; hence if you Read more items than are in the Data statements in the current procedure, the data pointer will move to the next Data statement it finds and continue to read from there until there are none further, when an error will be thrown. In addition, if a Restore command is not used, the data pointer starts from the first data statement it finds in the program listing, regardless of whether it is in the current procedure. This behaviour is possibly a throwback and/or compatibility measure to when procedures where not so 'stand alone'. The following examples illustrates this behaviour:
DataRead2 // Reads 8 items of data from DataRead1
DataRead1 // Reads the remaining 2 items of data from DataRead1 and then the first 6 from DataRead2
Procedure DataRead1
Local n%, a$
For n% = 1 To 8 : Read a$ : Print a$; " "; : Next n% : Print
Data A,B,C,D,E,F,G,H,I,J
EndProcedure
Procedure DataRead2
Restore
Local n%, a$
For n% = 1 To 8 : Read a$ : Print a$; " "; : Next n% : Print
Data K,L,M,N,O,P,Q,R,S,T
EndProcedure
Another way to initialize an array is by using the Array()= command. This command doesn't require Data lines, but instead assigns data as part of a string.
{Created by Sjouke Hamstra; Last updated: 17/05/2017 by James Gaite}