Database versioning and application programming

When database versioning is enabled in an IMS system, IMS can maintain multiple versions of the structural definition of a database so that existing application programs can continue to access a database after the database is modified to support new application programs.

When a new version of a database is defined, the database administrator specifies a version number for the new database definition. The version number is then used to request access to that version of the database.

When multiple version of a database are available, if a specific database version is not specified for an application program, IMS provides access to the current version of the database by default. The current version of a database has the highest version number and contains the latest changes to the database. This IMS system default can be changed so that IMS provides access to version 0 of the database instead.

The IMS system default can be overridden at the program specification block (PSB) level by specifying the DBLEVEL parameter in the PSBGEN statement during PSB generation.

If an application program requires a specific database version, that version number can be specified explicitly either on the DBVER parameter of a PCB statement when the PCB is defined or at runtime by issuing the DL/I INIT VERSION call.

If the requested version of a database definition cannot be found or if database versioning is not enabled when a version is requested, IMS terminates the program with abend 3303 and issues message DFS3303I, which contains details regarding the cause of the abend. Optionally, application programs can issue the INIT STATUS GROUPA call to receive a BA status code instead of abend 3303.

Attention: When a new version of a database is created, before application programs update the new version of the database, confirm that the prior versions of the database can still be accessed.

Database versioning supports only certain changes to a database definition. If unsupported changes are made to a database, application programs will not be able to access the prior versions of the database. Only the current version of the database is accessible.

For most database types, the unsupported changes are not detected until an application program that uses a prior version of the database is scheduled. However, if the HALDB alter function is used to apply the structural changes to a HALDB database, IMS detects unsupported database changes during alter processing.

If a new version of a database contains unsupported changes, either all application programs need to be updated to use the database structure of the new version or the database definition needs to be changed to remove the unsupported structure change.

Batch application programs and database versioning

You can enable database versioning for offline DL/I batch application programs that run in DLIBATCH or DBBBATCH regions by specifying DBVERSION=Y in a DFSDFxxx member in the IMS.PROCLIB data set.

The DLIBATCH or DBBBATCH application programs reference the DFSDFxxx member by specifying the DFSDF=xxx parameter in the EXEC statement of their JCL. For example:

//STEP1    EXEC PGM=DFSRRC00,REGION=0M,                                
// PARM=(DLI,DFSDDLT0,PSBCJK03,,01,,,,,,,BCH1,,Y,Y,,,,,,,,,,,,,,,,,,,,,
//       ,,,,,'DFSDF=C35')

Important: DLIBATCH application programs use PSB and DBD libraries instead of an ACB library. When using database versioning, DLIBATCH application programs must use the DBD library that contains the DBD member that matches the current physical database structure.