GROCERY LIST HELP TOPICS
------------------------
License and Warranty Information
Support
Program Configuration File
Database Files
Access Rights
Welcome Message
File Menu
Edit Menu
Database Menu
Find Menu
Print Menu
View Menu
Help Menu

LICENCE AND WARRANTY INFORMATION
--------------------------------
This program is FREEWARE. It is provided as an example program of
the Variable Block Database C++ class library. You are granted
the right to use this software product free of charge. You are
free to copy and/or distribute this software to others. The
software may not be circulated in any incomplete or modified
form, which means you may not alter, delete, or add any files in
the distribution archive. You may not lease, rent, sell, or make
any profit out of the software without written permission from
the author.  Moreover, this software is released as public
domain freeware, which means no one shall be charged any money
for the use of this software.

DISCLAIMER OF WARRANTY: THE USE OF THIS SOFTWARE IS AT THE
LICENSEE'S SOLE RISK. THIS SOFTWARE AND DOCUMENTION ARE PROVIDED
"AS IS" WITHOUT WARRANTY OF ANY KIND. THE ENTIRE RISK OF THE
QUALITY AND PERFORMANCE OF THIS SOFTWARE IS WITH YOU. SHOULD ANY
ELEMENT OF THIS SOFTWARE PROVE DEFECTIVE, YOU WILL ASSUME THE
COST OF ALL NECESSARY SERVICING, REPAIR, OR CORRECTION.
 
SUPPORT INFORMATION
-------------------
This program is provided as an example program of the Variable
Block Database C++ class library. It was never indented to be a
full-featured commercial application. Some features of this 
program may need to be changed to meet your specific needs.
The source code is freely available with no restrictions on
modifying it. For further information on VBD technology contact
the author at: 

Doug Gaer
11691 SW 17TH ST
Miami, FL 33165-2149

Phone: 305-229-4461
FAX: 305-553-1901

dgaer@email.com

ftp://ftp.nhc.noaa.gov/pub/doug

OVERVIEW
--------
The Grocery List Program was built with the "wxWindows" GUI library,
version 1.68B. For more information on wxWindows visit the
wxWindows Home Site at: 

http://web.ukonline.co.uk/julian.smart/wxwin/

The Grocery List Program is a persistent object database program used 
to store and manipulate strings, integer values, and floating point 
values. Each member is labeled with a program identifier to create the 
following entry fields in the user interface programs:  

ITEM NAME
BRAND NAME
STORE NAME
PRICE
QUANTITY
PURCHASING

The "ITEM NAME" field is a case-sensitive key member used to uniquely
identify each object in the database. An object's key name can
only appear once in the database. The key name restriction is
enforced to prevent duplicate names from appearing in the
database. The database will support duplicate names, but this
feature was not implemented in this program. All the other fields 
are optional and can be changed as needed.

The program consists of a main menu and a text window. All
database operations are performed through the main menu. The
program's text window is used by the program to display a welcome
message each time the program starts and echo the results of each
database operation performed. Welcome messages are text files
used to display information about this application. You can use
any text editor to change the program's welcome message.

PROGRAM CONFIGURATION FILE
--------------------------
The program's configuration file is used to load configurable
parameters from a text file. You can use any text editor to
modify the configuration file. 

This program will search for the its configuration file, named
"grocery.ini", in the directory where it was executed. If the program
cannot find its configuration file, it will search the
environment for the GDBCFG variable. The GDBCFG is used to 
tell the program where its configuration file is if it is located 
in a different directory. The following are some examples of how 
to set a path to the program configuration file in the environment:
 
set GDBCFG =C:\PROGRA~1\GROCERY\grocery.ini

If the program cannot find its configuration file or a
configuration file does not exist, it will substitute the
configurable parameters with preset default values. 

DATABASE FILES
--------------
When the program is executed for the first time a new data file
and index file will be created. The program will automatically
open its associated data file and index file every time after
that. The program's configuration file is used to point the
program to the location of the database and establish user access
rights. If the files cannot be found the program will create
empty ones in its working directory. If you want to specify a
specific database when the program starts type the program's name
followed by the name of the database with no file extension:
MyDbase mydbfile 

