Imported from /home/lorry/working-area/delta_berkeleydb/db-6.1.23.tar.gz.HEADdb-6.1.23master

4 files changed, 54 insertions, 11 deletions

diff --git a/examples/c/getting_started/example_database_load.c b/examples/c/getting_started/example_database_load.c
index 52127421..e09a1096 100644
--- a/examples/c/getting_started/example_database_load.c
+++ b/examples/c/getting_started/example_database_load.c
@@ -1,7 +1,7 @@
 /*-
  * See the file LICENSE for redistribution information.
  *
- * Copyright (c) 2004, 2012 Oracle and/or its affiliates.  All rights reserved.
+ * Copyright (c) 2004, 2015 Oracle and/or its affiliates.  All rights reserved.
  */
 
 #include "gettingstarted_common.h"
@@ -77,7 +77,7 @@ main(int argc, char *argv[])
     /* Open all databases */
     ret = databases_setup(&my_stock, "example_database_load", stderr);
     if (ret) {
-	fprintf(stderr, "Error opening databases\n");
+	fprintf(stderr, "Error opening databases.\n");
 	databases_close(&my_stock);
 	return (ret);
     }
@@ -121,6 +121,7 @@ load_vendors_database(STOCK_DBS my_stock, char *vendor_file)
 	return (-1);
     }
 
+    /* Iterate over the vendor file */
     while (fgets(buf, MAXLINE, ifp) != NULL) {
 	/* zero out the structure */
 	memset(&my_vendor, 0, sizeof(VENDOR));
@@ -164,6 +165,7 @@ load_vendors_database(STOCK_DBS my_stock, char *vendor_file)
 	my_stock.vendor_dbp->put(my_stock.vendor_dbp, 0, &key, &data, 0);
     } /* end vendors database while loop */
 
+    /* Close the vendor.txt file */
     fclose(ifp);
     return (0);
 }
@@ -220,6 +222,10 @@ load_inventory_database(STOCK_DBS my_stock, char *inventory_file)
 	    return (-1);
     }
 
+    /*
+     * Read the inventory.txt file line by line, saving each line off to
+     * the database as we go.
+     */
     while (fgets(buf, MAXLINE, ifp) != NULL) {
 	/*
 	 * Scan the line into the appropriate buffers and variables.
@@ -238,10 +244,22 @@ load_inventory_database(STOCK_DBS my_stock, char *inventory_file)
 	bufLen = 0;
 	dataLen = 0;
 
+	/*
+	 * We first store the fixed-length elements. This makes our code
+	 * to retrieve this data from the database a little bit easier.
+	 */
+
+	/* First discover how long the data element is. */
 	dataLen = sizeof(float);
+	/* Then copy it to our buffer */
 	memcpy(databuf, &price, dataLen);
+	/*
+	 * Then figure out how much data is actually in our buffer.
+	 * We repeat this pattern for all the data we want to store.
+	 */
 	bufLen += dataLen;
 
+	/* Rinse, lather, repeat. */
 	dataLen = sizeof(int);
 	memcpy(databuf + bufLen, &quantity, dataLen);
 	bufLen += dataLen;
@@ -251,11 +269,19 @@ load_inventory_database(STOCK_DBS my_stock, char *inventory_file)
 	bufLen = pack_string(databuf, category, bufLen);
 	bufLen = pack_string(databuf, vendor, bufLen);
 
+	/*
+	 * Now actually save the contents of the buffer off
+	 * to our database.
+	 */
+
 	/* Zero out the DBTs */
 	memset(&key, 0, sizeof(DBT));
 	memset(&data, 0, sizeof(DBT));
 
-	/* The key is the item's SKU */
+	/*
+	 * The key is the item's SKU. This is a unique value, so we need
+	 * not support duplicates for this database.
+	 */
 	key.data = sku;
 	key.size = (u_int32_t)strlen(sku) + 1;
 
diff --git a/examples/c/getting_started/example_database_read.c b/examples/c/getting_started/example_database_read.c
index 79a9fc2c..0e8486ff 100644
--- a/examples/c/getting_started/example_database_read.c
+++ b/examples/c/getting_started/example_database_read.c
@@ -1,7 +1,7 @@
 /*-
  * See the file LICENSE for redistribution information.
  *
- * Copyright (c) 2004, 2012 Oracle and/or its affiliates.  All rights reserved.
+ * Copyright (c) 2004, 2015 Oracle and/or its affiliates.  All rights reserved.
  */
 
 #include "gettingstarted_common.h"
@@ -72,6 +72,10 @@ main(int argc, char *argv[])
 	return (ret);
     }
 
