Resolution:
Description:
============
When migrating to a new release of TIBCO Object Service Broker (OSB), best practices includes a backup of the current MetaStor before the upgrade is attempted.

Environment:
============
All operating systems executing TIBCO Object Service Broker.

Background:
===========
Migrating to a new TIBCO Object Service Broker release involves a number of steps including application of a new software execution library and maintenance to the OSB MetaStor (Segment 0). The MetaStor contains a combination of system and customer defined objects such as rule and table definitions. Although table definitions are stored in the MetaStor, the table data may reside in other segments of the OSB.

Execution run time modules and MetaStor definitions may contain relationships that must be kept in synchronization. For instance, a new field may be added to a system table to support new function in the target migration release. When the MetaStor is changed, it may not be compatible with the previous version's executables. This relationship can affect back off procedures, should the new release need to be removed from service.

Resolution:
===========
Prior to executing the migration process which is documented in the "TIBCO Object Service Broker Release Notes", you should always perform a complete backup of Segment 0, the MetaStor, along with a backup of the executable program library. Since the migration process does not usually modify customer-based segments, you can optionally backup your other segments or not.

When the backup of the MetaStor is performed, do not use a Continuous Backup based on journaled data but rather, shut down the Data Object Broker cleanly with no inflight work or termination failures. You can check for inflight work on Open Systems by using the hrntladm (Administration menu) or on z/OS by using the S6BTLADM utility under TSO. Use the "IN-DOUBT TRANSACTIONS" option to make sure no inflight work exists. If in-doubt work exists, resolve the issue before proceeding with the backup and migration upgrade.

Run the backup utility, such as S6BTLBPS on z/OS or hrntlbps (Backup Pagestore) on Open Systems, against Segment 0, the MetaStor. There are supplied procedures or recommendations contained in the migration process which you should use for this purpose. These are documented in the migration Release Notes. Make sure you validate your Segment 0 MetaStor backup by passing the backup through Pointer Check S6BBRPTR on z/OS or hrnbrptr (Batch Pointer Check) on Open Systems. This will verify that the backup is physically sound and give you some metrics on the characteristics of the backup. Make sure you review the output of the Pointer Check utility to ensure that no errors were found in the backup.

You should also backup your executable library in case a back off is required.

Back off Considerations:
========================
Application promotions should be avoided until a comfort level is attained with the newly migrated system. This will make back off easier, should a back off be required, avoiding regression of promoted objects.

Customer tables should only be defined on segments other than the MetaStor (Segment 0). This will allow a back off of the migration, should that be necessary, without backing out updated customer table data. Although the data for customer tables will be stored in non-MetaStor segments, the actual table definition is always stored in the MetaStor. In early releases of ObjectStar (prior to TIBCO Object Service Broker), customer tables could be defined on the MetaStor. Customers are advised to move such tables off the MetaStor should any still reside there. This will facilitate back off of upgrades as well as avoid problems such as exhausting space in Segment 0 which necessitates an outage while extra space is added to the segment.

If a back off is required, shut down the migrated Data Object Broker cleanly with no inflight work or termination failures as you did before the migration, then restore the MetaStor and executable library from your backup along with your original executable library. On z/OS you can use S6BTLRPS to restore the MetaStor from your backup or on Open Systems hrntlrps (Restore Pagestore). You may need to initialize your Data Object Broker system files such as: journals, cache and redolog datasets using your original executable library. Once this is accomplished, your OSB system should be at the software level you were using prior to the migration.

TIBCO Support:
==============
Should you have any concerns about migration procedures and your specific situation, open a problem report with TIBCO Support to seek advice.


References:
==========
* TIBCO® Object Service Broker for Open Systems Installing and Operating Software Release 5.2.0
* TIBCO® Object Service Broker for Open Systems Managing Backup and Recovery Software Release 5.2.0
* TIBCO® Object Service Broker for Open Systems Utilities Software Release 5.2.0
* TIBCO® Object Service Broker for z/OS Installing and Operating Software Release 5.2.0
* TIBCO® Object Service Broker for z/OS Managing Backup and Recovery Software Release 5.2.0
* TIBCO® Object Service Broker for z/OS Utilities Software Release 5.2.0
* TIBCO® Object Service Broker Release Notes Software Release 5.2.0