Engine Installation
===================

1. Weiterführende Hilfe
-----------------------

Lesen Sie auch den Eintrag "Engine Installation" in der PapihelpV12.nsf.
Diese Help-Datenbank ist im Distributions-Paket enthalten.


2. Voraussetzungen
------------------

- HCL Domino Server ab Version 10
  Ältere Domino-Versionen sind nicht freigegeben bzw. nicht getestet.
  Domino 14 ist derzeit noch nicht freigegeben.

- HCL Notes Client

- Betriebssysteme Server:
  Windows Server 2019 oder höher, Windows 10 oder Windows 11

- Betriebssysteme Client:
  Windows / macOS

- Ausreichende Rechte zum Kopieren von Dateien in das
  Domino-Data-Verzeichnis

- Ausreichende Rechte zum Kopieren von Dateien in das
  Domino-Program-Verzeichnis

- Administratorrechte zur Änderung der Notes.INI auf dem Domino-Server
  oder Zugriff auf "Set config" über die Remote-Konsole

- Visual Studio Code wird nur für die komfortable Bearbeitung von
  Engine-Scripts benötigt, nicht für den Betrieb der Engine.


3. Ablage der System-Datenbanken
--------------------------------

Alle System-Datenbanken der Engine sollten in einem Unterverzeichnis
(z. B. "Engine" oder "System") des Domino-Data-Verzeichnisses auf dem
jeweiligen Domino-Server liegen.

Dies sind:

- APICTRL.NSF
- APILOG.NSF
- APIJOB.NSF
- SRVJOBS.NSF

Die Hilfe-Datenbank PapiHelpV12.nsf muss nicht in dieses Verzeichnis.


4. Zugriffsschutz und Signatur
------------------------------

Die ACLs von APICTRL.NSF, APIJOB.NSF und SRVJOBS.NSF sollten grundsätzlich
nur Administratoren und Entwicklern Zugriff ermöglichen.

Auch die APILOG.NSF kann vertrauliche Informationen enthalten und sollte
deshalb ebenfalls auf Administratoren und Entwickler beschränkt sein.

Normale Anwender sollten keinen direkten Zugriff auf APICTRL.NSF,
APIJOB.NSF, APILOG.NSF und SRVJOBS.NSF erhalten.

Optional:
Die Datenbanken sollten mit einer vertrauenswürdigen Server- oder
Administrator-ID signiert werden, um Ausführungs-Prompts des Notes-Clients
zu vermeiden.


5. Lizenz-Datei engine.aei
--------------------------

Die Datei engine.aei, die im Distributions-Paket mitgeliefert wird, wird
in das Domino-Data-Verzeichnis auf dem jeweiligen Domino-Server kopiert.

Dies ist die Lizenz-Datei für die Engine.

Nach dem ersten Start ist diese Lizenz-Datei fest an den Domino-Server
gebunden und kann nicht mehr auf einen anderen Domino-Server übertragen
werden.


6. Installation
---------------

6a. Erstinstallation
~~~~~~~~~~~~~~~~~~~~

Für eine Erstinstallation sind in der Regel folgende Schritte notwendig:

- Domino-Server beenden
- Backup des Domino-Servers erstellen
- System-Datenbanken in ein eigenes Unterverzeichnis, z. B. "Engine",
  im Domino-Data-Verzeichnis kopieren
- Lizenz-Datei engine.aei in das Domino-Data-Verzeichnis kopieren
- Binaries aus dem Distributions-Paket in das Domino-Program-Verzeichnis
  kopieren
- Domino-Server starten
- API Engine über die Domino-Server-Konsole starten:

    load engine

  Danach folgt der Initialisierungslauf.


6b. Initialisierungslauf
~~~~~~~~~~~~~~~~~~~~~~~~

Nach dem Kopieren der Dateien in die entsprechenden Verzeichnisse kann die
Engine über die Domino-Server-Konsole mit folgendem Kommando gestartet
werden:

    load engine

Die Engine erwartet bei einer Neuinstallation, dass die Lizenz-Datei
engine.aei heißt und im Domino-Data-Verzeichnis zu finden ist.

Wenn dies so ist und bisher kein Eintrag APIKeyFilename in der Notes.INI
vorhanden ist, wird ein Initialisierungslauf ausgeführt.

Die Engine setzt beim Initialisierungslauf selbständig eine Reihe von
Einträgen. Die Notes.INI wird entsprechend einer API-Engine-Standard-
Konfiguration um zahlreiche Einträge ergänzt.

Wenn die Datenbanken ihre Standardbezeichnungen haben:

- APICTRL.NSF
- APILOG.NSF
- APIJOB.NSF
- SRVJOBS.NSF

