Using buffer objects with IccResource classes

The resource classes that pass data to CICS® (for example, by writing data records) and get data from CICS (for example, by reading data records) use the IccBuf class. These classes include IccConsole, IccDataQueue, IccFile, IccFileIterator, IccJournal, IccProgram, IccSession, IccStartRequestQ, IccTempStore, and IccTerminal.

Figure 1 shows an example of writing a queue item to CICS temporary storage using IccTempstore class.

Figure 1. Code example: Using a buffer with a temporary storage queue

IccTempStore store("TEMP1234");
IccBuf       buffer(50);
buffer = "Hello Temporary Storage Queue";
store.writeItem(buffer);

The IccTempStore object that is created is the application's view of the CICS temporary storage queue named "TEMP1234". The IccBuf object that is created holds a 50-byte data area (it also happens to be extensible).

The character string "Hello Temporary Storage Queue" is copied into the buffer. This is possible because the operator = has been overloaded in the IccBuf class.

The IccTempStore object calls its writeItem method, and passes a reference to the IccBuf object as the first parameter. The contents of the IccBuf object are written out to the CICS temporary storage queue.

Now consider the inverse operation, reading a record from the CICS resource into the application program's IccBuf object:

buffer = store.readItem(5);

The readItem method reads the contents of the fifth item in the CICS Temporary Storage queue and returns the data as an IccBuf reference.

The C++ compiler actually resolves the above line of code into two method calls, readItem, which is defined in class IccTempStore, and operator =, which has been overloaded in class IccBuf. The second method takes the contents of the returned IccBuf reference and copies its data into the buffer.

Finally, Figure 2 shows how to write code, using a similar style to the above example, but this time accessing a CICS transient data queue.

Figure 2. Code example: Using a buffer with a transient data queue

IccDataQueue queue("DATQ");
IccBuf       buffer(50);
buffer = queue.readItem();
 buffer << "Some extra data";
 queue.writeItem(buffer);

The readItem method of the IccDataQueue object is called, returning a reference to an IccBuf object, which it then assigns (by way of the operator =, overloaded in class IccBuf) to the buffer object. The character string "Some extra data" is appended to the buffer (by way of the operator <<, overloaded in class IccBuf). The writeItem method then writes back this modified buffer to the CICS transient data queue.

The sample programs in CICS Services show further examples of this syntax.

Refer to the reference section for further information about the IccBuf class. The sample program iccbuf.cpp is also helpful for understanding buffers.