Skip to main content
Version: 19

Command Line Interface

You can use the macOS Terminal or the Windows console to drive your 4D applications (4D and 4D Server) using command lines. More particularly, this functionality allows you to:

  • launch a database remotely, which can be especially useful for administering Web servers.
  • run automatic tests for your applications.

Basic information

You can execute command lines for 4D applications using the macOS Terminal or the Windows Console.

  • Under macOS, you should use the open command.
  • Under Windows, you can just pass the arguments directly.

Under macOS, you can pass the arguments directly by going to the folder where the application is found inside the package (Contents/MacOS path), which allows to address the stderr stream. 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.

Launch a 4D application

Here is a description of command lines and the arguments supported to launch 4D applications.

Syntax:

<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]
ArgumentValueDescription
applicationPathPath of the 4D, 4D Server or merged applicationLaunches the application. Identical to double-clicking the 4D application. When called without structure file argument, the application is executed and the 'select database' dialog box appears.
--versionDisplays application version and exits
--helpDisplays help and exits. Alternate arguments: -?, -h
--projectprojectPath | packagePath | 4dlinkPathProject file to open with the current data file. No dialog box appears.
--datadataPathData file to open with the designated project file. If not specified, 4D uses the last opened data file.
--opening-modeinterpreted | compiledRequests database to open in interpreted or compiled mode. No error is thrown if the requested mode is unavailable.
--create-dataAutomatically creates a new data file if no valid data file is found. No dialog box appears. 4D uses the file name passed in the "--data" argument if any (generates an error if a file with the same name already exists).
--user-paramCustom user stringA string that will be available within the 4D application through the Get database parameter command (the string must not start with a "-" character, which is reserved).
--headlessLaunches the 4D, 4D Server or merged application without interface (headless mode). 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.
    --datalessLaunches 4D, 4D Server or merged application in dataless mode. Dataless mode is useful when 4D runs tasks with no need for data (project compilation for example). 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-fileFile pathPath of the custom WebAdmin .4DSettings file for the WebAdmin web server
    --webadmin-access-keyStringAccess key for the WebAdmin web server
    --webadmin-auto-startBooleanStatus of the automatic startup for the WebAdmin web server
    --webadmin-store-settingsStore 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
    (*) 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). In such case, an error message is thrown both in the stderr stream and the system event log, and then the application quits.

    Examples

    The current folder of the user is reached using the "~ " command under macOS and the "%HOMEPATH%" command under Windows.

    Launch a 4D application stored on the desktop:

    • macOS:
    open ~/Desktop/4D.app
    open "~/Desktop/4D Server.app"
    • Windows:
    %HOMEPATH%\Desktop\4D\4D.exe
    %HOMEPATH%\Desktop\"4D Server.exe"

    Open a package file on macOS:

    --args ~/Documents/myDB.4dbase

    Open a project file:

    • macOS:
    --args ~/Documents/myProj/Project/myProj.4DProject
    • Windows:
    %HOMEPATH%\Documents\myProj\Project\myProj.4DProject

    Open a project file and a data file:

    • macOS:
    --args --project ~/Documents/myProj/Project/myProj.4DProject --data ~/Documents/data/myData.4DD
    • Windows:
    --project %HOMEPATH%\Documents\myProj\Project\myProj.4DProject --data %HOMEPATH%\Documents\data\myData.4DD
    or:
    /project %HOMEPATH%\Documents\myProj\Project\myProj.4DProject /data %HOMEPATH%\Documents\data\myData.4DD

    Open a .4DLink file:

    • macOS:
    ~/Desktop/MyDatabase.4DLink
    • Windows:
    %HOMEPATH%\Desktop\MyDatabase.4DLink

    Open compiled mode and create a data file if not available:

    • macOS:
    ~/Documents/myBase.4dbase --args --opening-mode compiled --create-data true
    • Windows:
    %HOMEPATH%\Documents\myBase.4dbase\myDB.4db --opening-mode compiled --create-data true

    Open a project file and a data file and pass a string as a user parameter:

    • macOS:
    --args --project ~/Documents/myProj/Project/myProj.4DProject --data ~/Documents/data/myData.4DD --user-param "Hello world"
    • Windows:
    --project %HOMEPATH%\Documents\myProj\Project\myProj.4DProject --data %HOMEPATH%\Documents\data\myData.4DD --user-param "Hello world"

    Open without interface (headless mode):

    • macOS:
    --args --project ~/Documents/myProj/Project/myProj.4DProject --data ~/Documents/data/myData.4DD --headless  
    • Windows:
    --project %HOMEPATH%\Documents\myProj\Project\myProj.4DProject --data %HOMEPATH%\Documents\data\myData.4DD --headless