Setup4j

Setup4j is step 4 of the Install Guide. It tells Commander4j where your database is, tests the connection, and creates the tables. It is also the tool you run after every upgrade (see Upgrading). Its window title is Host Administration.

Everything Setup4j saves goes into one file, xml/hosts/hosts.xml in the Commander4j folder. If you later set up the scanner web application on Apache Tomcat, you copy that file to the server (see Installation).

Before you start

You need a database ready and these details from Install Database: server name, instance name or port, database name, and either a username and password or the decision to use Windows login.

Open Setup4j

On Windows, open the Start menu, find the Commander4j folder and click Setup4j. On a Mac it is in the Commander4j folder inside Applications. On Linux run Setup4j from the install folder.

The window has three parts:

• Connections on the left: the list of databases Commander4j knows about. A fresh install shows three examples, one for each database type. None of them can connect to anything; they are there to show what a filled-in connection looks like. Users see this list when they log in, so delete the examples once your own connection works.
• The form in the middle: the details of the connection selected on the left.
• Buttons on the right: the actions described below.

Add your connection

The easiest way is to edit the example that matches your database type.

1. Click the example in the Connections list, for instance SQL Server Example Only.
2. Change Description to something users will recognise, such as Production or Test.
3. Check Database Type is right (mySQL, SQL Server or Oracle). The Driver and JDBC URL fields fill themselves in from the other fields; you never type into them.
4. Fill in the connection fields for your database:

Field	SQL Server Express	MySQL / MariaDB	Oracle
Server	localhost, or the server's name or IP address from another PC	localhost or the server name	server name
Database	Commander4j	Commander4j	leave blank
Port	1433	3306	1521
SID	SQLEXPRESS (the instance name; blank for a default instance)	leave blank	the service name or SID
Username / Password	the SQL login, or blank with Integrated Security ticked	commander4j and its password	the schema user and password
Integrated Security	tick to log in as the Windows user (Option A in Install Database)	leave unticked	leave unticked
Trust Server Cert	tick	leave unticked	leave unticked
Collation / CharSet	leave as set	utf8mb4_0900_ai_ci / utf8mb4 (MariaDB: utf8mb4_general_ci / utf8mb4)	leave as set

The other fields (timeouts, timezone, DB Date Time, DB Select Limit, DB Schema, Unique ID) already hold the right values for the database type. Leave them alone.

To start from a blank connection instead, click Add DB Connection. Delete DB Connection removes the selected one.

Test the connection

Click Connect / Check DB. One of three things happens:

• Connected, and the Version Information panel shows Actual Schema Version as -1. Correct for a brand-new empty database: it means Setup4j reached the database and found no Commander4j tables yet. Go to the next section.
• Connected, and the actual and required versions match, with green ticks. The database is already set up for this version of Commander4j. Click Save Configuration and you are done.
• An error message. The status bar at the bottom explains what went wrong. Common causes: TCP/IP not enabled in SQL Server, wrong server or instance name, wrong password, or SQL Server still in Windows-only authentication mode. See Install Database and Install Guide#If something goes wrong.

Create or upgrade the tables

When the actual version is lower than the required version, the AUTO Update DB button becomes available. Click it. Setup4j creates or upgrades every table, view and function, then loads the standard data (menus, permissions, language text, example records).

On an empty database this takes several minutes, and the progress bar at the bottom moves slowly at first. Let it finish. When it does, both versions match and show green ticks.

If the update stops with an error, it is almost always a permissions problem: the database user is not allowed to create tables or views. Fix the permissions as described in Install Database, drop any tables that were created, and run AUTO Update DB again.

Save

Click Save Configuration. Setup4j writes hosts.xml and you can close it.

Tidy-up, once your own connection works: select each example connection and either untick Enabled (it stays in the file but users no longer see it) or click Delete DB Connection.

Next step: First Login.

Other things Setup4j can do

• Enable Splash Screen and Single Instance control how the application starts. Single Instance stops a user opening Commander4j twice on the same PC.
• Protect Configuration with Password stops users opening Setup4j and changing connections.
• Assign to Service links a connection to the Windows interface service on a Full install. See Install Interface Services.
• DB Schema Report lists the tables and columns in the connected database.
• Update Mode, URL App Update and URL Hosts Update configure automatic update checks. They are optional and can be left alone.
• Open Hosts File switches to a different hosts.xml, for example when maintaining connections for a Tomcat server.