Prev	Chapter 3. - Access Method Operations -	Chapter 3. Access Method Operations	Next

Chapter 3. - Access Method Operations -

Chapter 3. Access Method Operations

- A database cursor refers to a single key/data pair in the database. - It supports traversal of the database and is the only way to access - individual duplicate data items. Cursors are used for operating on - collections of records, for iterating over a database, and for - saving handles to individual records, so that they can be modified - after they have been read. +

+ A database cursor refers to a single key/data pair in the + database. It supports traversal of the database and is the + only way to access individual duplicate data items. Cursors + are used for operating on collections of records, for + iterating over a database, and for saving handles to + individual records, so that they can be modified after they + have been read.

- The DB->cursor() method opens a cursor into a database. Upon return - the cursor is uninitialized, cursor positioning occurs as part of - the first cursor operation. + The DB->cursor() method opens a cursor into a database. Upon + return the cursor is uninitialized, cursor positioning occurs + as part of the first cursor operation.

- Once a database cursor has been opened, records may be retrieved - (DBC->get()), stored (DBC->put()), and deleted (DBC->del()). + Once a database cursor has been opened, records may be + retrieved (DBC->get()), stored (DBC->put()), and deleted + (DBC->del()).

- Additional operations supported by the cursor handle include - duplication (DBC->dup()), equality join (DB->join()), and a count of - duplicate data items (DBC->count()). Cursors are eventually closed - using DBC->close(). +

+ Additional operations supported by the cursor handle + include duplication (DBC->dup()), equality join (DB->join()), and + a count of duplicate data items (DBC->count()). Cursors are + eventually closed using DBC->close().

- For more information on the operations supported by the cursor - handle, see the - Database Cursors and Related Methods - section in the Berkeley DB C API Reference Guide. + For more information on the operations supported by the + cursor handle, see the Database Cursors and Related + Methods section in the + Berkeley DB C API Reference Guide.

Retrieving records with a cursor

Retrieving records with a + cursor

- The DBC->get() method retrieves records from the database using a - cursor. The DBC->get() method takes a flag which controls how the - cursor is positioned within the database and returns the key/data - item associated with that positioning. Similar to DB->get(), - DBC->get() may also take a supplied key and retrieve the data - associated with that key from the database. There are several - flags that you can set to customize retrieval. + The DBC->get() method retrieves records from the database + using a cursor. The DBC->get() method takes a flag which + controls how the cursor is positioned within the database and + returns the key/data item associated with that positioning. + Similar to DB->get(), DBC->get() may also take a supplied key and + retrieve the data associated with that key from the database. + There are several flags that you can set to customize + retrieval.

Cursor position flags

@@ -136,43 +139,45 @@

DB_FIRST, DB_LAST

- Return the first (last) record in the database. +

+ Return the first (last) record in the + database.

DB_NEXT, DB_PREV

- Return the next (previous) record in the database. +

+ Return the next (previous) record in the + database.

DB_NEXT_DUP

- Return the next record in the database, if it is a - duplicate data item for the current key. For Heap - databases, this flag always results in the cursor - returning the DB_NOTFOUND - error. +

+ Return the next record in the database, if + it is a duplicate data item for the current key. + For Heap databases, this flag always results in + the cursor returning the + DB_NOTFOUND error.

DB_NEXT_NODUP, DB_PREV_NODUP

- Return the next (previous) record in the database that - is not a duplicate data item for the current - key. + Return the next (previous) record in the + database that is not a duplicate data item for the + current key.

DB_CURRENT

- Return the record from the database to which the cursor - currently refers. +

+ Return the record from the database to + which the cursor currently refers.

@@ -181,7 +186,7 @@

Retrieving specific key/data pairs

@@ -193,12 +198,12 @@

- Return the record from the database that matches the - supplied key. In the case of duplicates the first - duplicate is returned and the cursor is positioned at - the beginning of the duplicate list. The user can then - traverse the duplicate entries for the - key. + Return the record from the database that + matches the supplied key. In the case of + duplicates the first duplicate is returned and the + cursor is positioned at the beginning of the + duplicate list. The user can then traverse the + duplicate entries for the key.

