Converting a tableBASE library

The Library Conversion Utility DK1TCNV (your.prefix.CNTL) is used to convert tableBASE libraries between Version 5 (V5), Library Bridge (Bridge), Version 6 Transition (V6Trans), and Version 6 (V6).

This section identifies and describes DK1TCNV input parameters, shows a variety of conversion functions, describes a sample conversion and ends with example JCL for executing DK1TCNV.

The DK1TCNV utility has free-format input using keywords that invoke four library conversion functions. The general format is:

• COMMAND KEYWORD1=VALUE KEYWORD2=VALUE;

KEYWORD=VALUE is the representation of a keyword-value combination and may be repeated for each parameter of the command.

The following rules apply:

1. Each command sequence must start on a new line.
2. A command sequence must be terminated by a semicolon (;). Anything following a semicolon is ignored.
3. The command and each keyword-value combination must be followed by at least one blank.
4. Keyword-value combinations may appear in any order.
5. Many library conversion requests may be entered in the same input file.
6. Columns 73-80 of a statement are ignored.
7. An asterisk (*) in column one means that the line is a comment.

Keyword parameters

Input parameters for DK1TCNV are keywords with assigned values:

Conversion utility commands

There are four conversion utility commands:

• CONVERT
• REVERT
• FIXLIB
• DIAGNOSE

CONVERT

The tableBASE library is converted to the format specified with the TOFORMAT parameter, the version of the source library is detected automatically. There are four types of libraries: Version 5 (V5), Library Bridge (Bridge), Version 6 Transition (V6Trans) and Version 6 (V6). For more information on these library types, see Description of tableBASE library versions.

It is used to perform to do the following:

1. Convert from V5 to BRIDGE, V6TRANS or V6.
2. Convert from BRIDGE or V6TRANS to V6.
3. Convert from BRIDGE to V6TRANS.
4. Convert from V6TRANS to BRIDGE.

CONVERT FROMLIB = MAINLIB TOLIB = TESTLIB TOFORMAT = BRIDGE;

CONVERT FROMLIB = MAINLIB TOLIB = MAINLIB2 TOFORMAT = V6;

CONVERT FROMLIB = OLDLIB TOLIB = JANLIB2 TOFORMAT = BRIDGE;

REVERT

Backward conversion from BRIDGE or V6TRANS to V5. The target library will be in V5 format.

REVERT FROMLIB = MAINLIB TOLIB = NEWLIB;

FIXLIB

Detect and fix V5 problems which conversion would also detect and fix. The source must be a Version 5 library. The target library remains in a Version 5 format.

FIXLIB FROMLIB=MAINLIB TOLIB=PRODLIB;

FIXLIB FROMLIB=OLDLIB TOLIB=MAINLIB2 TBLPREFX=V5@@;

DIAGNOSE

Diagnose a tableBASE library.

Example:

DIAGNOSE FROMLIB = MAINLIB;

Completion codes

Completion codes listed in Table 8 are set to indicate whether problems were encountered. If any of the commands or parameters are invalid, none of the commands will be processed, errors will be displayed in TBREPORT and a completion code of 16 will be returned. If more than one completion code applies, the highest code will be returned and complete details will be found in TBREPORT.

Description of Conversion Process

Below is a sample output from a typical conversion job.

The messages displayed in the output, as referenced by the numbers in the sample output, are described below. They represent the basic processing steps performed by the conversion program:

1. Identification of the command to be processed.
2. Identification of the table prefix to be used for renaming invalid table names.
3. Diagnosis of the source library to be converted to check the integrity of the internal structure.
4. Copying of all tables from the source library to the target library.
5. Repairing of invalid tables names in the target library using the default table name prefix.
6. Repairing of linkage to empty directory blocks in the target library.
7. Reorganization of tables in target library to make internal format changes between V5 and V6 libraries like block size changes, converting of paged tables to pointer tables and ensuring that the order of data is similar to that in V5.
8. Diagnosis of the converted target library to check the integrity of the internal structure.

JCL for creating BRIDGE libraries

Converting to BRIDGE libraries

Here is a sample JCL (BDAM) for the execution of DK1TCNV to create a BRIDGE library (can be found in your.prefix.CNTL).

Converting to V6 transition libraries

Here are two samples of JCL (BDAM and VSAM) for the execution of DK1TCNV to create a V6 Transition library.

Converting to V6 libraries

Here are two samples of JCL (BDAM and VSAM) for the execution of DK1TCNV to create a V6 library.

Reverting to V5 libraries

Here is a sample JCL (BDAM) for the execution of DK1TCNV to revert back to a V5 library.

Virtual memory requirements

The DK1TCNV utility requires sufficient virtual memory (specified using the REGION parameter within DK1TCNV) to load the program and to read parts of the library into memory. The amount of virtual memory required can be calculated by using the following formulas and using the result that is largest:

Region size (in bytes) = Number-of-library-blocks * 16 + 3120 + 3120 + 512000 or

Region size (in bytes) = Largest-table-size * 2 + 512000

(where table-size = row-size * number-rows)

Conversion notes

The library conversion process introduces some changes:

• Once a library has been converted to the Version 6 format it cannot be converted back. However, it is possible to convert Library Bridge and Version 6 Transition Libraries back to the Version 5 format provided that the V6TRANS library has not been expanded.
• Paged tables that are converted will no longer be SMC=Paged, Index=True but rather SMC=Resident, Index=Pointer. These tables remain Resident/Pointer/Hash even if the library is converted back to the Version 5 format.
• A larger TSR may be required for tables opened from a converted library which were converted from SMC=Paged. When such a table is opened, the entire table must now fit into the TSR and not just a single 3120-byte page at a time. This may be the largest impact in the migration to Version 6. Most installations however, never use Paged tables and if this is the case no change in TSR size is anticipated.
• Library expansion must be done using the corresponding version of TBEXEC. For example if a Version 5 library must be expanded, use the TBEXEC provided with Version 5. Note that the Library Bridge version of TBEXEC will create a Version 5 library, which must, in turn, be converted to Bridge. Version 5 expansion restrictions still apply (see tableBASE version 5 library expansion limits).
• In order to define a library with Version 5 format, run the TBEXEC using Version 5 loads. In order to define a library with Version 6 format, run the TBEXEC using Version 6 loads.