A DataWindow data expression can return a large amount of data.
Single row and column When your data expression refers to a single row and column, you can assign the data to a variable whose data matches the column’s datatype. When the expression refers to a single column but can refer to multiple rows, you must specify an array of the appropriate datatype.
More than one column When the expression refers to more than one column, you can get or set the data with a structure or user object. When you create the definition, you must assign datatypes to the fields (in a structure) or instance variables (in a user object) that match the datatypes of the columns. When your expression refers to multiple rows, you get an array of the structure or user object.
Likewise, if you want to set data in the DataWindow control, you will set up the data in structures or user objects whose elements match the columns referred to in the expression. An array of those structures or user objects will provide data for multiple rows.
Datatypes For matching purposes, the datatypes should be appropriate to the data—for example, any numeric datatype matches any other numeric type.
The following table presents some examples of data specified by an expression and the type of data structures you might define for storing the data:
Type of selection |
Sample data storage |
|---|---|
A single item |
A single variable of the appropriate datatype. |
A column of values |
An array of the appropriate datatype. |
A row |
A structure whose elements have datatypes that match the DataWindow object’s columns. A user object whose instance variables match the DataWindow object’s columns. |
Selected rows or all rows |
An array of the structure or user object defined for a row. |
A block of values |
An array of structures or user objects whose elements or instance variables match the columns included in the selected range. |
When a data expression is assigned to an array, values are assigned beginning with array element 1 regardless of the starting row number. If the array is larger than the number of rows accessed, elements beyond that number are unchanged. If it is smaller, a variable-size array will grow to hold the new values. However, a fixed-size array that is too small for the number of rows will cause an execution error.
Two ways to instantiate user objects
A user object needs to be instantiated before it is used.
One way is to use the CREATE statement after you declare the user object. If you declare an array of the user object, you must use CREATE for each array element.
The second way is to select the Autoinstantiate box for the user object in the User Object painter. When you declare the user object in a script, the user object will be automatically instantiated, like a structure.
The actual datatype of a DataWindow data expression is Any, which allows the compiler to process the expression even though the final datatype is unknown. When data is accessed at runtime, you can assign the result to another Any variable or to a variable, structure, or user object whose datatype matches the real data.
A single value This example gets a value from column 2, whose datatype is string:
string ls_name
ls_name = dw_1.Object.Data[1,2]
A structure that matches DataWindow columns In this example, a DataWindow object has four columns:
An ID (number)
A name (string)
A retired status (boolean)
A birth date (date)
A structure to hold these values has been defined in the Structure painter. It is named str_empdata and has four elements whose datatypes are integer, string, boolean, and date. To store the values of an expression that accesses some or all the rows, you need an array of str_empdata structures to hold the data:
str_empdata lstr_currdata[]
lstr_currdata = dw_1.Object.Data
After this example executes, the upper bound of the array of structures, which is variable-size, is equal to the number of rows in the DataWindow control.
A user object that matches DataWindow columns If the preceding example involved a user object instead of a structure, then a user object defined in the User Object painter, called uo_empdata, would have four instance variables, defined in the same order as the DataWindow columns:
integer id
string name
boolean retired
date birthdate
Before accessing three rows, three array elements of the user object have been created (you could use a FOR NEXT loop for this). The user object was not defined with Autoinstantiate enabled:
uo_empdata luo_empdata[3]
luo_empdata[1] = CREATE uo_empdata
luo_empdata[2] = CREATE uo_empdata
luo_empdata[3] = CREATE uo_empdata
luo_empdata = dw_1.Object.Data[1,1,3,4]
