# Array

> [HTML Version](array_xtree.htm)

In array mode (i.e. when the _file_ parameter is empty) the _array_ parameter supplies the contents to be loaded into the XTREE grid. It may be specified in the form of an array of fixed length strings, whose layout is determined by the coldef parameter, or as [gridmap](gridmaps.htm.md); see History below. 

For the array case, you may either specify an explicit starting element (e.g. ARRAY(1)) or an unformatted variable under which the array is defined (ARRAYX in the example below). Note that you can use DIMX to dynamically allocate the array (either a simple array or a [Dynamic Array of Structures](dynamicarrayofstructures.htm.md)), in which case you have to pass it to XTREE via the starting element.

MAP1 ARRAYX               \! unformatted variable

   MAP2 ARRAY(50),S,100



Each array element must have at least one trailing null byte. Note that by using the overlay feature, you could support several array layouts with the same XTREE statement, i.e.

MAP1 ARRAYX2,@ARRAYX      \! overlay on ARRAYX above

   MAP2 ARRAY2(10),S,60   \! array of ten sixty byte strings

MAP1 ARRAYX3,@ARRAYX      \! yet another overlay

   MAP2 ARRAY3(80),S,8    \! array of eighty 8 byte strings



Any text in an individual cell (in array mode) or line (in file mode) which follows a backslash ("\\") will be hidden from view (unless the _cformat_ \\ switch is specified).

In single-selection **file** mode, the _array_ parameter is interpreted as an ordinary string to return the text of the selected items (all columns, but with right-justified columns stripped of trailing blanks.) If the XTF\_FILANS flag is set, then array is ignored on entry; otherwise it should contain the text of the item to initially select, as returned from the prior call. In CSV mode (see [XTF2\_CSV](xtf2_csv.htm.md)), although the return string will contain all the columns (comma-delimited), on entry only the first column is used for locating the initially selected item. If you need more precision than that, use the XTF\_FILANS flag/method.

In multiple-selection **file** mode, the _array_ parameter is ignored. The selection information is passed via the array of one byte flags in the _answer_ parameter, just as in multiple-selection **array** mode.

For the [gridmap](gridmaps.htm.md) case, specify the gridmap name with an empty pair of parens, e.g. 

xcall XTREE, sr, sc, answer, \$grid(), count, exitcode, er, ec, flags...

Either form of gridmap is accepted, although the handling is somewhat different for the two types. In the case of _gridmap(int;varstr;varstr)_, the handling is analogous to CSV mode except without a file. This is more memory efficient but doesn't support AutoFilter. 

In the case of _gridmap(int;int;varstr)_, the grid data is expanded out to an array using column widths based on the actual maximum lengths of the data. 

In either case, the operation is limited to display and select only; no editing. The application may specify an empty, partial (pseudo columns only), or full _coldef_. In the empty or partial case, the column headers are extracted from the gridmap—row 1 in the _int;int;varstr_ case). If the app supplies a _coldef_ with any real columns defined, the column names from the gridmap are ignored, and it is up to the app to make sure that the _coldef_ supplied actually matches the layout of the data.

**History**

2023 September, A-Shell 6.5.1742:  The tree data _array_ argument may now be supplied in the form of a gridmap.

**Subtopics**

- [Array Descriptors](arraydescriptors.htm.md)