Daniel Jacobs, IBM TPF Development

TPF collection support (TPFCS) APAR PJ27380, which is available on TPF PUT 14, provides the ability to do things with data stores that previously were difficult to do or could not be done! Have you ever created a data store and then wanted to delete it, only to find out that there was no functional message to do this? Have you ever wanted to migrate your TPFCS data stores from one file address format to another, but could not figure out how? Have you ever wanted to get rid of all the collections marked for deletion right away? Have you ever wanted to quit your job and travel around the world? Well, APAR PJ27380 will let you accomplish at least some of the desires that you might have, and more! Read on to figure out which of these desires will be satisfied!

Data Store Deletion

You probably know that data stores and data definitions are created with the ZOODB DEFINE functional message. However, the shrewd observer will realize that there is a DELETE parameter to remove data definitions, but there is no corresponding parameter to remove data stores! With APAR PJ27380, the DELETE parameter will now remove a data store from your TPF system. Before you start using this new function, there are some additional considerations that you should be made aware of.

Deleting a data store results in the deletion of the data store entry from the TPF system dictionary as well as the deletion of all system collections and data definitions defined in that data store. All resources used by these collections are returned to the system and none of these collections can be reclaimed. However, user collections are not deleted and it is your responsibility to delete them before using this function.

You can enter data store deletion requests from any subsystem. Although the TPFDB data store cannot be deleted, other TPF system data stores, such as the ones used for MATIP, MQSeries, and others can be deleted. Again, remember that this would result in the loss of all data in those data stores, and some pool files used in those collections will appear as lost during the next recoup run.

Data Store Migration

There may come a time when you need to migrate your TPFCS data stores and collections to new formats. Perhaps you are using new pools support, or a new file address referencing format, or a new collection format . . . who knows! In any of those cases, you need to be able to convert your existing data into a new format. You may be thinking, "Couldn't I just use the TO2_copyCollection application programming interface (API)?" Well, you probably could use this in several different circumstances. It does use new pool records to store your data, for example. However, it has its limitations. For example, the internal collection structures are copied instead of being built from scratch, so new collection formats would not be utilized. Furthermore, you could not use this API to update data store system collections.

The solution to this is provided in APAR PJ27380 in the form of two new functional messages and APIs. The ZOODB MIGRATE functional message does several things:

• It re-creates all system collections in a data store. This includes any collections in the #INODE fixed file records when a file system data store (IFSX....) is migrated, and any MATIP definitions when the MATIP_DS data store is migrated.
• It copies the contents of the old system collections to new system collections one element at a time.
• It deletes the old system collections.

You can also perform migration using an application program. TO2_migrateCollection is used to migrate an individual collection. The results might appear to be the same as the TO2_copyCollection API, but internal processing differs so that new structure formats would be used (if they were available). Note that this API does not delete the original collection.

TO2_migrateDS allows you to migrate all the system collections in a data store. That is, it re-creates all data store system collections and copies the contents of the old system collections to the new system collections. It is similar to using the ZOODB MIGRATE functional message, but there are some important differences: First, it does not automatically delete the original system collections like the functional message does. Second, it does not migrate TPF system collections, such as ones automatically created by using functions like MATIP and MQSeries.

Data Store Re-Creation

From time to time, you might experience the need to re-create a data store from scratch. With APAR PJ27380, the ZOODB RECREATE functional message is available to re-create the system collections in a data store and put it back into an initialized state.

The ZOODB RECREATE functional message does several things:

• It re-creates and replaces all system collections contained in a data store by using new pool file addresses.
• It deletes the old system collections, except for the old recoup indexes. The pools used by the old recoup index collections will be lost until the next recoup is run.

Using this functional message will result in all user collections and recoup indexes being lost. If you do not delete all user collections before using this functional message, the pool records associated with those collections will not be available for use until the next recoup is run. As with the ZOODB DELETE functional message, the TPFDB data store cannot be deleted, but other TPF system data stores can be re-created. This too would result in the loss of all data in those data stores, and some pool files used in those collections will appear as lost during the next recoup run.

Emptying Collections

Currently, if you want to empty a collection, you have to loop through the entire collection and remove elements one by one. Furthermore, some collection types don't truly removeelements. For these collection types, such as array or binary large object (BLOB), removing elements means zeroing them out; the size of the collection doesn't change. This all changes with the introduction of a new parameter, EMPTY, on the ZBROW COLLECTION functional message. This functional message allows you to remove all elements from a collection. Furthermore, the physical size of that collection is reduced to the minimum allowed when a collection of any collection type is emptied, although the residency (compact or extended) will not change.

Recycling Deleted Collections

Did you ever wish that TPFCS had a feature similar to the Recycle Bin on Microsoft Windows operating systems, where you could actually process items waiting to be deleted? Well, guess what APAR PJ27380 provides! Before I tell you how to do that, let me give you a little background about delete processing.

A data store can either process deletions immediately, or with a delay. This is set initially with the DELETE parameter on the ZOODB DEFINE functional message and can be modified with the ZOODB CHANGE functional message. For delayed deletes, the persistent identifiers (PIDs) of the collections to be deleted are stored in the DS_DELETED collection and thus the collections are only marked for deletion. They can be reclaimed (undeleted) within 48 hours. After that amount of time, TPFCS will actually delete the collection by releasing the collection's pool records and removing the corresponding PID from the DS_DELETED collection.

Now, if you use the new EMPTY parameter on the ZBROW COLLECTION functional message with the DS_DELETED collection in any data store, it not only empties the DS_DELETED collection, but also processes the pending deletion of every collection whose PID was stored in DS_DELETED! So if you ever notice your DS_DELETED collection growing rapidly in size, you now have a way to "clean it out." (Remember that you will not be able to recover those deleted collections once they are processed!)

Other Miscellaneous Changes

APAR PJ27380 also changed a couple of other TPFCS behaviors, including the following:

• In addition to copying the collection itself, the TO2_copyCollection API now copies a collection's associated recoup index, access mode, and properties. This is also true when using the COPY parameter on the ZBROW COLLECTION functional message. The TO2_copyCollectionTemp and TO2_copyCollectionWithOptions APIs and COPYDD parameter on the ZBROW COLLECTION functional message are not affected by this change.
• When TPFCS automatically re-creates the DS_DELETED collection because of corruption, it now automatically associates recoup index IT00002 with it as well.

For more information about the changes provided with this APAR, see the APAR description as well as the following TPF publications:

• TPF C/C++ Language Support User's Guide
• TPF Operations.

Second Quarter 2001 - Table of Contents