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 Unified Diffs Show Whitespace Changes Patch

Changes to pages/zipfile.in.

162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
...
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
...
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263


264
265
266
267
268
       etc.). In this case, if the string cannot be parsed it is an error.

<tr><td> mtime
<td>   If NULL is inserted into the mtime column, then the timestamp
       of the new entry is set to the current time. Otherwise, the specified
       value is interpreted as an integer and used as is.

<tr><td> sz, rawdata, data, method
<td>
       To insert a directory into the archive, all four of these fields
       must be set to NULL. In this case if a value was explicitly specified
       for the "mode" column, then it must be consistent with a directory 
       (i.e. it must be true that (mode & 0040000)=0040000). <br><br>

       Otherwise, these fields are used to specify the contents of a
       regular file or the target of a symbolic link. There are three
       different ways to do this, depending on whether compressed or
       uncompressed data is being inserted, and whether or not zipfile should
       automatically choose a compression algorithm and compress the data:
       <br><br>
<ol style="margin:0"><li>
       <b>sz=NULL, rawdata=NULL, data&ne;NULL, method=NULL</b>:
       Insert uncompressed data, have zipfile automatically decide whether to
       compress it or not.<p>
       In this case the value specified for the "data" column is stored as the
       associated data in the archive. Zipfile automatically compresses it
       using the deflate algorithm (method=8) if doing so would be advantageous.
       Otherwise, if the data is not compressible, it is stored verbatim in
       the archive (method=0).

<li>
       <b>sz=NULL, rawdata=NULL, data&ne;NULL, method IN (0,8)</b>: 
       Insert uncompressed data, explictly specify whether or not zipfile
       should compress it before storing it in the archive.<p>
       In this case the value supplied for the "method" column must
       be either 0 or 8. In either case the value specified for the "data"
       column is stored as the associated data, compressed if 8 was specified
       for the "method" column, or as is otherwise.

<li>
       <b>sz&ne;NULL, rawdata&ne;NULL, data=NULL, method&ne;NULL</b>: 
       Insert pre-compressed data.<p>
       In this case the value supplied for column "rawdata" must be
       already compressed according to the integer method supplied for "method"
       (which can take any unsigned 16-bit value, not just 0 or 8). The size of
       the uncompressed data in bytes (an integer) must be specified for 
       column "sz".  
</ol>
</table>

<p> Specifying an explicit value for the rowid field as part of an INSERT
statement is not supported. Any value supplied is ignored.

<h3> Deleting Zip Archive Entries </h3>

................................................................................
editing the archive accessed via virtual table temp.zzz:

<codeblock>
  <i>-- Create a new, empty, archive: </i>
  CREATE VIRTUAL TABLE temp.newzip USING zipfile('new.zip');

  <i>-- Copy the contents of the existing archive into the new archive</i>
  INSERT INTO temp.newzip(name, mode, mtime, sz, rawdata, method) 
      SELECT name, mode, mtime, sz, rawdata, method FROM temp.zzz;
</codeblock>

<h3> Updating Existing Zip Archive Entries </h3>

<p>Existing zip archive entries may be modified using UPDATE statements.

<p>The three leftmost columns of a zipfile virtual table, "name", "mode" 
................................................................................
and "mtime", may each be set to any value that may be inserted into the same
column (see above). If either "mode" or "mtime" is set to NULL, the final 
value is determined as described for an INSERT of a NULL value - the current
time for "mtime" and either 33188 or 16877 for "mode", depending on whether 
or not the values specified for the next four columns of the zipfile table
indicate that the entry is a directory or a file.

<p>If an UPDATE statement does not specify new values for any of the "sz",
"rawdata", "data" or "method" column, then the data and compression method
associated with the zipfile entry are left unmodified. But, if a new value
is specified for even one of these four columns, then the value of any of
the four for which no explicit value was provided is set to NULL. For
example, the following two statements are identical:

<codeblock>
  UPDATE zzz SET                        data=?              WHERE name=?;
  UPDATE zzz SET sz=NULL, rawdata=NULL, data=?, method=NULL WHERE name=?;
</codeblock>



<p>Once these implicit <i>col=NULL</i> clauses are taken into account, the
combination of values specified for "sz", "rawdata", "data" and "method" 
are handled in the same way as described above for INSERT statements.








|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<
<
<
<
<
<
<
<
<







 







|
|







 







|
|
<
<
<
<

<
<
<
<
>
>

<
<
<
<
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200









201
202
203
204
205
206
207
...
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
...
237
238
239
240
241
242
243
244
245




246




247
248
249




       etc.). In this case, if the string cannot be parsed it is an error.

<tr><td> mtime
<td>   If NULL is inserted into the mtime column, then the timestamp
       of the new entry is set to the current time. Otherwise, the specified
       value is interpreted as an integer and used as is.

<tr><td> sz
<td>   This column must be set to NULL. If a non-NULL value is inserted into
       this column, or if a new non-NULL value is provided using an UPDATE
       statement, it is an error.

<tr><td> rawdata
<td>   This column must be set to NULL. If a non-NULL value is inserted into
       this column, or if a new non-NULL value is provided using an UPDATE
       statement, it is an error.

<tr><td> data
<td>
       To insert a directory into the archive, this field must be set to 
       NULL. In this case if a value was explicitly specified for the "mode"
       column, then it must be consistent with a directory (i.e. it must be
       true that (mode & 0040000)=0040000). <br><br>

       Otherwise, the value inserted into this field is the file contents
       for a regular file, or the target of a symbolic link.
<tr><td> method
<td>
       This field must be set one of integer values 0 and 8, or else to
       NULL. <br><br>

       For a directory entry, any value inserted into this field is ignored.
       Otherwise, if it is set to 0, then the file data or symbolic link
       target is stored as is in the zip archive and the compression method
       set to 0. If it is set to 8, then the file data or link target is
       compressed using deflate compression before it is stored and the
       compression method set to 8. Finally, if a NULL value is written
       to this field, the zipfile module automatically decides whether
       or not to compress the data before storing it.









</table>

<p> Specifying an explicit value for the rowid field as part of an INSERT
statement is not supported. Any value supplied is ignored.

<h3> Deleting Zip Archive Entries </h3>

................................................................................
editing the archive accessed via virtual table temp.zzz:

<codeblock>
  <i>-- Create a new, empty, archive: </i>
  CREATE VIRTUAL TABLE temp.newzip USING zipfile('new.zip');

  <i>-- Copy the contents of the existing archive into the new archive</i>
  INSERT INTO temp.newzip(name, mode, mtime, data, method)
      SELECT name, mode, mtime, data, method FROM temp.zzz;
</codeblock>

<h3> Updating Existing Zip Archive Entries </h3>

<p>Existing zip archive entries may be modified using UPDATE statements.

<p>The three leftmost columns of a zipfile virtual table, "name", "mode" 
................................................................................
and "mtime", may each be set to any value that may be inserted into the same
column (see above). If either "mode" or "mtime" is set to NULL, the final 
value is determined as described for an INSERT of a NULL value - the current
time for "mtime" and either 33188 or 16877 for "mode", depending on whether 
or not the values specified for the next four columns of the zipfile table
indicate that the entry is a directory or a file.

<p>It is an error to attempt to set the sz or rawdata field to any value
other than NULL. 









<p>The data and method columns may also be set as described for an INSERT
above.