From 780b92ada9afcf1d58085a83a0b9e6bc982203d1 Mon Sep 17 00:00:00 2001 From: Lorry Tar Creator 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/am_misc_bulk.html | 222 ++++++++++++++++++---------- 1 file changed, 141 insertions(+), 81 deletions(-) (limited to 'docs/programmer_reference/am_misc_bulk.html') diff --git a/docs/programmer_reference/am_misc_bulk.html b/docs/programmer_reference/am_misc_bulk.html index fcfd4736..f69e712b 100644 --- a/docs/programmer_reference/am_misc_bulk.html +++ b/docs/programmer_reference/am_misc_bulk.html @@ -14,7 +14,7 @@

Library Version 11.2.5.3

Library Version 12.1.6.1

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

Prev	Chapter 4. - Access Method Wrapup -	Chapter 4. Access Method Wrapup	Next

@@ -57,11 +55,12 @@

When retrieving or modifying large numbers of records, the number -of method calls can often dominate performance. Berkeley DB offers bulk get, -put and delete interfaces which can significantly increase performance for some -applications. -

+ When retrieving or modifying large numbers of records, the + number of method calls can often dominate performance. + Berkeley DB offers bulk get, put and delete interfaces which + can significantly increase performance for some applications. +

@@ -70,68 +69,78 @@ applications.

+ To retrieve records in bulk, an application buffer must + be specified to the DB->get() or DBC->get() methods. This is + done in the C API by setting the data + and ulen fields of the + data DBT to reference an application + buffer, and the flags + field of that structure to DB_DBT_USERMEM. In the + Berkeley DB C++ and Java APIs, the actions are similar, + although there are API-specific methods to set the DBT + values. Then, the DB_MULTIPLE or DB_MULTIPLE_KEY flags + are specified to the DB->get() or DBC->get() methods, which + cause multiple records to be returned in the specified + buffer. +

- To retrieve records in bulk, an application buffer must be specified to - the DB->get() or DBC->get() methods. This is done in the C API by setting - the data and ulen fields of the data DBT to reference an application - buffer, and the - flags field of that structure to - DB_DBT_USERMEM. In the Berkeley DB C++ and Java APIs, the actions - are similar, although there are API-specific methods to set the DBT - values. Then, the DB_MULTIPLE or DB_MULTIPLE_KEY flags are - specified to the DB->get() or DBC->get() methods, which cause multiple - records to be returned in the specified buffer. -

+ The difference between DB_MULTIPLE and + DB_MULTIPLE_KEY is as follows: DB_MULTIPLE returns + multiple data items for a single key. For example, the + DB_MULTIPLE flag would be used to retrieve all of the + duplicate data items for a single key in a single call. + The DB_MULTIPLE_KEY flag is used to retrieve multiple + key/data pairs, where each returned key may or may not + have duplicate data items. +

+ Once the DB->get() or DBC->get() method has returned, the + application will walk through the buffer handling the + returned records. This is implemented for the C and C++ + APIs using four macros: DB_MULTIPLE_INIT, + DB_MULTIPLE_NEXT, DB_MULTIPLE_KEY_NEXT, and + DB_MULTIPLE_RECNO_NEXT. For the Java API, this is + implemented as three iterator classes: MultipleDataEntry, + MultipleKeyDataEntry, + and + MultipleRecnoDataEntry. +

- The difference between DB_MULTIPLE and DB_MULTIPLE_KEY is as - follows: DB_MULTIPLE returns multiple data items for a single key. - For example, the DB_MULTIPLE flag would be used to retrieve all of - the duplicate data items for a single key in a single call. The - DB_MULTIPLE_KEY flag is used to retrieve multiple key/data pairs, - where each returned key may or may not have duplicate data items. -

+ The DB_MULTIPLE_INIT macro is always called first. It + initializes a local application variable and the data DBT for stepping through + the set of returned records. Then, the application calls + one of the remaining three macros: DB_MULTIPLE_NEXT, + DB_MULTIPLE_KEY_NEXT, and DB_MULTIPLE_RECNO_NEXT. +

- Once the DB->get() or DBC->get() method has returned, the application will - walk through the buffer handling the returned records. This is - implemented for the C and C++ APIs using four macros: - DB_MULTIPLE_INIT, DB_MULTIPLE_NEXT, DB_MULTIPLE_KEY_NEXT, and - DB_MULTIPLE_RECNO_NEXT. For the Java API, this is implemented as - three iterator classes: - MultipleDataEntry, - MultipleKeyDataEntry, - and MultipleRecnoDataEntry. -

