Documentation Source Text

Check-in [424270babe]
Login

Many hyperlinks are disabled.
Use anonymous login to enable hyperlinks.

Overview
Comment:Update zipfile docs to remove the capability to insert compressed data.
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA3-256:424270babef04b0177c82d825646dfbc96bb0d3e41f4ca7853b7057c7c308b89
User & Date: dan 2018-01-15 18:55:08
Context
2018-01-16
13:55
Add the infinite-loop UPDATE problem to the bugfix list for 3.22.0. check-in: bb5411e371 user: drh tags: trunk
2018-01-15
18:55
Update zipfile docs to remove the capability to insert compressed data. check-in: 424270babe user: dan tags: trunk
18:50
Make sure 304 responses are always followed by a blank line to signal the client that the response is complete. check-in: b85fcc5367 user: drh tags: trunk
Changes
Hide Diffs Side-by-Side Diffs Ignore Whitespace Patch

Changes to pages/zipfile.in.

   162    162          etc.). In this case, if the string cannot be parsed it is an error.
   163    163   
   164    164   <tr><td> mtime
   165    165   <td>   If NULL is inserted into the mtime column, then the timestamp
   166    166          of the new entry is set to the current time. Otherwise, the specified
   167    167          value is interpreted as an integer and used as is.
   168    168   
   169         -<tr><td> sz, rawdata, data, method
          169  +<tr><td> sz
          170  +<td>   This column must be set to NULL. If a non-NULL value is inserted into
          171  +       this column, or if a new non-NULL value is provided using an UPDATE
          172  +       statement, it is an error.
          173  +
          174  +<tr><td> rawdata
          175  +<td>   This column must be set to NULL. If a non-NULL value is inserted into
          176  +       this column, or if a new non-NULL value is provided using an UPDATE
          177  +       statement, it is an error.
          178  +
          179  +<tr><td> data
          180  +<td>
          181  +       To insert a directory into the archive, this field must be set to 
          182  +       NULL. In this case if a value was explicitly specified for the "mode"
          183  +       column, then it must be consistent with a directory (i.e. it must be
          184  +       true that (mode & 0040000)=0040000). <br><br>
          185  +
          186  +       Otherwise, the value inserted into this field is the file contents
          187  +       for a regular file, or the target of a symbolic link.
          188  +<tr><td> method
   170    189   <td>
   171         -       To insert a directory into the archive, all four of these fields
   172         -       must be set to NULL. In this case if a value was explicitly specified
   173         -       for the "mode" column, then it must be consistent with a directory 
   174         -       (i.e. it must be true that (mode & 0040000)=0040000). <br><br>
   175         -
   176         -       Otherwise, these fields are used to specify the contents of a
   177         -       regular file or the target of a symbolic link. There are three
   178         -       different ways to do this, depending on whether compressed or
   179         -       uncompressed data is being inserted, and whether or not zipfile should
   180         -       automatically choose a compression algorithm and compress the data:
   181         -       <br><br>
   182         -<ol style="margin:0"><li>
   183         -       <b>sz=NULL, rawdata=NULL, data&ne;NULL, method=NULL</b>:
   184         -       Insert uncompressed data, have zipfile automatically decide whether to
   185         -       compress it or not.<p>
   186         -       In this case the value specified for the "data" column is stored as the
   187         -       associated data in the archive. Zipfile automatically compresses it
   188         -       using the deflate algorithm (method=8) if doing so would be advantageous.
   189         -       Otherwise, if the data is not compressible, it is stored verbatim in
   190         -       the archive (method=0).
   191         -
   192         -<li>
   193         -       <b>sz=NULL, rawdata=NULL, data&ne;NULL, method IN (0,8)</b>: 
   194         -       Insert uncompressed data, explictly specify whether or not zipfile
   195         -       should compress it before storing it in the archive.<p>
   196         -       In this case the value supplied for the "method" column must
   197         -       be either 0 or 8. In either case the value specified for the "data"
   198         -       column is stored as the associated data, compressed if 8 was specified
   199         -       for the "method" column, or as is otherwise.
   200         -
   201         -<li>
   202         -       <b>sz&ne;NULL, rawdata&ne;NULL, data=NULL, method&ne;NULL</b>: 
   203         -       Insert pre-compressed data.<p>
   204         -       In this case the value supplied for column "rawdata" must be
   205         -       already compressed according to the integer method supplied for "method"
   206         -       (which can take any unsigned 16-bit value, not just 0 or 8). The size of
   207         -       the uncompressed data in bytes (an integer) must be specified for 
   208         -       column "sz".  
   209         -</ol>
          190  +       This field must be set one of integer values 0 and 8, or else to
          191  +       NULL. <br><br>
          192  +
          193  +       For a directory entry, any value inserted into this field is ignored.
          194  +       Otherwise, if it is set to 0, then the file data or symbolic link
          195  +       target is stored as is in the zip archive and the compression method
          196  +       set to 0. If it is set to 8, then the file data or link target is
          197  +       compressed using deflate compression before it is stored and the
          198  +       compression method set to 8. Finally, if a NULL value is written
          199  +       to this field, the zipfile module automatically decides whether
          200  +       or not to compress the data before storing it.
   210    201   </table>
   211    202   
   212    203   <p> Specifying an explicit value for the rowid field as part of an INSERT
   213    204   statement is not supported. Any value supplied is ignored.
   214    205   
   215    206   <h3> Deleting Zip Archive Entries </h3>
   216    207   
