Date: Tue, 17 Feb 2015 17:25:57 +0000 Subject: Imported from /home/lorry/working-area/delta_berkeleydb/db-6.1.23.tar.gz. --- docs/programmer_reference/rq_conf.html | 444 +++++++++++++++++++-------------- 1 file changed, 255 insertions(+), 189 deletions(-) (limited to 'docs/programmer_reference/rq_conf.html') diff --git a/docs/programmer_reference/rq_conf.html b/docs/programmer_reference/rq_conf.html index ab9c302d..a7379d26 100644 --- a/docs/programmer_reference/rq_conf.html +++ b/docs/programmer_reference/rq_conf.html @@ -14,7 +14,7 @@

Library Version 11.2.5.3

Library Version 12.1.6.1

@@ -22,9 +22,7 @@ - +

Prev	Chapter 2. - Access Method Configuration -	Chapter 2. Access Method Configuration	Next

@@ -42,265 +40,334 @@

- Managing record-based databases + Managing record-based + databases
- Selecting a Queue extent size + Selecting a Queue extent + size
- Flat-text backing files + Flat-text backing + files
- Logically renumbering records + Logically renumbering + records

- There are a series of configuration tasks which you can perform when - using the Queue and Recno access methods. They are described in the following sections. -

+ There are a series of configuration tasks which you can + perform when using the Queue and Recno access methods. They + are described in the following sections. +

Managing record-based databases

Managing record-based + databases

When using fixed- or variable-length record-based databases, particularly -with flat-text backing files, there are several items that the user can -control. The Recno access method can be used to store either variable- -or fixed-length data items. By default, the Recno access method stores -variable-length data items. The Queue access method can only store -fixed-length data items.

+ When using fixed- or variable-length record-based databases, + particularly with flat-text backing files, there are several + items that the user can control. The Recno access method can + be used to store either variable- or fixed-length data items. + By default, the Recno access method stores variable-length + data items. The Queue access method can only store + fixed-length data items. +

Record Delimiters

When using the Recno access method to store variable-length records, -records read from any backing source file are separated by a specific -byte value which marks the end of one record and the beginning of the -next. This delimiting value is ignored except when reading records from -a backing source file, that is, records may be stored into the database -that include the delimiter byte. However, if such records are written -out to the backing source file and the backing source file is -subsequently read into a database, the records will be split where -delimiting bytes were found.

For example, UNIX text files can usually be interpreted as a sequence of -variable-length records separated by ASCII newline characters. This byte -value (ASCII 0x0a) is the default delimiter. Applications may specify a -different delimiting byte using the DB->set_re_delim() method. If no -backing source file is being used, there is no reason to set the -delimiting byte value.

+ When using the Recno access method to store + variable-length records, records read from any backing + source file are separated by a specific byte value which + marks the end of one record and the beginning of the next. + This delimiting value is ignored except when reading + records from a backing source file, that is, records may + be stored into the database that include the delimiter + byte. However, if such records are written out to the + backing source file and the backing source file is + subsequently read into a database, the records will be + split where delimiting bytes were found. +

+ For example, UNIX text files can usually be interpreted + as a sequence of variable-length records separated by + ASCII newline characters. This byte value (ASCII 0x0a) is + the default delimiter. Applications may specify a + different delimiting byte using the DB->set_re_delim() + method. If no backing source file is being used, there is + no reason to set the delimiting byte value. +

Record Length

When using the Recno or Queue access methods to store fixed-length -records, the record length must be specified. Since the Queue access -method always uses fixed-length records, the user must always set the -record length prior to creating the database. Setting the record length -is what causes the Recno access method to store fixed-length, not -variable-length, records.

The length of the records is specified by calling the -DB->set_re_len() method. The default length of the records is 0 bytes. -Any record read from a backing source file or otherwise stored in the -database that is shorter than the declared length will automatically be -padded as described for the DB->set_re_pad() method. Any record stored -that is longer than the declared length results in an error. For -further information on backing source files, see -Flat-text backing files.

+ When using the Recno or Queue access methods to store + fixed-length records, the record length must be specified. + Since the Queue access method always uses fixed-length + records, the user must always set the record length prior + to creating the database. Setting the record length is + what causes the Recno access method to store fixed-length, + not variable-length, records. +

+ The length of the records is specified by calling the + DB->set_re_len() method. The default length of the records + is 0 bytes. Any record read from a backing source file or + otherwise stored in the database that is shorter than the + declared length will automatically be padded as described + for the DB->set_re_pad() method. Any record stored that is + longer than the declared length results in an error. For + further information on backing source files, see Flat-text backing + files. +

