Overview

Any Jade version from 7.1.0 and higher will upgrade to a Jade 2016, 2018, 2020, or 2022 version. Downgrading from Jade 2022, 2020, or 2018 to a version less than Jade 2018.0.01 Hotfix 91 will fail.

The rules for the versions that will be handled when upgrading to a later release or downgrading to an earlier release may change in future releases.

You can automatically upgrade Jade and user software on presentation clients. This feature reduces Jade thin client deployment issues when presentation client software changes (installing a new Jade release or upgrading a patched library) and ensures that you cannot run different versions of software on the application server and presentation clients.

If required, the Microsoft Visual C++ redistributables will be installed by the presentation client, which requires administrator privileges.

See also "Effects of Security on Presentation Client Upgrades", in Chapter 1.

The automatic upgrade of Jade software from the application server keeps the binary files on the presentation client synchronized without any user action being required.

If Jade is installed in C:\Program Files, any thin client download requires administrator privileges.

If Jade is installed in the \Program Files directory (or the \Program Files (x86) directory on a 64‑bit machine with 32‑bit Jade binaries):

If the machine has had UAC disabled, the thin client upgrade will fail because of lack of permissions for standard users. For administration users, the necessary privileges are automatically granted so the upgrade will succeed.
If UAC is not disabled, administrative users are prompted with an Allow or a Cancel choice but standard users must know and supply the logon and password of a user with administrative privileges to enable the upgrade to succeed.

Set the appropriate parameters in the Jade initialization file only if you are utilizing additional features such as downloading non‑Jade files.

If the presentation client binaries are 64‑bit, they are always downloaded from the bin directory files on the application server and any additional files are downloaded from the download directory under the ..\x64‑msoft‑win64‑ansi if an ANSI or ..\x64‑msoft‑win64‑unicode if a Unicode directory, and these are expected to be the correct 64‑bit versions. No check of a 32‑bit versus a 64‑bit binary version is performed.

The automatic upgrade process enables you to:

Disable the facility.
Automatically update presentation client binaries.
Download additional files into the binary directory.
Download other files into a directory that you specify.
Pre‑download files ready for a future application server upgrade.
Control the number of concurrent downloads from an application server.
Monitor information about downloads in progress and pre‑downloads previously completed.
Run your own post-installation program on the presentation client.
Register any ActiveXControl or Ocx controls that are downloaded.
Installs any .msi installers that are downloaded.
Attempt to install C++ runtime, if the appropriate redistributable executable is downloaded (that is, vcredist_x64.exe or vcredist_x86.exe).

The Jade thin client automatic download process:

Rejects files greater than 1G byte.
Determines up-front the memory size required to collect all of the files, so that only one allocation is performed rather than resizing the buffer as each file is added.
Raises an exception if the memory allocation fails.
Reuses buffer allocation for all of the steps required in the download process.

As a Jade application server can handle presentation clients simultaneously, the application server requires different sets of files to be available for downloading to presentation clients. Those files must each reside in a different directory identified by the hardware type, vendor, operating system version, and whether they are ANSI or Unicode files.

The following rules apply to presentation clients.

The files for the thin client (jade.exe) environment are available on the application server, all of the files are upgraded as required.
Required binaries are not all available to be downloaded, the presentation client cannot continue the session because the existing presentation client binaries may not be valid and consistent with those of the application server, even though the Jade versions match; for example, because of ANSI versus Unicode binaries, presentation client protocol changes, or client operating system changes.
Microsoft Visual C++ Redistributables need to be installed, administrator privileges will be requested. If this fails, you can manually install them.

Files are downloaded if they are required.

The following are examples of directory file names.

i686-msoft-win32-ansi
x64-msoft-win64-ansi
i686-msoft-win32-unicode
x64-msoft-win64-unicode

The Jade initialization file on the application server must contain an [environment-type] section that controls the download process for each environment type; for example:

[x64-msoft-win64-ansi]
DownLoadDirectory        = <default>
FullJadeInstallDirectory =
PostInstallExe           =

The directory specified in the DownLoadDirectory parameter must have the following subdirectories.

download, which contains the directories and their read-only files to be downloaded to the Jade HOME directory on the presentation client (that is, the parent directory of the installation directory)
downloadProgramData, which contains program data and read-write files to be downloaded to the directory specified by the value of the ProgramDataDirectory parameter in the [JadeEnvironment] section of the Jade initialization file and the location of the installation directory on the presentation client
predownload, which contains the directories and their read-only files to be pre‑downloaded to the Jade HOME directory on the presentation client (that is, the parent directory of the installation directory)
predownloadProgramData, which contains the program data and read-write files to be pre‑downloaded to the directory specified by the value of the ProgramDataDirectory parameter in the [JadeEnvironment] section of the Jade initialization file and the location of the installation directory on the presentation client

