SELECTION RANGE TO ARRAY

version 3.5.3

SELECTION RANGE TO ARRAY (start; end; field | table; array{; field2 | table2; array2; ...; fieldN | tableN; arrayN})

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

Unlike SELECTION TO ARRAY, which applies to the current selection in its entirety, SELECTION RANGE TO ARRAY only applies to the range of selected records specified by the parameters start and end.

The command expects you to pass in start and end the selected record numbers complying with the formula 1 <= start <= end <= Records in selection ([...]).

If you pass 1 <= start = end < Records in selection ([...]), you will load fields or get the record number from the record whose selected record is start = end.

If you pass incorrect selected record numbers, the command does the following:

• If end > Records in selection ([...]), it returns values from the selected record specified by start to the last selected record.

• If start > end, it returns values from the record whose selected record is start only.

• If both parameters are inconsistent with the size of the selection, it returns empty arrays.

Like SELECTION TO ARRAY, the SELECTION RANGE TO ARRAY command applies to the selection for the table specified in the first parameter.

Also like SELECTION TO ARRAY, SELECTION RANGE 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, if there is a Many to One automatic relation between the tables or if you have previously called SET AUTOMATIC RELATIONS to change manual Many to One relations to automatic. In both cases, values can be 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. In this case, the array will remain a String array.

• A Time field is copied into a Long Integer array.

Note: You cannot specify Subtable fields or subfields.

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

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

WARNING: SELECTION RANGE TO ARRAY can create large arrays, depending on the range you specify in start and end, 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.

If the command is successful, the size of each resulting array is equal to (end-start)+1, except if the end parameter exceeded the number of records in the selection. In such a case, each resulting array contains (Records in selection([...])-start)+1 elements.

1. The following code addresses the first 50 records from the current selection for the [Invoices] table. It loads the values from the [Invoices]Invoice ID field and the [Customers]Customer ID related field.

   SELECTION RANGE TO ARRAY(1;50;[Invoices]Invoice ID;alInvoID;[Customers]Customer ID;alCustID)

2. The following code addresses the last 50 records from the current selection for the [Invoices] table. It loads the record numbers of the [Invoices] records as well as those of the [Customers] related records:

   lSelSize := Records in selection ([Invoices])
   SELECTION RANGE TO ARRAY (lSelSize-49;lSelSize;[Invoices];alInvRecN;[Customers];alCustRecN)

3. The following code process, in sequential "chunks"of 1000 records, a large selection that could not be downloaded in its entirety into arrays:

   lMaxPage := 1000
   lSelSize := Records in selection ([Phone Directory])
   For ($lPage ; 1; 1+((lSelSize-1)\lMaxPage) )
         ` Load the values and/or record numbers
      SELECTION RANGE TO ARRAY (1+(lMaxPage*($lPage-1));lMaxPage*$lPage;...;...;...;...;...;...)
         ` Do something with the arrays
   End for

ON ERR CALL, SELECTION TO ARRAY, SET AUTOMATIC RELATIONS.