Record Padding Byte Value

When storing fixed-length records in a Queue or Recno database, a pad -character may be specified by calling the DB->set_re_pad() method. Any -record read from the backing source file or otherwise stored in the -database that is shorter than the expected length will automatically be -padded with this byte value. If fixed-length records are specified but -no pad value is specified, a space character (0x20 in the ASCII -character set) will be used. For further information on backing source -files, see Flat-text backing files.

+ When storing fixed-length records in a Queue or Recno + database, a pad character may be specified by calling the + DB->set_re_pad() method. Any record read from the backing + source file or otherwise stored in the database that is + shorter than the expected length will automatically be + padded with this byte value. If fixed-length records are + specified but no pad value is specified, a space character + (0x20 in the ASCII character set) will be used. For + further information on backing source files, see Flat-text backing + files. +

Selecting a Queue extent size

Selecting a Queue extent + size

- In Queue databases, records are allocated sequentially and directly - mapped to an offset within the file storage for the database. As - records are deleted from the Queue, pages will become empty and will - not be reused in normal queue operations. To facilitate the - reclamation of disk space a Queue may be partitioned into extents. - Each extent is kept in a separate physical file. + In Queue databases, records are allocated sequentially and + directly mapped to an offset within the file storage for the + database. As records are deleted from the Queue, pages will + become empty and will not be reused in normal queue + operations. To facilitate the reclamation of disk space a + Queue may be partitioned into extents. Each extent is kept in + a separate physical file.

- Extent files are automatically created as needed and marked for - deletion when the head of the queue moves off the extent. The extent - will not be deleted until all processes close the extent. In addition, - Berkeley DB caches a small number of extents that have been recently - used; this may delay when an extent will be deleted. The number of - extents left open depends on queue activity. +

+ Extent files are automatically created as needed and marked + for deletion when the head of the queue moves off the extent. + The extent will not be deleted until all processes close the + extent. In addition, Berkeley DB caches a small number of + extents that have been recently used; this may delay when an + extent will be deleted. The number of extents left open + depends on queue activity.

- The extent size specifies the number of pages that make up each extent. - By default, if no extent size is specified, the Queue resides in a - single file and disk space is not reclaimed. In choosing an extent - size there is a tradeoff between the amount of disk space used and the - overhead of creating and deleting files. If the extent size is too - small, the system will pay a performance penalty, creating and deleting - files frequently. In addition, if the active part of the queue spans - many files, all those files will need to be open at the same time, - consuming system and process file resources. + The extent size specifies the number of pages that make up + each extent. By default, if no extent size is specified, the + Queue resides in a single file and disk space is not + reclaimed. In choosing an extent size there is a tradeoff + between the amount of disk space used and the overhead of + creating and deleting files. If the extent size is too small, + the system will pay a performance penalty, creating and + deleting files frequently. In addition, if the active part of + the queue spans many files, all those files will need to be + open at the same time, consuming system and process file + resources.

- You can set the Queue extent size using the DB->set_q_extentsize() - method. You can see the current extent size using the - DB->get_q_extentsize() method. + You can set the Queue extent size using the + DB->set_q_extentsize() method. You can see the current extent + size using the DB->get_q_extentsize() method.

Flat-text backing files

Flat-text backing + files

It is possible to back any Recno database (either fixed or variable -length) with a flat-text source file. This provides fast read (and -potentially write) access to databases that are normally created and -stored as flat-text files. The backing source file may be specified by -calling the DB->set_re_source() method.

The backing source file will be read to initialize the database. In the -case of variable length records, the records are assumed to be separated -as described for the DB->set_re_delim() method. For example, standard -UNIX byte stream files can be interpreted as a sequence of variable -length records separated by ASCII newline characters. This is the -default.

When cached data would normally be written back to the underlying -database file (for example, when the DB->close() or -DB->sync() methods are called), the in-memory copy of the database will -be written back to the backing source file.

The backing source file must already exist (but may be zero-length) when -DB->open() is called. By default, the backing source file is read -lazily, that is, records are not read from the backing source file until -they are requested by the application. If multiple processes (not -threads) are accessing a Recno database concurrently and either -inserting or deleting records, the backing source file must be read in -its entirety before more than a single process accesses the database, -and only that process should specify the backing source file as part of -the DB->open() call. This can be accomplished by calling the -DB->set_flags() method with the DB_SNAPSHOT flag.