If the Jade HOME directory and Jade program data directory of the presentation client are:

Identical, the result of the download installation is the same as if all the files and directories had been defined under the application server download and predownload directories.
Different, the read-only files installed under the Jade HOME directories are separated from the read‑write program data files installed under the Jade program data directories.

To ensure total read‑only and read‑write separation, the Jade initialization file cannot be located in the Jade HOME directory.

The DownLoadProgramDataDirectory and PreDownLoadProgramDataDirectory parameters in the [JadeThinClient] section of the Jade initialization file on the presentation client enable you to specify the directory and subdirectories on the presentation client into which all read-write program data files destined for the system directory are copied temporarily prior to them being installed during the automatic software upgrade process, and the directory and subdirectories into which all read-write program data files are copied ready for installation in the future, respectively.

By default, these directories and that of the DownLoadDirectory and PreDownLoadDirectory parameters are subdirectories of the directory specified by the value of the ProgramDataDirectory parameter in the [JadeEnvironment] section of the Jade initialization file and the location of the installation directory on the presentation client.

The following is an example of the directory structure on an application server.

jade (or the directory in which the Jade application server is installed)
  bin (or the name of the application server binary directory)
..\Win32\i686-msoft-win32-ansi
      \download\...              All files and directories to be installed in 
                                 the Jade HOME directory
          \bin
          \moredata
      \predownload\....          All files and directories to be pre-downloaded 
                                 for the Jade HOME directory
      \downloadProgramData\...   All files and directories to be installed in 
                                 the Jade program data directory
          \misc
      \predownloadProgramData\.  All files and directories to be pre-downloaded 
                                 for the Jade program data directory

The following is an example of the directory structure on a presentation client.

..\Jade-home-directory
      \bin\..
      \moredata\...              Example of installed directory under the Jade HOME 
                                 directory
..\Jade-program-data-directory
      \download                  Temporary files and directories prior to 
                                 installation in Jade HOME directory
      \predownload               Current pre-downloaded files for the Jade HOME 
                                 directory
      \downloadProgramData       Temporary files and directories prior to 
                                 installation in program data directory
      \predownloadProgramData\   Latest pre-downloaded files for the program data 
                                 directory
      \misc                      Example of installed directory under the Jade 
                                 program data directory

To support the separation of read‑only and read‑write files at run time, the jaddinst.exe program does not write any files into the Jade installation directory. The JadeWorkDirectory parameter in the [JadeEnvironment] section of the Jade initialization file defines the location of a directory that Jade uses for work files. This directory, which is required for internal use such as interlock files used during downloading, defaults to <jade‑program‑data‑directory>\temp.

If the Jade thin client binaries to be downloaded from the application server are placed in the base download directory (for example, ...download/jade.exe) instead of a subdirectory (for example, .../download/bin/jade.exe), the thin client installation or upgrade issues the following warning in the jommsg.log file on the application server and the thin client download.log file if jade.exe is found in the base download directory.

Warning: Jade.exe is in the download base directory on the app server instead of a sub-directory

e.g. ...\download\Jade.exe instead of ...download\bin\Jade.exe

This discrepancy will be handled, BUT no sub-directory downloading will be performed.

The thin client cache file is also written into this directory if the location has not been specified by the FormCacheFile parameter in the [JadeThinClient] section of the Jade initialization file. The download.log file created by the download install process is output to the log directory specified in the LogDirectory parameter in the [JadeLog] section of the Jade initialization file.

All directories and subdirectories under the download, downloadProgramData, predownload, and predownloadProgramData directories are downloaded to the presentation client. As a result, these directories should contain only those files relevant to a thin client environment. Only the download, downloadProgramData, predownload, and predownloadProgramData subdirectory names in each environment structure are fixed and should therefore not be changed. However, the presentation client directory names must be the same as the directories under the application server download and downloadProgramData directory for each presentation client environment, with the exception of the directory containing the jade.exe executable, which is installed into the equivalent directory on the presentation client. Any directories that are not present are created.

If the presentation client environment matches that of the application server (that is, the hardware type, vendor, operating system version, and the ANSI or Unicode file type), the Jade binary files are taken from the application server installation environment and any such files under the directory specified in the FullJadeInstallDirectory parameter are ignored.

