Interface de ligne de commande

You can use the macOS Terminal or the Windows console to drive your 4D applications (4D, 4D Server, merged application, and tool4d) using command lines. Cette fonctionnalité vous permet notamment :

• de lancer une base de données à distance, ce qui peut être particulièrement utile pour administrer des serveurs Web.
• d'exécuter des tests automatiques pour vos applications.

Informations de base

Vous pouvez exécuter des lignes de commande pour les applications 4D à l'aide du terminal macOS ou de la console Windows.

• Under macOS, you should use the open command.
• Sous Windows, vous pouvez simplement passer les arguments directement.

Sous macOS, vous pouvez passer les arguments directement en allant dans le dossier contenant l'application, à l'intérieur du package (Contents/MacOS), ce qui permet d'adresser le flux stderr. For example, if the 4D package is located in the MyFolder folder, you must write the command line as follows: /MyFolder/4D.app/Contents/MacOS/4D. However, we recommend that you use the open command whenever you do not need to access the stderr stream.

Lancer une application 4D

Voici une description des lignes de commande et des arguments pris en charge pour lancer les applications 4D.

Syntaxe :

<applicationPath> [--version] [--help] [--project] [<projectPath | packagePath | 4dlinkPath> [--data <dataPath>]] 
[--opening-mode interpreted | compiled] [--create-data] [--user-param <user string>] [--headless] [--dataless]  
[--webadmin-settings-file] [--webadmin-access-key] [--webadmin-auto-start] [--webadmin-store-settings]  
[--utility] [--skip-onstartup] [--startup-method <methodName string>] 

Argument                              	Valeur	Description
applicationPath	Chemin d'accès à 4D, 4D Server, application fusionnée ou tool4d	Lance l'application. S'il ne s'agit pas d'une application headless : identique à un double-clic sur l'application ; lorsqu'elle est appelée sans argument de fichier de structure, l'application est exécutée et la boîte de dialogue "sélectionner une base de données" apparaît.
--version		Affiche la version de l'application et quitte
--help		Affiche le message d'aide et quitte. Autres arguments : -?, -h
--project	projectPath | packagePath | 4dlinkPath	Fichier de projet à ouvrir avec le fichier de données courant. Aucune boîte de dialogue n'apparaît.
--data	dataPath	Fichier de données à ouvrir avec le fichier de projet désigné. S'il n'est pas spécifié, le dernier fichier de données ouvert est utilisé.
--opening-mode	interpreted | compiled	Base de données de requêtes à ouvrir en mode interprété ou compilé. Aucune erreur n'est générée si le mode demandé n'est pas disponible.
--create-data		Crée automatiquement un nouveau fichier de données si aucun fichier de données valide n'est trouvé. Aucune boîte de dialogue n'apparaît. 4D utilise le nom de fichier passé dans l'argument "--data" s'il en exise un (génère une erreur si un fichier du même nom existe déjà).
--user-param	Chaîne utilisateur personnalisée	A string that will be available within the application through the Get database parameter command (the string must not start with a "-" character, which is reserved).
--headless		Lance 4D, 4D Server ou l'application fusionnée sans interface (mode headless). In this mode: The Design mode is not available, database starts in Application mode No toolbar, menu bar, MDI window or splash screen is displayed No icon is displayed in the dock or task bar The opened database is not registered in the "Recent databases" menu The diagnostic log is automatically started (see SET DATABASE PARAMETER, selector 79) Every call to a dialog box is intercepted and an automatic response it provided (e.g. OK for the ALERT command, Abort for an error dialog...). All intercepted commands(*) are logged in the diagnostic log. For maintenance needs, you can send any text to standard output streams using the LOG EVENT command. Note that headless 4D applications can only be closed by a call to QUIT 4D or using the OS task manager.
--dataless		Lance 4D, 4D Server, une application fusionnée ou tool4d en mode sans données. Le mode Dataless est utile lorsque 4D exécute des tâches sans données (compilation de projet par exemple). In this mode: No file containing data is opened, even if specified in the command line or the .4DLink file, or when using the CREATE DATA FILE and OPEN DATA FILE commands. Commands that manipulate data will throw an error. For example, CREATE RECORD throws “no table to apply the command to”. Note: If passed in the command line, dataless mode applies to all databases opened in 4D, as long as the application is not closed. If passed using the .4DLink file, dataless mode only applies to the database specified in the .4DLink file. For more information on .4DLink files, see Project opening shortcuts.
--webadmin-settings-file	Chemin de fichier	Path of the custom WebAdmin .4DSettings file for the WebAdmin web server. Not available with tool4d.
--webadmin-access-key	String	Access key for the WebAdmin web server. Not available with tool4d.
--webadmin-auto-start	Boolean	Status of the automatic startup for the WebAdmin web server. Not available with tool4d.
--webadmin-store-settings		Store the access key and automatic starting parameters in the currently used settings file (i.e. the default WebAdmin.4DSettings file or a custom file designated with the --webadmin-settings-path parameter). Use the --webadmin-store-settings argument to save these settings if necessary. Not available with tool4d.
--utility		Disponible uniquement avec 4D Server. Launches 4D Server in utility mode.
--skip-onstartup		Launches the project without executing any "automatic" methods, including the On Startup and On Exit database methods
--startup-method	Nom de méthode projet (chaîne)	Project method to execute immediately after the On Startup database method (if not skipped with --skip-onstartup).

(*) Some dialogs are displayed before the database is opened, so that it's impossible to write into the Diagnostic log file (licence alert, conversion dialog, database selection, data file selection). Dans ce cas, un message d'erreur est envoyé à la fois dans le flux stderr et dans le journal d'événements système, puis l'application se ferme.

