Overview

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.

Because of the changes to the security model in Windows 10, Windows 8, and Windows 7, if you are upgrading presentation clients under Windows 10, Windows 8, or Windows 7, ensure that you have the appropriate privileges or capabilities to install applications. The configuration of Windows’ User Account Control (UAC) and your current user account privileges may affect the behavior of the installation.

The Microsoft Windows C++ 2017 Redistributable Package (x64) is required to be installed on all 64‑bit Windows systems that run JADE 2018. If 32‑bit thin clients are going to be installed, the equivalent C++ 2017 Redistributable Package (x86) will need to be installed. This will be done as part of the normal JADE installation or upgrade process. (This executable is supplied on the JADE distribution media.) Installing this Microsoft redistributable package requires administration privileges. If possible, deploy this package to all workstations before upgrading to JADE 2018, using the appropriate techniques that allow for privileged installations.

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 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.

The [JadeAppServer] section of the JADE initialization file on each application server provides the following parameter, which enables you to upgrade 32‑bit presentation (thin) client binaries to 64‑bit binaries when the client is using a 64‑bit operating system.

UpgradeRuntimeTo64bit

For details, see "Automatic Download Issues and Considerations", later in this appendix.

When a JADE 2016 Windows 32‑bit ANSI or Unicode presentation client connects to a JADE 2018 application server, the presentation client is upgraded to version 2016 Microsoft Visual Studio 2017 binaries, by default. (If the client is not running a JADE version that is using Visual Studio 2005 runtime libraries, the JADE thin client download will not revert to a version that uses Visual Studio 2005 runtime libraries.)

JADE 2018 does not support 32‑bit presentation clients using the Visual Studio 2005 C++ runtime binaries that were required by JADE 6.3 releases.

The presentation client binaries always check against the same version as the binaries themselves; for example, 32‑bit or 64‑bit. You can change them from 64‑bit to 32‑bit, or the reverse, only by re‑installing the presentation client binaries.

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.

If the presentation client binaries are 32‑bit and built with Microsoft Visual Studio 2017, Microsoft Visual Studio 2013, Microsoft Visual Studio 2010, or Microsoft Visual Studio 2005, the application server looks for all files to be downloaded under ..\i686‑msoft‑win32‑ansi or ..\i686‑msoft‑win32‑unicode, if ANSI or Unicode, respectively.

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.
May 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. If the files for:

The thin client (jade.exe) environment is 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.
The non-running environment are not available, they are ignored, no warnings are logged, and the download completes only for the environment that is running.
The required Microsoft redistributable packages are already installed, the JADE installation program skips the vcredict install step. A message is logged accordingly. If the redistributable package is not already installed, the installation fails if you are installing presentation clients and you do not have the appropriate administrator privileges. You must therefore manually install the redistributable package under administrator privileges.

To install Visual C++, execute one of the following from <jade>\<a_>bin or <u_>bin on the release medium, as applicable.
- vcredist_x64.exe
- vcredist_x86.exe

For example:

jade7103.002\Files\Ansi64\a_bin\vcredist_x64.exe

The automatic JADE thin client download process determines if the existing files on the presentation client and new files on the application server are identical. The automatic download rules are as follows. If the file:

Is not present, the file is downloaded.
Length is different, the file is downloaded.
Is an executable (that is, a file of type .dll or .exe), the timestamps of when the two files were linked are compared, rather than the timestamps of when the files were modified. (This timestamp is held in the file contents.)
Is not an executable and the modified timestamps of the two files do not match, an MD5 comparison of the file contents is used to determine if the two files are different.

A file download therefore occurs only when the two files on the presentation client and application server are actually different; not when the timestamps do not match.

The following are examples of directory file names.

i686‑msoft‑win64‑ansi
armv4i-msoft-wce42-unicode
armv4i-msoft-wce50-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:

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

The directory specified in the DownLoadDirectory parameter must have the following two 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 to 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.

The JADE 2018 release rejects a presentation client upgrade from 7.1 or earlier. You must handle a presentation client download from JADE 7.1 or earlier by first upgrading JADE on the presentation client to release 2016. In addition, a JADE 2018 presentation client cannot handle a reversion to JADE 7.1 or earlier.

The only reversion that is guaranteed is from JADE 2018 to JADE release 2016.