The program's working directory is the default location for the
database files. The program uses both a data file and an index
file. The data file named "grocery.pod" stores the database and
the index file named "grocery.btx" stores the location of each
object in the data file. Both the name and location of the
database files can be changed in the program's configuration
file. You can use any text editor to edit the program's
configuration file. 

The Persistent Object Database manager manages all of the string
objects created by the Grocery List program. Files created by the 
POD manager are given a ".pod" extension to allow the user to
identify them as POD data files. Index files created by the POD
manager are given a ".btx" extenuation to allow the user to
identify them as B-tree index files. An index file is a VBD file
used to store the address where the object's data can be found in
the data file. Index files were implemented to increase the speed
of search operations. 

ACCESS RIGHTS 
-------------
There are two levels of access for the database, administrative
access and a general access. Access levels are configured in the
program's configuration file. If an access level is not specified
the program will default to general access. Each time the program
starts it will display your current access level on the program's
status line. If you do have admin privileges the program's name
will be displayed on the status line when the program starts. At
any time, you can select the "Access Rights" option from the Help
Menu to display your current access rights. 

General Access:
General access grants you read-only privileges. You do not have
the capability to modify the database with an add, change,
delete, import, or merge operation. General access denies you the
right to create new database files. If you try to create a new
database with general access the program will flag you with a
file creation exception and terminate.

Administrative Rights:
Administrative access grants you read and write privileges. You
will be allowed to modify the database, assuming that you have
read and write privileges to the actual database files. If you
give yourself ADMIN privileges and do not have read and write
access to the database files, the program will flag you with an
error and terminate. ADMIN privileges does not give you exclusive
rights to the database. 

Exclusive Rights:
Exclusive rights, means that your instance of this program is the
only one running. If more then one version of this application is
using this database, either over the network or on the same
computer, you do not have exclusive access to the database. Any
modifications made to the database without exclusive rights will
flag the other users with an access violation. An access
violation means that the database has been modified and your
version is no longer valid. If you receive an access violation,
exit the program and restart it. 

WELCOME MESSAGE 
---------------
A file named "welcome.txt", located in the program's working
directory, contains the program's welcome message. The welcome
message is used to display program information when the program
first starts. Both the name and location of the welcome message
can be changed in the program configuration file. You can use any
text editor to edit the program's configuration file and welcome
message. 

FILE MENU 
---------
The File menu allows you to select various options to perform
file operations on the open database. 

VBD File Statistics
Export
Import
Create Template
Backup
Merge
Compare Index File
Rebuild Index File
Exit

VBD File Statistics:
Select the "VBD File Statistics" option to display detailed file
information about the open database. This information is used to
analyze and troubleshoot VBD files. File statistics for both the
data file and the index file will be displayed in the program's
text window. 

Export:
Select the "Export" option to export the entire database to a
text file delimited by tabs. The exported text files can be
imported into other applications such as Microsoft Excel. 

When this menu option is selected, a File Selection Box will
appear. Either select or enter the name of the file to export the
database into. After selecting or entering the file name click on
the Open button. If the file does not exist a new file will be
created. Pre-existing files will be overwritten. 

Import:
Select the "Import" option to import a text file delimited by
tabs into this database. The import file must contain the correct
number of strings per line, according to the format specified by
the Export option or the Create Template option. NOTE: You must have 
exclusive rights to the database to perform an import operation. 
See the Access Rights section. 

When this menu option is selected, a File Selection Box will
appear. Either select or enter the file name to import. After
selecting or entering the file name click on the Open button.

The import function parses the text file line by line searching
for text strings separated by tabs. If there is not enough
strings on a line to complete an entry, the import function will
flag you with an error and skip this entry. If an entry is
already in the database, the import function will give you the
option to update this entry, skip this entry, or update this
entry and all others without prompting. After completion, the
import function will report the number of new items that were
imported and the number of items that were updated. 

Create Template:
Select the "Create Template" option to create a template text
file used to create import files. When the file is imported, the
template information is discarded. 

When this menu option is selected, a File Selection Box will
appear. Either select or enter the name of the file to write the
text template to. After selecting or entering the file name click
on the Open button. If the file does not exist a new file will be
created. Pre-existing files will be overwritten. 

