Database versioning, existing free space, and new fields

In the IMS definition of a segment, any bytes in the length of the segment that are not used by the fields that are defined in the segment are considered free space.

Although free space appears unused to IMS, application programs can use or otherwise alter that free space without IMS knowing. In fact, the free space in a segment might be used for fields and data that are mapped by application program code, such as a COBOL copybook.

While database versioning supports the addition of new fields in the existing free space at the end of a segment, before you define any new fields for that free space, you must make sure that it is not used by any existing application programs.

The following examples illustrate the possible conflict that can occur between existing application programs and new fields that are added to existing free space.

If the free space is used by any application programs, you can either increase the length of the segment and add the new field after the existing free space, or you can modify the existing application programs so that they do not use the free space.

The following examples illustrate the potential problem and how you can avoid it.

How existing application programs can conflict with new fields in existing free space

In the following example, the base version of a database contains a 40-byte segment that has 10 bytes of free space at the end, which is seen by an existing application program, PGMA: 

10 bytes  20 bytes            10-byte undefined space at the end
----------------------------------------
|  123    |  Maple Ave.       |        |
----------------------------------------

In version 1 of the same database, the segment size is increased to 50 bytes and a new 20-byte field is defined at the end of the segment. A change like this is supported by database versioning; however, if the existing application program contains code that initializes the 10-byte space at the end of the segment, the existing application program can corrupt any data that is inserted into the new field in version 1 of the database.

The following example shows how the segment looks in version 1 of the database after the segment is extended by 10-bytes, a new 20-byte field is defined, and an application program, PGMB, updates the segment with data:
10 bytes  20 bytes            20 bytes 
---------------------------------------------------
|  123    |  Maple Ave.       | San Francisco     |
---------------------------------------------------
Then, PGMA makes a REPL call and, because PGMA includes code that initializes the 10 bytes of free space at the end of the segment, overwrites the data added by PGMB, as shown in the following example.
10 bytes  20 bytes            20 bytes 
---------------------------------------------------
|  456    |  Orchard Ave.     |         cisco     |
---------------------------------------------------

Given how PGMA is coded, a new field should not be coded in the existing space unless PGMA is modified. As an alternative to modifying PGMA, the length of the segment can be increased and the new field can be added after the existing free space in the new DBD version..

Example of defining a new field in new space after the existing free space

The following is an address segment as seen by PGMA: 
10 bytes  20 bytes            10-byte undefined space at the end
-----------------------------------------
|  123    |  Maple Ave.       |         |
-----------------------------------------
The segment is extended by 20 bytes and a new 20-byte field is defined. PGMB updates the segment with data, while the original 10-bytes of free space are untouched: 
10 bytes  20 bytes            10 bytes  20 bytes
-------------------------------------------------------------
|  123    |  Maple Ave.       |         | San Francisco     |
-------------------------------------------------------------
PGMA makes a REPL call, which initializes the 10 bytes of free space; however, the new 20-byte field is untouched. 
10 bytes  20 bytes            10 bytes  20 bytes
-------------------------------------------------------------
|  789    |  Walnut Ave.      |         | San Francisco     |
-------------------------------------------------------------