Exemples

Le dossier courant de l'utilisateur est atteint à l'aide de la commande "~" sous macOS et de la commande "%HOMEPATH%" sous Windows.

Lancez une application 4D stockée sur le bureau :

• Sous macOS :

open ~/Desktop/4D.app
open "~/Desktop/4D Server.app"

• Sous Windows :

%HOMEPATH%\Desktop\4D\4D.exe
%HOMEPATH%\Desktop\"4D Server.exe"

Ouvrez un paquet sur macOS :

--args ~/Documents/myDB.4dbase

Ouvrez un fichier de projet :

• Sous macOS :

--args ~/Documents/myProj/Project/myProj.4DProject

• Sous Windows :

%HOMEPATH%\Documents\myProj\Project\myProj.4DProject

Ouvrez un fichier de projet et un fichier de données :

• Sous macOS :

--args --project ~/Documents/myProj/Project/myProj.4DProject --data ~/Documents/data/myData.4DD

• Sous Windows :

--project %HOMEPATH%\Documents\myProj\Project\myProj.4DProject --data %HOMEPATH%\Documents\data\myData.4DD
ou :
/project %HOMEPATH%\Documents\myProj\Project\myProj.4DProject /data %HOMEPATH%\Documents\data\myData.4DD

Ouvrez un fichier .4DLink :

• Sous macOS :

~/Desktop/MyDatabase.4DLink

• Sous Windows :

%HOMEPATH%\Desktop\MyDatabase.4DLink

Lancez l'application en mode compilé et créer un fichier de données s'il n'est pas disponible :

• Sous macOS :

~/Documents/myBase.4dbase --args --opening-mode compiled --create-data true

• Sous Windows :

%HOMEPATH%\Documents\myBase.4dbase\myDB.4db --opening-mode compiled --create-data true

Lancez l'application avec un fichier projet et un fichier de données :

• Sous macOS :

--args --project ~/Documents/myProj/Project/myProj.4DProject --data ~/Documents/data/myData.4DD --user-param "Hello world"

• Sous Windows :

--project %HOMEPATH%\Documents\myProj\Project\myProj.4DProject --data %HOMEPATH%\Documents\data\myData.4DD --user-param "Hello world"

Ouverture sans interface (mode headless) :

• Sous macOS :

--args --project ~/Documents/myProj/Project/myProj.4DProject --data ~/Documents/data/myData.4DD --headless  

• Sous Windows :

--project %HOMEPATH%\Documents\myProj\Project\myProj.4DProject --data %HOMEPATH%\Documents\data\myData.4DD --headless

tool4d

tool4d is a free, lightweight, stand-alone application allowing you to open a 4D project in headless mode and execute some 4D code using the CLI.

tool4d est disponible sur Windows et macOS et est toujours associé à une version de 4D (même version et même numéro de build). Il n'est disponible qu'en anglais.

tool4d est l'outil parfait si vous souhaitez :

• mettre en place une chaîne CI/CD pour votre application 4D,
• utiliser un exécutable 4D léger pour lancer des scripts 4D, par exemple pour exécuter des tests unitaires automatiques.

Utilisation de tool4d

You can get tool4d from the 4D Product download page.

You use tool4d by executing a command line with a standard 4D project. You can use all arguments described in the above table, except --webadmin since this component is disabled in tool4d. Avec tool4d, la séquence spécifique suivante est lancée :

1. tool4d executes the On Startup database method (and all "automatic" methods such as user method), except if the --skip-onstartup argument is passed.
2. tool4d executes the method designated by the --startup-method argument, if any.
3. tool4d executes the On Exit database method, except if the --skip-onstartup argument is passed.
4. tool4d quitte.

On Windows, tool4d is a console application so that the stdout stream is displayed in the terminal (cmd, powershell...).

Notes

• tool4d is always executed headless (the headless command line option is useless).
• The Application type command returns the value 6 ("tool4d") when called from the tool4d application.
• the diagnostic log file is prefixed with "4DDiagnosticLogTool".

Fonctionnalités 4D désactivées

Keep in mind that tool4d runs automatically in headless mode (see --headless in this table), and does neither give access to the 4D IDE nor any of its servers. En particulier, les fonctions suivantes ne sont pas accessibles :

• serveur d'application, serveur Web, serveur SQL,
• planificateur de sauvegarde,
• ODBC et SQL pass-through,
• tous les composants tels que 4D View Pro, 4D SVG, 4D NetKit...,
• correcteur orthographique hunspell,
• japanese spellchecker (mecab library),
• WebAdmin,
• CEF,
• PHP,
• remote debugger (local debugger, TRACE command and breakpoints are ignored in headless applications).

4D Server en mode utilitaire

You can launch a 4D Server instance in a utility mode (headless) by using the --utility CLI option. Dans ce cas, la séquence suivante est déclenchée :

1. 4D Server executes the On Startup database method (and all "automatic" methods such as user method), except if the --skip-onstartup parameter is passed.
2. 4D Server executes the method designated by the --startup-method, if any.
3. 4D Server executes the On Exit database method, except if the --skip-onstartup parameter is passed.
4. 4D Server quitte.

info

Contrairement à tool4d, 4D Server en mode utilitaire a toutes ses fonctionnalités activées. Cependant, le serveur d'application et tous les autres serveurs ne sont pas démarrés.

Voir également

See this blog post for examples of how to use tool4d and 4D Server in utility mode.