Database versioning enhancement

Database versioning provides the ability to assign user-defined version identifiers to different versions of the structure of a database. These identifiers enable you to make structural changes to a database while providing multiple views of physical data to a variety of applications.

New applications that reference a newer structure of a database can be brought online without affecting applications that use previous database structures. Unchanged applications, which do not have to be sensitive to the new physical structure of the database, can continue to access the database.

Database versioning can be used for the following types of databases:

DEDB
HDAM
HIDAM
PHDAM
PHIDAM

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 IMS™ components are updated to support database versioning:

DFSDFxxx PROCLIB member: Two new keywords, DBVERSION and DBLEVEL, are added to the DATABASE section of the DFSDFxxx PROCLIB member that specify whether database versioning is enabled and, if so, what default versioning is to be used.
In the CATALOG section of the DFSDFxxx member, the keyword VERSIONS replaces INSTANCES. If INSTANCES is specified, it is ignored.
DBD and PSB generation statements: The DBD and PCB statements are enhanced with a new DBVER parameter, where you can specify the database version number.; The PSBGEN statement is enhanced with a new DBLEVEL parameter that can be used to override the DBLEVEL specification in the DFSDFxxx PROCLIB member.

Requirements:

The IMS catalog must be enabled.
The affected database descriptions (DBDs) must be in the IMS catalog.
After a change is implemented and a version number is assigned to the DBD, if the database is logically related to one or more databases, all logically related databases must be included in the ACBGEN process.

After versioning is enabled for a database, you can specify a version number for an application program by using the DBVER keyword in the PCB statement or the application program can specify a version number at run time by using the INIT VERSION DL/I call.

Application programs that use the INIT VERSION call must issue it before issuing any DL/I calls that access the database. A version specified on the INIT VERSION call overrides any version number that is specified on the PCB statement, as well as any defaults defined in either the PSB statement or at the IMS system level in the DFSDFxxx PROCLIB member.

Database versioning can be used in conjunction with the database alter functions to keep track of different versions of the structure of a database.

Migration considerations

All generated database definitions (DBDs) that do not specify the DBVER parameter have a version number of 0.

Coexistence considerations

Recommendation: Although an IMS Version 13 system in which database versioning is enabled can coexist with an IMS system that does not support database versioning, do not enable database versioning until all of your IMS systems are migrated to IMS Version 13.

If an IMS system that has database versioning enabled must coexist with an IMS system that does not support database versioning, prevent application programs that run on the IMS system that does not support database versioning from accessing any database that has multiple versions.

DBD and PSB source that is coded for database versioning support cannot be processed by the DBD Generation and PSB Generation utilities of IMS Version 12 and earlier systems. The DBVER and DBLEVEL keywords added in IMS Version 13 are not recognized by IMS Version 12 and earlier systems.

Impact to troubleshooting for IMS

The database versioning enhancement introduces new messages and codes and modifies the documentation of existing messages and codes.

In most cases, changes to the existing messages are limited to the introduction of new values in existing variable fields and documentation changes. However, the text of several messages that are issued by the IMS Catalog Record Purge utility has changed.

For a list of the messages and codes that are new or changed for this enhancement, see the IMS messages and codes row in the table in Documentation changes.

For a complete list of all of the new, changed, and deleted messages, and abend codes in IMS Version 13, see Message and code changes in IMS Version 13.

Impact to IMS reference information

Impact to commands

The QUERY DB command can now be used to display the current version of a database.

For a list of the commands that are new or changed for this enhancement see the IMS commands row in the table in Documentation changes.

Impact to utilities

The database versioning enhancement introduces changes to the DBD input statement of the DBD Generation utility.

This enhancement also introduces changes to the PCB and PSBGEN statements of the PSB Generation utility.

The IMS Catalog Record Purge utility is changed significantly to support purging catalog segment records for specific database versions.

Documentation changes

The following publications contain new or changed information for the Database Versioning enhancement. Publications that are not impacted by the enhancement are not included in the table.

Publication	Links to topics
System definition	Changed topics: CATALOG and CATALOGxxxx sections of the DFSDFxxx member DATABASE section of the DFSDFxxx member
Database administration	New topics: Database versioning Database versioning overview IMS catalog support for database versioning Database modifications supported by database versioning Database versioning, existing free space, and new fields System default for database versioning Implementing database versioning Logical relationships, secondary indexes, and database versioning
Database administration	Changed topics: IMS catalog Removing DBD and PSB instances from the IMS catalog Format of records in the IMS catalog database DBD segment type format HEADER segment format PCB segment type format PSB segment type format
Application programming	New topics: Database versioning and application programming
Application programming APIs	Changed topics: INIT call INIT call
System programming APIs	Changed topics: Changed data log record format CAPD block format (LOGID=X'00')
IMS messages and codes	New DFS messages: DFS0006E DFS0123E DFS3549E DFS4432E DFS4433E	New abends: 1002 New DL/I status codes: BE BF BG SF	New DBDGEN messages: DBD180 DBD181 New PSBGEN messages: PCB540 PGEN259
IMS messages and codes	Changed DFS messages: DFS3303I DFS4420E DFS4421E DFS4424E DFS4426I DFS4429E DFS4430I DFS4810I	Changed abends: 3303	Changed DL/I status code topics: About DL/I status codes AG AJ BA NA SA
IMS commands	Changed IMS commands: QUERY DB command
System utilities	Changed topics: Database Description (DBD) Generation utility DBD statements Program Specification Block (PSB) Generation utility Full-function or Fast Path database PCB statement PSBGEN statement IMS Catalog Record Purge utility (DFS3PU10)