+	/*
+	 * Show either a single item or all items, depending
+	 * on whether itemname is set to a value.
+	 */
     if (itemname == NULL)
 	ret = show_all_records(&my_stock);
     else
@@ -197,23 +201,33 @@ show_inventory_item(void *vBuf)
     char *category, *name, *sku, *vendor_name;
     char *buf = (char *)vBuf;
 
+    /* Get the price. */
     price = *((float *)buf);
     buf_pos = sizeof(float);
 
+    /* Get the quantity. */
     quantity = *((int *)(buf + buf_pos));
     buf_pos += sizeof(int);
 
+    /* Get the inventory item's name */
     name = buf + buf_pos;
     buf_pos += strlen(name) + 1;
 
+    /* Get the inventory item's sku */
     sku = buf + buf_pos;
     buf_pos += strlen(sku) + 1;
 
+    /*
+     * Get the category (fruits, vegetables, desserts) that this
+     * item belongs to.
+     */
     category = buf + buf_pos;
     buf_pos += strlen(category) + 1;
 
+    /* Get the vendor's name */
     vendor_name = buf + buf_pos;
 
+    /* Display all this information */
     printf("name: %s\n", name);
     printf("\tSKU: %s\n", sku);
     printf("\tCategory: %s\n", category);
@@ -221,6 +235,7 @@ show_inventory_item(void *vBuf)
     printf("\tQuantity: %i\n", quantity);
     printf("\tVendor:\n");
 
+    /* Return the vendor's name */
     return (vendor_name);
 }
 
diff --git a/examples/c/getting_started/gettingstarted_common.c b/examples/c/getting_started/gettingstarted_common.c
index 86faa1c0..f388b13d 100644
--- a/examples/c/getting_started/gettingstarted_common.c
+++ b/examples/c/getting_started/gettingstarted_common.c
@@ -1,7 +1,7 @@
 /*-
  * See the file LICENSE for redistribution information.
  *
- * Copyright (c) 2004, 2012 Oracle and/or its affiliates.  All rights reserved.
+ * Copyright (c) 2004, 2015 Oracle and/or its affiliates.  All rights reserved.
  */
 
 #include "gettingstarted_common.h"
@@ -49,9 +49,11 @@ get_item_name(DB *dbp, const DBT *pkey, const DBT *pdata, DBT *skey)
 
 /* Opens a database */
 int
-open_database(DB **dbpp, const char *file_name,
-  const char *program_name, FILE *error_file_pointer,
-  int is_secondary)
+open_database(DB **dbpp,       /* The DB handle that we are opening */
+    const char *file_name,     /* The file in which the db lives */
+    const char *program_name,  /* Name of the program */
+    FILE *error_file_pointer,
+    int is_secondary)
 {
     DB *dbp;    /* For convenience */
     u_int32_t open_flags;
@@ -173,8 +175,8 @@ initialize_stockdbs(STOCK_DBS *my_stock)
     my_stock->inventory_dbp = NULL;
     my_stock->vendor_dbp = NULL;
     my_stock->itemname_sdbp = NULL;
-    my_stock->vendor_db_name = NULL;
     my_stock->inventory_db_name = NULL;
+    my_stock->vendor_db_name = NULL;
     my_stock->itemname_db_name = NULL;
 }
 
diff --git a/examples/c/getting_started/gettingstarted_common.h b/examples/c/getting_started/gettingstarted_common.h
index 7365fc7f..90c12e6e 100644
--- a/examples/c/getting_started/gettingstarted_common.h
+++ b/examples/c/getting_started/gettingstarted_common.h
@@ -1,7 +1,7 @@
 /*-
  * See the file LICENSE for redistribution information.
  *
- * Copyright (c) 2004, 2012 Oracle and/or its affiliates.  All rights reserved.
+ * Copyright (c) 2004, 2015 Oracle and/or its affiliates.  All rights reserved.
  */
 
 #include <db.h>
@@ -52,8 +52,8 @@ typedef struct vendor {
 } VENDOR;
 
 /* Function prototypes */
-int	databases_close(STOCK_DBS *);
 int	databases_setup(STOCK_DBS *, const char *, FILE *);
+int	databases_close(STOCK_DBS *);
 void	initialize_stockdbs(STOCK_DBS *);
 int	open_database(DB **, const char *, const char *, FILE *, int);
 void	set_db_filenames(STOCK_DBS *my_stock);