IccBuf, which is described in detail in the reference part of this book, provides generalized manipulation of data areas. Because it can be used in a number of ways, there are several IccBuf constructors that affect the behavior of the object. Two important attributes of an IccBuf object are now described.
IccBuf has an attribute indicating whether the data area has been allocated inside or outside of the object. The possible values of this attribute are 'internal' and 'external'. It can be interrogated by using the dataAreaOwner method.
When DataAreaOwner = external, it is the application programmer's responsibility to ensure the validity of the storage on which the IccBuf object is based. If the storage is invalid or inappropriate for a particular method applied to the object, unpredictable results will occur.
This attribute defines whether the length of the data area within the IccBuf object, once created, can be increased. The possible values of this attribute are 'fixed' and 'extensible'. It can be interrogated by using the dataAreaType method.
As an object that is 'fixed' cannot have its data area size increased, the length of the data (for example, a file record) assigned to the IccBuf object must not exceed the data area length, otherwise a C++ exception is thrown.
There are several forms of the IccBuf constructor, used when creating IccBuf objects. Some examples are shown here.
IccBuf buffer;
This creates an 'internal' and 'extensible' data area that has an initial length of zero. When data is assigned to the object the data area length is automatically extended to accommodate the data being assigned.
IccBuf buffer(50);
This creates an 'internal' and 'extensible' data area that has an initial length of 50 bytes. The data length is zero until data is assigned to the object. If 50 bytes of data are assigned to the object, both the data length and the data area length return a value of 50. When more than 50 bytes of data are assigned into the object, the data area length is automatically (that is, without further intervention) extended to accommodate the data.
IccBuf buffer(50, IccBuf::fixed);
This creates an 'internal' and 'fixed' data area that has a length of 50 bytes. If an attempt is made to assign more than 50 bytes of data into the object, the data is truncated and an exception is thrown to notify the application of the error situation.
struct MyRecordStruct
{
short id;
short code;
char data(30);
char rating;
};
MyRecordStruct myRecord;
IccBuf buffer(sizeof(MyRecordStruct), &myRecord);
This creates an IccBuf object that uses an 'external' data area called myRecord. By definition, an 'external' data area is also 'fixed'. Data can be assigned using the methods on the IccBuf object or using the myRecord structure directly.
IccBuf buffer("Hello World");
This creates an 'internal' and 'extensible' data area that has a length equal to the length of the string "Hello World". The string is copied into the object's data area. This initial data assignment can then be changed using one of the manipulation methods (such as insert, cut, or replace) provided.
IccBuf buffer("Hello World");
buffer << " out there";
IccBuf buffer2(buffer);
Here the copy constructor creates the second buffer with almost the same attributes as the first; the exception is the data area ownership attribute - the second object always contains an 'internal' data area that is a copy of the data area in the first. In the above example buffer2 contains "Hello World out there" and has both data area length and data length of 21.
An IccBuf object can be manipulated using a number of supplied methods; for example you can append data to the buffer, change the data in the buffer, cut data out of the buffer, or insert data into the middle of the buffer. The operators const char*, =, +=, ==, !=, and << have been overloaded in class IccBuf. There are also methods that allow the IccBuf attributes to be queried. For more details see the reference section.
To illustrate this, consider writing a queue item to CICS® temporary storage using IccTempstore class.
IccTempStore store("TEMP1234");
IccBuf buffer(50);
The IccTempStore object created is the application's view of the CICS temporary storage queue named "TEMP1234". The IccBuf object created holds a 50-byte data area (it also happens to be 'extensible').
buffer = "Hello Temporary Storage Queue";
store.writeItem(buffer);
The character string "Hello Temporary Storage Queue" is copied into the buffer. This is possible because the operator= method has been overloaded in the IccBuf class.
The IccTempStore object calls its writeItem method, passing 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 defined in class IccTempStore and operator= which has been overloaded in class IccBuf. This second method takes the contents of the returned IccBuf reference and copies its data into the buffer.
The above style of reading and writing records using the foundation classes is typical. The final example shows how to write code - using a similar style to the above example - but this time accessing a CICS 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 which it then assigns (via operator= method, overloaded in class IccBuf) to the buffer object. The character string - "Some extra data" - is appended to the buffer (via operator<< method, overloaded in class IccBuf). The writeItem method then writes back this modified buffer to the CICS transient data queue.
You can find further examples of this syntax in the samples presented in the following sections, which describe how to use the foundation classes to access CICS services.
Please refer to the reference section for further information on the IccBuf class. You might also find the supplied sample - ICC$BUF - helpful.
[[ Contents Previous Page | Next Page Index ]]