Using JDECACHE Partial Keys

A JDECACHE partial key is a subset of a JDECACHE key that is ordered in the same way as the defined index, beginning with the first key in the defined index. For example, for a defined index of N keys, the partial key is the subset of the keys 1, 2, 3, 4...N-1 in that specific order. The order is critical. Partial key components must appear in the same order as the key components in the index. (The index is passed to jdeCacheInit or jdeCacheInitEx.)

For example, suppose that an index is defined as a structure containing the fields in this order: A, B, C, D, E. The partial keys that can be synthesized from this index are this, in order: A, AB, ABC, ABCD. The previous set is the only set of partial keys that can be synthesized for the defined index: A, B, C, D, E.

A JDECACHE partial key implements the JDECACHE cursor. When you implement the JDECACHE partial key, consider that the JDECACHE cursor works within a JDECACHE data set, which comprises the records within the cache ordered by the defined index, the full index. If you call a jdeCacheFetchPosition API and pass the partial key, the JDECACHE cursor activates and points to the first record in the JDECACHE data set that matches the partial key. If a jdeCacheFetchPosition API was called, subsequent calls to jdeCacheFetch will fetch all of the records in the data set that succeed the fetched record to the end of the data set. The cursor does not stop on the last record that matches the partial key, but continues on to fetch the next record using the next call to jdeCacheFetch, even if it does not match the partial key. When a partial key is sent to jdeCacheFetchPosition, it merely indicates from where the JDECACHE begins fetching. Because the records in the JDECACHE data set are always ordered, the fetch always retrieves all of the records that satisfy the partial key first.

JDECACHE knows that you are passing a partial key because the fourth parameter to jdeCacheFetchPosition indicates the number of key fields that are in the key being sent to the API. If the number of key fields is less than the keys that were indicated when jdeCacheInit or jdeCacheInitEx was called, then it is a partial key. Suppose the number of keys is N so that JDECACHE uses the first N key fields to make comparisons in order to achieve the partial key functionality. If jdeCacheFetchPosition is called with a number of keys that is greater than the number specified on the call to jdeCacheInit or jdeCacheInitEx, an error is returned.

To delete a partial key, you must make a call to jdeCacheDeleteAll. This call deletes all of the records that match the partial key. To indicate to JDECACHE the partial keys that you are using, pass the number of key fields to this API.

Verify that the actual number of key fields in the structure corresponds to the numeric value that describes the number of keys that must be sent to either jdeCacheFetchPosition or jdeCacheDeleteAll.