@@ -206,23 +211,24 @@

- Return the smallest record in the database greater than - or equal to the supplied key. This functionality - permits partial key matches and range searches in the - Btree access method. + Return the smallest record in the database + greater than or equal to the supplied key. This + functionality permits partial key matches and + range searches in the Btree access method.

DB_GET_BOTH

- Return the record from the database that matches both - the supplied key and data items. This is particularly - useful when there are large numbers of duplicate - records for a key, as it allows the cursor to easily be - positioned at the correct place for traversal of some - part of a large set of duplicate records. +

+ Return the record from the database that + matches both the supplied key and data items. This + is particularly useful when there are large + numbers of duplicate records for a key, as it + allows the cursor to easily be positioned at the + correct place for traversal of some part of a + large set of duplicate records.

@@ -230,11 +236,13 @@

- If used on a database configured for sorted duplicates, this - returns the smallest record in the database greater than or equal - to the supplied key and data items. If used on a database that is - not configured for sorted duplicates, this - flag behaves identically to DB_GET_BOTH. + If used on a database configured for sorted + duplicates, this returns the smallest record in + the database greater than or equal to the supplied + key and data items. If used on a database that is + not configured for sorted + duplicates, this flag behaves identically to + DB_GET_BOTH.

In all cases, the cursor is repositioned by a DBC->get() - operation to point to the newly-returned key/data pair in the - database. + operation to point to the newly-returned key/data pair in + the database.

- The following is a code example showing a cursor walking - through a database and displaying the records it contains to - the standard output: + The following is a code example showing a cursor + walking through a database and displaying the records it + contains to the standard output:

int @@ -387,13 +395,14 @@ err: if (close_dbc && (ret = dbcp->close(dbcp)) != 0)

- The DBC->put() method stores records into the database using a - cursor. In general, DBC->put() takes a key and inserts the - associated data into the database, at a location controlled by a - specified flag. + The DBC->put() method stores records into the database using + a cursor. In general, DBC->put() takes a key and inserts the + associated data into the database, at a location controlled by + a specified flag.

- There are several flags that you can set to customize storage: + There are several flags that you can set to customize + storage:

- Create a new record, immediately after the record to which - the cursor refers. +; + Create a new record, immediately after the + record to which the cursor refers.
DB_BEFORE: - Create a new record, immediately before the record to - which the cursor refers. +; + Create a new record, immediately before the + record to which the cursor refers.
@@ -421,17 +430,17 @@ err: if (close_dbc && (ret = dbcp->close(dbcp)) != 0): - Replace the data part of the record to which the cursor - refers. + Replace the data part of the record to which + the cursor refers.
DB_KEYFIRST: - Create a new record as the first of the duplicate records - for the supplied key. +; + Create a new record as the first of the + duplicate records for the supplied key.
@@ -439,18 +448,20 @@ err: if (close_dbc && (ret = dbcp->close(dbcp)) != 0): - Create a new record, as the last of the duplicate records - for the supplied key. + Create a new record, as the last of the + duplicate records for the supplied key.

- In all cases, the cursor is repositioned by a DBC->put() operation to - point to the newly inserted key/data pair in the database. +

+ In all cases, the cursor is repositioned by a DBC->put() + operation to point to the newly inserted key/data pair in the + database.

- The following is a code example showing a cursor storing two data - items in a database that supports duplicate data items: +

+ The following is a code example showing a cursor storing + two data items in a database that supports duplicate data + items:

int
@@ -504,12 +515,12 @@ err:    if ((ret = dbcp->close(dbcp)) != 0)
         
           Note
           
