 | DDF Builder User's Guide (v10) |  |
|
DDF Builder provides a graphical user interface (GUI). The GUI includes various editors, views, and wizards with which you display and work with objects.
The object being edited is represented by a tab on top of the editor. The tab contains the name of the object. Data modified within an editor must be explicitly saved.
Views can be opened only one at a time. Actions performed within a view are applied immediately. No explicit save is required.
Wizards contain one or more dialogs and guide you through a task to obtain a specific result.
The following table lists the editors, views, and wizards that DDF Builder provides.
Each time you start DDF Builder, the Welcome page displays. From this page you can quickly access a variety of information and perform common tasks.
Common tasks you can perform from this page are adding a new server and creating a new database.
A variety of information is also available from this page. The page contains several links which provide quick access to various pieces of information. The information provided in the Welcome page includes the following:
If you have closed the Welcome page in DDF Builder, you can view it again at any time. From the DDF Builder menu bar, click Help 4 Welcome to display the Welcome page.
DDF Builder uses a file explorer-like motif-a tree of objects-referred to as the Data Sources Explorer. Examples of objects include databases, data paths, Btrieve files, and SQL tables. The tree objects are referred to as nodes.
Nodes can be expanded or collapsed to reveal or conceal subordinate nodes. The expand/collapse icon appears to the left of the node if a subordinate node is available.
Btrieve File Editor creates the file and key specification for a new Btrieve file. DDFs are not automatically created for a new Btrieve file. You must add them separately, if you want them (see SQL Tables ).
Tip
To create a Btrieve file and its DDFs, use the SQL Editor in the Pervasive PSQL Control Center.
In Data Sources Explorer, right-click on a data path under the Data Paths node, then click Create Btrieve File.
A Btrieve file must be located on physical storage, which is why the editor is invoked from a data path.
Btrieve File Editor contains two tabs: one for specifying the characteristics of the file and one for specifying characteristics of the keys. The Apply button on each tab saves the specifications for that tab. Click File 4 Save to save the editing changes for both tabs.
At a minimum, you must supply a file name and a record length to create a Btrieve file. You specify these on the File Specifications tab.
As stated in What You Need to Know , this book assumes that you thoroughly understand the transactional access method and relational concepts. This section does not attempt to explain the controls on the Btrieve File Editor tabs. The following table provides links to related documentation if you need to further your understanding of Btrieve files.
Only one Btrieve file can be created at a time. On the Key Specifications tab, click Apply after adding or changing each segment of a segmented key. This saves the changes to each segment before you create or edit the next segment.
The Table Definition Editor creates new or changes existing schemas for SQL metadata. Note that Table Definition Editor is conceptually similar to the Table Editor in Pervasive PSQL Control Center (PCC). See "Table Editor" chapter in Pervasive PSQL User's Guide.
Perform one of the following actions in Data Sources Explorer:
The Table Definition Editor, like the Table Editor in Pervasive PSQL Control Center (PCC), uses tabs or pages to display different views of table definition information. Some of the pages contain read-only information, while others provide the work area in which you will create and modify your table definitions.
You cannot change the size, offset, or data type for a column if the column is used in a key in the Btrieve file. DDF Builder does not change nor permit changing the layout structure of an existing Btrieve file.
The Table Page in the Table Definition Editor provides two primary views of the metadata-raw data view and grid data view. These two views, respectively, display the table definition information as it is in the Btrieve file and the SQL table.
Select the Table page by clicking the Table tab at the bottom of the Table Definition Editor.
The raw data view simultaneously shows the Hex and ASCII values of data records. This view also displays the record length as well as offset and size for selected bytes. Offset and size are adjusted accordingly as bytes are selected from within this view.
Field, column, null and unknown indicators display at the top of the raw data view. Field indicators show where each field within the record begins. Null indicators show where the null indicator byte is located. Unknown fields and bytes are also illustrated in the raw data view.
The following lists the attributes displayed in the raw data view:
The grid data view shows the schema structure of the fields in a table-like grid. Each field is represented in a row on the grid. Each row contains cells that show the attributes for each field.
The following lists the attributes displayed in the grid data view:
Selecting a cell in the grid data view displays the corresponding bytes for that field in the raw data view, just as selecting individual bytes in the raw data view, selects the corresponding element(s) in the grid data view.
If you try to select past the field definition, an error message displays, and both rows in the grid data view are selected. Both error and warning messages display in this are of the raw data view.
The Indexes tab is read-only, with the exception of changing the SQL Index name. You cannot change the structure of any of the indexes on this tab. Index additions or changes to an SQL table must be made with Pervasive PSQL Control Center. See "Table Editor" chapter in Pervasive PSQL User's Guide.
Select the Indexes page by clicking the Indexes tab at the bottom of the Table Definition Editor.
Name changes made on the Tables page to columns specified as indexes are updated and shown immediately on the Indexes page.
Only the SQL Index name may be edited from the Indexes page.
When working with Btrieve files that use alternate collating sequence (ACS) files, the ACS file must reside in the same directory as the Btrieve file and must have an .ALT extension (for example, UPPER.ALT).
The Preview page shows the data from the file in a readable layout.
Select the Preview page by clicking the Preview tab at the bottom of the Table Definition Editor.
You navigate among data records with the buttons at the bottom center of the page. The file position displays to the right of these buttons. The file position shows how many records are being displayed out of the total number of records. For example, "100-199/1314" indicates that the page displays records 100 through 199 out of a total of 1,314 records.
Changes made on the Tables page to any of the column definitions are reflected immediately on the Preview page.
Information on this page is read-only and cannot be modified.
The Statistics page displays the file and key specifications for a Btrieve file. The information is read-only; you cannot change it in the view.
Select the Statistics page by clicking the Statistics tab at the bottom of the Table Definition Editor.
Statistics provides a convenient way to look at the structural characteristics of a Btrieve file. This is particularly useful if you are considering exporting the file schema but are unfamiliar with the file and key specifications.
See also Export Btrieve Schema .
Note
The statistics information is based solely on information in the physical Btrieve file; it does not show any metadata information.
The SQL View page displays the contents of the Structured Query Language (SQL) statement necessary to create the current table definition.
Select the SQL View page by clicking the SQL View tab at the bottom of the Table Definition Editor.
Most SQL statements created here can be copied and reused in the Pervasive PSQL Control Center for creating new schemas based on the ones you created with DDF Builder. SQL statements that you use in the Pervasive PSQL Control Center can also be saved for future use.
Although the SQL statements created here can be copied and reused, they are not saved, nor is a means for automatically saving them currently offered in DDF Builder. To save the statement, you must copy from this window and save the statement in a text editor.
Caution
Do not reuse any statement that contains a reference to any of the Pervasive dictionary system objects. These objects are easily identified by their X$<tablename> and include a proprietary comment prohibiting reuse.
The Add Database Wizard creates a new database. This wizard is shared with Pervasive PSQL Control Center (PCC). See Databases and New Database GUI Reference in Pervasive PSQL User's Guide.
DDF Builder provides an action with which you check the consistency of a table. A consistency check uses a set of validation rules to compare the physical data file against its metadata (the table against the data dictionary files).
Consistency check validates conditions such as the following:
You can check the consistency of all tables at once or of tables selected individually. The check reports a count of the validation messages, errors, and warnings by object. An object is the database, a table, or a data dictionary file (DDF).
The validation messages are grouped under the heading "PASSED" because they list the checks that passed consistency. Errors are grouped under "ERROR" and warnings under "WARNING."
Error messages, if any, are always displayed. If an object has both errors and warnings, the warnings are also listed under the "ERROR" grouping.
Optionally, you can display or hide the validation messages and the warnings.
Icons on the results view identify the different types of messages:
An error indicates a problem in the table definition that will, in most cases, cause a failure or incorrect data to be returned when the data file is accessed. For example, an index defined in the DDFs but not in the data file results in an error. An SQL query that causes the engine to optimize on that particular index generates a failure because no such index actually exists in the data file.
Warnings are indicative of possible problems, but the problem may not cause any failures. For example, an index defined in a data file without a corresponding DDF entry results in a warning. SQL access does not know about the index and will not try to use it. The result may be a slow query, but the query eventually returns the correct results.
In Data Sources Explorer, right-click the name of a database then click Check Database, or right-click an SQL table name under either the Data Paths or SQL Tables node, then click Check Tables. (You can select multiple tables by holding down the Shift or Control key then clicking the desired table names.)
The DBCheck pane can be undocked and moved to any other area in DDF Builder. The pane can be minimized and maximized.
In addition, the pane provides icons with which you can save the consistency check results to a text file, and filter (hide) validation check messages and warnings.
A tip displays if you click on an error message. The tip provides comments about the message and may include a suggested corrective action. The tips are also written to the text file if you save the DBCheck results to a file.
The Copy SQL Definition Wizard creates a new SQL table based on the schema of an existing, or source, SQL table. The wizard also creates a Btrieve file with which the new SQL table is associated.
In Data Sources Explorer, right-click an SQL file name, then click Copy SQL Definition.
If the source table contains data, the wizard does not include the data in the new table. You can, if you want, export the data from the source table and import it into the new table. See Importing Data with Import Data Wizard and Exporting Data with Export Data Wizard in Pervasive PSQL User's Guide.
The wizard requires that you specify the following:
The Export Btrieve Schema Wizard creates an XML file that specifies the schema of a source Btrieve file. You can use the XML file to create a new Btrieve file based on the structure of an existing Btrieve file. See Import Btrieve Schema .
Data from the source file is not exported. If you want to export data, see Exporting Data with Export Data Wizard in Pervasive PSQL User's Guide.
In Data Sources Explorer, right-click a Btrieve file name under the Data Paths node, then click Export Btrieve Schema.
By default, the wizard uses the source file name for the exported XML file name. The wizard adds a file extension of "xml" and locates the output file in the same directory as the source file. You can change the name and location of the XML output file if you choose.
The wizard also provides a preview of the XML content before you export it.
The Import Btrieve Schema Wizard creates a Btrieve file based on the structure of another Btrieve file. The structure must be a schema of the source file in XML format.
Data from the source file is not imported. If you want to import data, see Importing Data with Import Data Wizard in Pervasive PSQL User's Guide.
In Data Sources Explorer, right-click on a data path under the Data Paths node, then click Import Btrieve Schema.
A Btrieve file must be located on physical storage, which is why the wizard is invoked from a data path.
Since the wizard is invoked from the context of a known data path, you do not specify a path for the target file, only a file name. The file name length must be less than or equal to 255 bytes. The file name cannot contain spaces unless the Embedded Spaces client configuration option is enabled. The option is enabled by default. See "Embedded Spaces" section in the "Configuration Reference" chapter in Advanced Operations Guide.
Data paths are added to the Data Sources Explorer by using Add Data Path. A data path represents a location on physical storage where the Btrieve file resides. Each Pervasive PSQL database must have at least one data path identified for it.
Any DDFs that you create for Btrieve files are located in the original data path for the database. This is because all SQL tables for an entire database are defined in the same set of DDFs.
In Data Sources Explorer, right-click the Data Paths node, then click Add Data Path.
The existing directory can be empty or contain files.
Use the Delete command to remove a data path from Data Sources Explorer (right-click Data Paths or a database name, then click Delete). The directory is not deleted from physical storage.
DDF Builder allows you to change the data file associated with a selected table definition (SQL Table).
In Data Sources Explorer, right-click the SQL Table which you want to change the associated data file, then click Change Associated Data File. You may enter or browse to select the full path name for the data file you want associated.
When changing the data file associated with a particular SQL table, you may enter the filename or use the browse button to select a file, based on the location.
DDF Builder provides a separate view for displaying the Btrieve data types and sizes, along with the corresponding SQL data types to which they map.
The Btrieve Types view can be used to analyze your data. Highlight bytes in the raw data view and the Btrieve Types displays how the data would appear for different types compatible with the size. When a particular column is selected in the Table Definition Editor, the Btrieve Types view also displays a preview of the formatted data.
The Btrieve Types tab is located in the left pane of the DDF Builder window, next to the Data Sources Explorer tab. Click the Btrieve Types tab to display the view.
The Btrieve Types pane can be undocked and moved to any other area in DDF Builder. Moving the Btrieve Types pane allows you the flexibility to position the viewer so that you can easily resolve data type and size conflicts.
A preview column is also provided, showing how the selected data would appear as that particular data type. Previewing the data in each column can also be used to determine the size of a data type. Using the Btrieve Types pane to compare and preview the data is extremely useful when trying to resolve incorrect data type and size issues.
Anytime that DDF Builder detects problems and alters your existing table definition, the Definition Errors window automatically displays. You may close this window and revisit the changes later by opening the Definition Errors view.
From the menu bar in DDF Builder, click Window 4 View Definition Errors.
The issues listed in the Definition Errors window contains specific information regarding the problems addressed by DDF Builder. The original table definition is also provided in a read-only mode in the Original Definitions window. This window may be moved so that comparisons to the updated table definition may be viewed.
The following table lists the possible table definition errors that can be detected by DDF Builder in your existing definitions. A general description of what caused the error and how DDF Builder has modified the table definitions as a result are also provided.
Anytime that DDF Builder detects problems and alters your existing table definition, your original table definition is retained until you save your changes. If you are making changes to an existing table definition, the original definition is also retained until your changes are saved. Until you save your changes, your original table definition can be viewed at any time by opening the Original Definition view.
From the menu bar in DDF Builder, click Window 4 View Original Definition.
The original table definition is provided in a read-only mode in this tab. This window may be moved so that comparisons to the updated table definition may be viewed.
You can always retain the original table definition by saving either the modified or the original definition with a different name. To do this, click File 4 Save As and enter a different name.
|
Chapter contents
Prev topic: DDF Builder Concepts
|
) to show where each field within the record begins.
) if the field is designated as nullable. This byte represents the null indicator byte.
) if the field has not yet been defined.
) if the bytes have not yet been defined.
) if the field is used in a key (index) definition.
) if the field is an unknown variable-length portion.