Database versioning overview

To create a new version of a database, database versioning must be enabled by specifying DBVERSION=Y in the DFSDFxxx PROCLIB member.

After database versioning is enabled, you create a new version of a database by updating the database definition (DBD) of the database with a version number and the structural changes you are introducing with the new version. The version number is specified on the DBVER keyword and must increase incrementally by one in each new version.

After the DBD and ACB members for the new version are generated and the ACB members are activated in the ACB library, the older versions of the database exist only in the DBD record of the database in the IMS catalog. When an application program requests data from a version of the database that is not the active version in the ACB library, IMS retrieves the requested version from the IMS catalog.

Attention: If a DBD record in the IMS catalog contains multiple instances of a version of the DBD, IMS uses the most recent instance to return the data, as determined by the ACB generation timestamp.

The database version that an application program requires can be specified on the DBVER= parameter in the PCB or at runtime by issuing the INIT DL/I call with the VERSION subfunction.

By default, when no version number is specified for an application program, IMS returns data that conforms to the DBD that is currently active in the ACB library. Usually, the version that is active in the ACB library reflects the current physical structure of the database on DASD.

If version 0 of a DBD still exists in the IMS catalog, you can change the default so that IMS returns data by using version 0 of the DBD. Version 0 of a DBD is the most recent instance of the DBD in the IMS catalog that does not contain the DBVER parameter. If version 0 of a DBD no longer exists in the IMS catalog, only the active version of the DBD can be used as the default version of the DBD.

The default can be set at the system level and at the program specification block (PSB) level. The PSB level default overrides the system level default.

The system level default is set by the DBLEVEL= keyword in the DFSDFxxx member. The PSB level default is set by the DBLEVEL= keyword on the PSBGEN statement of the PSB definition.

If an application program requests a database version that does not exist in the IMS catalog, IMS returns a status code to the application program.

When database versioning is not enabled, IMS ignores any specified version numbers in PSB or DBD macros and returns data only in the format that is defined by the physical database structure. If an application program specifies a version number on the DBVER= parameter of a PCB when database versioning is not enabled, IMS either terminates the application program with a 3303 abend or returns a BA DL/I status code to the application program, depending on how your application program is designed.

Recommendation: As soon as you create a new version of a database, confirm that application programs can still access the prior versions of the database. Database versioning supports only certain changes to the structure of a database. The only way to validate that new changes are supported by database versioning is to schedule an application program to access a prior version of the database. Because the most recent version of the database does not require the data to be reformatted before returning it to an application program, accessing the most recent version does not detect unsupported changes.

When a change is made to a DBD with versioning enabled, applications that are impacted by the change will need to be modified. A PSBGEN with the desired DBLEVEL specification should be run.

Database versioning supports the following changes to a database definition:
  • An increase to the length of a segment.
  • The addition of new fields to existing undefined space at the end of a segment.
Attention: Before you add new fields to a segment in existing space that is undefined to IMS, you must make sure that your existing application programs do not initialize, modify, or otherwise use the free space.
The following database types support database versioning:
  • DEDB
  • HDAM
  • HIDAM
  • PHDAM
  • PHIDAM

IMS database versioning supports both databases that have logical relationships and databases that have secondary indexes. However, segments that are involved in the relationship between the two databases, or that are paired with another segment in the same database, cannot change in new versions of the DBD. Only the segments in the databases that are not involved in a relationship can change.