Backup:
Select the "Backup" option to backup the contents of this data
file to a new data file. NOTE: Since the index file can always be
rebuilt by selecting the Rebuild Index File option, only the data
file will be copied. Backup copies of the database should be made
regularly in case of disk failures or file corruption. 

When this menu option is selected, a File Selection Box will
appear. Either select or enter the file name to copy this
database into. After selecting or entering the file name click on
the Open button. If the file does not exist a new file will be
created. Pre-existing files will be overwritten. 

Merge:
Select the "Merge" option to merge the contents of another
database with this one. Merges are used to update the database
when other copies of it exist on other systems, such as laptop
computers. NOTE: You must have exclusive rights to the database
to perform a merge operation. See the Access Rights section. 

When this menu option is selected, a File Selection Box will
appear. Either select or enter the file name of the merge file.
After selecting or entering the file name click on the Open
button. 

The merge function checks each variable block header for the
correct class identification numbers before importing a new
object. This ensures that no objects from another VBD file will
be imported into this database. If an object with correct class
ID is already in the database, the merge function will give you
the option to update this entry, skip this entry, or update this
entry and all others without prompting. After completion, the
merge function will report the number of new objects that were
imported and the number of objects that were updated. 

Compare Index File:
Select the "Compare Index File" option to compare each object in
the data file with its entry key in the index file. The result of
the test will be echoed in the program's text window. If the test
fails, rebuild the index file with the Rebuild Index File option
and copy the new index file over this one. 

Index files are used to locate objects in the data file by
associating each object's entry key with a file address. Each new
object added to the database is assigned a unique key name. The
key name and the object's file address is then stored in the
index file. If all the objects in the data file do not have valid
key entries in the index file, either the index file or the data
file could be corrupt. If the compare index file function still
fails after the index file is rebuilt and installed, the data
file is corrupt. A corrupt data file can be restored from a
backup copy or rebuilt with the VBD file Debug Utility. 

Rebuild Index File:
Select the "Rebuild Index File" option to rebuild the index file.
Index files are used to locate objects in the data file. Each
index file is unique and can only be rebuilt by the application
that created it. 

When this menu option is selected, a File Selection Box will
appear. Either select or enter the name of the new index file.
After selecting or entering the file name click on the Open
button under. If the file does not exist a new file will be
created. Pre- existing files will be overwritten. 

NOTE: The rebuild function will not allow you to overwrite the
existing index file, even though it no longer contains valid
entry keys. After the index file is rebuilt, you have to exit the
program and copy the new index file over the existing one: 

C:\>copy C:\temp\new_file.btx C:\PROGRA~1\GORCERY\grocery.btx 

Exit:
Select the "Exit" option to exit the program.

EDIT MENU 
---------
The Edit menu is used to perform clipboard operations. 

Cut:
Select the "Cut" option to cut a block of text and place it on
the Windows clipboard. You can perform a cut operation outside of
the program's text window by pressing Control-X. This allows you
to cut and paste text during an add or change operation. Text
placed on the clipboard by a cut or a copy can be pasted into
another applications. 

Copy:
Select the "Copy" option to copy a block of text and place it on
the Windows clipboard. You can perform a copy operation outside
of the program's text window by pressing Control-C. This allows
you to cut and paste text during an add or change operation. Text
placed on the clipboard by a copy or a cut can be pasted into
another applications. 

Paste:
Select the "Paste" option to paste a block of text from the
Windows clipboard. You can perform a paste operation outside of
the program's text window by pressing Control-V. This allows you
to paste text during an add or change operation. 

DATABASE MENU 
-------------
The Database menu is used to perform all database display,
insert, change, and remove operations. 

Display
Add
Change
Remove
Reset Purchasing List
Set All For Purchase

Display:
Select the "Display" option to display the database object by
object. When selected, the display panel will appear and display
the first object. The display panel contains a series of buttons
that allows you to manipulate the objects being displayed. 

- Click on the Next button to advance to the next object.
- Click on the Prior button to display the prior object.
- Click on the Change button to change this object.
- Click on the Close button to close the display panel.
- Click on the Remove button to delete this object.

