SELECTION TO ARRAY

version 3

SELECTION TO ARRAY (aField | aTable; array{; aField2 | aTable2; array2; ...; aFieldN | aTableN; arrayN})

The SELECTION TO ARRAY command creates one or more arrays and copies data in the fields or record numbers from the current selection into the arrays.

The command SELECTION TO ARRAY applies to the selection for the table specified in the first parameter. SELECTION TO ARRAY, can perform the following:

• Load values from one or several fields.

• Load Record numbers using the syntax ...;[table];Array;...

• Load values from related fields, provided that there is a Many to One automatic relation between the tables or provided that you have previously called SET AUTOMATIC RELATIONS to make manual Many to One relations automatic. In both cases, values are loaded from tables through several levels of Many to One relations.

Each array is typed according to the field type. There are two exceptions:

• If a Text field is copied into a String array, the array will remain a String array.

• In ASCII compatibility mode (non-Unicode), if a Time field is copied into a Long Integer array, the array will also remain a String array.

If you load record numbers, they are copied into a Long Integer array.

4D Server: The SELECTION TO ARRAY command is optimized for 4D Server. Each array is created on the server and then sent, in its entirety, to the client machine.

WARNING: The SELECTION TO ARRAY command can create large arrays, depending on the size of the current selection and on the type and size of the data you are loading. Arrays reside in memory, so it is a good idea to test the result after the command is completed. To do so, test the size of each resulting array or cover the call to the command, using an ON ERR CALL project method.

Note: After a call to SELECTION TO ARRAY, the current selection and current record remain the same, but the current record is no longer loaded. If you need to use the values of the fields in the current record, use the LOAD RECORD command after the SELECTION TO ARRAY command.

1. In the following example, the [People] table has an automatic relation to the [Company] table. The two arrays asLastName and asCompanyAddr are sized according to the number of records selected in the [People] table and will contain information from both tables:

   SELECTION TO ARRAY ([People]Last Name;asLastName;[Company]Address;asCompanyAddr)

2. The following example returns the [Clients] record numbers in the array alRecordNumbers and the [Clients]Names field values in the array asNames:

   SELECTION TO ARRAY([Clients];alRecordNumbers;[Clients]Names; asNames)

ARRAY TO SELECTION, MULTI SORT ARRAY, ON ERR CALL, SELECTION RANGE TO ARRAY, SET AUTOMATIC RELATIONS.