Building a project package

4D Developer includes a final application builder to create a project package (final build). This builder simplifies the finalization and deployment process for 4D compiled applications. It automatically handles the specific features of different operating systems and facilitates the deployment of client-server applications.

The application builder allows you to:

• Build a compiled database, without interpreted code,
• Build a stand-alone, double-clickable application, i.e., merged with 4D Volume Desktop, the 4D database engine,
• Build different applications from the same compiled database via an XML project,
• Build homogeneous client-server applications,
• Build client-server applications with automatic updating of client and server parts.
• Save your build settings for future use (Save settings button).

Build application overview

Building a project package can be carried out using:

• either the BUILD APPLICATION command,
• or the Build Application window.

To display the Build Application dialog, select Design > Build Application... from the menu bar.

The Build Application dialog includes several pages that can be accessed using tabs:

Building can only be carried out once the database is compiled. If you select this command without having previously compiled the database, or if the compiled code does not correspond to the interpreted code, a warning dialog box appears indicating that the database must be (re)compiled.

Build application settings

Each build application parameter is stored as an XML key in the application project file named "buildApp.4DSettings" XML file, located in the Settings folder of the database.

Default parameters are used the first time the Build Application dialog box is used. The contents of the project file are updated, if necessary, when you click Build or Save settings. You can define several other XML settings file for the same project and employ them using the BUILD APPLICATION command.

XML keys provide additional options besides those displayed in the Build Application dialog box. The description of these keys are detailed in the 4D XML Keys BuildApplication manual.

Log file

When an application is built, 4D generates a log file in the Logs folder. The log file stores the following information for each build:

• The start and end of building of targets,
• The name and full access path of the files generated,
• The date and time of the build,
• Any errors that occurred.

Application name and destination folder

Enter the name of the application in Application Name.

Specify the folder for the built application in Destination Folder. If the specified folder does not already exist, 4D will create a Build folder for you.

Compiled structure page

This tab allows you to build a standard compiled structure file and/or a compiled component:

Build compiled structure

Builds a database containing only compiled code.

This feature creates a .4dz file within a Compiled Database folder. If you have named your application “MyProject”, 4D will create:

\<destination\>/Compiled Database/\<database name>/\MyProject.4dz

A .4dz file is essentially a zipped (packed) version of the project folder. .4dz files can be used by 4D Server, 4D Volume license (merged applications), and 4D Developer. The compact and optimized size of .4dz files makes project packages easy to deploy.

Include related folders

When you check this option, any folders related to the database are copied into the Build folder as Components and Resources folders. For more information about these folders, refer to Database Architecture.

Build component

Builds a compiled component from the structure.

A component is a standard 4D project in which specific functionalities have been developed. Once the component has been configured and installed in another 4D database (the host database), its functionalities are accessible from the host database. For more information about components, refer to the Developing and installing 4D components" documentation.

If you have named your application, MyComponent, 4D will create a Components folder containing MyComponent.4dbase folder:

\<destination>/Components/name.4dbase/\<name>.4DZ

The MyComponent.4dbase folder contains:

• MyComponent.4DZ file
• A Resources folder - any associated Resources are automatically copied into this folder. Any other components and/or plugins folders are not copied (a component cannot use plug-ins or other components).

Application page

This tab allows you can build a stand-alone, single-user version of your application:

Build stand-alone Application

Checking the Build stand-alone Application option and clicking Build will create a stand-alone (double-clickable) application directly from your database project.

The following elements are required for the build:

• 4D Volume Desktop (the 4D database engine),
• an appropriate license

On Windows, this feature creates an executable file (.exe). On macOS, it handles the creation of software packages.

The principle consists of merging a compiled structure file with 4D Volume Desktop. The functionality provided by the 4D Volume Desktop file is linked with the product offer to which you have subscribed. For more information about this point, refer to the sales documentation and to the 4D Store.

You can define a default data file or allow users to create and use their own data file (see the Data file management section).