Reading and writing the backing source file cannot be transactionally -protected because it involves filesystem operations that are not part of -the Berkeley DB transaction methodology. For this reason, if a temporary -database is used to hold the records (a NULL was specified as the file -argument to DB->open()), it is possible to lose the -contents of the backing source file if the system crashes at the right -instant. If a permanent file is used to hold the database (a filename -was specified as the file argument to DB->open()), normal database -recovery on that file can be used to prevent information loss. It is -still possible that the contents of the backing source file itself will -be corrupted or lost if the system crashes.

For all of the above reasons, the backing source file is generally used -to specify databases that are read-only for Berkeley DB applications, and that -are either generated on the fly by software tools, or modified using a -different mechanism such as a text editor.

+ It is possible to back any Recno database (either fixed or + variable length) with a flat-text source file. This provides + fast read (and potentially write) access to databases that are + normally created and stored as flat-text files. The backing + source file may be specified by calling the DB->set_re_source() + method. +

+ The backing source file will be read to initialize the + database. In the case of variable length records, the records + are assumed to be separated as described for the + DB->set_re_delim() method. For example, standard UNIX byte + stream files can be interpreted as a sequence of variable + length records separated by ASCII newline characters. This is + the default. +

+ When cached data would normally be written back to the + underlying database file (for example, when the DB->close() or + DB->sync() methods are called), the in-memory copy of the + database will be written back to the backing source + file. +

+ The backing source file must already exist (but may be + zero-length) when DB->open() is called. By default, the backing + source file is read lazily, that is, records are not read from + the backing source file until they are requested by the + application. If multiple processes (not threads) are accessing + a Recno database concurrently and either inserting or deleting + records, the backing source file must be read in its entirety + before more than a single process accesses the database, and + only that process should specify the backing source file as + part of the DB->open() call. This can be accomplished by calling + the DB->set_flags() method with the DB_SNAPSHOT flag. +

+ Reading and writing the backing source file cannot be + transactionally protected because it involves filesystem + operations that are not part of the Berkeley DB transaction + methodology. For this reason, if a temporary database is used + to hold the records (a NULL was specified as the file argument + to DB->open()), it is possible to lose the + contents of the backing source file if the system crashes + at the right instant. If a permanent file is + used to hold the database (a filename was specified as the + file argument to DB->open()), normal database recovery on that + file can be used to prevent information loss. It is still + possible that the contents of the backing source file itself + will be corrupted or lost if the system crashes. +

+ For all of the above reasons, the backing source file is + generally used to specify databases that are read-only for + Berkeley DB applications, and that are either generated on the + fly by software tools, or modified using a different mechanism + such as a text editor. +

Logically renumbering records

Logically renumbering + records

Records stored in the Queue and Recno access methods are accessed by -logical record number. In all cases in Btree databases, and optionally -in Recno databases (see the DB->set_flags() method and the -DB_RENUMBER flag for more information), record numbers are -mutable. This means that the record numbers may change as records are -added to and deleted from the database. The deletion of record number -4 causes any records numbered 5 and higher to be renumbered downward by -1; the addition of a new record after record number 4 causes any -records numbered 5 and higher to be renumbered upward by 1. In all -cases in Queue databases, and by default in Recno databases, record -numbers are not mutable, and the addition or deletion of records to the -database will not cause already-existing record numbers to change. For -this reason, new records cannot be inserted between already-existing -records in databases with immutable record numbers.

Cursors pointing into a Btree database or a Recno database with mutable -record numbers maintain a reference to a specific record, rather than -a record number, that is, the record they reference does not change as -other records are added or deleted. For example, if a database contains -three records with the record numbers 1, 2, and 3, and the data items -"A", "B", and "C", respectively, the deletion of record number 2 ("B") -will cause the record "C" to be renumbered downward to record number 2. -A cursor positioned at record number 3 ("C") will be adjusted and -continue to point to "C" after the deletion. Similarly, a cursor -previously referring to the now deleted record number 2 will be -positioned between the new record numbers 1 and 2, and an insertion -using that cursor will appear between those records. In this manner -records can be added and deleted to a database without disrupting the -sequential traversal of the database by a cursor.

