File services

CICS supports the following types of files:
  • Key Sequenced Data Sets (KSDS)
  • Entry Sequenced Data Sets (ESDS)
  • Relative Record Data Sets (RRDS)

KSDS and ESDS files can have alternate (or secondary) indexes. (CICS does not support access to an RRDS file through a secondary index.) Secondary indexes are treated by CICS as though they were separate KSDS files in their own right, which means they have separate FD entries.

There are a few differences between accessing KSDS, ESDS (primary index), and ESDS (secondary index) files, which means that you cannot always use a common interface.

Records can be read, updated, deleted, and browsed in all types of file, with the exception that records cannot be deleted from an ESDS file.

See the CICS® Application Programming Guide for more information about datasets.

Java commands that read data support only the equivalent of the SET option on EXEC CICS commands. The data returned is automatically copied from CICS storage to a Java object.

The Java interfaces relating to File Control are in five categories:
File
The superclass for the other file classes; contains methods common to all file classes.
KeyedFile
Contains the interfaces common to a KSDS file accessed through the primary index, a KSDS file accessed through a secondary index, and an ESDS file accessed through a secondary index.
KSDS
Contains the interface specific to KSDS files.
ESDS
Contains the interface specific to ESDS files accessed through Relative Byte Address (RBA—its primary index).
RRDS
Contains the interface specific to RRDS files accessed through Relative Record Number (RRN—its primary index).
For each file, there are two objects that can be operated on—the File object and the FileBrowse object. The File object represents the file itself and can be used with methods to perform the following operations:
  • DELETE
  • READ
  • REWRITE
  • UNLOCK
  • WRITE
  • STARTBR
A File object is created by the user application explicitly instantiating the desired file class. The FileBrowse object represents a browse operation on a file. (There can be more than one active browse against a specific file at any time, each browse being distinguished by a REQID.) Methods can be invoked against a file browse object to perform the following operations:
  • ENDBR
  • READNEXT
  • READPREV
  • RESETBR

A FileBrowse object is not instantiated explicitly by the user application; it is created and returned to the user class by the methods that perform the STARTBR operation.

The following tables show how the JCICS classes and methods map to the EXEC CICS commands for each type of CICS file (and index). In these tables, the JCICS classes and methods are shown in the form class.method(). For example, KeyedFile.read() refers to the read() method in the KeyedFile class.

This table shows the classes and methods for keyed files:
KSDS primary or secondary index ESDS secondary index CICS File command
KeyedFile.read() KeyedFile.read() READ
KeyedFile.readForUpdate() KeyedFile.readForUpdate() READ UPDATE
KeyedFile.readGeneric() KeyedFile.readGeneric() READ GENERIC
KeyedFile.rewrite() KeyedFile.rewrite() REWRITE
KSDS.write() KSDS.write() WRITE
KSDS.delete()   DELETE
KSDS.deleteGeneric()   DELETE GENERIC
File.unlock() File.unlock() UNLOCK
KeyedFile.startBrowse() KeyedFile.startBrowse() START BROWSE
KeyedFile.startGenericBrowse() KeyedFile.startGenericBrowse() START BROWSE GENERIC
KeyedFileBrowse.next() KeyedFileBrowse.next() READNEXT
KeyedFileBrowse.previous() KeyedFileBrowse.previous() READPREV
KeyedFileBrowse.reset() KeyedFileBrowse.reset() RESET BROWSE
FileBrowse.end() FileBrowse.end() END BROWSE
This table shows the classes and methods for non-keyed files. ESDS and RRDS are accessed by their primary indexes:
ESDS primary index RRDS primary index CICS File command
ESDS.read() RRDS.read() READ
ESDS.readForUpdate() RRDS.readForUpdate() READ UPDATE
ESDS.rewrite() RRDS.rewrite() REWRITE
ESDS.write() RRDS.write() WRITE
  RRDS.delete() DELETE
File.unlock() File.unlock() UNLOCK
ESDS.startBrowse() RRDS.startBrowse() START BROWSE
ESDS_Browse.next() RRDS_Browse.next() READNEXT
ESDS_Browse.previous() RRDS_Browse.previous() READPREV
ESDS_Browse.reset() RRDS_Browse.reset() RESET BROWSE
FileBrowse.end() FileBrowse.end() END BROWSE

Data to be written to a file must be in a Java byte array.

Data is read from a file into a RecordHolder object; the storage is provided by CICS and will be automatically released at the end of the program.

The KEYLENGTH does not need to be explicitly specified on any File method; the length used will be the actual length of the key passed. When a FileBrowse object is created, it contains the keylength of the key specified on the startBrowse method, and this length is passed to CICS on subsequent browse requests against that object.

It is not necessary for the user to provide a REQID for a browse operation; each browse object will contain a unique REQID which is automatically used for all subsequent browse requests against that browse object.