When the presentation client environment differs from that of the application server and a value is specified in the FullJadeInstallDirectory parameter in the environment-specific section of the Jade initialization file, the specified directory in that parameter is used as the source for downloading the Jade thin client binary files to the presentation client. Use this parameter to ensure that the thin client files are downloaded from a standard Jade installation file set without having to maintain a separate copy of the Jade thin client files for the download process.

All files and directories in the application server download and downloadProgramData directories are downloaded to the presentation client using the same directory structure. The first of the following examples is installed into the presentation client Jade install directory C:/41260/. The second of these examples is installed into the C:/41260/a_thin subdirectory of the Jade presentation client install directory C:/41260/.

../i686-msoft-win32-ansi/download/File1.txt
../i686-msoft-win32-ansi/download/a_thin/File2.txt

When files and directories are downloaded to the presentation client from the application server, the directory structure under the application server download directory (for example, ...download/jade.exe) for the architecture of the presentation client is duplicated in the Jade installation directory on the presentation client. The files in those directories on the application server are downloaded and copied to the equivalent directory on the presentation client. (The directories are created if they are not present.) The exception to this, however, is the directory that contains the jade.exe executable on the presentation client and the application server download directory that contains the jade.exe executable, as those directories are assumed to be the equivalent bin directories in both environments.

The result is that all of the files in the download bin directory of the application server are copied to the presentation client bin directory, even if the names are different. In addition all subdirectories of the application server bin directory are copied as subdirectories of the presentation client bin directory. For example, the:

Application server has:

......\download\bin\ (which contains jade.exe)

 .....\download\bin\sub-bin\

Presentation client has:

<Jade-install-directory>\mybin\ (which contains jade.exe)

The result is that the files in bin are copied to mybin and a sub‑bin directory is created as a subdirectory of mybin.

The presentation client DownLoadDirectory and DownLoadProgramDataDirectory parameters in the [JadeThinClient] section of the Jade initialization file specify the temporary location of the respective downloaded read-only and read-write program data files before they are installed.

The JadeWorkDirectory parameter in the [JadeEnvironment] section of the Jade initialization file specifies the location of the Jade presentation client jade.exe or jaddinst.exe program.

The DownLoadVersion, DownLoadDescription, and PreDownLoadDescription parameters in the [JadeAppServer] section of the Jade initialization file are global to the application server. Changing the version causes all presentation client users who attach to the application server and have a different local version to compare their file set with that of the environment type on the application server. In all other situations, automatic download version checking and update occurs only when:

One of the Jade libraries used by the presentation client has a different version from that being run by the application server.
The Jade executable in use by the presentation client has a different version from the file in the directory specified by the DownLoadDirectory parameter in the [environment-type] section of the Jade initialization file that controls the download process for each environment type section (for example, the [i686‑msoft‑win32‑ansi] section).

When the presentation client connects to the application server, a comparison of the release versions and patch numbers of the Jade thin client libraries and the jaddinst programs is performed. If there is a mismatch of any module, a download is initiated by default. If there is a mismatch and the automatic download feature is turned off, a version error is reported.

The current values of the download version and pre‑download versions are stored in the DownLoadVersion and PreDownLoadVersion parameters in the [JadeThinClient] section of the Jade initialization file on the presentation client and are automatically maintained. This enables the use of the same binary (bin) directory for different database systems if unique Jade initialization files are used in each shortcut or command line on the presentation client. As this assumes that each database system is at the same Jade version level, use of each shortcut or command line causes a download to occur when the Jade version level of the database differs.

To perform the installation of downloaded files in Jade thin client mode, the jaddinst file must be available. If this program is not available, a message is logged in the jommsg.log file on the presentation client and the automatic download feature is switched off.

The new jaddinst installation program is therefore not required. If a new jaddinst executable file has been downloaded, a copy of that new file with a name of jade‑binary‑directory\jaddinstall is taken after the latest jade.exe file has been installed on each presentation client. The installation is performed by executing the new jaddinst file so that the old jaddinst file can be backed up and replaced. The temporary jaddinstall executable file is removed when the next thin client session is initiated.

In addition, the [JadeThinClient] section of the Jade initialization file on the presentation client provides the AskToDownload and AskToPreDownload parameters, which are set to true by default. These parameters control whether the thin client download and pre‑download processes are automatically performed.

The download progress form is always displayed as the top window for the first four seconds of its display, after which it reverts to being a normal window. For more details, see "Jade Presentation Client Section [JadeThinClient]", in the Jade Initialization File Reference.