The steps to implement batching in the server include:

  1. Set the BATCH-SIZE attribute for the temp-table.
  2. Set the RESTART-ROWID attribute for the data-source.
  3. FILL the temp-table using the FILL( ) method.
  4. Return the NEXT-ROWID attribute and the dataset to the client.

By default, the FILL operation on a dataset retrieves all available records for all temp-tables in a single batch. To change this default behavior, you assign a value to the BATCH-SIZE for one or more temp-tables. In addition, ensure that the server code uses the NEXT-ROWID and RESTART-ROWID of the data-source for a temp-table to specify where in the batch the next retrieval should begin.

The BATCH-SIZE attribute

BATCH-SIZE is the maximum number of temp-table rows to be retrieved in each FILL operation. The default value of the BATCH-SIZE attribute is 0 (zero). This instructs the dataset to retrieve all rows that satisfy the associated query.

To change the value of the BATCH-SIZE attribute, set the BATCH-SIZE attribute for one or more temp-tables.

How BATCH-SIZE works with table relations

Consider the situation where you have two temp-tables in a dataset and you defined one temp-table as a child of the other. If you specify a batch size for the child table, the batch size is used for each set of child records that are retrieved for each parent record. The AVM restarts the BATCH-SIZE counter for each parent record as you scroll through the parent records.

The NEXT-ROWID attribute

NEXT-ROWID is an attribute of the data-source of the temp-table. After a FILL operation, this attribute contains the ROWID value for the next record of a database table when the FILL does not retrieve all the records in the database table. The server-side code must obtain this value after a FILL operation and return it to the client.

The RESTART-ROWID attribute

RESTART-ROWID is an attribute of the data-source of a temp-table. Before a FILL operation, this attribute must be set so that the batch retrieval from the database table begins from a specific row.

Server-side code for batching of data

The following example is the fetchOrders.p code used to retrieve a batch of data. If rowRestart is unknown, the FILL begins with the beginning of the database table. Otherwise, the RESTART-ROWID attribute is set for the data-source of the temp-table using the rowRestart parameter. The BATCH-SIZE attribute is set for the temp-table using the batchSize parameter. Once these attributes are set, the FILL operation is called and the appropriate number of records are added to the temp-table. If the FILL operation encounters the end of the database table, then it sets the temp-table's LAST-BATCH attribute to TRUE. Finally, the code must update the rowRestart value to the NEXT-ROWID of the data-source of the temp-table, as this value must be returned to the client.

/* fetchOrders.p */

{include/dsOrder.i}

DEFINE DATA-SOURCE srcOrder FOR Order.
DEFINE INPUT PARAMETER batchSize AS INTEGER NO-UNDO.
DEFINE INPUT-OUTPUT PARAMETER rowRestart AS ROWID NO-UNDO.
DEFINE OUTPUT PARAMETER DATASET FOR dsOrder.

BUFFER ttOrder:ATTACH-DATA-SOURCE(DATA-SOURCE srcOrder:HANDLE).

/* Set the RESTART-ROWID using the rowid passed back from server. */
IF rowRestart NE ? THEN
 DATA-SOURCE srcOrder:RESTART-ROWID = rowRestart.
 
/* Set the batch size. */
BUFFER ttOrder:BATCH-SIZE = batchSize.

/* Set FILL-MODE to EMPTY. */
IF THIS-PROCEDURE:PERSISTENT THEN
 BUFFER ttOrder:FILL-MODE = "EMPTY".
 
/* Fill the dataset using the settings applied above. */
DATASET dsOrder:FILL().

/* Get the NEXT-ROWID from the DATA-SOURCE to be passed back here
   again for the fetch of a subsequent batch. */
rowRestart = DATA-SOURCE srcOrder:NEXT-ROWID.
BUFFER ttOrder:DETACH-DATA-SOURCE().

RETURN.