Documentation Source Text

Check-in [c5aa49ff35]
Login

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

Overview
Comment:Improve the internal links from text to glossary definitions in fileformat.html. Also fix a bunch of issues reported by John Machin on the mailing list.
Downloads: Tarball | ZIP archive
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA1: c5aa49ff3588e33fb2e71d012ca7fbe3c5d0454a
User & Date: dan 2009-05-26 23:13:58.000
Context
2009-05-26
23:52
Fix an error in the previous commit. A "todo" note was added in the wrong place. (check-in: e0634484e3 user: dan tags: trunk)
23:13
Improve the internal links from text to glossary definitions in fileformat.html. Also fix a bunch of issues reported by John Machin on the mailing list. (check-in: c5aa49ff35 user: dan tags: trunk)
15:13
Add a "todo" note to fix the schema file-format range. Also fix another todo in fileformat.html. (check-in: 14e677d1dc user: dan tags: trunk)
Changes
Unified Diff Ignore Whitespace Patch
Changes to images/fileformat/rtdocs.css.
54
55
56
57
58
59
60
61
62
63
64
65

66
67
68
69
70
71
72
73
  **     <p class=todo>Longer todo note.</p>
  */
  .todo        { color: #AA3333 ; font-style : italic }
  .todo:before { content: 'TODO:' }
  p.todo       { border: solid #AA3333 1px; padding: 1ex }

  cite a, cite a:visited { color: inherit; text-decoration: none ; font-style: normal; }
  .defnlink    { 
    color: inherit; 
    text-decoration: none;
    font-style: italic;
  }

  .defnlink:visited    { color: inherit }
  h1 .defnlink, h2 .defnlink, h3 .defnlink, h4 .defnlink, .defn .defnlink{ font-style: inherit }
  :link:hover,:visited:hover { background: wheat }

  img {
    display:block;
  }








|
|

<

>
|







54
55
56
57
58
59
60
61
62
63

64
65
66
67
68
69
70
71
72
73
  **     <p class=todo>Longer todo note.</p>
  */
  .todo        { color: #AA3333 ; font-style : italic }
  .todo:before { content: 'TODO:' }
  p.todo       { border: solid #AA3333 1px; padding: 1ex }

  cite a, cite a:visited { color: inherit; text-decoration: none ; font-style: normal; }
  .defnlink, .reqlink { 
    color: inherit;
    text-decoration: none;

  }
  .defnlink { font-style: italic }
  .defnlink:visited,.reqlink:visited { color: inherit }
  h1 .defnlink, h2 .defnlink, h3 .defnlink, h4 .defnlink, .defn .defnlink{ font-style: inherit }
  :link:hover,:visited:hover { background: wheat }

  img {
    display:block;
  }

Changes to pages/fileformat.in.
17
18
19
20
21
22
23

24
25
26
27

28
29
30
31
32
33
34
# the process in which this document is converted into HTML, TCL script runs
# and imports requirements from that file over into this file whenever you
# see:
#            <t*l>fileformat_import_requirement H00000</t*l>
#
unset -nocomplain ffreq
hd_read_requirement_file $::DOC/req/hlr30000.txt ffreq

proc fileformat_import_requirement {reqid} {
  return [lindex $::ffreq($reqid) 1]
}
proc fileformat_import_requirement2 {reqid} {

  return "<p class=req id=$reqid>[fileformat_import_requirement $reqid]</p>"
}
###############################################################################

catch { array unset ::SectionNumbers }
set ::SectionNumbers(1) 0
set ::SectionNumbers(2) 0







>




>







17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
# the process in which this document is converted into HTML, TCL script runs
# and imports requirements from that file over into this file whenever you
# see:
#            <t*l>fileformat_import_requirement H00000</t*l>
#
unset -nocomplain ffreq
hd_read_requirement_file $::DOC/req/hlr30000.txt ffreq
set ::Requirements [list]
proc fileformat_import_requirement {reqid} {
  return [lindex $::ffreq($reqid) 1]
}
proc fileformat_import_requirement2 {reqid} {
  lappend ::Requirements $reqid
  return "<p class=req id=$reqid>[fileformat_import_requirement $reqid]</p>"
}
###############################################################################

catch { array unset ::SectionNumbers }
set ::SectionNumbers(1) 0
set ::SectionNumbers(2) 0
83
84
85
86
87
88
89
90






91


92
93
94
95
96







97
98
99




100
101
102
103
104

105
106
107
108
109
110
111
112
113
114
115
116



117
118
119
120
121
122
123
      </center>
  }
}

proc sort_by_length {lhs rhs} {
  return [expr [string length $lhs] - [string length $rhs]]
}







proc FixReferences {body} {


  foreach E [lsort -decr -index 1 -command sort_by_length $::Glossary] {
    # puts $E
    foreach {term anchor} $E {}
    set re [string map {" " [-[:space:]]+} $term]
    set re "${re}s?"







    set body [regsub -all -nocase $re $body "<a class=defnlink href=\"#$anchor\">\\0</a>"]
    # set body [regsub -all -nocase {(defnlink[^<]*) } $body "\\1&20;"]
  }





  foreach {key value} [array get ::References] {
    foreach {zNumber zTitle} $value {}
    lappend l <cite>$key</cite> "<cite><a href=\"#$key\" title=\"$zTitle\">$zNumber</a></cite>"
  }

  set body [string map $l $body]
}

set ::Glossary {}
proc Glossary {term definition} {
  set anchor [string map {" " _ ' _} $term]
  set anchor "glossary_$anchor"
  lappend ::Glossary [list $term $anchor]

  return "<tr><td class=defn><a name=\"$anchor\"></a>$term <td>$definition"
}




proc Table {} {
  set ::Stripe 1
  return "<table class=striped>"
}
proc Tr {} {
  set ::Stripe [expr {($::Stripe+1)%2}]
  if {$::Stripe} {








>
>
>
>
>
>

>
>





>
>
>
>
>
>
>
|


>
>
>
>





>








<



>
>
>







85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134

135
136
137
138
139
140
141
142
143
144
145
146
147
      </center>
  }
}

proc sort_by_length {lhs rhs} {
  return [expr [string length $lhs] - [string length $rhs]]
}

set ::Random 0
proc randomstring {} {
  incr ::Random
  return [expr $::Random + rand()]
}

proc FixReferences {body} {
  if {[info commands hd_resolve_2ndpass] ne ""} return 

  foreach E [lsort -decr -index 1 -command sort_by_length $::Glossary] {
    # puts $E
    foreach {term anchor} $E {}
    set re [string map {" " [-[:space:]]+} $term]
    set re "${re}s?"

    while { [regexp -nocase $re $body thisterm] } {
      set xxx [randomstring]
      set body [regsub -nocase $re $body $xxx]
      lappend l $xxx "<a class=defnlink href=\"#$anchor\">$thisterm</a>"
    }

    # set body [regsub -all -nocase $re $body "<a class=defnlink href=\"#$anchor\">\\0</a>"]
    # set body [regsub -all -nocase {(defnlink[^<]*) } $body "\\1&20;"]
  }

  foreach R $::Requirements {
    set body [regsub -all "(\[^=\])$R" $body "\\1<a class=reqlink href=#$R>$R</a>"]
  }

  foreach {key value} [array get ::References] {
    foreach {zNumber zTitle} $value {}
    lappend l <cite>$key</cite> "<cite><a href=\"#$key\" title=\"$zTitle\">$zNumber</a></cite>"
  }

  set body [string map $l $body]
}

set ::Glossary {}
proc Glossary {term definition} {
  set anchor [string map {" " _ ' _} $term]
  set anchor "glossary_$anchor"
  lappend ::Glossary [list $term $anchor]

  return "<tr><td class=defn><a name=\"$anchor\"></a>$term <td>$definition"
}

# Procs to generate <table> and <tr> tags. They also give alternating rows
# of the table a grey background, which can make it easier to read.
# 
proc Table {} {
  set ::Stripe 1
  return "<table class=striped>"
}
proc Tr {} {
  set ::Stripe [expr {($::Stripe+1)%2}]
  if {$::Stripe} {
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874

      <ul>
        <li> The file-format write version (single byte field, byte offset 18), 
             is always set to 0x01.
        <li> The file-format read version (single byte field, byte offset 19), 
             is always set to 0x01.
        <li> The number of unused bytes on each page (single byte field, byte 
             offset 20), is always set to 0x01.
        <li> The maximum fraction of an index B-Tree page to use for embedded content 
	     (single byte field, byte offset 21), is always set to 0x40.  <li>
	     The minimum fraction of an index B-Tree page to use for embedded
	     content when using overflow pages (single byte field, byte 
             offset 22), is always set to 0x20.
	<li> The minimum fraction of a table B-Tree page to use for embedded
	     content when using overflow pages (single byte field, byte offset 23),







|







884
885
886
887
888
889
890
891
892
893
894
895
896
897
898

      <ul>
        <li> The file-format write version (single byte field, byte offset 18), 
             is always set to 0x01.
        <li> The file-format read version (single byte field, byte offset 19), 
             is always set to 0x01.
        <li> The number of unused bytes on each page (single byte field, byte 
             offset 20), is always set to 0x00.
        <li> The maximum fraction of an index B-Tree page to use for embedded content 
	     (single byte field, byte offset 21), is always set to 0x40.  <li>
	     The minimum fraction of an index B-Tree page to use for embedded
	     content when using overflow pages (single byte field, byte 
             offset 22), is always set to 0x20.
	<li> The minimum fraction of a table B-Tree page to use for embedded
	     content when using overflow pages (single byte field, byte offset 23),
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
        [Tr]<td style="white-space:nowrap">Associated table name.
            <td>A string value. For "table" 
            or "view" records this is a copy of the second (previous) value. 
            For "index" and "trigger" records, this field is set to the name 
            of the associated database table.
        [Tr]<td style="white-space:nowrap">The "root page" number. 
            <td>For "trigger" and "view" records, as well as "table" records
                associated with virtual tables, this is set to NULL. For other
                "table" and "index" records (including those associated with
                UNIQUE or PRIMARY KEY clauses), this field contains the root
                page number (an integer) of the B-Tree structure that contains
                the table or index data.
        [Tr]<td>The SQL statement.
            <td>A string value. The SQL statement used to create the schema
                item (i.e.  the complete text of an SQL "CREATE TABLE"
                statement). This field contains an empty string for table
                entries associated with PRIMARY KEY or UNIQUE clauses.







|
|
|







1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
        [Tr]<td style="white-space:nowrap">Associated table name.
            <td>A string value. For "table" 
            or "view" records this is a copy of the second (previous) value. 
            For "index" and "trigger" records, this field is set to the name 
            of the associated database table.
        [Tr]<td style="white-space:nowrap">The "root page" number. 
            <td>For "trigger" and "view" records, as well as "table" records
	        associated with virtual tables, this is set to integer value 0. 
		For other "table" and "index" records (including those associated 
		with UNIQUE or PRIMARY KEY clauses), this field contains the root
                page number (an integer) of the B-Tree structure that contains
                the table or index data.
        [Tr]<td>The SQL statement.
            <td>A string value. The SQL statement used to create the schema
                item (i.e.  the complete text of an SQL "CREATE TABLE"
                statement). This field contains an empty string for table
                entries associated with PRIMARY KEY or UNIQUE clauses.
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182

      [Table]
        [Tr]<th>Decimal<th>Hexadecimal        <th>Variable Length Integer
        [Tr]<td>43     <td>0x000000000000002B <td>0x2B
        [Tr]<td>200815 <td>0x000000000003106F <td>0x8C 0xA0 0x6F
        [Tr]<td>-1     <td>0xFFFFFFFFFFFFFFFF 
            <td>0xFF 0xFF 0xFF 0xFF 0xFF 0xFF 0xFF 0xFF 0xFF
        [Tr]<td>-78056 <td>0xFFFFFFFFFFFECD56
            <td>0xFF 0xFF 0xFF 0xFF 0xFF 0xFF 0xFD 0xCD 0x56
      </table>

          [fileformat_import_requirement2 H30520]
          [fileformat_import_requirement2 H30530]
          [fileformat_import_requirement2 H30540]
          [fileformat_import_requirement2 H30550]







|







1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206

      [Table]
        [Tr]<th>Decimal<th>Hexadecimal        <th>Variable Length Integer
        [Tr]<td>43     <td>0x000000000000002B <td>0x2B
        [Tr]<td>200815 <td>0x000000000003106F <td>0x8C 0xA0 0x6F
        [Tr]<td>-1     <td>0xFFFFFFFFFFFFFFFF 
            <td>0xFF 0xFF 0xFF 0xFF 0xFF 0xFF 0xFF 0xFF 0xFF
        [Tr]<td>-78506 <td>0xFFFFFFFFFFFECD56
            <td>0xFF 0xFF 0xFF 0xFF 0xFF 0xFF 0xFD 0xCD 0x56
      </table>

          [fileformat_import_requirement2 H30520]
          [fileformat_import_requirement2 H30530]
          [fileformat_import_requirement2 H30540]
          [fileformat_import_requirement2 H30550]
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
            <td>The literal SQL integer 1 (type SQLITE_INTEGER). The value
                consumes zero bytes of space in the record's data area.
                Values of this type are only present in databases with
                a schema file format (the 32-bit integer at byte offset 44
                of the database header) value of 4 or greater.

        [Tr]<td style="white-space:nowrap"><i>bytes</i> * 2 + 12
            <td>Even values greater than 12 are used to signify a blob of
                data (type SQLITE_BLOB) (<i>n</i>-12)/2 bytes in length, where
                <i>n</i> is the integer value stored in the record header.
                
        [Tr]<td style="white-space:nowrap"><i>bytes</i> * 2 + 13
            <td>Odd values greater than 12 are used to signify a string
                (type SQLITE_TEXT) (<i>n</i>-13)/2 bytes in length, where
                <i>n</i> is the integer value stored in the record header.
      </table>
      <p>







|
|
|







1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
            <td>The literal SQL integer 1 (type SQLITE_INTEGER). The value
                consumes zero bytes of space in the record's data area.
                Values of this type are only present in databases with
                a schema file format (the 32-bit integer at byte offset 44
                of the database header) value of 4 or greater.

        [Tr]<td style="white-space:nowrap"><i>bytes</i> * 2 + 12
	    <td>Even values greater than or equal to 12 are used to signify a 
	        blob of data (type SQLITE_BLOB) (<i>n</i>-12)/2 bytes in length, 
	        where <i>n</i> is the integer value stored in the record header.
                
        [Tr]<td style="white-space:nowrap"><i>bytes</i> * 2 + 13
            <td>Odd values greater than 12 are used to signify a string
                (type SQLITE_TEXT) (<i>n</i>-13)/2 bytes in length, where
                <i>n</i> is the integer value stored in the record header.
      </table>
      <p>
1554
1555
1556
1557
1558
1559
1560
1561
1562
1563
1564
1565
1566
1567
1568
        <p> 
          Following the child page number is the total number of bytes 
          consumed by the cell's record, stored as a variable length integer
          (see section <cite>varint_format</cite>). 
        <p> 
          If the record is small enough, it is stored verbatim in the cell.
          A record is deemed to be small enough to be completely stored in
          the cell if it consists of less than:
        <pre>
            <i>max-local</i> := (<i>usable-size</i> - 12) * <i>max-embedded-fraction</i> / 255 - 23
</pre>
        <p>
          bytes. In the formula above, <i>usable-size</i> is the page-size
          in bytes less the number of unused bytes left at the end of every
          page (as read from byte offset 20 of the database header), and







|







1578
1579
1580
1581
1582
1583
1584
1585
1586
1587
1588
1589
1590
1591
1592
        <p> 
          Following the child page number is the total number of bytes 
          consumed by the cell's record, stored as a variable length integer
          (see section <cite>varint_format</cite>). 
        <p> 
          If the record is small enough, it is stored verbatim in the cell.
          A record is deemed to be small enough to be completely stored in
          the cell if it consists of less than or equal to:
        <pre>
            <i>max-local</i> := (<i>usable-size</i> - 12) * <i>max-embedded-fraction</i> / 255 - 23
</pre>
        <p>
          bytes. In the formula above, <i>usable-size</i> is the page-size
          in bytes less the number of unused bytes left at the end of every
          page (as read from byte offset 20 of the database header), and
1700
1701
1702
1703
1704
1705
1706




1707
1708
1709
1710
1711
1712
1713
        <p>The following database properties discuss table B-Tree records 
           with implicit (default) values.

          [fileformat_import_requirement2 H31100]
          [fileformat_import_requirement2 H31110]
          [fileformat_import_requirement2 H31120]





      [h4 "Table B-Tree Page Format"]
        <p>
          Table B-Tree structures use the same page format as index B-Tree 
          structures, described in section <cite>index_btree_page_format</cite>,
          with the following differences:
        <ul>
          <li>The first byte of the page-header, the "flags" field, is set to 







>
>
>
>







1724
1725
1726
1727
1728
1729
1730
1731
1732
1733
1734
1735
1736
1737
1738
1739
1740
1741
        <p>The following database properties discuss table B-Tree records 
           with implicit (default) values.

          [fileformat_import_requirement2 H31100]
          [fileformat_import_requirement2 H31110]
          [fileformat_import_requirement2 H31120]

	<p class=todo>
          See the note to do with the schema file format version above. Turns
          out this field may also be set to 0 by SQLite.

      [h4 "Table B-Tree Page Format"]
        <p>
          Table B-Tree structures use the same page format as index B-Tree 
          structures, described in section <cite>index_btree_page_format</cite>,
          with the following differences:
        <ul>
          <li>The first byte of the page-header, the "flags" field, is set to 
Changes to req/hlr30000.txt.
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
<i>schema table</i> records associated with SQL tables that are not
virtual tables contains the page number (an integer value) of the root
page of the associated <i>table B-Tree</i> structure within the
database file.

HLR H30300
If the associated database table is a virtual table, the fourth
field of the <i>schema table</i> record shall contain an SQL NULL
value.

HLR H30310
In a well-formed database, the fifth field of all <i>schema table</i>
records associated with SQL tables shall contain a "CREATE TABLE"
or "CREATE VIRTUAL TABLE" statment (a text value).  The details
of the statement shall be such that executing the statement
would create a table of precisely the same name and schema as the







|
|







124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
<i>schema table</i> records associated with SQL tables that are not
virtual tables contains the page number (an integer value) of the root
page of the associated <i>table B-Tree</i> structure within the
database file.

HLR H30300
If the associated database table is a virtual table, the fourth
field of the <i>schema table</i> record shall contain the integer
value 0 (zero).

HLR H30310
In a well-formed database, the fifth field of all <i>schema table</i>
records associated with SQL tables shall contain a "CREATE TABLE"
or "CREATE VIRTUAL TABLE" statment (a text value).  The details
of the statement shall be such that executing the statement
would create a table of precisely the same name and schema as the
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
HLR H31190
When a table B-Tree cell is stored partially in an
<i>overflow page chain</i>, the prefix stored on the B-Tree
leaf page consists of the two <i>variable length integer</i> fields,
followed by the first <i>N</i> bytes of the database record, where
<i>N</i> is determined by the following algorithm:
<code>
<i>min-local</i> := (<i>usable-size</i> - 12) * 255 / 32 - 23
<i>max-local</i> := (<i>usable-size</i> - 35)
<i>N</i> := <i>min-local</i> + (<i>record-size</i> - <i>min-local</i>) % (<i>usable-size</i> - 4)
if( <i>N</i> &gt; <i>max-local</i> ) N := <i>min-local</i>
</code>

HLR H31200
A single <i>overflow page</i> may store up to <i>available-space</i>







|







694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
HLR H31190
When a table B-Tree cell is stored partially in an
<i>overflow page chain</i>, the prefix stored on the B-Tree
leaf page consists of the two <i>variable length integer</i> fields,
followed by the first <i>N</i> bytes of the database record, where
<i>N</i> is determined by the following algorithm:
<code>
<i>min-local</i> := (<i>usable-size</i> - 12) * 32 / 255 - 23
<i>max-local</i> := (<i>usable-size</i> - 35)
<i>N</i> := <i>min-local</i> + (<i>record-size</i> - <i>min-local</i>) % (<i>usable-size</i> - 4)
if( <i>N</i> &gt; <i>max-local</i> ) N := <i>min-local</i>
</code>

HLR H31200
A single <i>overflow page</i> may store up to <i>available-space</i>