-            If you are using the Heap access method and you are creating a
-            new record in the database, then the key that you provide to
-            the DBC->put() method should be empty.  The DBC->put() method will
-            return the record's ID (RID) in the key. The RID is
-            automatically created for you when Heap database records are
-            created.
+            If you are using the Heap access method and you are
+            creating a new record in the database, then the key that
+            you provide to the DBC->put() method should be empty. The
+            DBC->put() method will return the record's ID (RID) in the
+            key. The RID is automatically created for you when Heap
+            database records are created. 
         
         
       
@@ -521,10 +532,12 @@ err:    if ((ret = dbcp->close(dbcp)) != 0)
             
           
         
-        The DBC->del() method deletes records from the database using a cursor.
-The DBC->del() method deletes the record to which the cursor currently
-refers.  In all cases, the cursor position is unchanged after a
-delete.
+        
+        The DBC->del() method deletes records from the database using
+        a cursor. The DBC->del() method deletes the record to which the
+        cursor currently refers. In all cases, the cursor position is
+        unchanged after a delete.
+    
       
       
         
@@ -534,18 +547,24 @@ delete.
             
           
         
-        Once a cursor has been initialized (for example, by a call to
-DBC->get()), it can be thought of as identifying a particular
-location in a database.  The DBC->dup() method permits an application to
-create a new cursor that has the same locking and transactional
-information as the cursor from which it is copied, and which optionally
-refers to the same position in the database.
-        In order to maintain a cursor position when an application is using
-locking, locks are maintained on behalf of the cursor until the cursor is
-closed.  In cases when an application is using locking without
-transactions, cursor duplication is often required to avoid
-self-deadlocks.  For further details, refer to
-Berkeley DB Transactional Data Store locking conventions.
+        
+        Once a cursor has been initialized (for example, by a call
+        to DBC->get()), it can be thought of as identifying a particular
+        location in a database. The DBC->dup() method permits an
+        application to create a new cursor that has the same locking
+        and transactional information as the cursor from which it is
+        copied, and which optionally refers to the same position in
+        the database.
+    
+        
+        In order to maintain a cursor position when an application
+        is using locking, locks are maintained on behalf of the cursor
+        until the cursor is closed. In cases when an application is
+        using locking without transactions, cursor duplication is
+        often required to avoid self-deadlocks. For further details,
+        refer to Berkeley DB Transactional Data
+        Store locking conventions.
+    
       
       
         
@@ -555,18 +574,25 @@ self-deadlocks.  For further details, refer to
             
           
         
-        Berkeley DB supports "equality" (also known as "natural"), joins on secondary
-indices.  An equality join is a method of retrieving data from a primary
-database using criteria stored in a set of secondary indices.  It
-requires the data be organized as a primary database which contains the
-primary key and primary data field, and a set of secondary indices.
-Each of the secondary indices is indexed by a different secondary key,
-and, for each key in a secondary index, there is a set of duplicate data
-items that match the primary keys in the primary database.
-        For example, let's assume the need for an application that will return
-the names of stores in which one can buy fruit of a given color.  We
-would first construct a primary database that lists types of fruit as
-the key item, and the store where you can buy them as the data item:
+        
+        Berkeley DB supports "equality" (also known as "natural"),
+        joins on secondary indices. An equality join is a method of
+        retrieving data from a primary database using criteria stored
+        in a set of secondary indices. It requires the data be
+        organized as a primary database which contains the primary key
+        and primary data field, and a set of secondary indices. Each
+        of the secondary indices is indexed by a different secondary
+        key, and, for each key in a secondary index, there is a set of
+        duplicate data items that match the primary keys in the
+        primary database.
+    
+        
+        For example, let's assume the need for an application that
+        will return the names of stores in which one can buy fruit of
+        a given color. We would first construct a primary database
+        that lists types of fruit as the key item, and the store where
+        you can buy them as the data item:
+    
         
           @@ -607,8 +633,11 @@ the key item, and the store where you can buy them as the data item:

             

             
           
         
