Client/Server page

4D allows you to build customized client-server applications that are homogenous, cross-platform and with an automatic update option. Client and server applications are configured on the Client/Server page of the Build Application dialog box.

A client-server application comes from the combination of three items:

• A compiled 4D database,
• The 4D Server application,
• The 4D Volume Desktop application (Mac OS and/or Windows).

Once built, a client-server application is composed of two customized parts: the Server portion (unique) and the Client portion (to install on each client machine). For comparison reasons, remember that a standard deployment using 4D Server requires the 4D Server application, the database structure file, the database data file and the 4D application in remote mode. 

Also, the client-server application is customized and its handling simplified:

• To launch the server portion, the user simply double-clicks on the server application. The structure file does not need to be selected.
• To launch the client portion, the user simply double-clicks the client application, which connects directly to the server application. You do not need to choose a database in a connection dialog box. The client targets the server either using its name, when the client and server are on the same sub-network, or using its IP address, which is set using the IPAddress XML key in the buildapp.xml file (see following section). If the connection fails, specific alternative mechanisms can be implemented, which are described in the Management of connections by client applications section).
  You can also “force” the display of the standard connection dialog box by holding down the Option (Mac OS) or Alt (Windows) key while launching the client application.
  Only the client portion can connect to the corresponding server portion. If a user tries to connect to the server portion using a standard 4D application, an error message is returned and connection is impossible.

Finally, a client/server application can be set so that the client portion can be updated automatically over the network. This function is detailed in the Copy of client applications in the server application section.

It is also possible to automate the update of the server part through the use of a sequence of language commands (see Automatic updating of server or single-user applications).

• Build server application: Check this option to generate the server part of your application during the building phase. You must designate the location on your disk of the 4D Server application to be used. This 4D Server must correspond to the current platform (which will also be the platform of the server application).
  To select the 4D Server folder, click on the [...] button and use the Browse for folder dialog box to locate the 4D Server application. Under Mac OS, you must select the 4D Server package directly.

• Current version: Used to indicate the current version number for the application generated. You may then accept or reject connections by client applications according to their version number. The interval of compatibility for client and server applications is set using specific XML keys (see XML keys of parameters).

• Build client application: Check this option to generate the client part of your application during the building phase. You must designate the location on your disk of the 4D Volume Desktop application to be used. This 4D Volume Desktop must correspond to the current platform (which will also be the platform of the client application). If you want to build a client application for a “concurrent” platform, you must carry out an additional build operation using a 4D application running on that platform. This is only necessary for the initial version of the client application since subsequent updates can be handled directly on the same platform using the automatic update mechanism. For more information about this point, see the following section.
  To select the 4D Volume Desktop folder, click on the [...] button and use the Browse for folder dialog box to locate the application. Under Mac OS, you must select the 4D Volume Desktop package directly.

Note: Starting with 4D v15, the 4D Server and 4D Volume Desktop version numbers must match the 4D Developer Edition version number. For example, if you use 4D Developer v15.4, you have to select a 4D Server v15.4 and a 4D Volume Desktop v15.4.

If you want the client application to connect to the server using a specific address (other than the server name published on the sub-network), you must use the IPAddress XML key in the buildapp.xml file. For more information about this file, refer to the description of the BUILD APPLICATION command. You can also implement specific mechanisms in the event of a connection failure. The different scenarios proposed are described in the Management of connections by client applications section. 

During the build of the executable client/server application, 4D duplicates the contents of the 4D Server folder in the Server subfolder of the destination folder and the contents of the 4D Volume Desktop folder in the Client subfolder of the destination folder. You can then totally customize the contents of the original 4D Server and 4D Volume Desktop folders as necessary. 

For example, you can:

• Install a version of 4D Server that corresponds to a specific language;
• Add files or folders in the PlugIns folder;
• Customize the 4D Extensions folder contents.

Note: Under Mac OS, 4D Server is provided as a package. You must first display its contents (Control+click on its icon) to be able to modify it.

This option lets you choose the linking mode between the merged application and the local data file. Two data linking modes are available. Both have advantages and disadvantages so you should select the mode that best fits your needs.

Note: This option is only available when the Use new architecture for application deployments option is checked (see the Compatibility page section).

• By application name (default)
  In this mode, the 4D application automatically opens the most recently opened data file that corresponds to the structure file. This flexible and intuitive mode allows you to move the application package freely on the disk. It should usually be used for merged applications, unless you specifically need to duplicate your application. 

• By application path
  In this mode, the merged 4D application will parse the application's lastDataPath.xml file and try to open the data file with an "executablePath" attribute that matches the application's full path. If such an entry is found, its corresponding data file (defined through its "dataFilePath" attribute) is opened. Otherwise, the last opened data file is opened (default mode).
  This mode allows you to duplicate your merged applications without breaking the link to the data file. However, with this option, if the application package is moved on the disk, the user will be prompted for a data file, since the application path will no longer match the "executablePath" attribute (after a user has selected a data file, the lastDataPath.xml file is updated accordingly).

For more information about the data linking mode, refer to the Configuring the data linking mode section.

You use the options of this area to set up the mechanism for updating the client parts of your client/server applications using the network each time a new version of the application is generated.

