Enabling client-side caching

By default, records in SFS files are written to and read from the SFS server, and a remote procedure call (RPC) is needed whenever a record is accessed. If you enable client-side caching, however, you can improve performance because less time is needed to access records.

About this task

With client-side caching, records are stored in local memory (a cache) on the client machine and sent (flushed) to the server in a single RPC. You can specify either or both of two types of caching: read caching and insert caching:

  • If you enable read caching, the first sequential read of a file causes the current record and a number of neighboring records to be read from the server and placed in the read cache. Subsequent sequential reads, updates, and deletes are made in the read cache rather than on the server.
  • If you enable insert caching, insert operations (but not reads, updates, or deletes) are done in the insert cache rather than on the server.

To enable client-side caching for all the SFS files in your application, set the ENCINA_VSAM_CACHE environment variable before you run the application. To see a syntax diagram that describes setting ENCINA_VSAM_CACHE, see the related reference about runtime environment variables.

You can code a single value for the cache size to indicate that the same number of pages is to be used for the read cache and for the insert cache, or you can code distinct values for the read and insert cache by separating the values by a colon (:). Express® size units as numbers of pages. If you code zero as the size of the read cache, insert cache, or both, that type of caching is disabled. For example, the following command sets the size of the read cache to 16 pages and the size of the insert cache to 64 pages for each SFS file in the application:

export ENCINA_VSAM_CACHE=16:64

You can also specify one or both of the following flags to make client-side caching more flexible:

  • To allow uncommitted data (records that are new or modified but have not yet been sent to the server, known as dirty records) to be read, specify ALLOW_DIRTY_READS.

    This flag removes the restriction for read caching that the files being accessed must be locked.

  • To allow any inserts to be cached, specify INSERTS_DESPITE_UNIQUE_INDICES.

    This flag removes the restriction for insert caching that all active indices for clustered files and active alternate indices for entry-sequenced and relative files must allow duplicates.

For example, the following command allows maximum flexibility:


To set client-side caching differently for certain files, code a putenv() call that sets ENCINA_VSAM_CACHE before the OPEN statement for each file for which you want to change the caching policy. During a program, the environment-variable settings that you make in a putenv() call take precedence over the environment-variable settings that you make in an export command.

Example: setting and accessing environment variables