It is possible to automate the update of merged single-user applications by means of a sequence of language commands (see Automatic updating of server or single-user applications.

4D Volume Desktop Location

In order to build a stand-alone application, you must first designate the folder containing the 4D Volume Desktop file:

• Windows - the folder contains the 4D Volume Desktop.4DE, 4D Volume Desktop.RSR, as well as various files and folders required for its operation. These items must be placed at the same level as the selected folder.
• macOS - 4D Volume Desktop is provided in the form of a structured software package containing various generic files and folders.

To select the 4D Volume Desktop folder, click on the [...] button. A dialog box appears allowing you to designate the 4D Volume Desktop folder (Windows) or package (macOS).

Once the folder is selected, its complete pathname is displayed and, if it actually contains 4D Volume Desktop, the option for building an executable application is activated.

The 4D Volume Desktop version number must match the 4D Developer Edition version number. For example, if you use 4D Developer v18, you must select a 4D Volume Desktop v18.

Data linking mode

This option lets you choose the linking mode between the merged application and the local data file. Two data linking modes are available:

• By application name (default) - The 4D application automatically opens the most recently opened data file corresponding to the structure file. This allows you to move the application package freely on the disk. This option should generally be used for merged applications, unless you specifically need to duplicate your application.

• By application path - 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).

For more information about the data linking mode, refer to the Last data file opened section.

Generated files

When you click on the Build button, 4D automatically creates a Final Application folder in the specified Destination Folder. Inside the Final Application folder is a subfolder with the name of the specified application in it.

If you have specified "MyProject" as the name of the application, you will find the following files in this subfolder (aka MyProject):

• Windows
  • MyProject.exe - Your executable and a MyProject.rsr (the application resources)
  • 4D Extensions folder, Resources folder, various libraries (DLL), Native Components folder, SASL Plugins folder - Files necessary for the operation of the application
  • Database folder - Includes a Resources folder and MyProject.4DZ file. They make up the compiled structure of the database as well as the database Resources folder. Note: This folder also contains the Default Data folder, if it has been defined (see Data file management.
  • (Optional) Components folder and/or Plugins folder - Contains any components and/or plug-in files included in the database. For more information about this, refer to the Plugins and components page section.
  • Licenses folder - An XML file of license numbers integrated into the application. For more information about this, refer to the Licenses & Certificate section.
  • Additional items added to the 4D Volume Desktop folder, if any (see Customizing the 4D Volume Desktop folder).

All these items must be kept in the same folder in order for the executable to operate.

• macOS
  • A software package named MyProject.app containing your application and all the items necessary for its operation, including the plug-ins, components and licenses. For more information about integrating plug-ins and components, refer to the Plugins and components section. For more information about integrating licenses, refer to the Licenses & Certificate section. Note: In macOS, the Application file command of the 4D language returns the pathname of the ApplicationName file (located in the Contents:macOS folder of the software package) and not that of the .comp file (Contents:Resources folder of the software package).

Customizing 4D Volume Desktop folder

When building a stand-alone application, 4D copies the contents of the 4D Volume Desktop folder into Destination folder > Final Application folder. You're then able to customize the contents of the original 4D Volume Desktop folder according to your needs. You can, for example:

• Install a 4D Volume Desktop version corresponding to a specific language;
• Add a custom PlugIns folder;
• Customize the contents of the Resources folder.

In macOS, 4D Volume Desktop is provided in the form of a software package. In order to modify it, you must first display its contents (Control+click on the icon).

Location of Web files

If your stand-alone 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.

Items must be installed:

• on Windows: in the Final Application\MyProject\Database subfolder.
• on macOS: next to the MyProject.app software package.

Client/Server page

On this tab, you can build customized client-server applications that are homogenous, cross-platform and with an automatic update option.

What is a Client/Server application?

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

• A compiled 4D database,
• The 4D Server application,
• The 4D Volume Desktop application (macOS 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).

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 database 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.4DSettings file. If the connection fails, specific alternative mechanisms can be implemented. You can "force" the display of the standard connection dialog box by holding down the Option (macOS) 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.
• A client/server application can be set so that the client portion can be updated automatically over the network.
• It is also possible to automate the update of the server part through the use of a sequence of language commands (SET UPDATE FOLDER and RESTART 4D).

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

4D Server location

Click on the [...] button and use the Browse for folder dialog box to locate the 4D Server application. In macOS, 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).

Data linking mode

This option lets you choose the linking mode between the merged application and the local data file. Two data linking modes are available:

• By application name (default) - The 4D application automatically opens the most recently opened data file corresponding to the structure file. This allows you to move the application package freely on the disk. This option should generally be used for merged applications, unless you specifically need to duplicate your application.

• By application path - 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).

For more information about the data linking mode, refer to the Last data file opened section.

Build client application

