File services (Java)

The EXEC CICS commands for each type of CICS® file (and index) can be mapped to the CICS Java™ classes and methods.

CICS supports the following file types:
  • Key sequenced data set (KSDS)
  • Entry sequenced data set (ESDS)
  • Relative record data set (RRDS)

In addition, KSDS and ESDS files can have alternate (or secondary) indexes, which CICS treats as though they are separate KSDS files (they have separate FD entries). However, the differences among KSDS, ESDS (primary index) and ESDS (secondary index) accessing mean that they cannot always use a common interface. CICS does not support the accessing of an RRDS file through a secondary index. 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.

The Java interfaces that relate to file control separate into five categories:
File
Contains methods that are common to all file types (the superclass for the other file types).
KeyedFile
Contains the interfaces that are common to a KSDS file that is accessed by use of the primary index, a KSDS file that is accessed by use of a secondary index, and an ESDS file that is accessed by use of a secondary index.
KSDS
Contains the interface that is specific to KSDS files.
ESDS
Contains the interface that is specific to ESDS files that are accessed by use of a relative byte address (RBA).
RRDS
Contains the interface that is specific to RRDS files that are accessed by use of a relative record number (RRN).
Each type of file has two objects that can be operated on: the file object and the browse object. The file object can be used with methods to perform the following API operations:
  • DELETE
  • READ
  • REWRITE
  • UNLOCK
  • WRITE
  • STARTBR

A file object is created by the user application that is explicitly instantiating the desired file class.

The file browse object represents a browse operation on a file. More than one browse object can be active against a given file at any time; each is distinguished by a REQID. Methods can be invoked against these objects to perform the following API operations:
  • EDNBR
  • READNEXT
  • READPREV
  • RESETBR

A file browse 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 EXEC CICS commands for each type of CICS file (and index) map to the CICS Java classes and methods.

Classes and methods for the keyed files are shown in the following table.

Table 1. Classes and methods for keyed files
File command KSDS index ESDS secondary index
READ KeyedFile.read KeyedFile.read
READ UPDATE KeyedFile.readForUpdate KeyedFile.readForUpdate
READ GENERIC KeyedFile.readGeneric KeyedFile.readGeneric
READ UPDATE GENERIC KeyedFile.readGenericForUpdate KeyedFile.readGenericForUpdate
REWRITE KeyedFile.rewrite KeyedFile.rewrite
WRITE KSDS.write ESDS.write
DELETE KSDS.delete  
DELETE GENERIC KSDS.deleteGeneric
UNLOCK File.unlock File.unlock
START BROWSE KeyedFile.startBrowse KeyedFile.startBrowse
START GENERIC BROWSE KeyedFile.startGenericBrowse KeyedFile.startGenericBrowse
READNEXT KeyedFileBrowse.next KeyedFileBrowse.next
READPREV KeyedFileBrowse.previous KeyedFileBrowse.previous
RESET BROWSE KeyedFileBrowse.reset KeyedFileBrowse.reset
END BROWSE FileBrowse.end FileBrowse.end
Table 2 lists the classes and methods for nonkeyed files: ESDS and RRDS files accessed by their primary indexes.
Table 2. Classes and methods for nonkeyed files
File command ESDS primary index RRDS primary index
READ ESDS.read RSDS.read
READ UPDATE ESDS.readForUpdate RRDS.readForUpdate
REWRITE ESDS.rewrite RRDS.rewrite
WRITE ESDS.write RRDS.write
DELETE   RRDS.delete
UNLOCK File.unlock File.unlock
START BROWSE ESDS.startBrowse RRDS.startBrowse
READNEXT ESDS_Browse.next RDS_Browse.next
READPREV ESDS_Browse.previous RRDS_Browse.previous
RESET BROWSE ESDS_Browse.reset RRDS_Browse.reset
END BROWSE FileBrowse.end FileBrowse.end

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

The data length that is provided by an application to a write or rewrite method is not specified by the application. CICS determines the data length from the actual data that is provided.

You do not need to specify the key length on any file method. The length that is used is the actual length of the key that is passed. When a file browse object is created, it contains the key length of the key that is specified on the startBrowse method. This length is passed to CICS on subsequent browse requests against that object.

It is not necessary for the user to provide a request ID for a browse operation. Each browse object contains a unique request ID that is automatically used for all subsequent browse requests against that browse object.