• Allow automatic update of Windows/Macintosh client application: Check these options so that your client/server application can take advantage of the automatic update mechanism for clients via the network.
  If you want to create a cross-platform client application, you must designate the location on your disk of the 4D Volume Desktop application that corresponds to the “concurrent” platform of the build platform. For example, if you build your application under Windows, you must use the [...] button to designate the 4D Volume Desktop Mac OS application (provided as a package).

Updating the client application is necessary when you want to use a new version of 4D Server or one of the components.

Note that the changes made to the custom application (development and/or data) are always transmitted automatically to each client machine. 

Updating the client application prevents the developer from having to manually install new versions of 4D on each client machine. The automatic update procedure for 4D client applications is carried out by means of HTTP and uses a utility application installed on client machines named "updater" that is responsible for managing updates.

The client application update notification is actually carried out automatically following the server application update.

This works as follows: when a new version of the client/server application is built using the application builder, the new client portion is copied as a compressed file in the Upgrade4DClient subfolder of the ApplicationName Server folder (under Mac OS, these folders are included in the server package). If you have followed the process for generating a cross-platform client application, a .4darchive update file is available for each platform:

Note: The additional archive.mac and archive.win files are used to upgrade v13 applications to v14. You can disable their automatic generation by using the BuildV13ClientUpgrades XML key with the BUILD APPLICATION command.

To trigger client application update notifications, simply replace the old version of the server application with the new one and then execute it. The rest of the process is automatic. 

On the client side, when the “old” client application tries to connect to the updated server application, a dialog box is displayed on the client machine, indicating that a new version is available. The user can either update their version or cancel the dialog box.

• If the user clicks OK, the new version is downloaded to the client machine over the network. Once the download is complete, the old client application is closed and the new version is launched and connects to the server. The old version of the application is then placed in the machine’s recycle bin.
• If the user clicks Cancel, the update is cancelled; if the old version of the client application is not in the range of versions accepted by the server (please refer to the following paragraph), the application is closed and connection is impossible. Otherwise (by default), the connection is established.

In some cases, you may want to prevent client applications from being able to cancel the update download. For example, if you used a new version of the 4D Server source application, the new version of the client application must absolutely be installed on each client machine.

To force the update, simply exclude the current version number of client applications (X-1 and earlier) in the version number range compatible with the server application. In this case, the update mechanism will not allow non-updated client applications to connect. For example, if the new version of the client-server application is 6, you can stipulate that any client application with a version number lower than 6 will not be allowed to connect. 

The current version number is set on the Client-Server page of the Build Application dialog box (see above). The intervals of authorized numbers are set in the application project using specific XML keys. For more information about this, refer to XML keys of parameters.

If 4D cannot carry out the update of the client application, the client machine displays the following error message: “The update of the client application failed. The application is now going to quit.”

There are many possible causes for this error. When you get this message, it is advisable to check the following parameters first off:

• Pathnames: Check the validity of the pathnames set in the application project via the Application builder dialog box or via XML keys (for example ClientMacFolderToWin). More particularly, check the pathnames to the versions of 4D Volume Desktop.
• Read/write privileges: On the client machine, check that the current user has write access rights for the client application update.

Once a client/server application is built, you will find a new folder in the destination folder named Client Server executable. This folder contains two subfolders, ApplicationName Client and ApplicationName Server:

Note: These folders are not generated if an error occurs. In this case, open the log file (see Log file) in order to find out the cause of the error. 

The ApplicationName Client folder contains the client portion of the application corresponding to the execution platform of the application builder. This folder must be installed on each client machine. The ApplicationName Server folder contains the server portion of the application. 

The contents of these folders vary depending on the current platform:

• Under Windows, each folder contains the application executable file, named ApplicationName Client.exe for the client part and ApplicationName Server.exe for the server part as well as the corresponding .rsr files. The folders also contain various files and folders necessary for the applications to work and customized items that may be in the original 4D Volume Desktop and 4D Server folders.

• Under Mac OS, each folder contains only the application package, named ApplicationName Client for the client part and ApplicationName Server for the server part. Each package contains all the necessary items for the application to work. Under Mac OS, launch a package by double-clicking it.
  

Note: The Mac OS packages built contain the same items as the Windows subfolders. You can display their contents (Control+click on the icon) in order to be able to modify them. 

If you check the “Allow automatic update of client application” option, an additional subfolder called Upgrade4DClient is added in the ApplicationName Server folder/package. This subfolder contains the client application in Mac OS and/or Windows format as a compressed file. This file is used during the automatic client application update.

If the server and/or client part of your double-clickable application is used as a Web server, the files and folders required by the server must be installed in specific locations. These items are the following:

• cert.pem and key.pem files (optional): These files are used for SSL connections and by data encryption commands,
• Default Web root folder (WebFolder).

Under Windows

• Server application: These items must be installed in the Client Server executable\ApplicationName Server\Server Database subfolder.
• Client application: These items must be installed in the Client Server executable\ApplicationName Client subfolder.

Under Mac OS

• Server application: These items must be installed next to the ApplicationName Server software package.
• Client application: These items must be installed next to the ApplicationName Client software package.