Checking this option generates the client part of your application during the building phase.

4D Volume Desktop

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.

The 4D Volume Desktop version number must match the 4D Developer Edition version number. For example, if you use 4D Developer v18, you must select a 4D Volume Desktop v18.

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.4DSettings 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 paragraph.

Copy of client applications in the server application

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 client application - Check these options so that your Windows client/server application can take advantage of the automatic update mechanism for clients via the network.

• Allow automatic update of Macintosh client application - Check these options so that your Macintosh client/server application can take advantage of the automatic update mechanism for clients via the network.

• Allow automatic update of Macintosh client application - 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 in Windows, you must use the [...] button to designate the 4D Volume Desktop macOS application (provided as a package).

Displaying update notification

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

It 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 (in macOS, 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:

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.

Forcing automatic updates

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. The intervals of authorized numbers are set in the application project using specific XML keys.

Update Error

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.

Generated files

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.

These folders are not generated if an error occurs. In this case, open the 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:

• Windows - Each folder contains the application executable file, named \<ApplicationName>Client.exefor 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.
• macOS - 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 macOS, launch a package by double-clicking it.

The macOS 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 checked 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 macOS and/or Windows format as a compressed file. This file is used during the automatic client application update.

Customizing 4D Volume Desktop folder

When building a double-clickable application, 4D copies the contents of the 4D Volume Desktop folder into the Final Application subfolder of the destination folder. You are then able to customize the contents of the original 4D Volume Desktop folder according to your needs. You can, for instance:

• Install a 4D Volume Desktop version corresponding to a specific language;
• Add a custom PlugIns folder;
• Customize the contents of the Resources folder.

Location of Web files

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

Items must be installed:

• on Windows

  • Server application - in the Client Server executable\ \<ApplicationName>Server\Server Database subfolder.
  • Client application - in the Client Server executable\ \<ApplicationName>Client subfolder.

• on macOS

  • Server application - next to the \<ApplicationName>Server software package.
  • Client application - next to the \<ApplicationName>Client software package.

Plugins & components page

On this tab, you set each plug-in and each component that you will use in your stand-alone or client/server application.

The page lists the elements loaded by the current 4D application:

• Active column - Indicates that the items will be integrated into the application package built. All the items are checked by default. To exclude a plug-in or a component, deselect the check box next to it.

• Plugins and components column - Displays the name of the plug-in/component.

• ID column - Displays the plug-in/component's identification number (if any).

• Type column - Indicates the type of item: plug-in or component.

If you want to integrate other plug-ins or components into the executable application, you just need to place them in a PlugIns or Components folder next to the 4D Volume Desktop application or next to the 4D Server application. The mechanism for copying the contents of the source application folder (see Customizing the 4D Volume Desktop folder) can be used to integrate any type of file into the executable application.

If there is a conflict between two different versions of the same plug-in (one loaded by 4D and the other located in the source application folder), priority goes to the plug-in installed in the 4D Volume Desktop/4D Server folder. However, if there are two instances of the same component, the application will not open.

The use of plug-ins and/or components in a deployment version requires the necessary license numbers.

Licenses & Certificate page

The Licences & Certificate page can be used to:

• designate the license number(s) that you want to integrate into your single-user stand-alone application
• sign the application by means of a certificate in macOS.

Licenses

This tab displays the list of available deployment licenses that you can integrate into your application. By default, the list is empty. You must explicitly add your 4D Developer Professional license as well as each 4D Desktop Volume license to be used in the application built. You can add another 4D Developer Professional number and its associated licenses other than the one currently being used.

To remove or add a license, use the [+] and [-] buttons at the bottom of the window.

When you click on the [+] button, an open file dialog box appears displaying by default the contents of the Licenses folder of your machine. For more information about the location of this folder, refer to the Get 4D folder command.

You must designate the files that contain your Developer license as well as those containing your deployment licenses. These files were generated or updated when the 4D Developer Professional license and the 4D Desktop Volume licenses were purchased.

Once you have selected a file, the list will indicate the characteristics of the license that it contains.

• License # - Product license number
• License - Name of the product
• Expiration date - Expiration date of the license (if any)
• Path - Location on disk

If a license is not valid, a message will warn you.

You can designate as many valid files as you want. When building an executable application, 4D will use the most appropriate license available.

Dedicated "R" licenses are required to build applications based upon "R-release" versions (license numbers for "R" products start with "R-4DDP").

After the application is built, a new deployment license file is automatically included in the Licenses folder next to the executable application (Windows) or in the package (macOS).

OS X signing certificate

The application builder can sign merged 4D applications under macOS (single-user applications, 4D Server and client parts under macOS). Signing an application authorizes it to be executed using the Gatekeeper functionality of macOS when the "Mac App Store and identified Developers" option is selected (see "About Gatekeeper" below).

• Check the Sign application option to include certification in the application builder procedure for OS X. 4D will check the availability of elements required for certification when the build occurs:

This option is displayed under both Windows and macOS, but it is only taken into account for macOS versions.

• Name of certificate - Enter the name of your developer certificate validated by Apple in this entry area. The certificate name is usually the name of the certificate in the Keychain Access utility (part in red in the following example):

To obtain a developer certificate from Apple, Inc., you can use the commands of the Keychain Access menu or go here: http://developer.apple.com/library/mac/#documentation/Security/Conceptual/CodeSigningGuide/Procedures/Procedures.html.

This certificate requires the presence of the Apple codesign utility, which is provided by default and usually located in the “/usr/bin/” folder. If an error occurs, make sure that this utility is present on your disk.

About Gatekeeper

Gatekeeper is a security feature of OS X that controls the execution of applications downloaded from the Internet. If a downloaded application does not come from the Apple Store or is not signed, it is rejected and cannot be launched.

The Sign application option of the 4D application builder lets you generate applications that are compatible with this option by default.

About Notarization

Application notarization is highly recommended by Apple as of macOS 10.14.5 (Mojave) and 10.15 (Catalina), since non-notarized applications deployed via the internet are blocked by default.

In 4D v18, the built-in signing features have been updated to meet all of Apple's requirements to allow using the Apple notary service. The notarization itself must be conducted by the developer and is independent from 4D (note also that it requires installing Xcode). Please refer to this 4D blog post that provides a step-by-step description of the notarization process.

For more information on the notarization concept, please refer to this page on the Apple developer website.

Customizing application icons

4D associates a default icon with stand-alone, server, and client applications, however you can customize the icon for each application.

• macOs - When building a double-clickable application, 4D handles the customizing of the icon. In order to do this, you must create an icon file (icns type), prior to building the application file, and place it next to the project folder.

Apple, Inc. provides a specific tool for building icns icon files (for more information, please refer to Apple documentation).

Your icon file must have the same name as the project file and include the .icns extension. 4D automatically takes this file into account when building the double-clickable application (the .icns file is renamed ApplicationName.icns and copied into the Resources folder; the CFBundleFileIcon entry of the info.plist file is updated).

• Windows - When building a double-clickable application, 4D handles the customizing of its icon. In order to do this, you must create an icon file (.ico extension), prior to building the application file, and place it next to the project folder.

Your icon file must have the same name as the project file and include the .ico extension. 4D automatically takes this file into account when building the double-clickable application.

You can also set specific XML keys in the buildApp.4DSettings file to designate each icon to use. The following keys are available:

• RuntimeVLIconWinPath
• RuntimeVLIconMacPath
• ServerIconWinPath
• ServerIconMacPath
• ClientMacIconForMacPath
• ClientWinIconForMacPath
• ClientMacIconForWinPath
• ClientWinIconForWinPath

Management of data file(s)

Opening the data file

When a user launches a merged application or an update (single-user or client/server applications), 4D tries to select a valid data file. Several locations are examined by the application successively.

The opening sequence for launching a merged application is:

1. 4D tries to open the last data file opened, as described below (not applicable during initial launch).
2. If not found, 4D tries to open the data file in a default data folder next to the .4DZ file in read-only mode.
3. If not found, 4D tries to open the standard default data file (same name and same location as the .4DZ file).
4. If not found, 4D displays a standard "Open data file" dialog box.

Last data file opened

Path of last data file

Any standalone or server applications built with 4D stores the path of the last data file opened in the application's user preferences folder.

The location of the application's user preferences folder corresponds to the path returned by the following statement:

userPrefs:=Get 4D folder(Active 4D Folder)

The data file path is stored in a dedicated file, named lastDataPath.xml.

Thanks to this architecture, when you provide an update of your application, the local user data file (last data file used) is opened automatically at first launch.

This mechanism is usually suitable for standard deployments. However, for specific needs, for example if you duplicate your merged applications, you might want to change the way that the data file is linked to the application (described below).

Configuring the data linking mode

With your compiled applications, 4D automatically uses the last data file opened. By default, the path of the data file is stored in the application's user preferences folder and is linked to the application name.

This may be unsuitable if you want to duplicate a merged application intended to use different data files. Duplicated applications actually share the application's user preferences folder and thus, always use the same data file -- even if the data file is renamed, because the last file used for the application is opened.

4D therefore lets you link the data file path to the application path. In this case, the data file will be linked using a specific path and will not just be the last file opened. You therefore link your data by application path.

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

Duplication when data linked by application name:

Duplication when data linked by application path:

You can select the data linking mode during the build application process. You can either:

• Use the Application page or Client/Server page of the Build Application dialog box.
• Use the LastDataPathLookup XML key (single-user application or server application).

Defining a default data folder

4D allows you to define a default data file at the application building stage. When the application is launched for the first time, if no local data file is found (see opening sequence described above), the default data file is automatically opened silently in read-only mode by 4D. This gives you better control over data file creation and/or opening when launching a merged application for the first time.

More specifically, the following cases are covered:

• Avoiding the display of the 4D "Open Data File" dialog box when launching a new or updated merged application. You can detect, for example at startup, that the default data file has been opened and thus execute your own code and/or dialogs to create or select a local data file.
• Allowing the distribution of merged applications with read-only data (for demo applications, for instance).

To define and use a default data file:

• You provide a default data file (named "Default.4DD") and store it in a default folder (named "Default Data") inside the database project folder. This file must be provided along with all other necessary files, depending on the database configuration: index (.4DIndx), external Blobs, journal, etc. It is your responsibility to provide a valid default data file. Note however that since a default data file is opened in read-only mode, it is recommended to uncheck the "Use Log File" option in the original structure file before creating the data file.
• When the application is built, the default data folder is integrated into the merged application. All files within this default data folder are also embedded.

The following graphic illustrates this feature:

When the default data file is detected at first launch, it is silently opened in read-only mode, thus allowing you to execute any custom operations that do not modify the data file itself.

Management of client connection(s)

The management of connections by client applications covers the mechanisms by which a merged client application connects to the target server, once it is in its production environment.

Connection scenario

The connection procedure for merged client applications supports cases where the dedicated server is not available. The startup scenario for a 4D client application is the following:

• The client application tries to connect to the server using the discovery service (based upon the server name, broadcasted on the same subnet).
  OR
  If valid connection information is stored in the "EnginedServer.4DLink" file within the client application, the client application tries to connect to the specified server address.
• If this fails, the client application tries to connect to the server using information stored in the application's user preferences folder ("lastServer.xml" file, see last step).
• If this fails, the client application displays a connection error dialog box.
  • If the user clicks on the Select... button (when allowed by the 4D developer at the build step, see below), the standard "Server connection" dialog box is displayed.
  • If the user clicks on the Quit button, the client application quits.
• If the connection is successful, the client application saves this connection information in the application's user preferences folder for future use.

Storing the last server path

The last used and validated server path is automatically saved in a file named "lastServer.xml" in the application's user preferences folder. This folder is stored at the following location:

userPrefs:=Get 4D folder(Active 4D Folder)

This mechanism addresses the case where the primary targeted server is temporary unavailable for some reason (maintenance mode for example). When this case occurs for the first time, the server selection dialog box is displayed (if allowed, see below) and the user can manually select an alternate server, whose path is then saved if the connection is successful. Any subsequent unavailability would be handled automatically through the "lastServer.xml" path information.

• When client applications cannot permanently benefit from the discovery service, for example because of the network configuration, it is recommended that the developer provide a host name at build time using the IPAddress key in the "BuildApp.4DSettings" file. The mechanism addresses cases of temporary unavailability.
• Pressing the Alt/Option key at startup to display the server selection dialog box is still supported in all cases.

Availability of the server selection dialog box in case of error

You can choose whether or not to display the standard server selection dialog box on merged client applications when the server cannot be reached. The configuration depends on the value of the ServerSelectionAllowed XML key on the machine where the application was built:

• Display of an error message with no access possible to the server selection dialog box. Default operation. The application can only quit.
  ServerSelectionAllowed: False or key omitted

• Display of an error message with access to the server selection dialog box possible. The user can access the server selection window by clicking on the Select... button. ServerSelectionAllowed: True