-        We would then create a secondary index with the key color, and,
-as the data items, the names of fruits of different colors.
+        
+        We would then create a secondary index with the key
+        color, and, as the data
+        items, the names of fruits of different colors.
+    
         
           @@ -649,35 +678,54 @@ as the data items, the names of fruits of different colors.

             

             
           
         
-        This secondary index would allow an application to look up a color, and
-then use the data items to look up the stores where the colored fruit
-could be purchased.  For example, by first looking up blue,
-the data item blueberry could be used as the lookup key in the
-primary database, returning Farmer's Market.
-        Your data must be organized in the following manner in order to use the
-DB->join() method:
+        
+        This secondary index would allow an application to look up a
+        color, and then use the data items to look up the stores where
+        the colored fruit could be purchased. For example, by first
+        looking up blue, the data
+        item blueberry could be used
+        as the lookup key in the primary database, returning Farmer's Market.
+    
+        
+        Your data must be organized in the following manner in order
+        to use the DB->join() method:
+    
         
           
-            The actual data should be stored in the database represented by the
-DB object used to invoke this method.  Generally, this
-DB object is called the primary.
-            Secondary indices should be stored in separate databases, whose keys
-are the values of the secondary indices and whose data items are the
-primary keys corresponding to the records having the designated
-secondary key value.  It is acceptable (and expected) that there may be
-duplicate entries in the secondary indices.
-These duplicate entries should be sorted for performance reasons, although
-it is not required.  For more information see the DB_DUPSORT flag
-to the DB->set_flags() method.
+            
+            The actual data should be stored in the database
+            represented by the DB object used to invoke this method.
+            Generally, this DB object is called the
+            primary.
+        
+            
+            Secondary indices should be stored in separate
+            databases, whose keys are the values of the secondary
+            indices and whose data items are the primary keys
+            corresponding to the records having the designated
+            secondary key value. It is acceptable (and expected) that
+            there may be duplicate entries in the secondary indices.
+                
+                    These duplicate entries should be sorted for
+                    performance reasons, although it is not required. For
+                    more information see the DB_DUPSORT flag to the
+                    DB->set_flags() method.
+                
           
         
-        What the DB->join() method does is review a list of secondary keys, and,
-when it finds a data item that appears as a data item for all of the
-secondary keys, it uses that data item as a lookup into the primary
-database, and returns the associated data item.
-        If there were another secondary index that had as its key the cost
-of the fruit, a similar lookup could be done on stores where inexpensive
-fruit could be purchased:
+        
+        What the DB->join() method does is review a list of secondary
+        keys, and, when it finds a data item that appears as a data
+        item for all of the secondary keys, it uses that data item as
+        a lookup into the primary database, and returns the associated
+        data item.
+    
+        
+        If there were another secondary index that had as its key
+        the cost of the fruit, a
+        similar lookup could be done on stores where inexpensive fruit
+        could be purchased:
+    
         
           @@ -722,25 +770,33 @@ fruit could be purchased:

             

             
           
         
-        The DB->join() method provides equality join functionality.  While not
-strictly cursor functionality, in that it is not a method off a cursor
-handle, it is more closely related to the cursor operations than to the
-standard DB operations.
-        It is also possible to do lookups based on multiple criteria in a single
-operation.  For example, it is possible to look up fruits that are both
-red and expensive in a single operation.  If the same fruit appeared as
-a data item in both the color and expense indices, then that fruit name
-would be used as the key for retrieval from the primary index, and would
-then return the store where expensive, red fruit could be purchased.
+        
+        The DB->join() method provides equality join functionality.
+        While not strictly cursor functionality, in that it is not a
+        method off a cursor handle, it is more closely related to the
+        cursor operations than to the standard DB operations.
+    
+        
+        It is also possible to do lookups based on multiple criteria
+        in a single operation. For example, it is possible to look up
+        fruits that are both red and expensive in a single operation.
+        If the same fruit appeared as a data item in both the color
+        and expense indices, then that fruit name would be used as the
+        key for retrieval from the primary index, and would then
+        return the store where expensive, red fruit could be
+        purchased.
+    
         
           
             
               
-                Example
+                Example
               
             
           
