Overview

You can convert a JADE user database in multiuser mode to copy the data from the database server and write it to a local directory. This feature enables you to:

Upgrade a user database from an earlier release (for example, from a JADE 2018 release to JADE 2020)
Convert a database from one operating system or hardware platform to another
Convert an ANSI databases containing multiple-byte characters to Unicode

You can run multiple copies of the file convert worker application inside the client node if you want multiple database file conversions to occur concurrently.

The user database conversion creates a copyfile.log file in the logs directory, which reports when processing a database file (by number) starts and when the file is converted.

For details about running the jadclient program to execute a non-GUI application within your JADE code, see "Running a Non-GUI Client Application using jadclient", in Chapter 1.

Converting a database requires the JADE bin and empty system directories be installed on the target platform and be at the same patch level as the source platform.

Converting an ANSI database to an empty Unicode database using the jadclient program with the userData and userSchema arguments set to true avoids exceptions that can occur if you use the JADE Load utility (jadload or jadloadb) to load schemas into a Unicode JADE system.

If you are manually loading user-defined schemas (that is, the value of the userSchema argument is false), schemas loaded into the target system must just have been extracted from the source database, to ensure that the target database control file has the identical number for each database file. Extract all schemas from the source database, load them into a new target database (that is, they are the first set of schemas loaded into the target database), and then perform the convert operation.

As patch history information is stored in compressed binary format, converting a system from ANSI to Unicode does not convert this information. This information will not be valid when using it in a Unicode system unless you first extract the patch history from the ANSI system and load it into the Unicode system using the Replace option (that is, you must perform the patch history extract action before converting the ANSI database and then perform the load action in the converted Unicode database). For details, see "Extracting and Loading a Patch History", in Chapter 3 of the JADE Development Environment Administration Guide.

The JadeConvertDb application converts up to 1,000 files. If more than 1,000 files are being converted, an error message is output and the application will not convert any files.

To convert a user database, specify the following arguments in the jadclient program.

jadclient path=database-path      
          schema=RootSchema
          app=JadeConvertDb
          ini=jade-initialization-file
          startAppParameters
          defaultPath=default-destination-map-file-directory
         [codepage=codepage-identifier]
         [copies=number-of-multiple-parallel-file-copies]
         [copySingleFileJadeBytes=true|false]
         [excludeuserfiles=map-file-list]
         [existing=true|false]
         [userPath=map-file-directory]
         [mapFile]
         [overwrite=true|false]
         [rebuildDicts=true|false]
         [userData=true|false]
         [userSchema=true|false]

For details, see "Database Conversion Arguments" in the following section.

When rebuilding dictionaries (that is, the rebuildDicts argument is set to true), the JadeConvertDb application must be run from a user-defined schema only.

If an argument value is longer than 2,048 characters, an exception is raised and logged (including the argument text).