NOTE: You must have exclusive rights to the database to perform a
change or remove operation. See the Access Rights section. 

Add:
Select the "Add" option to add new objects to the database. NOTE:
You must have exclusive rights to the database to perform an add
operation. See the Access Rights section. 

When selected, the add panel will appear. You can paste text in the 
entry fields from the Windows clipboard by pressing Control-V after 
a cut or copy operation. From here enter the name of the entry and 
its associated fields: 

ITEM NAME - Name of the item (variable length string.)
BRAND NAME - Brand name of the item (variable length string.)
STORE NAME - Store name of the item (variable length string.)
PRICE - Cost of the item (floating point value: 1.88)
QUANTITY - Number of items to be purchased (integer value: 02)

You can set an item for purchase by toggling the NO/YES selection in 
the PUCHASING choice box. By default this value is always set to NO. 

- Click on the Add button to add the object to the database.
- Click on the Cancel button to abort this entry.
- Click on the Close button to close the add panel.
- Click on the Revert to display the previous object entered.

The name of the object, entered in the first entry field, must be
unique and can only be entered once. If the object already exists
in the database the add function will flag you with an error.
NOTE: The database will support duplicate objects, but this
feature was not implemented in this program. 

Change:
Select the "Change" option to change an object in the database.
NOTE: You must have exclusive rights to the database to perform a
change operation. See the Access Rights section. When selected,
the change panel will appear. From here, enter the object's key
name and click on the Search button. After changing you must
click on the Commit button to enter the changes. 

If the object is found, it will be displayed in the change panel
with its key name grayed out. You are allowed to change
everything except the object's key name. NOTE: The key name
restriction is enforced to prevent duplicate names from appearing
in the database. The database will support duplicate names, but
this feature was not implemented in this program. 

After changing the data, use the change panel buttons to process
it. You can paste text in the entry fields from the Windows
clipboard by pressing Control-V after a cut or copy operation. 

- Click on the Search button to find the object in the database.
- Click on the Commit button to commit the changes.
- Click on the Cancel button to abort this change.
- Click on the Close button to close the change panel.
- Click on the Revert to display the previous object.

Remove:
Select the "Remove" option to remove an object from the database.
NOTE: You must have exclusive rights to the database to perform a
remove operation. See the Access Rights section. When selected, a
string-input box will appear and prompt you for the object's key
name. Enter the key name of the object you want to delete. You
can paste in the object's key name from the Windows clipboard by
pressing Control-V after a cut or copy operation.

Reset Purchasing List:
Select the "Reset Purchasing List" option to select none of the 
objects in the database for purchase. 

Set All For Purchase:
Select the "Set All For Purchase" option to select all the objects 
in the database for purchase.

FIND MENU 
---------
The Find menu is used to find objects in the database. A search
can be performed on the object's key name or any of its
associated string fields. 

After selecting the key name or field to perform the search on, a
string-input box will appear and prompt you to enter a string to
search for. You can paste in the text from the Windows clipboard
by pressing Control-V after a cut or copy operation. After
entering the string, click on the Ok button to execute the search
operation. 

Two types of searches can be performed, a plain search or a wild
card search. A plain search is not case sensitive, but it
requires you to enter the complete string. 

The plain search will find a single match if searching by key
name or will find every match of the complete string if searching
on any of the other entry fields. After a plain search or
wildcard search, you will be given the option to display the
object(s) that matched the string. If no matches are found, the
program will alert you with a message stating that no matches
were found. 

A wildcard search is performed by entering the wildcard character
"*" anywhere in the string. Wildcard searches are case sensitive,
but only require you to enter a piece of the string. The wild
card search will find every occurrence of the string in the
specified field.

PRINT MENU 
----------
The Print menu is used to print the database to a selected
printer, a PostScript file, or a text file. 

Print
Printer Setup
Page Setup
Print Preview
Print to PostScript file
Print to text file

Print:
Select the "Print Items to be Purchased" option to print only 
the objects selected for purchase to a selected printer, using 
the Windows 95 print manager. The total cost with tax is printed 
on the last page of the document. The sales tax is calculated 
from a percentage given in the program configuration file. 