-          Consider the following three databases:
+          
+            Consider the following three databases:
+        
           
             
               
@@ -750,7 +806,9 @@ then return the store where expensive, red fruit could be purchased.
                 
                   
                     key = SSN
-                    data = record containing name, address, phone number, job title
+                    data = record containing name,
+                            address, phone number, job
+                            title
                   
                 
               
@@ -778,15 +836,22 @@ then return the store where expensive, red fruit could be purchased.
               
             
           
-          Consider the following query:
+          
+            Consider the following query:
+        
           Return the personnel records of all people named smith with the job
 title manager.
-          This query finds are all the records in the primary database (personnel)
-for whom the criteria lastname=smith and job title=manager is
-true.
-          Assume that all databases have been properly opened and have the
-handles:  pers_db, name_db, job_db.  We also assume that we have an
-active transaction to which the handle txn refers.
+          
+            This query finds are all the records in the primary
+            database (personnel) for whom the criteria lastname=smith and job
+            title=manager is true.
+        
+          
+            Assume that all databases have been properly opened and
+            have the handles: pers_db, name_db, job_db. We also assume
+            that we have an active transaction to which the handle txn
+            refers.
+        
           
           DBC *name_curs, *job_curs, *join_curs;
 DBC *carray[3];
@@ -846,11 +911,15 @@ if (job_curs != NULL &&
     ret = tret;
 
 return (ret);
-          The name cursor is positioned at the beginning of the duplicate list
-for smith and the job cursor is placed at the beginning of
-the duplicate list for manager.  The join cursor is returned
-from the join method.  This code then loops over the join cursor getting
-the personnel records of each one until there are no more.
+          
+            The name cursor is positioned at the beginning of the
+            duplicate list for smith
+            and the job cursor is placed at the beginning of the
+            duplicate list for manager.
+            The join cursor is returned from the join method. This code then
+            loops over the join cursor getting the personnel records of each one
+            until there are no more.
+        
         
       
       
@@ -861,12 +930,15 @@ the personnel records of each one until there are no more.
             
           
         
-        Once a cursor has been initialized to refer to a particular key in the
-database, it can be used to determine the number of data items that are
-stored for any particular key.  The DBC->count() method returns
-this number of data items.  The returned value is always one, unless
-the database supports duplicate data items, in which case it may be any
-number of items.
+        
+        Once a cursor has been initialized to refer to a particular
+        key in the database, it can be used to determine the number of
+        data items that are stored for any particular key. The
+        DBC->count() method returns this number of data items. The
+        returned value is always one, unless the database supports
+        duplicate data items, in which case it may be any number of
+        items.
+    
       
       
         
@@ -876,12 +948,15 @@ number of items.
             
           
         
-        The DBC->close() method closes the DBC cursor, after which the
-cursor may no longer be used.  Although cursors are implicitly closed
-when the database they point to are closed, it is good programming
-practice to explicitly close cursors.  In addition, in transactional
-systems, cursors may not exist outside of a transaction and so must be
-explicitly closed.
+        
+        The DBC->close() method closes the DBC cursor, after which
+        the cursor may no longer be used. Although cursors are
+        implicitly closed when the database they point to are closed,
+        it is good programming practice to explicitly close cursors.
+        In addition, in transactional systems, cursors may not exist
+        outside of a transaction and so must be explicitly
+        closed.
+    
       
     
     
@@ -899,9 +974,7 @@ explicitly closed.
           
             Home
           
-           Chapter 4. 
-		Access Method Wrapup
-        
+           Chapter 4.  Access Method Wrapup 
         
       
     
-- 
cgit v1.2.1

Retrieving records with a cursor

Retrieving records with a + cursor

Cursor position flags

Cursor position flags

Retrieving specific key/data pairs

Retrieving specific key/data pairs

Retrieving based on record numbers

Retrieving based on record numbers

Special-purpose flags

Special-purpose flags

Note

Example

Example