- The DB_MULTIPLE_INIT macro is always called first. It initializes a - local application variable and the data DBT for stepping through the set of - returned records. Then, the application calls one of the remaining - three macros: DB_MULTIPLE_NEXT, DB_MULTIPLE_KEY_NEXT, and - DB_MULTIPLE_RECNO_NEXT. -

- If the DB_MULTIPLE flag was specified to the DB->get() or DBC->get() - method, the application will always call the DB_MULTIPLE_NEXT macro. - If the DB_MULTIPLE_KEY flag was specified to the DB->get() or DBC->get() - method, and the underlying database is a Btree or Hash database, the - application will always call the DB_MULTIPLE_KEY_NEXT macro. If the - DB_MULTIPLE_KEY flag was specified to the DB->get() or DBC->get() method, - and the underlying database is a Queue or Recno database, the - application will always call the DB_MULTIPLE_RECNO_NEXT macro. The - DB_MULTIPLE_NEXT, DB_MULTIPLE_KEY_NEXT, and - DB_MULTIPLE_RECNO_NEXT macros are called repeatedly, until the end of - the returned records is reached. The end of the returned records is - detected by the application's local pointer variable being set to NULL. -

- Note that if you want to use a cursor for bulk retrieval of records in - a Btree database, you should open the cursor using the - DB_CURSOR_BULK flag. This optimizes the cursor for - bulk retrieval. -

- The following is an example of a routine that displays the contents of - a Btree database using the bulk return interfaces. -

+ If the DB_MULTIPLE flag was specified to the DB->get() + or DBC->get() method, the application will always call the + DB_MULTIPLE_NEXT macro. If the DB_MULTIPLE_KEY flag + was specified to the DB->get() or DBC->get() method, and the + underlying database is a Btree or Hash database, the + application will always call the DB_MULTIPLE_KEY_NEXT + macro. If the DB_MULTIPLE_KEY flag was specified to the + DB->get() or DBC->get() method, and the underlying database is + a Queue or Recno database, the application will always + call the DB_MULTIPLE_RECNO_NEXT macro. The + DB_MULTIPLE_NEXT, DB_MULTIPLE_KEY_NEXT, and + DB_MULTIPLE_RECNO_NEXT macros are called repeatedly, + until the end of the returned records is reached. The end + of the returned records is detected by the application's + local pointer variable being set to NULL. +

+ Note that if you want to use a cursor for bulk + retrieval of records in a Btree database, you should open + the cursor using the DB_CURSOR_BULK + flag. This optimizes the cursor for bulk retrieval. +

+ The following is an example of a routine that displays + the contents of a Btree database using the bulk return + interfaces. +

int
 rec_display(DB *dbp)
@@ -205,13 +214,34 @@ rec_display(DB *dbp)
             
           
         
-        To put records in bulk with the btree or hash access methods, construct bulk buffers in the key and data DBT using DB_MULTIPLE_WRITE_INIT and DB_MULTIPLE_WRITE_NEXT.  To put records in bulk with the recno or queue access methods, construct bulk buffers in the data DBT as before, but construct the key DBT using DB_MULTIPLE_RECNO_WRITE_INIT and DB_MULTIPLE_RECNO_WRITE_NEXT with a data size of zero;.  In both cases, set the DB_MULTIPLE flag to DB->put().
-        Alternatively, for btree and hash access methods, construct a single bulk buffer in the key DBT using DB_MULTIPLE_WRITE_INIT and DB_MULTIPLE_KEY_WRITE_NEXT.  For recno and queue access methods, construct a bulk buffer in the key DBT using DB_MULTIPLE_RECNO_WRITE_INIT and DB_MULTIPLE_RECNO_WRITE_NEXT.  In both cases, set the DB_MULTIPLE_KEY flag to DB->put().
-
-
-        A successful bulk operation is logically equivalent to a loop through each key/data pair, performing a DB->put() for each one.
         