Select the "Print All Items" option to print all the objects 
database to a selected printer, using the Windows 95 print manager. 
The total cost with tax is printed on the last page of the document. 
The sales tax is calculated from a percentage given in the program 
configuration file.

Printer Setup:
Select the "Printer Setup" option to configure the printer before
printing. 

NOTE: If you select landscape mode in the Page Setup panel, you
must setup this printer to print in landscape mode. To setup the
printer for landscape mode, click on the Properties button in the
printer dialog box and then find the page orientation group box.
Select Landscape and click on Ok. 

Page Setup:
Select the "Page Setup" option to set various page parameters
before previewing or printing the document. The default page
parameters are manually set in the program's configuration file.
All the page parameters will revert to the default settings each
time the program is executed. After changing or defaulting to the
configuration file settings, you must click the Accept button to
enter the changes. 

- The Lines Per Page slider sets the number of lines per page.
- The Cell Length slider sets the max number of field characters.
- The Font Size slider sets the font size.
- The Left Margin slider sets the left margin.
- The Orientation choice box is used to select Landscape mode. 
- The Font choice box is used to select a desired font family.  

NOTE: If you select landscape mode, you must setup this printer
to print in landscape mode. To setup the printer for landscape
mode, click on the Properties button in the printer dialog box
and then find the page orientation group box. Select Landscape
and click on Ok. 

After changing the page parameters, use the panel buttons to
process the changes. 

- Click on the Close button to close this panel.
- Click on the Accept button to enter the page settings.
- Click on the Cancel button to cancel and revert.
- Click on the Default button to revert to the default settings.
 
Print Preview:
Select the "Print Preview Items for Purchase" option to preview 
only the objects selected for purchase before printing the document. 
The total cost with tax is printed on the last page of the document. 
The sales tax is calculated from a percentage given in the program 
configuration file. 

Select the "Print Preview for All Items" option to preview all the 
objects in the database before printing the document. The total cost 
with tax is printed on the last page of the document. The sales tax 
is calculated from a percentage given in the program configuration 
file.

The print preview panel allows you to zoom in or out on the selected 
page. You can also move back and forth between the pages.

Print to PostScript File:
Select the "Print to PostScript File" option to print only the objects
selected for purchase to a PostScript file. The total cost with tax is
printed on the last page of the document. The sales tax is calculated 
from a percentage given in the program configuration file. 

Select the "Print all Items to PostScript File" option to print all
the objects in the database to a PostScript file. The total cost with 
tax is printed on the last page of the document. The sales tax is 
calculated from a percentage given in the program configuration file.

All the PostScript printing parameters are loaded from the program's 
configuration file each time a document is printed. 

When this menu option is selected, a File Selection Box will
appear. Either select or enter the name of the PostScript file to
create. After selecting or entering the file name click on the
Open button. If the file does not exist a new file will be
created. Pre-existing files will be overwritten. 

The PostScript file must be manually sent to a PostScript printer
after it is created: 

C:>type c:\temp\grocery.ps > LPT1 

Print to text file:
Select the "Print to text file" option to only the objects selected 
for purchase to a text file.

Select the "Print all Items to text file" option to all the objects 
in the database to a text file.

When this menu option is selected, a File Selection Box will
appear. Either select or enter the name of the text file to
create. After selecting or entering the file name click on the
Open button. If the file does not exist a new file will be
created. Pre-existing files will be overwritten. 

VIEW MENU 
---------
The View menu is used to clear the program's text window and view 
the purchasing totals with tax. The sales tax is calculated from a 
percentage given in the program configuration file. 

Clear Window:
Select the "Clear Window" option to clear the program's text window. 

View Cost of Purchase:
Select the "View Cost of Purchase" option to view the cost of only 
the objects selected for purchase. 

View Cost of All Items:
Select the "View Cost of All Items" option to view the cost of all 
the items in the database.

HELP MENU 
---------
The Help menu is used to display the program's version number and
your user access rights. 

About:
Select the "About" option to display this program's name version
number. 

Access Rights:
Select the "Access Rights" option to display your current user
access rights. Your access level is set in the program's
configuration file.