findet die Engine diese beim ersten Startup auch dann, wenn sie in einem
anderen Unterverzeichnis unterhalb des Domino-Data-Verzeichnisses liegen
als "System". Die gefundenen Datenbanken werden anschließend mit ihrem
aktuellen Ort in die Notes.INI eingetragen.

Außerdem trägt sich die API Engine automatisch, jedoch nur bei diesem
Initialisierungslauf, in den Eintrag "ServerTasks" in der Notes.INI ein,
damit sie beim Start des Servers automatisch mit gestartet wird.

Wenn dies nicht gewünscht ist, sollte dieser Eintrag in der Notes.INI
wieder um den Engine-Eintrag bereinigt werden.

Bei API-Lizenzen, die an eine Internet-Aktivierung gebunden sind, wird der
Aktivierungsserver bei diesem ersten Startup automatisch kontaktiert und
die Lizenz an den Server gebunden.

Bei API-Lizenzen, die an eine Internet-Aktivierung gebunden sind, wird
außerdem bei jedem Serverstart der Aktivierungsserver kontaktiert. Es muss
nicht bei jedem Start eine Verbindung hergestellt werden können, aber in
regelmäßigen Abständen ist eine erfolgreiche Verbindung erforderlich, um
die Lizenzlaufzeit zu verlängern.

Dabei werden keine persönlichen Daten und keine Daten aus Datenbanken auf
dem Server an den Aktivierungsserver übermittelt.


Wichtige Notes.INI-Einträge
~~~~~~~~~~~~~~~~~~~~~~~~~~~

Nachfolgend die wichtigsten Notes.INI-Einträge auf dem Server:

    APIKeyFilename=C:\domino\data\engine.AEI
    APIControlDB=SYSTEM\APICTRL.NSF
    APILogFileName=SYSTEM\APILOG.NSF
    APIJobDB=SYSTEM\APIJOB.NSF
    APIToolBox=SYSTEM\SRVJOBS.NSF
    APIFunctionDLLs=naefun1,naemysql
    ...

APIKeyFilename:
    Dieser Eintrag legt die Lizenz-Datei für die Engine fest.
    Nach einem abgeschlossenen Initialisierungslauf kann die Lizenz-Datei
    auch umbenannt werden, z. B. testserver.aei. In diesem Fall muss dieser
    Eintrag in der Notes.INI entsprechend angepasst werden.

APIControlDB:
    Dieser Eintrag legt die Steuerdatenbank für die Engine fest.

APILogFileName:
    Dieser Eintrag legt die Log-Datenbank für die Engine fest.

APIJobDB:
    Dieser Eintrag legt die APIJOB-Datenbank für die Engine fest.
    Die APIJOB ist standardmäßig inaktiv. Siehe hierzu die Hilfe.

APIToolBox:
    Dieser Eintrag legt die Toolbox-Datenbank für die Engine fest.
    Die Toolbox ist die Parameter-Datenbank für eine Sammlung von
    Out-of-the-box-Anwendungen.

APIFunctionDLLs:
    Über diesen Eintrag werden die von der Engine zu ladenden
    @Functions-Bibliotheken festgelegt.

    Im Beispiel werden die Standard-@Functions und die MySQL-@Functions
    geladen. Beide sind im Evaluierungs-Distributions-Paket enthalten.

    Achtung:
    Beim Initialisierungslauf wird nur die Standard-@Functions-DLL
    naefun1 automatisch eingetragen.

    Weitere @Functions-DLLs müssen manuell hinzugefügt werden, z. B.
    naemysql für die MySQL-@Functions.


Beispiel: Engine-Start im Server-Log
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Bei einem erfolgreichen Engine-Start werden Log-Einträge geschrieben.

Die ersten Vorgänge werden im Domino-Server-Log protokolliert:

    > load engine
    06.07.2026 16:19:00   APIKeyFilename=C:\Program Files\HCL\Domino\Data\ENGINE.AEI
    06.07.2026 16:19:00   APICreateTemplateAPIControlDB=0
    06.07.2026 16:19:00   APIControlDB=Engine\APICTRL.NSF
    06.07.2026 16:19:00   SysDB Template Created :APILOG.NTF
    06.07.2026 16:19:01   APILogFileName=Engine\APILOG.NSF
    06.07.2026 16:19:01   APILogTmpFileName=Engine\TMPALOG.NSF
    06.07.2026 16:19:01   SysDB Template Created :APIJOB.NTF
    06.07.2026 16:19:01   APIJobDB=Engine\APIJOB.NSF
    06.07.2026 16:19:02   APIToolBox=Engine\SRVJOBS.NSF
    ...


