Documentation Source Text

Check-in [33a36d6b95]
Login

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

Overview
Comment:Add a description of how UPDATE statements work to zipfile.in.
Downloads: Tarball | ZIP archive
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA3-256: 33a36d6b95047a9b6c7d461f8accdf147ef2fc345063f9149c645a9af72cd4d5
User & Date: dan 2018-01-13 16:45:17.367
Context
2018-01-13
20:37
Fix typo in the how-to-corrupt document. (check-in: 66c7f7dcd6 user: drh tags: trunk)
16:45
Add a description of how UPDATE statements work to zipfile.in. (check-in: 33a36d6b95 user: dan tags: trunk)
14:33
Update the file-format documentation on serial-types 10 and 11. They are no longer "reserved for expansion" but have shifted to "reserved for internal use". (check-in: 9b212044e0 user: drh tags: trunk)
Changes
Unified Diff Ignore Whitespace Patch
Changes to pages/zipfile.in.
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117

<p>Such a virtual table has the same columns as the table-valued function
described in the previous section. It may be read from using a SELECT 
statement in the same way as the table-valued function can. 

<p>Using the virtual table interface, new entries may be added to a zip
archive by inserting new rows into the virtual table. Entries may be
removed by deleting rows. UPDATE statements are not supported by zipfile
virtual tables. 

<h3 tags="Adding to Zip">Adding Entries to a Zip Archive</h3>

<p>Entries may be added to a zip archive by inserting new rows. The easiest
way to do this is to specify values for the "name" and "data" columns only and
have zipfile fill in sensible defaults for other fields.  To insert a directory
into the archive, set the "data" column to NULL.  For example, to add the







|
<







102
103
104
105
106
107
108
109

110
111
112
113
114
115
116

<p>Such a virtual table has the same columns as the table-valued function
described in the previous section. It may be read from using a SELECT 
statement in the same way as the table-valued function can. 

<p>Using the virtual table interface, new entries may be added to a zip
archive by inserting new rows into the virtual table. Entries may be
removed by deleting rows or modified by updating them.


<h3 tags="Adding to Zip">Adding Entries to a Zip Archive</h3>

<p>Entries may be added to a zip archive by inserting new rows. The easiest
way to do this is to specify values for the "name" and "data" columns only and
have zipfile fill in sensible defaults for other fields.  To insert a directory
into the archive, set the "data" column to NULL.  For example, to add the
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
       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>


       <b>sz=NULL, rawdata=NULL, data&ne;NULL, method=NULL</b>:


       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).
       <br><br>


       <b>sz=NULL, rawdata=NULL, data&ne;NULL, method IN (0,8)</b>: 


       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.
       <br><br>


       <b>sz&ne;NULL, rawdata&ne;NULL, data=NULL, method&ne;NULL</b>: 

       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 (an integer) must be specified for column "sz".


</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>








|
|
>

>
>





<

>

>
>




<

>

>



|
>
>







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
       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>

226
227
228
229
230
231
232





























  <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>




































>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
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
  <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.