Stellt eine Datenbank (darf KEINE ASE-System-DB wie z.B. „master“ sein !) aus einem (Full-)Backup wieder her.

Um die Prozedur ausführen zu können, muß der Benutzer die sogenannte „sa_role“ („Rolle“ im ASE) besitzen ! Zur Wiederherstellung einer Datenbank reicht eigentlich auch die „oper_role“, aber i.d.R. müssen wir noch weitere Aktionen durchführen (s. z.B. Parameter „KillProcessesOnDBFirst“), die „sa_role“ erfordern, also vereinfachen wir das Ganze und setzen nur diese eine „Rolle“ voraus.

Anmerkungen und Hinweise zum Parameter „DeviceNames“ :

1.) Die Sicherungsdateien („devices“), die das Backup enthalten, sind in „DeviceNames“ (durch „DeviceNamesSeparatedBy“ getrennt) anzugeben - derzeit sind maximal 10 „devices“ erlaubt und der Name eines „devices“ darf nicht mehr als 100 Bytes belegen !

2.) Bei Angabe von „NULL“ gehen wir von einem einzigen „device“ aus, und zwar mit dem Namen „<DatabaseName>_01_full.dump“.
Hintergrund für diesen „fallback“ ist, daß wir davon ausgehen, daß eine „dStore Engine“-Datenbank wiederhergestellt werden soll, die mit mi_DumpDatabase_Ad (die entsprechende „device“-Namen erzeugt, s. Doku dort) gesichert wurde.

3.) Ein „device“-Name darf nur aus Zahlen, den Buchstaben A bis Z (Groß- und Kleinschreibung egal) sowie Leertasten, den „slashes“ („/“ und „\“), Unter- und Bindestrichen („_“, „-“) sowie Punkten („.“) bestehen.

4.) Sicherungsdateien von Datenbanken im ASE können „logisch“ definiert (in der Tabelle „master..sysdevices“) oder sie können „physikalisch“ (Dateiname inkl. Pfad im zugrunde liegenden Betriebssystem) angegeben sein. Falls „NULL“ für „DevicePath“ übergeben wird, gehen wir ZUERST davon aus, daß die „devices“ (in „DeviceNames“ bzw. „<DatabaseName>_01_full.dump“) LOGISCH
angegeben sind. Werden wir NICHT fündig, gehen wir davon aus, daß „DatabaseName“ eine „dStore Engine“-Datenbank ist, die mit mi_DumpDatabase_Ad gesichert wurde, weswegen wir den im „Settings“-Eintrag zum Schlüssel „DumpPath_FullDumpOnly“ oder (falls zu „DumpPath_FullDumpOnly“ nichts konfiguriert ist) „DumpPath“ konfigurierten Wert als Pfad wählen.
Schlägt auch dies fehl (weil z.B. „DatabaseName“ gar keine „Engine“ ist, sprich es keine entsprechende „Settings“-Tabelle gibt oder weil die DB „offline“ ist oder weil keiner der Einträge konfiguriert ist), gibt es einen Fehler !

5.) Wenn mehrere „devices“ in „DeviceNames“ angegeben sind, müssen natürlich ALLE entweder „logisch“ oder „physikalisch“ (s. Punkt 4 oben) sein !

Anmerkungen zum Parameter „AdjustDBUserToLogins“ :

Falls das Backup von einem ANDEREN ASE-Server stammt, gibt es häufig folgende Situation : Die Datenbankbenutzer oder zumindest einige sind keinem oder einem falschen „login“ zugeordnet. Das kommt daher, weil die „logins“ in der „master“-Datenbank gespeichert werden und die Zuordnung „Benutzer zu Login“ über IDs erfolgt (und die sind halt auf dem ASE-Server, von dem das Backup stammt, ANDERS als auf dem aktuellen ASE-Server). Nach der Wiederherstellung gleichen wir daher (natürlich nur wenn „OnlineDatabaseAfterLoad = 1“ - sprich die DB nach dem Laden auch zugreifbar - ist) die Benutzer-Login-Zuordnung ab, sofern „AdjustDBUserToLogins = 1“ ist. D.h. wir versuchen, über den NAMEN (1:1-Zuordnung) zum jeweiligen Benutzer das entsprechende Login zu finden - alle Benutzer, zu denen KEIN gleichnamiges Login existiert, werden gelöscht !

Noch zwei weitere Besonderheiten, deren wir uns im Fall „AdjustDBUserToLogins = 1“ annehmen :

1.) Manchmal lädt man die Produktions-DB in eine Test- oder Entwicklungs-DB, weshalb der Super-Admin (Name entspricht dem Datenbanknamen) dann häufig fehlt (sofern nicht zufällig schon in der Produktions-DB ein Benutzer mit dem Namen der Test-/Entwicklungs-DB angelegt ist). Daher sorgen wir dafür, daß ein Super-Admin vorhanden ist - nätürlich nur, wenn auch ein gleichnamiges login existiert (was aber ja immer der Fall sein sollte, sofern die Engine korrekt installiert wurde).
Hinweise :
a) Da wir das Kennwort des Super-Admins natürlich NICHT kennen, ist es uns aber natürlich NICHT möglich, dafür zu sorgen, daß zum Super-Admin eine entsprechende Person des speziellen Typs „dStoreUser“ existiert (wir könnten natürlich eine anlegen, aber die Passwort-Eigenschaft wäre falsch, weil wir ja irgendeinen „dummy“-Wert nehmen müssten) !
b) Wir sorgen sowohl dafür, daß der Super-Admin in „sysusers“ von „DatabaseName“ vorhanden ist als auch in „UserInfo“.