Beispiel: Engine-Start im APILOG
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Sobald die Engine ihr eigenes Log-File kennt, in der Regel APILOG.NSF,
werden die weiteren Vorgänge dort protokolliert.

Die ersten Einträge schreibt der Scheduler.
Sie finden sich in der Ansicht Scheduler\by Time im APILOG.

Beispiel für eine Installation mit nur der Standard-@Functions-DLL:

    06.07.2026 16:32:20   Engine V12.11 B562 [c]2026 SL-NetSolutions,
                          started with (Engine Scheduler)
    06.07.2026 16:32:20   Engine-Modus is ENGINE
    06.07.2026 16:32:21   Engine License activated
    06.07.2026 16:32:21   Engine License valid until 07.10.2026 13:29:03
    06.07.2026 16:32:21   Engine Standard @Functions V12.11 B562 LOADED
    06.07.2026 16:32:21   Engine Hook Manager not available in this Version

Beispiel für eine Installation mit zusätzlicher MySQL-@Functions-DLL:

    06.07.2026 16:46:40   Engine V12.11 B562 [c]2026 SL-NetSolutions,
                          started with (Engine Scheduler)
    06.07.2026 16:46:40   Engine-Modus is ENGINE
    06.07.2026 16:46:40   Engine License activated
    06.07.2026 16:46:40   Engine License valid until 07.10.2026 13:43:22
    06.07.2026 16:46:40   Engine Standard @Functions V12.11 B562 LOADED
    06.07.2026 16:46:40   Register new Datatype:MYSH (0)
    06.07.2026 16:46:40   Register new Datatype:MYRH (1)
    06.07.2026 16:46:40   Register new Datatype:MYPH (2)
    06.07.2026 16:46:40   Engine MySQL @Functions V12.11.06 LOADED
    06.07.2026 16:46:40   Engine Hook Manager not available in this Version

In der Ansicht Protocol\by Time finden sich die Einträge zu den jeweils
laufenden Engine-Scripts.

Dort findet sich auch das Initialisierungs-Script, das den System-
Datenbanken eigene Replik-IDs gibt, damit nicht alle Engine-Installationen
dieselben Replik-IDs haben.

Der eigentliche Eintrag für dieses ausgeführte Engine-Script enthält
beispielsweise die protokollierten Verarbeitungsschritte des
Initialisierungslaufs.


6c. Engine-Updates
~~~~~~~~~~~~~~~~~~

Die Engine spielt niemals automatisch Updates ein.

Wenn der Aktivierungs- und Update-Server über die Verfügbarkeit eines
Updates informiert, siehe Scheduler-Eintrag im APILOG, ist ein neues
Update verfügbar und kann über den üblichen Weg bei SL Net-Solutions
bezogen werden.

Ein Update wird wieder als Distributions-Paket zur Verfügung gestellt.

Für ein Update sind in der Regel folgende Schritte notwendig:

- Domino-Server beenden
- Backup des Domino-Servers erstellen
- Binaries aus dem Distributions-Paket in das Domino-Program-Verzeichnis
  kopieren
- Domino-Server starten


Design-Updates für System-Datenbanken
-------------------------------------

Wenn ein Datenbank-Design-Update für die System-Datenbanken vorliegt, wird
auch hier empfohlen, zuerst ein Backup der Engine-System-Datenbanken
durchzuführen.

Danach die Engine auf dem Server beenden:

    tell engine exit

Anschließend das Design über einen Notes-Client über

    Anwendung -> Gestaltung aktualisieren

durch die neue Schablone aktualisieren.

Abschließend die Engine über die Server-Konsole wieder starten:

    load engine


Hinweise
--------

Die System-Datenbanken werden anhand ihrer Default-Namen gesucht und in die
Notes.INI eingetragen.

Von den Datenbanken werden NTFs mit den aktuellen Default-Namen im
Domino-Data-Verzeichnis angelegt. Bei APIControlDB werden die enthaltenen
Dokumente in das NTF mit kopiert.

Beispiel:

    APICTRL.NSF -> APICTRL.NTF

Bereits vorhandene Notes.INI-Einträge werden nicht geändert.

Wird bei einer bereits installierten Engine APIKeyFileName aus der
Notes.INI gelöscht, wird nur die AEI neu gesucht.

Wird einer der System-Datenbank-Einträge aus der Notes.INI gelöscht, wird
die betreffende Datenbank neu gesucht und eingetragen. Außerdem wird ein
neues NTF dieser System-Datenbank angelegt.

Verweist ein System-Datenbank-Eintrag der Notes.INI auf eine nicht
existierende Datei, wird die betreffende System-Datenbank aus dem bei der
Installation angelegten NTF neu erzeugt.
