File batch read mode

file_id->batch_read = ON | OFF

This property is only relevant if the program is running in client/server mode. It is set at run time, turning batch read mode ON or OFF for the file. The file may be open or closed when the property is set. The default is OFF.

In client/server mode, performance can be improved substantially by reading records from specified keyed files in batches, rather than singly. Setting batch_read to ON is recommended when records are being read sequentially and not locked, or only locked very occasionally. A typical example of a suitable file is the driving file in a report. If used inappropriately, setting batch_read to ON may change the behaviour of an application or may have a negative effect on performance. This would be the case if the records were being read sequentially using a non-locking command and several were then being locked.

The smaller the file record length, the greater the improvement in performance will be, because more records can be stored in each network packet. However, there is still a useful improvement even if the record length exceeds the network packet length, because of the reduction in network handshaking.

If batch_read is turned ON, and the file is open, or is subsequently opened on a server (running the Sculptor server program kfserver | kfservnt), then Sculptor performs a read-ahead operation, obtaining a batch of records or keys from the server, whenever any of the following commands are executed twice consecutively on the same index:

nextu, prevu, nextkey, prevkey

The matchu command also performs a read-ahead, with the previous findu command being treated as the first of the command pair.

If the file is open in read-only mode, the following commands also read-ahead and obtain batches:

next, prev, match

Once a batch of records has been read, all subsequent file access commands which do not lock a record read the required record from the local batch, if it is present there, rather than reading it from the server.

If a command that locks a record is executed and the record is in the batch buffer, the record is re-read from the server and the batch buffer updated. Such commands include read (if the file is open in read-only mode), read[u], readkey and testkey. If the record is subsequently written back, it is sent to the server and the batch buffer is again updated.

See Servers for full details of client/server operations in Sculptor.

Note

Batch file commands are only relevant if the program is running in client/server mode, and are otherwise ignored

Clearing or refreshing the batch buffer

The batch buffer is cleared or refreshed, as appropriate, when one of the following conditions occurs:

1

An insert or delete command is executed on any record in the file.

2

A record that is not currently in the batch buffer is read.

3

A write command is executed, causing an update to the index used to sequence the records in the batch buffer.

4

A read command is executed, using a different index from the one used to sequence the records in the batch buffer.

5

An incompatible command is executed. This might be a request for a record when the batch buffer contains only keys, or might be a next | prev type command when the buffer contains a record set generated by find[u] and match[u].

6

The programmer explicitly clears the batch buffer by use of the clearbatch command.

7

The batch_read property is turned OFF.

8

The file is closed.

Batch buffer memory

The memory for a batch buffer is allocated when the file is open and the batch_read property is ON. If the batch_read property is turned OFF or the file is closed, the memory is released.

Sculptor calculates an optimum size for the batch buffer, based on the record length, the network packet size, and a maximum size beyond which there is no significant improvement in performance. All memory overhead is on the client side, not the server.

Examples of buffer size and number of records per batch:

Record length

Buffer size (approx)

Records per batch

64 bytes

1.5K

21

1024 bytes

12K

11

Programmers should be aware that certain sections of code may not work as intended when the batch read feature is enabled. Here is an example:

!temp Handle,,i4

     Names->batch_read = ON
     nextu Names
     nextu Names
     while (Names.flag = FALSE) {
          readu Names
          sleep 2
     }

The readu command will continue to read the same record from the batch buffer, and will be unaware if another process updates the record.

ODBC

In an ODBC database, setting batch_read to ON causes Sculptor to use a cursor type that fetches records in batches, provided that such a cursor type is supported by the database in use. Leaving batch_read OFF improves the compatibility between ODBC tables and Sculptor files, but performance can be improved substantially by turning it ON when appropriate.

See Reading records in batches (ODBC) for details.

RELATED TOPICS

Keyed files