Only cursors created using a single DB handle can adjust each -other's position in this way, however. If multiple DB handles -have a renumbering Recno database open simultaneously (as when multiple -processes share a single database environment), a record referred to by -one cursor could change underfoot if a cursor created using another -DB handle inserts or deletes records into the database. For -this reason, applications using Recno databases with mutable record -numbers will usually make all accesses to the database using a single -DB handle and cursors created from that handle, or will -otherwise single-thread access to the database, for example, by using -the Berkeley DB Concurrent Data Store product.

In any Queue or Recno databases, creating new records will cause the -creation of multiple records if the record number being created is more -than one greater than the largest record currently in the database. For -example, creating record number 28, when record 25 was previously the -last record in the database, will implicitly create records 26 and 27 -as well as 28. All first, last, next and previous cursor operations -will automatically skip over these implicitly created records. So, if -record number 5 is the only record the application has created, -implicitly creating records 1 through 4, the DBC->get() method with the -DB_FIRST flag will return record number 5, not record number 1. -Attempts to explicitly retrieve implicitly created records by their -record number will result in a special error return, -DB_KEYEMPTY.

In any Berkeley DB database, attempting to retrieve a deleted record, using -a cursor positioned on the record, results in a special error return, -DB_KEYEMPTY. In addition, when using Queue databases or Recno -databases with immutable record numbers, attempting to retrieve a deleted -record by its record number will also result in the DB_KEYEMPTY -return.

+ Records stored in the Queue and Recno access methods are + accessed by logical record number. In all cases in Btree + databases, and optionally in Recno databases (see the + DB->set_flags() method and the DB_RENUMBER flag for more + information), record numbers are mutable. This means that the + record numbers may change as records are added to and deleted + from the database. The deletion of record number 4 causes any + records numbered 5 and higher to be renumbered downward by 1; + the addition of a new record after record number 4 causes any + records numbered 5 and higher to be renumbered upward by 1. In + all cases in Queue databases, and by default in Recno + databases, record numbers are not mutable, and the addition or + deletion of records to the database will not cause + already-existing record numbers to change. For this reason, + new records cannot be inserted between already-existing + records in databases with immutable record numbers. +

+ Cursors pointing into a Btree database or a Recno database + with mutable record numbers maintain a reference to a specific + record, rather than a record number, that is, the record they + reference does not change as other records are added or + deleted. For example, if a database contains three records + with the record numbers 1, 2, and 3, and the data items "A", + "B", and "C", respectively, the deletion of record number 2 + ("B") will cause the record "C" to be renumbered downward to + record number 2. A cursor positioned at record number 3 ("C") + will be adjusted and continue to point to "C" after the + deletion. Similarly, a cursor previously referring to the now + deleted record number 2 will be positioned between the new + record numbers 1 and 2, and an insertion using that cursor + will appear between those records. In this manner records can + be added and deleted to a database without disrupting the + sequential traversal of the database by a cursor. +

+ Only cursors created using a single DB handle can adjust + each other's position in this way, however. If multiple DB + handles have a renumbering Recno database open simultaneously + (as when multiple processes share a single database + environment), a record referred to by one cursor could change + underfoot if a cursor created using another DB handle + inserts or deletes records into the database. For this reason, + applications using Recno databases with mutable record numbers + will usually make all accesses to the database using a single + DB handle and cursors created from that handle, or will + otherwise single-thread access to the database, for example, + by using the Berkeley DB Concurrent Data Store product. +

+ In any Queue or Recno databases, creating new records will + cause the creation of multiple records if the record number + being created is more than one greater than the largest record + currently in the database. For example, creating record number + 28, when record 25 was previously the last record in the + database, will implicitly create records 26 and 27 as well as + 28. All first, last, next and previous cursor operations will + automatically skip over these implicitly created records. So, + if record number 5 is the only record the application has + created, implicitly creating records 1 through 4, the DBC->get() + method with the DB_FIRST flag will return record number 5, + not record number 1. Attempts to explicitly retrieve + implicitly created records by their record number will result + in a special error return, DB_KEYEMPTY. +

+ In any Berkeley DB database, attempting to retrieve a + deleted record, using a cursor positioned on the record, + results in a special error return, DB_KEYEMPTY. + In addition, when using Queue databases or Recno databases + with immutable record numbers, attempting to retrieve a + deleted record by its record number will also result in the + DB_KEYEMPTY return. +

@@ -314,13 +381,12 @@ return.

Next - Heap access method specific configuration + Heap access method specific + configuration Home - Chapter 3. - Access Method Operations - + Chapter 3. Access Method Operations

-- cgit v1.2.1