-
+            To put records in bulk with the btree or hash access
+            methods, construct bulk buffers in the key and data 
+            DBT using DB_MULTIPLE_WRITE_INIT
+            and DB_MULTIPLE_WRITE_NEXT. To put records in bulk with
+            the recno or queue access methods, construct bulk buffers
+            in the data DBT as
+            before, but construct the key 
+            DBT using DB_MULTIPLE_RECNO_WRITE_INIT and
+            DB_MULTIPLE_RECNO_WRITE_NEXT with a data size of zero;.
+            In both cases, set the DB_MULTIPLE flag to
+            DB->put().
+        
+        
+            Alternatively, for btree and hash access methods,
+            construct a single bulk buffer in the key DBT using
+            DB_MULTIPLE_WRITE_INIT and DB_MULTIPLE_KEY_WRITE_NEXT.
+            For recno and queue access methods, construct a bulk
+            buffer in the key DBT
+            using DB_MULTIPLE_RECNO_WRITE_INIT and
+            DB_MULTIPLE_RECNO_WRITE_NEXT. In both cases, set the
+            DB_MULTIPLE_KEY flag to DB->put(). 
+        
+        
+            A successful bulk operation is logically equivalent to a loop through
+            each key/data pair, performing a DB->put() for each
+            one.
+        
       
       
         
@@ -221,9 +251,40 @@ rec_display(DB *dbp)
             
           
         
-        To delete all records with a specified set of keys with the btree or hash access methods, construct a bulk buffer in the key DBT using DB_MULTIPLE_WRITE_INIT and DB_MULTIPLE_WRITE_NEXT.  To delete a set of records with the recno or queue access methods, construct the key DBT using DB_MULTIPLE_RECNO_WRITE_INIT and DB_MULTIPLE_RECNO_WRITE_NEXT with a data size of zero.  In both cases, set the DB_MULTIPLE flag to DB->del().  This is equivalent to calling DB->del() for each key in the bulk buffer.  In particular, if the database supports duplicates, all records with the matching key are deleted.
-        Alternatively, to delete a specific set of key/data pairs, which may be items within a set of duplicates, there are also two cases depending on whether the access method uses record numbers for keys.  For btree and hash access methods, construct a single bulk buffer in the key DBT using DB_MULTIPLE_WRITE_INIT and DB_MULTIPLE_KEY_WRITE_NEXT.  For recno and queue access methods, construct a bulk buffer in the key DBT using DB_MULTIPLE_RECNO_WRITE_INIT and DB_MULTIPLE_RECNO_WRITE_NEXT.  In both cases, set the DB_MULTIPLE_KEY flag to DB->del().
-        A successful bulk operation is logically equivalent to a loop through each key/data pair, performing a DB->del() for each one.
+        
+            To delete all records with a specified set of keys with
+            the btree or hash access methods, construct a bulk buffer
+            in the key DBT using
+            DB_MULTIPLE_WRITE_INIT and DB_MULTIPLE_WRITE_NEXT. To
+            delete a set of records with the recno or queue access
+            methods, construct the key DBT using
+            DB_MULTIPLE_RECNO_WRITE_INIT and
+            DB_MULTIPLE_RECNO_WRITE_NEXT with a data size of zero.
+            In both cases, set the DB_MULTIPLE flag to DB->del(). This
+            is equivalent to calling DB->del() for each key in the bulk
+            buffer. In particular, if the database supports
+            duplicates, all records with the matching key are
+            deleted.
+        
+        
+            Alternatively, to delete a specific set of key/data
+            pairs, which may be items within a set of duplicates,
+            there are also two cases depending on whether the access
+            method uses record numbers for keys. For btree and hash
+            access methods, construct a single bulk buffer in the
+            key DBT using
+            DB_MULTIPLE_WRITE_INIT and DB_MULTIPLE_KEY_WRITE_NEXT.
+            For recno and queue access methods, construct a bulk
+            buffer in the key DBT
+            using DB_MULTIPLE_RECNO_WRITE_INIT and
+            DB_MULTIPLE_RECNO_WRITE_NEXT. In both cases, set the
+            DB_MULTIPLE_KEY flag to DB->del().
+        
+        
+            A successful bulk operation is logically equivalent to a
+            loop through each key/data pair, performing a DB->del() for
+            each one.
+        
       
     
     
@@ -237,13 +298,12 @@ rec_display(DB *dbp)
            Next
         
         
-          Chapter 4. 
-		Access Method Wrapup
-         
+          Chapter 4.  Access Method Wrapup  
           
             Home
           
-           Partial record storage and retrieval
+           Partial record storage and
+        retrieval
         
       
     
-- 
cgit v1.2.1