File services and examples

Categories of Java interfaces relating to File Control

File and FileBrowse objects

For each file, there are two objects that can be operated on; the File object and the FileBrowse object.

File objects

The File object represents the file itself and 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 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:

• ENDBR
• READNEXT
• READPREV
• RESETBR

FileBrowse objects

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.

Mapping from JCICS classes and methods to CICS API commands

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.

Classes and methods for keyed files

This table shows the classes and methods for keyed files.

Classes and methods for non-keyed files

This table shows the classes and methods for non-keyed files. ESDS and RRDS are accessed by their primary indexes.

Writing and reading data

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

Data is read from a file into a RecordHolder object.

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.

Samples

The following snippet shows how to use the KSDS class to read and write structured records to a VSAM file. In this example a StockPart record is used to represent the structured record, and was created from a COBOL copybook structure using IBM® Record Generator for Java .

private static final String FILE_NAME = "XMPLKSDS";
private final KSDS ksds;
....
 
public void addRecord(StockPart sp)
{
    this.ksds = new KSDS();
    this.ksds.setName(FILE_NAME);
    //Get the byte structure from the generated record using the getByteBuffer() method on the StockPark record
    byte[] record = sp.getByteBuffer();
    
    //Create a byte array containing the key for this record
    byte[] key = StockPartHelper.getKey(sp);
     
    try
    {     
        //Write the record into the VSAM file using the specified key
        this.ksds.write(key, record);
    }
    //Catch specific responses from the WRITE FILE commmand
    catch (DuplicateRecordException dre) 
    {  // Collision on the generated key
        String strMsg = "Tried to insert duplicate key 0x%08X"; 
        Task.getTask().out.println( String.format(strMsg, sp.getPartId()) );
        throw new RuntimeException(dre);
    }
    //Catch specific responses from the WRITE FILE commmand
    catch (InvalidRequestException ire) 
    {            
        if ( ire.getRESP2() == 20 ) // File not addable
        { 
            String strMsg = "Add operations not permitted for file %s";
            Task.getTask().out.println( String.format(strMsg, this.ksds.getName()) );
        }            
        // Throw an exception to rollback the current UoW
        throw new RuntimeException(ire);
    }
    //Catch all other responses and throw an exception to abend the task
    catch (CicsConditionException cce) 
    {         
        throw new RuntimeException(cce);
    }
}

For full working samples, go to GitHub, where sample CICS Java programs are provided to demonstrate how to use the JCICS API in an OSGi JVM server environment. In particular, use com.ibm.cicsdev.vsam for accessing KSDS, ESDS, and RRDS VSAM files.