SET ORDER TO TAG (m.tag_name) &direction IN (m.dbf_name)
FULL_DBF
STAG_NAME
FGO_HOME
stDIRECTION
DBF_NAME
CDX_NAME
OLAST_DBF
LAST_PATH
OPENED_OK
TOPIC
DETAILS
CRITERIA_1
OBJECTTYPE
About ProBuilder 8 General
Acknowledgements 10 General
Getting Started 16 General
How do I...? 75 General
ProBuilder Methodology 1163 General
Technical Support 154 General
Third Wave Software 160 General
What is ProBuilder? 162 General Adding and Removing Tags 229TAG_OPTS STRUCTURE Push Button Ascending vs. Descending Tags 247ASC_OR_DSCSTRUCTURE Radio Button Black Box 257 Real-world entity Building defined databases 289DICT_OPTS5_Q9S14XTHQPush Button Change Log 310_QA013GGD0 Dialog Child Database 320TARGET_DBF_Q9S0ZCJE4Popup Child Database Order 331TARGETORDR_Q9S0ZCJE4Popup Database Description 345DBF_CALL STRUCTURE Data entry field Database Name 352DBF_NAME STRUCTURE Data entry field Database Schema 361HAS_DSCHEMSTRUCTURE Check Box Default Value 378HASDEFAULTSTRUCTURE Check Box Define Options 390DICT_OPTS1_Q9S11C2TDPush Button Deleting a Definition 416DICT_OPTS6_Q9S14XTHQPush Button Exiting ProBuilder 431DICT_OPTS7_Q9S16HHC2Push Button Field Decimals 438FIELD_DEC Data entry field Field Description 447FIELD_CALL Data entry field Field List 455FIELDS STRUCTURE List Field Name 472FIELD_NAME Data entry field Field Object Checkbox 486HAS_OBJECTSTRUCTURE Check Box Field Object List 520CURR_OBJ OBJECTS Push Button Field Object Name 534OBJECTNAMEOBJECTS Data entry field Field Object Options 543OBJECTOPTSOBJECTS Push Button Field Object Schema 569HAS_SCHEMAOBJECTS Check Box Field Object Tag 583TAGGED OBJECTS Check Box Field Objects 592DICT_OPTS3_QAO0MLYCCReal-world entity Field Schema 615HAS_FSCHEMSTRUCTURE Check Box Field Type 628FIELD_TYPE Data entry field Field Width 648FIELD_LEN Data entry field File List 666THIS_DBF _Q9S11C2TDList File Picker 680PICKLIST Dialog For Expression 711FOR_EXPR STRUCTURE Check Box Importing Definitions 731 Menu Bar Inserting and Deleting Fields 745FIELD_OPTSSTRUCTURE Push Button Okay Dialog 765PRESS_OK W_YESNO Dialog PathFinder 774_QC2134U3S Dialog ProBuilder Menu 791 Menu Pad Program Assignment Dialog 829PROGRAM Dialog Program Assignment Option 838GETPROGRAMSTRUCTURE Check Box Relation Expression Builder 855KEY_EXPR _Q9S0ZCJE4Push Button Relationship Expression 865RELATE_KEY_Q9S0ZCJE4Data entry field Relationship List 879RELATIONS _Q9S0ZCJE4List Relationship Name 891RELAT_NAME_Q9S0ZCJE4Data entry field Relationship Options 904DICT_OPTS4_Q9S11C2TDPush Button Relationship Setting Options 922RELAT_OPTS_Q9S0ZCJE4Push Button Report Options 943_QAQ0T7ITP Dialog Selecting a Structure File 969DICT_OPTS2_Q9S16HHC2Push Button Structure Editor Options 994STRU_OPTS STRUCTURE Push Button Tag Description 1015TAG_CALL STRUCTURE Data entry field Tag Expression 1023TAG_EXPR STRUCTURE Data entry field Tag Expression Builder 1036EXPRESS STRUCTURE Push Button Tag Field 1056TAG_FIELD STRUCTURE Check Box Tag List 1078TAGS STRUCTURE List Tag Name 1090TAG_NAME STRUCTURE Data entry field Tag Schema 1103HAS_TSCHEMSTRUCTURE Check Box Unique Tag 1117TAG_UNIQUESTRUCTURE Check Box Yes/No Alert 1123ANSWER W_YESNO Alert Yes/No/Cancel Alert 1140ANSWER1 WYESNO1 Alert
a ProBuilder 2.0
(c) 1992 by Third Wave Software
4529 Logsdon Drive
Annandale, VA 22003
;We'd like to extend thanks to the following folks for their help in bringing ProBuilder to market:
Lisa Slater and the FoxTalk Journal, without whom ProBuilder would never have reached critical mass.
Joe Paquette, first-class beta testing.
Connie and Brad, for patience in the many hours of my abscence.
Getting Started
General
ProBuilder brings to the FoxPro development environment a new method of controlling and documenting data structures. With easy interactive dialogs and a logical program flow, ProBuilder can simply and cleanly bring a meaningful data dictionary functionality to FoxPro.
Starting ProBuilder
There are two ways to call ProBuilder.
Add ProBuilder to the menu
Create a new menu option on your system menu that calls BUILDER.APP. A good location is creating a "ProBuilder Dictionary" entry on the System menu pad, and giving it a hotkey of CTRL+Y. This is unlikely to conflict with other menu options, and allows you to call ProBuilder without first calling forward the command window.
Type "DO builder.app"
If you chose not to place ProBuilder on your system menu, you can call it directly from the command window. The problem with this is the need to either a)maintain ProBuilder in your path, or b)always type the path name to ProBuilder.
Defining a Database
ProBuilder works on the meta-data level. In other words, it doesn't create databases so much as it creates _definitions_ of databases. The Build option does then turn these definitions into databases on disk.
You can begin defining your structures to the dictionary in a few different ways.
Creating definitions
If you are beginning a project from scratch, it makes the most sense just to create a new definition by selecting the New option at the main window. This will bring forward the Structure Editor, in which you define the field names, types, tags, and other characteristics of a given database.
Just as FoxPro's MODIFY STRUCTURE command allows only a single database definition to be edited at a time, so does ProBuilder. When finished, you simply save your work with
, and then either build that database or define another one.
Import existing structures
Since many projects are ongoing, ProBuilder provides a way to import to the dictionary the structures and tag information for databases that already exist on disk. Selecting the Import option from the main Data Dictionary menu will do this for you.
Defining a Field Object
Since ProBuilder provides a method of defining "global fields", or Field Objects, it may make sense to define all the Field Objects for your system's databases before using ProBuilder to create the definitions for those databases. By doing this first, you can force somewhat greater structure onto your design process by determining which types of elements are common across multiple tables, and define standard characteristics for such fields.
For example, you might use a "key ID number" field in each database. To simplify programming and enforce some logical structure, it might make sense to define a Field Object called "Unique ID Numbers", and then insert that object into each of your database definitions. In this way, you can centralize control (through the Field Object Editor) over the characteristics of key, shared fields.
See also:
How do I...?, Define Options, Importing Definitions, Building Databases, Selecting a Structure File, Field Objects, Field Object Options
How do I...?
General
This help topic serves as quick guide to the help system, targeted to specific tasks. If the question you'd like to ask is stated here, simply refer to the help topic associated with that question.
Defining Databases
How do I...
...import my existing file structures into the ProBuilder dictionary? See Importing Definitions
...create a new database definition? See Define Options
...modify an existing definition in ProBuilder? See Define Options
...set the field order for a definition? See Field List
...tag a field in a definition? See Tag Field
Describing Elements
How do I...
...enter plain-english user descriptions for databases, fields, and schemas? See Database Description, Field Description, Tag Description
...enter full-text descriptions for databases, fields, and tags? See Database Schema, Field Schema, Tag Schema
Defining Objects
How do I...
...use Field Objects in my dictionary? See Field Objects
...create a Field Object from an existing field? See Field Object Checkbox
Handling Relationships
How do I...
...create relationships between databases? See Relationship Options
...use those relationships defined with ProBuilder in my applications? See Black Box
Definition Management
How do I...
...re-build index tags? See Build Defined Databases
...build defined databases? See Build Defined Databases
...delete defined databases? See Deleting a Definition
Reporting
How do I...
...get reports that describe the structures and relationships between defined databases? See ProBuilder Menu, Report Options
See also: Importing Definitions, Define Options, Field List, Tag Field, Database Description, Field Description, Tag Description, Database Schema, Field Schema, Tag Schema, Field Objects, Field Object Checkbox, Relationship Options, Black Box, Build Defined Databases, Deleting a Definition, ProBuilder Menu, Report Options
ProBuilder Methodology
General
A number of basic assumptions were made during the design of ProBuilder. These assumptions were the result of numerous conversations with FoxPro developers in general and ProBuilder beta testers in particular.
Assumption #1: Performance is king.
However good and detailed a data dictionary add-on might be, if it appreciably degrades performance in the field, it's not worth the trouble.
Assumption #2: Simplify, simplify, simplify.
Many DOS FoxPro developers look with some longing at the mainframe and Unix DBMSs that offer full data dictionary implementations, flush with repository management, data integrity enforcement, and other goodies. Many in the DOS world are leery of the amount of work involved in maintaining and managing such complex systems for the purposes (primarily) of documentation, and many other purposes are too performance intensive to be workable on the installed base of 80286 computers.
A strong concensus developed around the idea of a greatly enhanced version of FoxPro's own STRUCTURE EXTENDED databases: a single database that contains the entire definition for each database. What is lost in fine relationality is gained in ease-of-distribution.
The most obvious outcome of this assumption is the implementation of the Objects database. While it is basically relational at heart (in that Field Objects are referred to by ID number), it operates on the assumption that it's easier and preferable to distribute a single STRUCTUR.DBF file than it is to distribute three databases (STRUCTURE, OBJECTS, and SCHEMAS). With this in mind, we chose to duplicate each object's information directly into the definition in which it resides, which eliminates the need for a "generate a distribution file" process.
Assumption #3: Open it up.
It was clear that all of us as developers wanted to be able to tweak the dictionary to our own style of development, to "kit-bash", as Chuck Werner put it in FoxTalk. Clean, well-documented source code was an important component of a successful program.
iProBuilder is supported on CompuServe's FoxForum. Third Wave Software can be reached at CIS 73730,3201 and at phone (730)354-6283.
TWS only agrees to provide support for a)general user queries and b)bugs in the original source code. Consulting services are available for data structure analysis and systems development services. Contact TWS for details.
bThird Wave Software
4529 Logsdon Drive
Annandale, VA 22003
CIS 73730,3201
(703)354-6283
What is ProBuilder?
General
ProBuilder is a simplified data dictionary tool that works completely within the FoxPro environment. It is written completely in the FoxPro 2.0 development language, and takes extensive advantage of the interface elements and design philosophy inherent in FoxPro.
Why a data dictionary?
When developing database systems, we as FoxPro developers are often faced with a serious roadblock to effective database management: FoxPro itself. Since FoxPro offers no data dictionary implementation, we have to fend for ourselves when it comes to documenting our system and strategies for reindexing and rebuilding databases.
While FoxPro's venerable MODIFY STRUCTURE command will allow us to create and modify database structures, it provides no meaningful objective record of those structures. One trashed database can mean hours of tedious reconstruction based on program code or old versions of the database. Fortunately, FoxPro does provide us with the tools to develop our own data dictionary.
A data dictionary not only provides a reliable means to create and modify databases and indexes during development, but also a distributable reference point for managing file rebuilds and reindexes in the field. In addition, and just as importantly, a data dictionary provides valuable documenting capabilities. Relying on LIST STATUS and a word processor to document our systems is a notoriously difficult, time consuming, and inexact method of producing usable, up-to-date guides to our databases, and their relationships to one another.
And what happens if you're hit by the proverbial truck? How will your client (or your replacement) get a handle on the actual status of the system, and know which pieces of the system are out of date with the official documentation?
Why ProBuilder?
ProBuilder addresses these issues by offering a one-stop-shopping approach to the average developer's data dictionary needs. By using ProBuilder to create and modify our databases and indexes, to draw relationships between databases, and to enter full-text schemas to describe our system components, the documentation almost writes itself.
ProBuilder is written entirely in FoxPro 2.0, and the source code is included. Being a FoxPro application not only means that you have access to your dictionaries from within FoxPro, but also that you can break ProBuilder into its elements and place them -- in whole or in part -- on your system menu, for seamless integration into the FoxPro environment.
Features
ProBuilder offers these features, among many others:
Replaces and enhances most of the functionality of the Database Setup dialog
Creates and modifies databases and index tags (with full support for compound .CDXs and the FOR/UNIQUE/ASC-DESC clauses)
Automatically imports existing file structures and .CDX tags
Manages relationships between databases through a simple point-and-click dialog
Generates .PRGs to handle the setting of relations from within your applications
Allows you to assign plain-English names to databases, fields and indexes for easier user-querying
Provides full schema support for databases, fields, and index tags via FoxPro's unlimited length memo fields
Logs changes for fields and index tags
Associates databases with programs, or sets of programs
Outputs reports to the printer, screen, or file on disk
Introduces the Field Object Editor for creating "global fields" that can be assigned to multiple databases, which helps enforce standardization of data elements
Supports multiple dictionaries
Dozens of helpful utilities, alerts, dialogs, and programming ideas
Clean, well-documented FoxPro 2.0 source code included
Thorough, context-sensitive help for all ProBuilder features
Adding and Removing Tags
Push Button
Index tags can be defined and removed in two ways. The first is to check the "Tag field" checkbox, which creates a tag for the current field, or removes the current tag if one exists. The second method is to select either the Add Tag or Remove Tag push buttons.
< Add tag >
This push button will create a new tag, with a generic file name similar to that which is created with the < Insert field > push button. The description and expression for the tag will default to the new tag name.
< Remove tag >
Select this button to remove the tag currently highlighted in the tag list. If the current tag is associated with the current field, the Tag Field checkbox will be unchecked.
See also: Tag List, Tag Field, Tag Name, Tag Description, Tag Expression, Inserting and Deleting Fields
Ascending vs. Descending Tags
Radio Button
Index tags can either operate in ascending (A...Z, 0...9) order, or the opposite (descending). By default, any tag definition created in ProBuilder is in ascending order (which is also FoxPro's default).
To change the order of the index tag, select either ascending or descending. To accept the default, make no changes.
Black Box
Real-world entity
The ideal is programming is to develop the proverbial black box: you put various items into the box, some mysterious process takes place, and completely different items come out the other side. As FoxPro developers, we're all familiar with the concept in the form of generic UDFs that do all sort of neat tricks. ProBuilder now provides you with such a black box for setting relationships.
In complex systems that rely on many different databases relating to one another in various ways, it's important to have a schema of those relations. ProBuilder presents such as a schema in the form of BLACKBOX.PRG. This program, which ProBuilder generates based on the relationships defined for each database in the dictionary, is designed to be incorporated into your distributed application. It provides one stop shopping for setting relations during program execution.
Each relation is saved with a simple, plain-English description that you create. Then, when BLACKBOX.PRG is generated, those descriptions become the basis of a DO CASE...ENDCASE construct. If you then bundle BLACKBOX.PRG with your distributed application, all you have to write in your code is a line that says:
DO blackbox.prg WITH "Invoices to Customers"
and BLACKBOX.PRG will make sure both databases are open, orders are set correctly, and the relationship is established. All without writing any code on your part (except maybe the relational key expression).
Each time a dictionary definition is deleted or the files are rebuilt, you will be asked if you want to re-generate the black box.
See also: Relationship Options, Define Options, Deleting a Database Definition, Building Database
Building defined databases
Push Button
After a database has been defined to the ProBuilder dictionary, it can be created by selecting the < Build... > push button. This calls forward the File Picker dialog, where you can choose to build only the definition highlighted in the File List, or any other definition.
The database built from the definition will be placed in the directory where the current Structur.dbf file was located. If a database with the same name as the definition being built already exists on disk, its records will be appended into the newly built database; no records will be lost.
The procedures that are called by the < Build... > routine (primarily the file_bld, pickerv, make_dbf, and make_cdx .PRG files) should be included in your distributed application, to allow your users to rebuild applications in the field.
After a build has been attempted, you will be given an opportunity to rebuild the relation-setting black box.
See also: File Picker, Black Box, Developer Tips
Change Log
Dialog
This displays all fields and tags for the current definition, and indicates when the last changes were made for each field and tag. The display is arranged in the same order as the field and tag lists, with the fields appearing first.
See also: Field List, Tag List
Child Database
Popup
This is a listing of all databases defined to the current dictionary, with the exception of the currently selected database, which is operating as the parent in the relationships. The database selected will become the "INTO" database, meaning the child of the relationship.
See also: Child Database Order
Child Database Order
Popup
This popup contains all the index tags that have been defined for the selected child database, plus an entry for record number order ("RECNO()"). Since the child of a relationship must be indexed in the same order as the tag expression, it is important to select the correct tag order to match the tag expression defined in the Relationship Expression field.
If the selected child database has no index tags defined, this will display only "RECNO()", and cannot be changed.
See also: Relationship Expression, Child Database, Tag List
Database Description
Data entry field
Each database can be assigned a plain-English description, in addition to the DOS filename. This field allows twenty characters for this purpose.
Database Name
Data entry field
This is the DOS filename for the database being defined. It must be no more than eight characters in length, and will automatically be assigned an extension of ".DBF".
See also: Database Description
Database Schema
Check Box
Each database is defined by four basic criteria:
Its DOS filename
Its fields and their characteristics
Relationships to other databases in the system
A full-text description
This checkbox addresses that last element. When selected, ProBuilder provides an opportunity to describe this database's role in your system with free-form text of a length limited only by your system's and FoxPro's restraints. This information is a very valuable contribution to the documentation of a system, and is optionally presented on the system reports.
There are also checkboxes through which a schema may be entered for each field and index tag.
See also: Relationship Setting Options, Report Options, Field Schema, Tag Schema
Default Value
Check Box
All fields except for memos may have default values assigned to them. If a field has been assigned a default value, this box will be checked. Select this box to assign, or change, the current field's default value.
Common default values might be: area codes; cities, states, and other geographic information; salutations (Mr., Ms., etc.); and application specific values, such as customer types.
See also: Field Type
Define Options
Push Button
There are three primary methods available for defining a database to ProBuilder: Creating a new definition, Modifying an existing definition, or Cloning an existing definition.
< New... > and < Modify... >
The only difference between the two options is that New creates an entirely new database definition, while Modify allows you to view and update an existing definition. Modify is only available if a database has already been defined.
Selecting either the < New... > or the < Modify... > push buttons will bring forward the structure building dialog, where a database name, its field names and characteristics, their tag names and characteristics, and any program associations can be created and modified.
Clone (menu bar)
The Clone option is only available if one or more databases have been defined. The definition currently highlighted will be cloned, creating a new item with identical characteristics to the original. The only difference will be in the DOS filename, which will be the same except for the last letter, which will be "X".
Import (menu bar)
The Import option is available at any time. This will ask you to identify existing databases whose definitions you wish to be included in the current dictionary.
See also: ProBuilder Menu, Importing Definitions
Deleting a Definition
Push Button
There are two methods available to delete a definition from the ProBuilder dictionary.
Select the < Delete > push button
After deleting the selected definition, you will be provided with the opportunity to rebuild the relation-setting black box.
Remove field definitions
While Modifying a definition, remove all field definitions, and save your work.
Both of these methods will delete a definition from the dictionary. Neither will delete any databases on disk; they only remove the definition from the dictionary.
See also: Black Box, Define Options
Exiting ProBuilder
Push Button
Selecting the
push button exits ProBuilder, resets your environment, and returns you to the FoxPro command window.
Field Decimals
Data entry field
If the field type is Numeric, decimals may be included in the field definition. The number of decimals must be no more than the field width, minus one for the period.
See also: Field Length
Field Description
Data entry field
In addition to the formal FoxPro-abiding name, each field can have its own plain-English description. ProBuilder provides 20 spaces for this.
See also: Field Name
Field List
List
This is a list of the fields defined for the current database definition.
As you scroll through the list, the values for field name, length, type, and other characteristics will be adjusted to reflect information about the field being highlighted. If the field being highlighted is tagged for an index entry, the Tag List and details will reflect the characteristics of the field's index tag.
Since this list is based upon a popup, entries can be raised and lowered in the field hierarchy. Use the standard FoxPro mover popup keys to rearrange entries in the list.
See also: Field Name, Field Type, Field Width, Field Decimals, Tag Field, Default Value, Tag List, Inserting and Deleting Fields
WINDMODIFY FILE_BLD.PRG F 585
Field Name
Data entry field
Each field must be assigned a valid name. To be valid, a field must meet certain basic FoxPro criteria:
No more than 10 characters
Can include only the A-Z, 0-9, and "_" characters
Must not already be assigned to another field in the current definition
ProBuilder checks for these criteria, and only allows you to exit the field if all three are met. Otherwise, you will be notified of the violation, and returned for further editing.
See also: Field Type, Field Width, Field Decimals, Field Description, Inserting and Deleting Fields
Field Object Checkbox
Check Box
Selecting this checkbox will call forward the Field Object Editor, which is used to create, edit, and/or delete Field Objects. The manner in which the Field Object Editor is invoked depends on the status of the current field.
Not Currently a Field Object
If the field selected in the field list is *not* currently defined as a Field Object, you will have the chance to tell ProBuilder whether you wish to:
insert a new Field Object into the Objects database based on the values of the current field. This will insert the current field's characteristics into a new Field Object definition. You simply assign a name to the new Field Object.
enter the Field Object Editor to select another Field Object.
simply return to editing the current field.
Already a Field Object
This will simply call forward the Field Object Editor for the currently selected Field Object.
Whichever means is employed to enter the Field Object Editor, remember that exiting always works the same way:
Selecting
If called from the Structure Editor, this will result in the current field in the Structure Editor being replaced by the currently highlighted Field Object in the Field Object Editor. Be sure that you are highlighting the Field Object whose characteristics you want before selecting the
push button.
That Field Object will be inserted automatically, and access to editing that field's name, type, dimension, description, and schema will require editing the object itself.
Pressing ESCape (or Cancel)
If you hit ESCape or select the < Cancel > push button, it makes no difference what Field Object you're highlighting. Just be sure you haven't made any changes you want to save.
See also: Field Objects, Field Object Editing, Field List, Yes/No/Cancel Alerts
Field Object List
Push Button
This is a list of the FIeld Objects defined for the current dictionary.
As you scroll through the list, the values for object name, field name, length, type, and other characteristics will be adjusted to reflect information about the Field Object being highlighted. The Schema... and Tagged checkboxes will reflect whether the current Field Object has a schema and/or will be tagged upon insertion into a definition, respectively.
See also: Field Object Name, Field Name, Field Type, Field Width, Field Decimals, Field Object Tag
Field Object Name
Data entry field
Each Field Object is identified by a plain-English name, such as "Unique ID Numbers" or "Organization Names". Enter such a name in this field. If the field is left empty, the Field Object will optionally be deleted.
See also: Field Name
Field Object Options
Push Button
In addition to the other components of the Field Object Editor dialog, there are four push buttons that stand alone. Their functions are as follows:
OK
Selecting this button will return you to the main ProBuilder window, saving any changes that have been made during the current editing session.
< New >
This creates a new Field Object, leaving the name empty, and placing you on the Field Object name field.
< Delete >
This deletes the currently highlighted Field Object. When a Field Object is deleted, the current dictionary definitions are scanned, and any references to Field Objects that no longer exist are removed, leaving the field in the definition. In other words, deleting an object merely moves central editing control for a given Field Object from the Field Object Editor to the Structure Editor.
< Cancel >
This will return you to the main ProBuilder window. If any changes have been made during the current session, you will be warned that this option will abandon those changes, and that you may still save your work before exiting. If you chose not to save your work by answering "Yes", then any changes made during the current editing session will be lost.
See also: Field Objects, Field Object Name
Field Object Schema
Check Box
Each Field Object is described by its basic characteristics (name, type, and dimensions) and by two other criteria: whether or not it's tagged for an index entry, and a full-text description.
To enter a complete, plain-English description of a Field Object's function for the current dictionary, use this checkbox to enter ProBuilder's Schema Editor.
Full schemas can also be entered through the Structure Editor for fields, index tags, and whole databases.
See also: Field Schema, Tag Schema, Database Schema
Field Object Tag
Check Box
This checkbox is used to indicate the action taken upon inserting the current Field Object into a definition. If the field is to be tagged, this box should be checked.
Removing the check has no effect on previous insertions of the current Field Object; it only determines what happens on future insertions.
Field Objects
Real-world entity
When building a database system, we as FoxPro developers have the burden of enforcing data integrity constraints on the relations and elements of our system. ProBuilder provides a method for assisting in this enforcement through the introduction of Field Objects.
A Field Object is a field definition (the field name, type, dimensions, schema, and an indication of whether or not it is to be tagged) that is referred to by a plain-English name, such as "System ID Numbers". When you change the Field Object, all instances of that field in the current dictionary will be updated with the values of that Field Object. In this way, you can be assured that, for instance, the length of the City field in your Vendor and Customer databases will always be consistent simply by inserting the appropriate Field Object into the respective databases.
The Field Object Editor is accessible both through the main window (by selecting the < Objects... > push button) and the Structure Editor (by inserting a Field Object, or editing an existing one).
See also: Field Object Options, Inserting and Deleting Fields
Field Schema
Check Box
Each field is described by its basic characteristics (name, type, and dimensions) and, in ProBuilder, by three other criteria: default values, whether or not it's tagged for an index entry, and a full-text description.
To enter a complete, plain-English description of a field's function within a particular database, use this checkbox to enter ProBuilder's Schema Editor.
Full schemas can also be entered for index tags, and the database as a whole.
See also: Tag Schema, Database Schema
Field Type
Data entry field
ProBuilder supports the five basic field types that FoxPro 2.0 for DOS supports:
Character
Numeric
Date
Logical
Memo
Entering the first character of the field type you wish to assign to the current field is sufficient to identify that type. If you attempt to leave the field empty, a popup containing the acceptable types will be presented.
Since changing a field type in a database definition will make it impossible to append field data in records of an existing database with the same field name, but a different type, you must confirm that you intended to change the type when modifying an existing type.
The field type you select will determine what other fields require (or allow) input, whether you can assign a default value to that field, and whether or not that field can be tagged for
an index.
See also: Field Name, Field Width, Field Decimals
Field Width
Data entry field
This is where the maximum width of the current field is defined. Different fields have different restrictions placed on them by FoxPro. The basics are:
Character
The maximum width is 254 characters.
Numeric
The maximum width is 20 places. If decimals are being defined for the field, the width must at least be wide enough to account for the decimals places, plus one for the period.
Date
FoxPro assigns a mandatory width of 8 spaces.
Logical
FoxPro assigns a mandatory width of 1 space.
Memo
FoxPro assigns a mandatory width of 10 spaces in the database definition; the actual text is stored in the .FPT file, and the restrictions for that can be found in the FoxPro Developer's Guide.
See also: Field Type, Field Decimals
File List
List
This is the list of database that have been defined to the Probuilder dictionary. The DOS filename appears first, followed by any description that has been assigned for the database.
Databases are defined using Modify, and New push buttons, and the Clone menu option; built using the Build button; and deleted using the Delete button. Databases that exist on disk but have not yet been defined to ProBuilder can be imported using the Import option on the main Dictionary menu.
See also: Define Options, Deleting a Definition, Importing a Definition
File Picker
Dialog
This dialog allows you to select one, many, or all the files that might be appropriate to the current task. This dialog is called, for example, by both the Build and Import options, to determine what files are to be built or imported.
The dialog's options are as follows:
Source list box (left box)
This is the listing of available items that have not yet been selected. Items may be selected by highlighting the preferred item, and pressing enter, double-clicking with the mouse, or selecting one of the <Select> push buttons.
<Select one
This button allows you to select one item from the source list box. This button is only available if there is at least one item remaining in the list box.
<Select all
This button allows you to select all the remaining items in the source list box. This is only available if there are at least two items remaining in the list box.
Target list box (right box)
This is the listing of items that have been selected for processing, whatever that process might be. Items may be de-selected by highlighting the item to remove and pressing enter, double-clicking with the mouse, or selecting one of the <Remove> push buttons.
Remove one>
This works the same as the <Select one
> button, but in the opposite direction.
Remove all>
This works the same as the <Select all
> button, but in the opposite direction.
You select this push button any time there is at least one option in the target list box. This tells whatever process is running that is should continue with the items selected.
< Cancel >
This aborts the process that called the File Picker.
For Expression
Check Box
If a FOR expression has been defined for the current tag, this box will be checked. This push button calls forward FoxPro's Expression Builder. You can use the Expression Builder to create an index tag FOR expression for the current tag, and verify it to make sure it is valid.
A temporary cursor is created and made the default database so that the current field list will be available to the Expression Builder. To avoid any possible conflict between the temporary cursor and an existing database of the same name, the cursor is name "X_" plus the current database definition name. If you use FoxPro's resource file capabilities, you can use the Edit Preferences option in the Expression Builder to suppress entry of the alias when you select a field name from the Expression Builder's field list.
If the tag FOR expression is left empty, this box will be unchecked.
See also: Tag Expression, Tag Expression Builder
Importing Definitions
Menu Bar
The Import... menu bar on the Data Dictionary menu pad allows you to import the definitions of databases on disk into the current structure file.
When you select this option, you will use the File Open dialog to locate the name of a database whose definition you want to import to the dictionary. If there are more databases in the same directory as the database you chose, the File Picker will be called to allow you to select for import as many files in that directory as you'd like.
See also: File Picker, Define Options
Inserting and Deleting Fields
Push Button
Fields can be inserted and deleted by selecting the appropriate button.
< Insert field >
This inserts a new, empty, character type field definition with a width of 10. The default name is "NEWFIELDn", where n represents the current number of "NEWFIELD"s. The field description field also will be seeded with this name. Selecting this button three times in a row, for example, would add three fields: NEWFIELD1, NEWFIELD2, and NEWFIELD3.
The field name field becomes the _CUROBJ, where you can proceed to edit the field name and other field characteristics.
< Delete field >
This will remove the current field definition, and any associated tag.
See the Field Object Checkbox help topic for information about inserting and deleting Field Objects.
See also: Field Name, Field Type, Field Width, Tag Field, Field Object Checkbox, Field Objects, Field Object Options
Okay Dialog
Dialog
This window is simply a notice of some important event or fact that ProBuilder felt important enough to force a keystroke from you before proceeding.
See also: Yes/No Alert, Yes/No/Cancel Alert
PathFinder
Dialog
The PathFinder dialog is an enhanced version of the path-selection dialog that FoxPro provides in the Filer. PathFinder returns the fully qualified drive and path to any selected directory.
There are a few differences of note between PathFinder and FoxPro's dialog:
Unlike FoxPro's dialog, these directories are not enclosed in square brackets. This allows you to navigate the list by pressing the first letter of the directory you want.
The "one directory up" DOS marker ("..") appears in a network directory list in PathFinder; it does not do so in FoxPro's dialog.
You can pass a parameter to PathFinder that allows it to set the selected drive and directory as the default, and then sets the path to all directories one level underneath the selected directory.
sThe main ProBuilder window has a menu pad that accompanies it. It is main ProBuilder menu, and contains the following options:
About...
This brings forward the ProBuilder version of the FoxPro About... box. It provides information concerning the authorship, version, and build of ProBuilder (as well as of FoxPro), and other important system information.
Help
This help facility. Refer to the FoxPro documentation for assistance in using the FoxPro help facility.
New...
Calls forward the Structure Editor, for adding a new definition.
Modify...
Calls forward the Structure Editor, for editing the definition of the currently highlighted database.
Select...
Allows you to choose a different structure file to work with.
Objects...
This calls forward the Field Object Editor, for creating, editing, and deleting Field Objects.
Relations...
Calls forward the Relation Setting dialog, which allows you to define any relationships for which the currently highlighted database is the parent.
Blackbox...
Builds the black box program that will be included in your distributed application, for the handling of the setting of relations.
Build...
Calls forward the File Picker, which then turns all selected definitions into databases on disk, appending records from any previously existing database of the same name.
Delete
Deletes the currently highlighted definition.
Clone
Creates a clone of the currently highlighted database definition.
Import...
Allows you to indicate which existing databases on disk should have their definitions entered into the current structure file.
Pack
This will remove any deleted records from the dictionary, schema, and object files, and pack the memo fields for the dictionary and schema files. This is an important step to take prior to distribution of the dictionary with your application, in that it might reduce the size of the STRUCTUR.DBF and related files.
Reports...
This calls forward the Report Options dialog, which offers choices regarding which report to run, with what criteria, and to what destination.
See also: Define Options, Selecting a Structure File, Field Objects, Relationship Options, Building Defined Databases, Deleting a Definition, Importing Definitions, Report Options
Program Assignment Dialog
Dialog
This window allows you to assign the current database definition to a program or program group. For more details, refer to the Program Assignment Option help topic.
See also: Program Assignment Option
Program Assignment Option
Check Box
When checked, this indicates that the definition is tied to a program or program group. Selecting this check box calls forward the Program Assignment dialog.
Each database can be assigned to a program, or program group, that can be used to govern when the database should be opened and closed. A common method is through the use of an OPEN_ALL and SHUTDOWN pair of programs. OPEN_ALL might be called at the outset of each module in an application. It would scan the structure file to find all databases that need to be open for the duration of the current module. Similarly, a SHUTDOWN program can scan the structure file when leaving a module, to see which files should be closed.
See also: Program Assignment Dialog
Relation Expression Builder
Push Button
This calls forward FoxPro's Expression Builder, which can be used to define the relationship key expression. Refer to the Tag Expression Builder for more information about ProBuilder's use of the Expression Builder.
See also: Relationship Expression, Tag Expression Builder
Relationship Expression
Data entry field
This is the "TO" portion of the relational expression. Any valid expression can be used. Refer to the FoxPro documentation for help with valid relational expressions.
ProBuilder makes no effort to enforce the validity of the relational expression. If the target (or child) database is indicated as being in record number order, you will be reminded that your expression must then be numeric in value.
Leaving the expression empty will result in the removal of the relationship.
See also: Relation Expression Builder
Relationship List
List
This is a listing of all relationships where the currently selected database is the parent. As you scroll through the list of relationships, the components of those relationships will be refreshed to show that relationship's current status.
See also: Relationship Name, Relationship Expression, Relationship Expression Builder, Child Database, Child Database Order
Relationship Name
Data entry field
This is the name that you will assign to the current relationship. It is best to assign a plain-English name, such as "Invoices to Customers" or "Line Items to Invoices".
Your applications will be able to set relationships using the black box that ProBuilder creates from these definitions. The name assigned here can be referenced in the black box simply. For example, your code can say:
DO blackbox.prg WITH "Invoices to Customers"
See also: Black Box
Relationship Options
Push Button
ProBuilder can be used to maintain information concerning the relationships between defined databases. These two menu options permit the relationships to be defined, and generate a .PRG file that actually sets the relationships for you.
< Relations... >
This calls forward the relation-setting dialog, where all relationships are defined for which the currently highlighted definition in the file list is the parent in a relationship.
< Blackbox... >
This generates a .PRG of your choosing (defaulting to BLACKBOX.PRG) that contains all system relations in a single DO CASE...ENDCASE construct. This .PRG can then be included in any application to automatically open files and set relationships.
See also: Relation Setting Options, Black Box
Relationship Setting Options
Push Button
In addition to the other components of the Relationship Setting dialog, there are four push buttons that stand alone. Their functions are as follows:
OK
This is only enabled if there are relations presently defined. Selecting this button will return you to the main ProBuilder window, saving any changes that have been made during the current editing session.
< New >
This creates a new relationship, leaving the name empty, and placing you on the relationship name field.
< Delete >
This deletes the currently highlighted relationship.
< Cancel >
This will return you to the main ProBuilder window. If any changes have been made during the current session, you will be warned that this option will abandon those changes, and that you may still save your work before exiting. If you chose not to save your work by answering "Yes", then any changes made during the current editing session will be lost.
See also: Relationship Name, Black Box
Report Options
Dialog
This dialog sets the options and parameters for ProBuilder reporting, and starts the actual printing. The available options are as follows:
) All ( ) Some...
ProBuilder reports can (like the Build function) apply to one, many, or all of the definitions in the current dictionary. To select other than every definition for a report (which is the default), access the File Picker by choosing the Some... radio button.
[X] Database
[X] Field
[X] Index tag
The schemas for various database elements can be printed selectively. Check the appropriate box for the type(s) of schemas to print; the default prints all types.
Printer
All reports can be printed to either the Printer, Screen, or file on disk. Use this popup to select a printing destination.
LPT1:
If the report destination is the Printer, you can select which printer port to use. The default is the current setting of SET("PRINTER", 1).
What file? < File... >
If the report destination is a file on disk, you can enter the file path and name by typing it in, or select the File... push button to use the PUTFILE() dialog.
See also: File Picker
Selecting a Structure File
Push Button
Before you can begin defining data structures to ProBuilder, you must have selected (or created) a Structur.dbf dictionary file to hold the definitions. There are two ways of doing this.
Pass a file name to ProBuilder
ProBuilder can be started with a simple "DO builder.app", but, like all FoxPro applications, you can pass it a parameter. The only parameter that ProBuilder will accept is a character string pointing to a file called Structur.dbf. For example, You can call the program with:
"DO builder.app WITH '[<path>\]structur.dbf'".
If it finds the file in the path you provide, it will load that file. If not, it will search your path for a Structur.dbf file (refer to the FoxPro help topic for the LOCFILE() function for more information concerning how FoxPro searches paths). If it does not find a dictionary file, it will present you with an opportunity to locate via the GETFILE() dialog, or to create a new one in the directory of your choosing.
< Select... >
Pushing the Select button calls forward the GETFILE() dialog, providing you with the opportunity to locate another dictionary (Structur.dbf) file, or to create a new one in the directory of your choosing.
If no dictionary file was chosen or created, you will be returned to the current dictionary file (if any).
Structure Editor Options
Push Button
In addition to the other components of the Structure Editor, there are three push buttons that stand alone. There functions are as follows:
OK
This is only enabled if there are fields presently defined. Selecting this button will return you to the main ProBuilder window, saving any changes that have been made during the current editing session.
< Change log... >
This button is also only available if fields have been defined. This calls forward the Change Log dialog, which keeps track of the last time changes were made to any field or tag.
< Cancel >
This will return you to the main ProBuilder window. If any changes have been made during the current session, you will be warned that this option will abandon those changes, and that you may still save your work before exiting. If you chose not to save your work by answering "Yes", then any changes made during the current editing session will be lost.
See also: Structure Editor Menu, Change Log
Tag Description
Data entry field
In addition to the formal FoxPro-abiding name, each tag can have its own plain-English description. ProBuilder provides 20 spaces for this.
See also: Tag Name
Tag Expression
Data entry field
Use this field to edit the current tag's index expression. You are limited to 100 characters in length. Any changes you make to the tag expression using the Tag Expression Builder option will be immediately reflected here.
If the tag expression is left empty, you will be asked whether or not to delete the tag, since empty index expressions will generate errors at build time.
See also: Tag Expression Builder, Adding and Removing Tags
Tag Expression Builder
Push Button
This push button calls forward FoxPro's Expression Builder. You can use the Expression Builder to create an index tag expression for the current tag, and verify it to make sure it is valid.
A temporary cursor is created and made the default database so that the current field list will be available to the Expression Builder. To avoid any possible conflict between the temporary cursor and an existing database of the same name, the cursor is name "X_" plus the current database definition name. If you use FoxPro's resource file capabilities, you can use the Edit Preferences option in the Expression Builder to suppress entry of the alias when you select a field name from the Expression Builder's field list.
If the tag expression is left empty, you will be asked whether or not to delete the tag, since empty index expressions will generate errors at build time.
See also: Tag Expression, Adding and Removing Tags
Tag Field
Check Box
Any character- or numeric-type field can be tagged for an index. To help facilitate this process, ProBuilder allows a simple check box to handle the creation (or deletion) of an index tag.
When a field is not yet tagged, clicking on the Tag Field checkbox will perform the following acts:
Create a tag name the same as the field's
Create a tag description the same as the field's. If the field description is empty, the tag description will be a PROPER() version of the field name.
Create a tag expression based on the field type being tagged.
Character fields expressions are:
UPPER([field name])
Date field expression are:
DTOS([field name])
Numeric and logical field expressions are simply:
[field name]
Make the new tag the current item selected in the Tag List.
If the field was already tagged when the check box was selected, you are asked if you want to remove the tag.
See also: Field Name, Field Type, Tag List, Tag Name, Tag Description, Tag Expression, Adding and Removing Tags
Tag List
List
This is a list of the tags defined for the current database definition.
As you scroll through the list, the values for tag name, description, and index expression will be adjusted to reflect information about the tag being highlighted.
See also: Tag Name, Tag Description, Tag Expression, Tag Expression Builder, For Expression, Unique Tag, Ascending vs. Descending Tag, Adding and Removing Tags
Tag Name
Data entry field
Each tag must be assigned a valid name. To be valid, a tag name must meet certain basic FoxPro criteria:
No more than 10 characters
Can include only the A-Z, 0-9, and "_" characters
Must not already be assigned to another tag
ProBuilder checks for these criteria, and only allows you to exit the field if all three are met. Otherwise, you will be notified of the violation, and returned for further editing.
See also: Tag Description
Tag Schema
Check Box
Each index tag is described by its basic characteristics (name, expression, FOR/UNIQUE/ASCENDING-DESCENDING clauses) and, in ProBuilder, by two other criteria: whether or not it's associated with a particular field, and a full-text description.
To enter a complete, plain-English description of a tag's intent and function within a particular database, use this checkbox to enter ProBuilder's Schema Editor.
Full schemas can also be entered for fields, and the database as a whole.
See also: Field Schema, Database Schema
Unique Tag
Check Box
If you want the current tag to be generated UNIQUE, check this box.
Yes/No Alert
Alert
This window appears whenever ProBuilder requires an immediate response. There are three sections to this window.
Description
The top portion will display the problem or concern identied, presented in a simple plain-English style.
Question
A straightforward yes-or-no question concerning the situation described is presented.
Response
You have two options:
Yes
This is an affirmative response to the question posed. Processing will continue along the lines presented in the description.
< No >
This reply has the same effect as pressing ESCape. You are answering "no" to the question being put to you.
See also: Yes/No/Cancel Alert, Okay Dialog
Yes/No/Cancel Alert
Alert
This window appears whenever ProBuilder requires an immediate response. There are three sections to this window.
Description
The top portion will display the problem or concern identied, presented in a simple plain-English style.
Question
A straightforward yes-or-no question concerning the situation described is presented.
Response
You have three options:
Yes
This is an affirmative response to the question posed. Processing will continue along the lines presented in the description.
< No >
You are answering "no" to the question being put to you.
< Cancel >
This response allows you to return to whatever process you were attempting to perform before you called forth this alert. For example, if you were editing in the Structure Editor and pressed ESCape or clicked on the Cancel push button after making changes, you would be presented with this dialog. Selecting < Cancel > would return you to the Structure Editor without either saving or losing your changes.
See also: Yes/No Alert, Okay Dialog
ProBuilder Methodology
General
A number of basic assumptions were made during the design of ProBuilder. These assumptions were the result of numerous conversations with FoxPro developers in general and ProBuilder beta testers in particular.
Assumption #1: Performance is king.
However good and detailed a data dictionary add-on might be, if it appreciably degrades performance in the field, it's not worth the trouble.
Assumption #2: Simplify, simplify, simplify.
Many DOS FoxPro developers look with some longing at the mainframe and Unix DBMSs that offer full data dictionary implementations, flush with repository management, data integrity enforcement, and other goodies. Many in the DOS world are leery of the amount of work involved in maintaining and managing such complex systems for the purposes (primarily) of documentation, and many other purposes are too performance intensive to be workable on the installed base of 80286 computers.
A strong consensus developed around the idea of a greatly enhanced version of FoxPro's own STRUCTURE EXTENDED databases: a single database that contains the entire definition for each database. What is lost in fine relationality is gained in performance and ease-of-distribution.
The most clear-cut outcome of this assumption is the implementation of the Objects database. While it is somewhat relational at heart (in that Field Objects are referred to by ID number), it operates on the assumption that it's easier and preferable to distribute a single STRUCTUR.DBF file than it is to distribute three databases (STRUCTURE, OBJECTS, and SCHEMAS). With this in mind, we chose to duplicate each object's information directly into the definition in which it resides, which eliminates the need for a "generate a distribution file" process.
Future version of ProBuilder will likely rely more heavily on a relational foundation during interactive use, and generate a single file for distribution. We at TWS will continue to rely heavily on input from you, the FoxPro/ProBuilder community, to tell us which directions to pursue.
Assumption #3: Open it up.
It was clear that all of us as developers wanted to be able to tweak the dictionary to our own style of development, to "kit-bash", as Chuck Werner put it in FoxTalk. Clean, well-documented source code was an important component of a successful program.
NameListObject CheckboxNameListscriptionField DecimalsExiting ProBuilderleting a Definitionine Optionsefault ValueSchemaNameDatabase Description Orderild DatabaseChange Loguilding defined databasesBlack Boxscending vs. Descending TagsAdding and Removing TagsWhat is ProBuilder?hird Wave SoftwareTechnical SupportProBuilder MethodologyHow do I...?Getting Startedcknowledgements
About ProBuilder
/Cancel AlertYes/No Alert
m.win_titlef
Please make your selection(s)
TALKz
COMPATIBLEz
picklist
m.source_sayf
Available
m.target_sayf
Selected
m.max_allowf
m.max_allowf
picklist
@ 1,1 GET m.src_value PICTURE "@&N" FROM src_array RANGE , m.src_arrctr SIZE 11,28 DEFAULT 1 VALID _qbe1314ke() COLOR SCHEME 6
@*VN \<Select one
;Select \<all
@ 1,47 GET m.tgt_value PICTURE "@&N" FROM tgt_array RANGE , m.tgt_arrctr SIZE 11,28 DEFAULT 1 VALID _qbe1314rs() COLOR SCHEME 6
Just a reminder! If you're finding that ProBuilder
increases your productivity
is changing the way you design
actually makes maintaining your data structures fun
easily integrates into your existing applications
then you owe it to yourself to register! Having the source code to utilities like the File Picker and PathFinder can save hours of programming, and those are just two of the serious, efficient dialogs you'd have access to. When you combine all that code with the increased efficiency of letting ProBuilder manager your structures, how can you afford *not* to register?
To register your copy of ProBuilder, simply run the REGISTER.APP program accompanying PROBUILD.APP, and send the printout or file to us here at Third Wave Software along with a check or money order for $79.95.
(.txt)