4D Doc Center : SELECTION RANGE TO ARRAY

4D v13.4

SELECTION RANGE TO ARRAY


SELECTION RANGE TO ARRAY ( start ; end {; aField \| aTable ; array} {; aField \| aTable2 ; array2 ; ... ; aField \| aTableN ; arrayN} )

Parameter	Type	Description
start	Longint	Selected record number where data retrieval starts
end	Longint	Selected record number where data retrieval ends
aField \| aTable	Field, Table	Field to use for retrieving data or Table to use for retrieving record numbers
array	Array	Array to receive field data or record numbers

Description

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:

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

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

Note: You can call the SELECTION RANGE TO ARRAY command with just the start and end parameters. You use this special syntax to launch, on a limited selection, the execution of a deferred series of SELECTION TO ARRAY commands using the * parameter (see example 4]).

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.

Example 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)

Example 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)

Example 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

Example 4

Use the first 50 current records of the [Invoices] table to load various arrays, in deferred execution:

  // Deferred statements

 SELECTION TO ARRAY([Invoices]InvoiceRef;arrLInvRef;*)

 SELECTION TO ARRAY([Invoices]Date;arrDInvDate;*)

 SELECTION TO ARRAY([Clients]ClientRef;arrLClientRef;*)

  // Execution of deferred statements

 SELECTION RANGE TO ARRAY(1;50)