2.) Wenn eine Datenbank auf einen anderen Server umgezogen wird, treten zwei Probleme auf :
A) Die Logins müssen separat übertragen werden (weil in der „master“-DB), was wir hier natürlich NICHT leisten können
B) Die Benutzer korrigieren wir in „DatabaseName“ selbst ja wie beschrieben, aber : Damit alle Funktionalitäten zur Verfügung stehen, müssen die Benutzer auch in den „dstore“-DBs („dstore“, „dstoreifin“ etc.) existieren (für Prozeduren nämlich, die auf Tabellen in diesen Datenbanken zugreifen). Und genau dafür sorgen wir (wenn „AdjustDBUserToLogins = 1“ ist

Anmerkung zum Parameter „CompressLevel“ :

Falls die Sicherungsdatei(en) komprimiert ist bzw. sind, wobei die „with compression“-Option beim Erstellen des backups verwendet wurde, wird dies automatisch (vom ASE-Backup-Server) erkannt und der Parameter „CompressLevel“ braucht nicht belegt zu werden. Falls jedoch bei der Erstellung die (veraltete) Syntax „compress::<Kompressions-Level>::<Pfad inkl. Dateiname>“ verwendet wurde, muß diese bei der Wiederherstellung bekannt sein (kann also nicht automatisch ermittelt werden). Daher ist in einem solchen Fall der „Kompressions-Level“ über den Parameter „CompressLevel“ anzugeben.
Hinweis : Wenn das backup mit mi_DumpDatabase_Ad gemacht wurde, wobei der dortige Parameter „CompressLevel“ übergeben wurde, muß man beim Wiederherstellen durch diese Prozedur hier „CompressLevel“ NICHT angegeben (weil die Implementierung in mi_DumpDatabase_Ad die „with compression“-Option benutzt) !

Die Prozedur hat keine Rückgaben.

Die Prozedur hat keine Output-Parameter.

Die Rückgabe erfolgt als XML-Dokument welches gegen das Schema Response/EngineProcedure_v1_0.xsd validiert.

Der folgende Link öffnet in einem separaten Fenster den Engine Playground der fest mit dem dbap-demo System verbunden ist:

• mi_LoadDatabase_Ad im Engine Playground öffnen

Unformatierte Ausgabe:

curl -X POST  'http://<partner>-<project>.dstore.de/default/engine/mi_LoadDatabase_Ad?DatabaseName=<value>'

Mit xmllint ⁵⁾ formatierte Ausgabe:

curl -X POST  'http://<partner>-<project>.dstore.de/default/engine/mi_LoadDatabase_Ad?DatabaseName=<value>' | xmllint --format -

use dStore_php\WebService;
 
$service = new WebService\Service( WebService\Scheme::HTTP,'<partner>-<project>.dstore.de', 80);
 
$request = new WebService\Requests\Engine\Procedure\Request(
			new WebService\Requests\AccessData('default'),
	'mi_LoadDatabase_Ad',
		array(
			'DatabaseName' => '<value>',
			// 'DeviceNames' => NULL,
			// 'DeviceNamesSeparatedBy' => ',',
			// 'DevicePath' => NULL,
			// 'KillProcessesOnDBFirst' => 1,
			// 'OnlineDatabaseAfterLoad' => 1,
			// 'AdjustDBUserToLogins' => 1,
			// 'CompressLevel' => NULL
		)
);
 
$service->execute($request);
 
			$xml_result = $request->getResponse()->getBody()->toSimpleXmlDocument();
			$ResultSet = $xml_result->getRowsAsArray();

XML zur Ausführung mit der Methode engine/execute, z.B. per

curl --header 'Content-Type: application/xml' -X POST 'http://<partner>-<kunde>.dstore.de/default/engine/execute' -d '<xml-daten>'

<?xml version="1.0" encoding="UTF-8"?>
<ListOfBatches>
	<Batch No="0">
		<Procedure Name="mi_LoadDatabase_Ad">
			<Parameters>
				<Parameter Name="DatabaseName"><!-- varchar value --></Parameter>
				<!-- <Parameter Name="DeviceNames">NULL</Parameter> -->
				<!-- <Parameter Name="DeviceNamesSeparatedBy">','</Parameter> -->
				<!-- <Parameter Name="DevicePath">NULL</Parameter> -->
				<!-- <Parameter Name="KillProcessesOnDBFirst">1</Parameter> -->
				<!-- <Parameter Name="OnlineDatabaseAfterLoad">1</Parameter> -->
				<!-- <Parameter Name="AdjustDBUserToLogins">1</Parameter> -->
				<!-- <Parameter Name="CompressLevel">NULL</Parameter> -->
			</Parameters>
		</Procedure>
	</Batch>
</ListOfBatches>