................................................................................
   230    221   editing the archive accessed via virtual table temp.zzz:
   231    222   
   232    223   <codeblock>
   233    224     <i>-- Create a new, empty, archive: </i>
   234    225     CREATE VIRTUAL TABLE temp.newzip USING zipfile('new.zip');
   235    226   
   236    227     <i>-- Copy the contents of the existing archive into the new archive</i>
   237         -  INSERT INTO temp.newzip(name, mode, mtime, sz, rawdata, method) 
   238         -      SELECT name, mode, mtime, sz, rawdata, method FROM temp.zzz;
          228  +  INSERT INTO temp.newzip(name, mode, mtime, data, method)
          229  +      SELECT name, mode, mtime, data, method FROM temp.zzz;
   239    230   </codeblock>
   240    231   
   241    232   <h3> Updating Existing Zip Archive Entries </h3>
   242    233   
   243    234   <p>Existing zip archive entries may be modified using UPDATE statements.
   244    235   
   245    236   <p>The three leftmost columns of a zipfile virtual table, "name", "mode" 
................................................................................
   246    237   and "mtime", may each be set to any value that may be inserted into the same
   247    238   column (see above). If either "mode" or "mtime" is set to NULL, the final 
   248    239   value is determined as described for an INSERT of a NULL value - the current
   249    240   time for "mtime" and either 33188 or 16877 for "mode", depending on whether 
   250    241   or not the values specified for the next four columns of the zipfile table
   251    242   indicate that the entry is a directory or a file.
   252    243   
   253         -<p>If an UPDATE statement does not specify new values for any of the "sz",
   254         -"rawdata", "data" or "method" column, then the data and compression method
   255         -associated with the zipfile entry are left unmodified. But, if a new value
   256         -is specified for even one of these four columns, then the value of any of
   257         -the four for which no explicit value was provided is set to NULL. For
   258         -example, the following two statements are identical:
          244  +<p>It is an error to attempt to set the sz or rawdata field to any value
          245  +other than NULL. 
   259    246   
   260         -<codeblock>
   261         -  UPDATE zzz SET                        data=?              WHERE name=?;
   262         -  UPDATE zzz SET sz=NULL, rawdata=NULL, data=?, method=NULL WHERE name=?;
   263         -</codeblock>
   264         -
   265         -<p>Once these implicit <i>col=NULL</i> clauses are taken into account, the
   266         -combination of values specified for "sz", "rawdata", "data" and "method" 
   267         -are handled in the same way as described above for INSERT statements.
          247  +<p>The data and method columns may also be set as described for an INSERT
          248  +above.  
   268    249