Documentation Source Text

      <li> <p>The start of the journal file is populated with data that is not
           a valid journal header.
      <li> <p>For each page in database image A that is not a free-list leaf 
           page and either does not exist in database image B or exists but
           is populated with different content, a record is written to the
           journal file. The record contains a copy of the original database
           image A page.
      <li> <p>The journal file is populated with a valid journal header. The
           page-count field of the journal header is set to the number of
           pages in database image A. The record-count is set to the number
           of records written to the journal file in step 2.
      <li> <p>The content of each page of database image B that is either not
           present or populated differently in database image A is copied
           into the database file. If database image B is smaller than database
           image A, the database file is truncated to the size required by
           database image B.
      <li> <p>One of several file-system operations that cause the journal file
           to become invalid is performed. For example:
................................................................................
    The final database image content is A, E and C. The intermim state depicted
    is that reached at the end of step 4 in the above procedure. In this state, 
    the file-system contains the initial database image, ABCD. However, if the 
    journal file were to be somehow invalidated, then the file-system would 
    contain the final database image, AEC.

    [Figure filesystem2.gif figure_filesystem2 "Interim file-system state used to atomically overwrite database image ABCD with AEC"]









    <p class=todo>
      The above does not explain multiple header journals. Or multi-file 
      transactions.

    <p class=todo> FINISH THIS!

  [h4 "Multiple Database Transactions" multi_db_transactions]








<!--




















  <p>
    SQLite is required 
    to do make all modifications associated with the transaction such that 
    the database image is modified atomically. If an application, OS or 
    power failure occurs while SQLite is updating the database, upon recovery 
    the contents of the database must reflect either that all modifications 

      <li> <p>The start of the journal file is populated with data that is not
           a valid journal header.
      <li> <p>For each page in database image A that is not a free-list leaf 
           page and either does not exist in database image B or exists but
           is populated with different content, a record is written to the
           journal file. The record contains a copy of the original database
           image A page.
      <li> <p>The start of the journal file is populated with a valid journal
           header. The page-count field of the journal header is set to the
           number of pages in database image A. The record-count is set to the 
           number of records written to the journal file in step 2.
      <li> <p>The content of each page of database image B that is either not
           present or populated differently in database image A is copied
           into the database file. If database image B is smaller than database
           image A, the database file is truncated to the size required by
           database image B.
      <li> <p>One of several file-system operations that cause the journal file
           to become invalid is performed. For example:
................................................................................
    The final database image content is A, E and C. The intermim state depicted
    is that reached at the end of step 4 in the above procedure. In this state, 
    the file-system contains the initial database image, ABCD. However, if the 
    journal file were to be somehow invalidated, then the file-system would 
    contain the final database image, AEC.

    [Figure filesystem2.gif figure_filesystem2 "Interim file-system state used to atomically overwrite database image ABCD with AEC"]

  <p>
    The procedure described above can be onourous to implement, as it requires
    that the data for all modified pages of database image B be available
    (presumably in main memory) at the same time, when step 4 is performed.
    For transactions that write to a large number of database pages, this 
    may be undesirable.
    

    <p class=todo>
      The above does not explain multiple header journals. Or multi-file 
      transactions.

    <p class=todo> FINISH THIS!

  <p>
    The following requirements require that the journal header at the start of
    a journal file is set to contain the original database page-size and 
    page-count and written to non-volatile storage before the size of the
    database file is modified. And that once the size of the database file has
    been modified, the journal header does not become unstable and the page-size 
    and page-count values stored therein are not modified until the end of
    the transaction.


       [fileformat_import_requirement2 H32320]
       [fileformat_import_requirement2 H32330]

  <p>
    Journal before overwrite:

       [fileformat_import_requirement2 H32340]
       [fileformat_import_requirement2 H32350]

  <p>
    Journal before truncate:

       [fileformat_import_requirement2 H32360]
       [fileformat_import_requirement2 H32370]
      

  [h4 "Multiple Database Transactions" multi_db_transactions]

<!--

  <p>
    SQLite is required 
    to do make all modifications associated with the transaction such that 
    the database image is modified atomically. If an application, OS or 
    power failure occurs while SQLite is updating the database, upon recovery 
    the contents of the database must reflect either that all modifications 

order to replace database image A with database image B, an operating
system or power failure should occur, then following recovery the database
file-system representation shall contain a database image equivalent to
either A or B.
















































HLR H33000
Before reading from a database file or journal file, a database
reader shall establish a SHARED or greater lock on the database file.

HLR H33010

order to replace database image A with database image B, an operating
system or power failure should occur, then following recovery the database
file-system representation shall contain a database image equivalent to
either A or B.



HLR H32320
When using the rollback-journal method to modify the file-system representation
of a database image, the database writer shall ensure that before the size of
the database file is modified, the first 28 bytes of the journal file contain a
stable valid journal header with the page-size and page-count fields set to
values corresponding to the original database image.

HLR H32330
When using the rollback-journal method to modify the file-system representation
of a database image, the database writer shall ensure that the first 28 bytes
of the journal file does not become unstable at any point after the size of the 
database file is modified until the journal file is invalidated to commit the
transaction.

HLR H32340
When using the rollback-journal method to modify the file-system representation
of a database image, the database writer shall ensure that before any part of
the database file that contained a page of the original database image that was
not a free-list leaf page is overwritten or made unstable the journal file
contains a valid and stable journal record containing the original page data.

HLR H32350
When using the rollback-journal method to modify the file-system representation
of a database image, the database writer shall ensure that after any part of
the database file that contained a page of the original database image that was
not a free-list leaf page has been overwritten or made unstable the corresponding
journal record (see H32340) is not modified or made unstable.

HLR H32360
When using the rollback-journal method to modify the file-system representation
of a database image, the database writer shall ensure that before the database
file is truncated, the journal file contains stable valid journal records 
corresponding to all pages of the original database image that were part of the
region being discarded by the truncate operation and were not free-list leaf 
pages.

HLR H32370
When using the rollback-journal method to modify the file-system representation
of a database image, the database writer shall ensure that after the database
file has been truncated the journal records corresponding to pages from the
original database image that were part of the truncated region and were not
free-list leaf pages are not modified or made unstable.



HLR H33000
Before reading from a database file or journal file, a database
reader shall establish a SHARED or greater lock on the database file.

HLR H33010