Documentation Source Text

  **     <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;
  }

  **     <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;
  }

# 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
................................................................................
      </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} {
................................................................................

      <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),
................................................................................
        [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.
................................................................................

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

# 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
................................................................................
      </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} {
................................................................................

      <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),
................................................................................
        [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.
................................................................................

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

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

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