Using a KcsAttributeSet Object

A KcsAttributeSet object is created when you need to map identifiers to variable data structures such as ICC tags (that is, integers, floats, strings, and dates). There are two ways to create a non-empty KcsAttributeSet object. The method you choose depends on the origin of the data used to populate the KcsAttributeSet object. The origin can be a supplied chunk or character buffer.

If you do not want to create a KcsAttributeSet object with data from a chunk, you can create a KcsAttributeSet object using a character buffer (the KcsAttributeSet object contains a null chunk set). The only issue you must be aware of in this case is that, in order to save the KcsAttributeSet object, you need to have set the internal chunk set pointer of that KcsAttributeSet object to a valid chunk set and gotten a chunk Id from that chunk set. If the chunk has not been set, then attempting to save the KcsAttributeSet object results in a KCS_UNINITIALIZED_CHUNKSET error.

Using a KcsAttributeSet object, you can perform the following operations:

• Insert new data

• Remove data

• Update data

All three operations performed on the KcsAttributeSet data are accomplished by calling setAttribute()(), a public method of the KcsAttributeSet class. The operation performed is decided by the parameters supplied to the setAttribute()() method and the state of the KcsAttributeSet object when the method is called. Conceptually, only two parameters to the method are important: an identifier and a structure used to contain the variable data associated with that identifier.

To insert new data into a KcsAttributeSet object call setAttribute()() with an identifier not currently used and information stored within the KcsAttributeSet object. For example, assume the structure contains the character string "today is my birthday" as variable data and that the identifier equals 30. After successful completion of a call to setAttribute()(), an association between "today is my birthday" and 30 is stored within the object.

To remove data from a KcsAttributeSet object call setAttribute()() with the identifier of the data you want to delete and assign the information structure parameter to NULL.

To update data in a KcsAttributeSet object call setAttribute()() with an identifier currently used and new information stored within the information structure. For example, assume that the information structure contains the integer data "100 200 300" as variable data and that the identifier is set to 30. After successful completion of a call to setAttribute()(), the association of 30 with "today is my birthday" would be replaced with the association of 30 with "100 200 300" in the object.

Several methods give you information about the KcsAttributeSet data as a whole, as well as information about specific associations that make up the KcsAttributeSet data. The returnCurrentNumberOfAttributes()() method provides the number of associations currently stored within a KcsAttributeSet object. The getAttribute()() method provides information associated with a specific identifier. The getTag()() method returns the nth identifier stored within the data. The setChunkSet()() method allows the chunk pointer associated with an instance of a KcsAttributeSet object to be reassigned to a new or different chunk; this method is needed to save KcsAttributeSet data for a KcsAttributeSet object with which no chunk has been supplied. The getAttributeInfo()() method provides detailed information associated with an identifier such as the type of data (for example, string, integer, float) and the number of tokens found within the variable data.

KcsAttributeSet data is loaded into a KcsAttributeSet object when a non-empty KcsAttributeSet object is constructed. The save()() method is used to store the KcsAttributeSet data. As mentioned earlier, a KcsAttributeSet object must have a valid chunk in order for the KcsAttributeSet data to be saved.

See the KCMS CMM Reference Manual for detailed information on all of the KcsAttributeSet class member functions.