File services

JCICS provides classes and methods that map to the EXEC CICS API commands for each type of CICS file and index.

For information about tools that allow Java programs to access existing CICS application data, see Interacting with structured data from Java.

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 alternative (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 VSAM data sets: KSDS, ESDS, RRDS for more information about data sets.

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 using the primary index, a KSDS file accessed using a secondary index, and an ESDS file accessed using 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) or Extended Relative Byte Address (XRBA). To use XRBA instead of RBA, issue the setXRBA(true) method.
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 API operations:

A File object is created by the user application explicitly starting the required 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 instantiated for a FileBrowse object to perform the following API operations:

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 API 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() references the read() method in the KeyedFile class.

The first table shows the classes and methods for keyed files:

Table 1. Classes and methods for keyed files
KSDS primary or secondary index class and method	ESDS secondary index class and method	CICS File API 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
KeyedFile.unlock()	KeyedFile.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 class and method	RRDS primary index class and method	CICS File API 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
KeyedFile.unlock()	RRDS.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
ESDS.setXRBA()

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 is released automatically at the end of the program.

You do not need to specify the KEYLENGTH value on any File method; the length used is the actual length of the key passed. When a FileBrowse object is created, it contains the length of the key specified on the startBrowse method, and this length is passed to CICS on subsequent browse requests against that object.

You do not need to provide a REQID for a browse operation; each browse object contains a unique REQID which is automatically used for all subsequent browse requests against that browse object.