void db_backup( SQLCA * sqlca, int op, int file_num, unsigned long page_num, struct sqlda * sqlda);
Muss als Benutzer mit der DBA-Berechtigung, REMOTE DBA-Berechtigung (SQL Remote) oder BACKUP-Berechtigung verbunden sein.
Obwohl diese Funktion eine Möglichkeit bietet, einer Anwendung Sicherungsfunktionen hinzuzufügen, wird empfohlen, diese Aufgabe über die BACKUP-Anweisung auszuführen. Weitere Hinweise finden Sie unter BACKUP-Anweisung.
Welche Aktion ausgeführt wird, hängt vom Wert des Parameters op ab:
DB_BACKUP_START Muss aufgerufen werden, bevor eine Sicherung beginnen kann. Zu einem Zeitpunkt kann immer nur eine Sicherung pro Datenbank auf einem gegebenen Datenbankserver laufen. Datenbank-Checkpoints sind deaktiviert, bis die Sicherung vollständig ist (db_backup wird mit dem Wert op für DB_BACKUP_END aufgerufen). Kann die Sicherung nicht starten, wird der SQLCODE mit SQLE_BACKUP_NOT_STARTED belegt. Andernfalls wird das Feld SQLCOUNT des sqlca mit der Größe der Datenbankseiten belegt. Sicherungen werden Seite für Seite durchgeführt.
Die Parameter file_num, page_num und sqlda werden nicht beachtet.
DB_BACKUP_OPEN_FILE Öffnet die mit file_num angegebene Datenbankdatei, sodass Seiten der angegebenen Datei mit DB_BACKUP_READ_PAGE gesichert werden können. Gültige Dateinummern sind 0 bis DB_BACKUP_MAX_FILE für die Stammverzeichnisdateien und 0 bis DB_BACKUP_TRANS_LOG_FILE für die Transaktionslogdatei. Falls die angegebene Datei nicht existiert, wird SQLCODE mit SQLE_NOTFOUND belegt. Andernfalls enthält SQLCOUNT die Anzahl der Seiten in der Datei, SQLIOESTIMATE enthält einen 32-Bit-Wert (POSIX time_t), der die Zeit angibt, zu der die Datenbankdatei erstellt wurde, und der Name der Betriebssystemdatei befindet sich im Feld sqlerrmc des SQLCA-Bereichs.
Die Parameter page_num und sqlda werden nicht beachtet.
DB_BACKUP_READ_PAGE Eine Seite der Datenbankdatei, die durch file_num festgelegt wird. Der Wert für page_num muss zwischen 0 und einer Zahl unter der Seitenanzahl liegen, die von SQLCOUNT nach einem erfolgreichen Aufruf von db_backup mit dem DB_BACKUP_OPEN_FILE-Vorgang zurückgegeben wurde. Andernfalls wird SQLCODE mit SQLE_NOTFOUND belegt. Der sqlda-Deskriptor sollte mit einer Variablen vom Typ DT_BINARY oder DT_LONG_BINARY eingerichtet werden, die auf einen Puffer zeigt. Der Puffer sollte groß genug sein, um Binärdaten in der Größe zu speichern, wie sie im Feld SQLCOUNT beim Aufruf von db_backup mit dem Vorgang DB_BACKUP_START zurückgegeben werden.
Die Daten in DT_BINARY enthalten eine 2 Byte lange Längenangabe, gefolgt von den eigentlichen Binärdaten, sodass der Puffer mindestens 2 Byte länger sein muss als die Seitengröße.
Dieser Aufruf erzeugt eine der angegebenen Datenbankseiten im Puffer, aber es bleibt der Anwendung überlassen, den Pufferinhalt auf einem Sicherungsdatenträger zu speichern.
DB_BACKUP_READ_RENAME_LOG Die gleiche Aktion wie bei DB_BACKUP_READ_PAGE, außer dass nach der letzten Seite das Transaktionslog zurückgegeben wurde, der Datenbankserver das bestehende Transaktionslog umbenennt und ein neues startet
Falls der Datenbankserver nicht in der Lage ist, das Log zu diesem Zeitpunkt umzubenennen (z.B. können in Datenbanken der Version 7.0.x oder älter unvollständige Transaktionen auftreten), tritt der Fehler SQLE_BACKUP_CANNOT_RENAME_LOG_YET auf. In diesem Fall verwenden Sie nicht die zurückgegebene Seite, sondern erneuern Sie die Anforderung, bis Sie SQLE_NOERROR erhalten, und schreiben Sie dann die Seite. Fahren Sie mit dem Lesen der Seiten fort, bis Sie den Zustand SQLE_NOTFOUND erhalten.
Die Fehlermeldung SQLE_BACKUP_CANNOT_RENAME_LOG_YET kann mehrere Male und für mehrere Seiten auftreten. In Ihrer Wiederholungsschleife sollten Sie eine Verzögerung einbauen, um den Server nicht mit zu vielen Anforderungen zu verlangsamen.
Erhalten Sie die Bedingung SQLE_NOTFOUND, wurde das Transaktionslog erfolgreich gesichert und die Datei umbenannt. Der Name der alten Transaktiondatei wird im Feld sqlerrmc des SQLCA-Bereichs zurückgegeben.
Sie sollten den Wert von sqlda->sqlvar[0].sqlind nach einem db_backup-Aufruf überprüfen. Ist dieser Wert größer als 0 (Null), wurde die letzte Logseite geschrieben und die Logdatei wurde umbenannt. Der neue Name befindet sich nach wie vor in sqlca.sqlerrmc, aber der Wert von SQLCODE ist SQLE_NOERROR.
Danach sollten Sie db_backup nicht nochmals aufrufen, außer Sie möchten Dateien schließen und die Sicherung beenden. Falls Sie das tun, erhalten Sie eine zweite Kopie Ihrer gesicherten Logdatei und SQLE_NOTFOUND.
DB_BACKUP_CLOSE_FILE Muss aufgerufen werden, wenn die Bearbeitung einer Datei abgeschlossen ist, um die mit file_num angegebene Datenbankdatei zu schließen.
Die Parameter page_num und sqlda werden nicht beachtet.
DB_BACKUP_END Muß beim Beenden der Sicherung aufgerufen werden. Keine andere Sicherung kann beginnen, bevor die letzte beendet wurde. Checkpoints werden wieder aktiviert.
Die Parameter file_num, page_num und sqlda werden nicht beachtet.
DB_BACKUP_PARALLEL_START Startet eine parallele Sicherung. Wie bei DB_BACKUP_START kann auf einem Datenbankserver jeweils nur eine Sicherung für eine Datenbank ausgeführt werden. Datenbank-Checkpoints sind deaktiviert, bis die Sicherung vollständig ist (bis db_backup mit dem Wert op für DB_BACKUP_END aufgerufen wird). Wenn die Sicherung nicht starten kann, erhalten Sie SQLE_BACKUP_NOT_STARTED. Andernfalls wird das Feld SQLCOUNT von sqlca mit der Größe der Datenbankseiten belegt.
Der Parameter file_num weist den Datenbankserver an, das Transaktionslog umzubenennen, und startet ein neues, nachdem die letzte Seite des Transaktionslogs zurückgegeben wurde. Wenn der Wert nicht Null ist, wird das Transaktionslog umbenannt oder neu gestartet. Andernfalls wird es nicht umbenannt und neu gestartet. Bei diesem Parameter ist der DB_BACKUP_READ_RENAME_LOG-Vorgang nicht erforderlich, der während eines parallelen Sicherungsvorangs nicht zulässig ist.
Der Parameter page_num informiert den Datenbankserer über die maximale Größe des Clientpuffers, angegeben in Datenbankseiten. Auf der Serverseite versuchen die Reader der parallelen Sicherung, sequenzielle Blöcke von Seiten zu lesen. Dieser Wert informiert den Server darüber, wie viel Speicherplatz diesen Blöcken zugewiesen werden muss. Bei der Übergabe des Werts N weiß der Server, dass der Client maximal N Datenbankseiten gleichzeitig vom Server akzeptiert. Der Server kann Blöcke von Seiten zurückgeben, die kleiner als N sind, wenn er nicht genügend Speicherplatz für Blöcke von N Seiten zuweisen kann. Wenn der Client die Größe der Datenbankseiten erst nach dem Aufruf von DB_BACKUP_PARALLEL_START erfährt, kann dieser Wert dem Server mit DB_BACKUP_INFO bereitgestellt werden. Dieser Wert muss vor dem ersten Abruf von Sicherungsseiten (DB_BACKUP_PARALLEL_READ) bereitgestellt werden.
Wenn Sie mit db_backup eine parallele Sicherung starten, erstellt db_backup keine Schreib-Threads. Der Aufrufer von db_backup muss die Daten empfangen und als Schreiber agieren.
DB_BACKUP_INFO Dieser Parameter liefert dem Datenbankserver zusätzliche Informationen zur parallelen Sicherung. Der Parameter file_num gibt den Typ der bereitgestellten Informationen an und der Parameter page_num liefert den Wert. Sie können folgende zusätzliche Informationen mit DB_BACKUP_INFO festlegen:
DB_BACKUP_INFO_PAGES_IN_BLOCK Das Argument page_num enthält die maximale Anzahl von Seiten, die in einem Block zurückgesendet werden sollen.
DB_BACKUP_INFO_CHKPT_LOG Dies ist die clientseitige Entsprechung zur Option WITH CHECKPOINT LOG der BACKUP-Anweisung. Der page_num-Wert von DB_BACKUP_CHKPT_COPY gibt COPY an, während der Wert DB_BACKUP_CHKPT_NOCOPY für NO COPY steht. Wenn dieser Wert nicht bereitgestellt wird, ist der Standardwert COPY.
DB_BACKUP_PARALLEL_READ Dieser Vorgang liest einen Block von Seiten vom Datenbankserver. Bevor Sie diesen Vorgang aufrufen, verwenden Sie den DB_BACKUP_OPEN_FILE-Vorgang, um alle Dateien zu öffnen, die Sie sichern wollen. DB_BACKUP_PARALLEL_READ ignoriert die Argumente file_num und page_num.
Der sqlda-Deskriptor sollte mit einer Variablen vom Typ DT_LONGBINARY eingerichtet werden, die auf einen Puffer zeigt. Der Puffer muss groß genug sein, um Binärdaten der Größe N Seiten zu speichern (angegeben im DB_BACKUP_START_PARALLEL-Vorgang oder in einem DB_BACKUP_INFO-Vorgang). Weitere Hinweise zu diesem Datentyp finden Sie unter DT_LONGBINARY unter Datentypen in Embedded SQL.
Der Server gibt einen sequenziellen Block von Datenbankseiten für eine bestimmte Datenbankdatei zurück. Die Seitennummer der ersten Seite im Block wird im Feld SQLCOUNT zurückgegeben. Die Dateinummer, zu der die Seiten gehören, wird im Feld SQLIOESTIMATE zurückgegeben. Dieser Wert stimmt mit einer der Dateinummern überein, die in den DB_BACKUP_OPEN_FILE-Aufrufen verwendet wurden. Die Größe der zurückgegebenen Daten ist im Feld stored_len der Variablen DT_LONGBINARY verfügbar. Sie ist immer ein Mehrfaches der Datenbankseitengröße. Während die von diesem Aufruf zurückgegebenen Daten einen Block sequenzieller Seiten für eine bestimmte Datei enthalten, kann nicht sicher davon ausgegangen werden, dass einzelne Datenblöcke in einer sequenziellen Reihenfolge zurückgegeben werden oder dass alle Seiten einer Datenbankdatei vor den Seiten einer anderen Datenbankdatei zurückgegeben werden. Der Aufrufer muss damit rechnen, bei einem bestimmten Aufruf Teile einer anderen Datei zu erhalten, die nicht in einer sequenziellen Reihenfolge sind, oder Teile einer beliebigen geöffneten Datenbankdatei zu erhalten.
Eine Anwendung sollte wiederholte Aufrufe dieses Vorgangs ausführen, bis die Größe der Lesedaten 0 oder der Wert von sqlda->sqlvar[0].sqlind größer als 0 ist. Wenn die Sicherung mit einer Umbenennung und einem Neustart des Transaktionslogs gestartet wird, könnte SQLERROR auf SQLE_BACKUP_CANNOT_RENAME_LOG_YET gesetzt werden. In diesem Fall verwenden Sie nicht die zurückgegebenen Seiten, sondern erneuern Sie die Anforderung, bis Sie SQLE_NOERROR erhalten, und schreiben Sie dann die Daten. Die Fehlermeldung SQLE_BACKUP_CANNOT_RENAME_LOG_YET kann mehrere Male und für mehrere Seiten auftreten. In Ihrer Wiederholungsschleife sollten Sie eine Verzögerung einbauen, damit der Server nicht mit zu vielen Anforderungen verlangsamt wird. Fahren Sie fort, die Seiten zu lesen, bis eine der beiden Bedingungen eingetreten ist.
Das Dienstprogramm dbbackup verwendet folgenden Algorithmus. Beachten Sie, dass es sich nicht um C-Code handelt, und dass keine Fehlerüberprüfung enthalten ist.
sqlda->sqld = 1;
sqlda->sqlvar[0].sqltype = DT_LONGBINARY
/* Allocate LONGBINARY value for page buffer. It MUST have */
/* enough room to hold the requested number (128) of database pages */
sqlda->sqlvar[0].sqldata = allocated buffer
/* Open the server files needing backup */
for file_num = 0 to DB_BACKUP_MAX_FILE
db_backup( ... DB_BACKUP_OPEN_FILE, file_num ... )
if SQLCODE == SQLE_NO_ERROR
/* The file exists */
num_pages = SQLCOUNT
file_time = SQLE_IO_ESTIMATE
open backup file with name from sqlca.sqlerrmc
end for
/* read pages from the server, write them locally */
while TRUE
/* file_no and page_no are ignored */
db_backup( &sqlca, DB_BACKUP_PARALLEL_READ, 0, 0, &sqlda );
if SQLCODE != SQLE_NO_ERROR
break;
if buffer->stored_len == 0 || sqlda->sqlvar[0].sqlind > 0
break;
/* SQLCOUNT contains the starting page number of the block */
/* SQLIOESTIMATE contains the file number the pages belong to */
write block of pages to appropriate backup file
end while
/* close the server backup files */
for file_num = 0 to DB_BACKUP_MAX_FILE
/* close backup file */
db_backup( ... DB_BACKUP_CLOSE_FILE, file_num ... )
end for
/* shut down the backup */
db_backup( ... DB_BACKUP_END ... )
/* cleanup */
free page buffer |
| Kommentieren Sie diese Seite in DocCommentXchange. Senden Sie uns Feedback über diese Seite via E-Mail. |
Copyright © 2009, iAnywhere Solutions, Inc. - SQL Anywhere 11.0.1 |