Cumba Data Browser for Windows - starting the application
==========================================================

The application runs on the Java runtime shipped in the jre\ folder. There are several
equivalent ways to start it; pick the one your IT policy allows.

1. databrowser.exe
   Double-click it. This launcher is not code-signed; if your organisation blocks unsigned
   programs, use one of the ways below instead.

2. databrowser.cmd
   Double-click it. It starts jre\bin\javaw.exe, which is signed by the Eclipse Foundation
   (Eclipse Temurin). A console window flashes up briefly and closes. The script itself is not
   signed; where scripts are restricted too, use a shortcut (3).

3. A shortcut to jre\bin\javaw.exe (recommended for managed installations)
   Create a shortcut with these fields, replacing C:\Apps\CumbaDataBrowser with the folder you
   unpacked the application into:

     Target:    "C:\Apps\CumbaDataBrowser\jre\bin\javaw.exe" @databrowser.jvmargs -jar databrowser.jar
     Start in:  C:\Apps\CumbaDataBrowser      (required: the two file names are relative to it)
     Icon:      C:\Apps\CumbaDataBrowser\databrowser.ico

   Or, independent of "Start in", with full paths in the Target (for a short installation path;
   the Target field of the shortcut dialog is limited in length):

     Target:    "C:\Apps\CumbaDataBrowser\jre\bin\javaw.exe" "-splash:C:\Apps\CumbaDataBrowser\splash_cup.png" @"C:\Apps\CumbaDataBrowser\databrowser.jvmargs" -jar "C:\Apps\CumbaDataBrowser\databrowser.jar"

   (The -splash: part keeps the start-up screen sharp on a scaled display, 125 % and more; the
   first form needs none, because "Start in" is the installation folder.)

   Software distribution tools (Intune, SCCM, group policy) can deploy the same shortcut.

   Optional helper: create-shortcut.ps1 creates this shortcut in the Start menu (and, with
   -Desktop, on the desktop). Run it in the installation folder:
     powershell -NoProfile -ExecutionPolicy Bypass -File .\create-shortcut.ps1 -Desktop
   ("-ExecutionPolicy Bypass" applies to this one run only; Windows otherwise refuses scripts,
   in particular ones unpacked from a downloaded zip.) If PowerShell scripts are not allowed on
   your computer, create the shortcut by hand as above; the result is the same.

4. From a terminal, for troubleshooting
   In the installation folder, run (in PowerShell or a Command Prompt alike)
     jre\bin\java.exe "@databrowser.jvmargs" -jar databrowser.jar
   Keep the double quotes: PowerShell gives a bare @ a meaning of its own. (Single quotes work in
   PowerShell only; a Command Prompt passes them on to Java.)
   The console stays open and shows start-up errors and the application's messages.

Memory and other JVM options
----------------------------
All four ways read the JVM options from ONE file, databrowser.jvmargs. To let the application use
more memory, open it in a text editor, change the line

  -Xmx4g

for example to -Xmx8g, save it, and restart the application. Save the file as plain text (ANSI, or
UTF-8 without a byte-order mark - Java does not skip one); in a script, write it with Set-Content -Encoding ASCII - not with ">" or Out-File in
Windows PowerShell 5.1, which write UTF-16, an encoding Java cannot read in this file.

Application settings
--------------------
Settings such as the AI chat provider or a proxy belong in
databrowser.conf - preferably in your own copy at
%USERPROFILE%\.cumbaDataBrowser\databrowser.conf, which an update leaves alone. The comments at the
top of databrowser.conf explain how.

Administrators: a config.json in the installation folder gives every user default settings and
can lock settings against change (for example the AI gateway URL). See ADMIN.md and
config.json.example in the installation folder. If that file is broken, the application shows a
message naming it and does not start.

A data browser WITHOUT the AI assistant: delete lib\cumba-databrowser-ai-*.jar,
lib\cumba-ai-*.jar and lib\commonmark-*.jar from the installation (the application starts
without the AI menu entries and the chat), or keep them and lock the assistant off for every
user in that config.json:
  {"$policy": {"locked": ["extensions.ai.enabled"]}, "extensions": {"ai": {"enabled": false}}}
Users switch it under Edit > Settings > Extensions when it is not locked.

Opening data sets from Explorer
-------------------------------
The data browser opens a data set given on its command line - and that is what a double-click
in Explorer does once the file type is associated with it: right-click a .sas7bdat (or .xpt,
.csv, .xlsx, .parquet, .rds, .xml for Define-XML, ...), choose "Open with" > "Choose another app",
pick databrowser.exe (or the shortcut's javaw.exe is NOT the right choice - pick databrowser.exe
or databrowser.cmd) in the installation folder, and tick "Always". Nothing is written to the
registry by the application itself; this distribution does not register file types.

A data set opens THROUGH ITS FOLDER: the folder becomes a library (named after the folder, e.g.
"SDTM_DATA"), and the data set a tab of it, so the other data sets of the folder are one click
away. A folder that is already open as a library is reused; selecting several files of one folder
and pressing Enter opens them in ONE library.

Single instance
---------------
One data browser runs per Windows user: opening a data set while the data browser already runs
brings its window to the front and opens the data set there (in the last active window) - no
second data browser starts. A dialog open in the data browser is brought to the front first, and
the data set opens once it is closed. This holds for databrowser.exe, databrowser.cmd and the
shortcut alike, and for every installed version (the instance is per user, not per installation).

  - A separate data browser for one time:  databrowser.exe --new-instance
  - Switch it off for good:  Edit > Settings > General > Startup  in the application; it
    writes  cumba.single.instance = ${sys:cumba.single.instance:-false}  into your user
    databrowser.conf (above). Switch it on the same way.

The lock and the socket of the running instance live in
%USERPROFILE%\.cumbaDataBrowser\instance. If a second window opens although single-instance mode
is on, the log (%USERPROFILE%\.cumbaDataBrowser\logs) says why in its "Single instance: ..." lines.
