Temporary storage queue services and examples

A temporary storage (TS) queue is a set of data items that can be read and re-read in any sequence, and TSQ resources can be dynamically created at runtime. JCICS supports the CICS® temporary storage commands: DELETEQ TS, READQ TS, and WRITEQ TS.

Interaction between JCICS methods and EXEC CICS commands

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

JCICS API mapping to EXEC CICS API lists the methods and JCICS classes that map to CICS temporary storage commands.

DELETEQ TS: You can delete a temporary storage queue (TSQ) using the delete() method in the TSQ class.
READQ TS: The CICS INTO option is not supported in Java programs. You can read a specific item from a TSQ using the readItem() and readNextItem() methods in the TSQ class. These methods take an ItemHolder object as one of their arguments, which will contain the data read in a byte array. The storage for this byte array is created by CICS and is garbage-collected at the end of the program.
WRITEQ TS: You must provide data to be written to a temporary storage queue in a Java byte array. The writeItem() and rewriteItem() methods suspend if a NOSPACE condition is detected, and wait until space is available to write the data to the queue. The writeItemConditional() and rewriteItemConditional() methods do not suspend in the case of a NOSPACE condition, but return the condition immediately to the application as a NoSpaceException.

Examples

The following snippets show how to use the TSQ class to write string data to a TSQ and then read it back using a JCICS holder. A full working example of this code is available in the TSQExample2 sample.

public class TSQExample2 extends TSQCommon
{
    //Initialize constants
    private static final String TSQ_NAME = "MYTSQ";
    private static final int DEPTH_COUNT = 5;
    private static final String CCSID = System.getProperty("com.ibm.cics.jvmserver.local.ccsid");
 
    public static void main(String[] args)
    {
        //Create TSQ object and set TSQ name and storage type as MAIN (in memory)
        TSQ tsq = new TSQ();
        tsq.setName(TSQ_NAME);
        tsq.setType(TSQType.MAIN);    
 
        //Loop around writing multiple records to the TSQ
        for (int i = 1; i <= DEPTH_COUNT; i++) 
        {
             
            String msg = MessageFormat.format("TSQ write from JCICS item {0}", i);
            //Create byte array from the input string using the CICS encoding
            byte[] data;        
            try
            {
                data = msg.getBytes(CCSID);
            }
            catch (UnsupportedEncodingException uee) 
            {
                throw new RuntimeException(uee);
            }
            try {
                //Write each item to the TSQ using the TSQ.writeItem() method
                this.tsq.writeItem(data);
            }
            catch (CicsConditionException cce) 
            {
                throw new RuntimeException(cce);
            }
        }
    }

The following method readFromQueue() shows how to use a JCICS ItemHolder to read bytes from a TSQ.

public void readFromQueue()
{
    //Create a JCICS ItemHolder to be used to read bytes from the TSQ
    ItemHolder holder = new ItemHolder();
     
    for (int i = 1; i <= DEPTH_COUNT; i++) 
    {
         
        try
        {
            //Use the TSQ.readItem() method to loop around reading items from the TSQ into the ItemHolder, starting from an index of 1 as this is the first record in a TS queue
            this.tsq.readItem(i, holder);
        }
        catch (CicsConditionException cce) 
        {
            throw new RuntimeException(cce);
        }
 
        //Extract the byte array from the item holder
        byte[] data = holder.getValue();    
        String strData;
        try
        {
            //Create a new string using the CICS encoding
            strData = new String(data, CCSID);
        }
        catch (UnsupportedEncodingException uee) 
        {
            throw new RuntimeException(uee);
        }
    ....           
    }
}