document backup

git-svn-id: https://silmor.de/svn/softmagic/smoke/trunk@220 6e3c4bff-ac9f-4ac1-96c5-d2ea494d3e33

diff --git a/doc/prog_protocol.html b/doc/prog_protocol.html
index 77309f5..94a1a3c 100644 (file)
--- a/doc/prog_protocol.html
+++ b/doc/prog_protocol.html
@@ -803,3 +803,56 @@ The <tt>settemplatedescription</tt> transaction sets a new description for a tem
 <h3>Deleting a Template</h3>
 
 The <tt>deletetemplate</tt> transaction deletes a template from the database. The request contains the file name (full name). The response is empty. The transaction does not return any errors.
+
+<!-- ************************************************************************************
+     ************************************************************************************
+     ************************************************************************************ -->
+
+<h2>Backup</h2>
+
+The currently implemented backup function is DB scheme dependent. This may change in the future.<p>
+
+The machine interface only provides for the retrieval of the backup file. Restoration is done via admin.php.<p>
+
+The <tt>backup</tt> transaction is used to retrieve a backup file. It does not have any parameters. The response is in the special backup format:<p>
+
+<pre>
+startbackup
+backupversion 0
+dbversion 00.02
+table exampletab
+value stringcolumn str TWFnaWNTbW9rZVZlcnNpb24=
+value intcolumn int 1
+value boolcolumn bool 1
+value anothercolumn NULL NULL
+insert
+endofbackup
+</pre>
+
+The format is command oriented: each line is a specific command that can be interpreted by the restore processor:
+
+<table frame="1" border="1">
+<tr><td><b>Command</b></td><td><b>Description</b></td></tr>
+<tr><td>startbackup</td><td>marks the begin of a backup file</td></tr>
+<tr><td>backupversion</td><td>defines the format version (integer version number) of this backup file - this only shows which commands are valid, not what content can be transferred</td></tr>
+<tr><td>dbversion</td><td>version of the database scheme this data is taken from</td></tr>
+<tr><td>table</td><td>marks the start of a new table, has the (scheme-)name of the table as parameter, deletes the current dataset buffer</td></tr>
+<tr><td>value</td><td>adds a value to the current dataset buffer, parameters are the column name, encoding format and value</td></tr>
+<tr><td>insert</td><td>pushes the current dataset buffer into the current table, then empties the dataset buffer</td></tr>
+<tr><td>endofbackup</td><td>marks the end of the backup file, the processor should stop here</td></tr>
+</table><p>
+
+Table cell values are encoded according to the content in the source database. The target database must decode the values according to the format used in the backup file and then escape the value as appropriate for the target database (irrespective of the just decoded source format).<p>
+
+The following encoding formats are currently known:
+<table frame="1" border="1">
+<tr><td><b>Format</b></td><td><b>Description</b></td></tr>
+<tr><td>NULL</td><td>a NULL value, the actual value in the backup file does not matter, the target value is NULL</td></tr>
+<tr><td>int</td><td>integer, the value must be converted into an integer number</td></tr>
+<tr><td>bool</td><td>boolean, the value "1" means true, the value "0" means false, everything else is an error and should be interpreted as NULL</td></tr>
+<tr><td>str</td><td>string or blob, the content is base64 encoded - if it is a string the result of base64 decoding is in UTF-8 encoding</td></tr>
+</table>
+
+
+
+</html>
\ No newline at end of file