High Voltage Shareware

home *** CD-ROM | disk | FTP | other *** search

/ High Voltage Shareware / high1.zip / high1 / DIR8 / DBSM21.ZIP / DBSM.DOC next >

Wrap

Text File | 1993-01-04 | 167KB | 3,289 lines

DataBase Structure Manager -------------------------- Version 2.1 by Progressive Data Systems P.O. Box 631 Middleton, WI 53562 Phone (608) 836-5075 Copyright 1989 Progressive Data Systems. All rights are reserved. This manual may not be transcribed, reproduced, or translated into any natural language or computer language in whole or in part, by any means or in any form without the prior written permission of a duly authorized representative of Progressive Data Systems in Middleton, Wisconsin. Page i DataBase Structure Manager, Version 2.1 Limited Warranty and Liability ------------------------------ Progressive Data Systems is not responsible for your specific application or any problems resulting from use of this software. Progressive Data Systems has no liability to you or any other person or entity for any lost profit, lost savings, loss of goodwill, or damage including special, consequential, or incidental damages caused either directly or indirectly by the use or inability to use this software, or for any claim by any other party. Some states do not allow the limitation or exclusion of liability for consequential or incidental damages, so the above limitation or exclusion may not apply to you. THE FOREGOING WARRANTY IS IN LIEU OF ALL OTHER WARRANTIES AND CONDITIONS EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THOSE CONCERNING MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE PROGRAM IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND. Progressive Data Systems DOES NOT WARRANT THAT THE SOFTWARE WILL MEET YOUR REQUIREMENTS OR THAT THE OPERATION OF THE SOFTWARE WILL BE UNINTERRUPTED OR ERROR FREE. ALL RISK CONCERNING THE PERFORMANCE AND QUALITY OF THE PROGRAM IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU (AND NOT Progressive Data Systems) ASSUME THE ENTIRE COST OF ALL NECESSARY CORRECTION, REPAIR, OR SERVICING. This agreement is governed by the laws of the State of Wisconsin. If any part of this agreement is invalidated, the remainder of the agreement will remain in effect. You acknowledge that you agree to be bound by the terms and conditions of this agreement. Your use of this software constitutes your acceptance of the limited warranty and license agreement. Trademark Acknowledgements -------------------------- ASP logo is a trademark of the Association of Shareware Professionals. CLIPPER is a trademark of Nantucket Corporation. dBASE, dBASE III, dBASE III PLUS, and dBASE IV are trademarks of Ashton-Tate, Inc. DESQview is a registered trademark of Quarterdeck Office Systems. FoxBase is a registered trademark of Fox Software, Inc. NANTUCKET is a registered trademark of Nantucket Corporation. Novell is a registered trademark of Novell, Inc. PLINK86-Plus is a trademark of Phoenix Technologies, Ltd. Page ii DataBase Structure Manager, Version 2.1 Limited Software License ------------------------ DataBase Structure Manager is copyrighted. Copyright 1989 Progressive Data Systems. Non-registered users are granted a limited license to use the DataBase Structure Manager software for a limited time to determine whether it meets their operating needs and requirements. This limited license is provided for the sole purpose of allowing non-registered users to evaluate the DataBase Structure Manager software. Continued use of the DataBase Structure Manager software requires a valid software license agreement with Progressive Data Systems. Your use of this software constitutes your acceptance of the limited warranty and license agreement. The license is terminated if you fail to comply with any term or condition of this license agreement. This limited license is for a single copy of the DataBase Structure Manager software and has been granted by Progressive Data Systems with their mailing address at Post Office Box 631, Middleton, Wisconsin 53562. The DataBase Structure Manager software is not sold. It may be licensed to you for your personal use on any one computer. (Please refer to Appendix D for license registration information.) Copies of this software may be made for trial use and short-term evaluation by others on a non-commercial basis. You may not charge anything for the DataBase Structure Manager software. The only exception to this is a cost-based fee (not to exceed the equivalent of fifteen dollars in U.S. currency) to cover distribution costs. The full set of programs and documentation must be included with any distributed copies. You may not modify DataBase Structure Manager or distribute this software in a modified form. The modification prohibition includes, but is not limited to, reverse engineering, disassembling and decompiling. You may not distribute this software in combination with any other service or product, or as a part of an institutionally or corporate-sponsored distribution. Bundling agreements and site licenses may be negotiated with Progressive Data Systems. The documentation provided here may change at any time without notice. Information presented in this documentation is not a representation of any form of commitment by Progressive Data Systems. Progressive Data Systems does not assume responsibility for the use of the documentation, nor for any patent infringements or other rights of third parties who may use the documentation. Page iii DataBase Structure Manager, Version 2.1 Shareware Distribution ---------------------- The DataBase Structure Manager is NOT public domain software, nor is it free (or freeware). The DataBase Structure Manager is distributed using the shareware marketing concept. The software may be freely copied and distributed to others provided no charge is assessed for the software and the software is not bundled with any other software. If you distribute this software, all files must be included without modification. Please take care to ensure all files are included in the distribution process. Shareware is the ultimate, consumer-oriented, value protection system. You, the consumer, may be assured of good values in software by acquiring and investigating the shareware software before you commit yourself to purchasing an extended software license agreement. You are indeed sought out for this very purpose and an attempt is made to get the software to you as inexpensively as possible. Shareware software must make it on its own merits without the expensive marketing hype of traditional commercial software. You are the judge and you can directly influence the acceptance of any of the shareware software you try by either recommending or not recommending the software to others. If you should find through your examination of the software that it does not perform up to your expectations or it does not meet your requirements, you are not obligated to pay anything so long as you do not continue to use the software. If this is the case with the DataBase Structure Manager, I sincerely thank you for trying the software. If you find the software to competently perform up to your expectations, but it does not satisfy your particular requirements, you may want to consider encouraging someone else to try it. If you find the software does meet your requirements, it performs in a suitable manner, and you wish to continue to use the software, (or you wish to continue to use the software for any other reason,) you are obligated to register with the author to obtain an extended software license agreement. The shareware marketing method must be successful for both the software users and software developers to ensure its viability. Please support the shareware marketing method and the software developers who are providing you with your quality programs by registering the shareware programs you continue to use. Page iv DataBase Structure Manager, Version 2.1 Technical Support ----------------- Technical support for registered users is provided for a period of one year beginning on the first day of registration. The technical support is available Monday through Friday from 9:00 AM to 5:00 PM (Central Standard Time). Please use the documentation provided to solve any problems before requesting technical assistance. Please have the following information available when you call Progressive Data Systems for technical support at (608) 836-5075: 1. DBSM license registration number. 2. DBSM version. 3. DOS version. 4. CONFIG.SYS and AUTOEXEC.BAT file contents. 5. Available system memory before executing the DBSM program as reported by the DOS CHKDSK command. Do not be deterred from requesting technical assistance if you cannot determine all of the above information. If you are at your computer when you call, we should be able to work together to gather the necessary information. _______ ____|__ | (tm) --| | |------------------- | ____|__ | Association of | | |_| Shareware |__| o | Professionals -----| | |--------------------- |___|___| MEMBER The Association of Shareware Professionals is dedicated to strengthening the future of shareware as an alternative to commercial software. Page v DataBase Structure Manager, Version 2.1 Table of Contents ----------------- Limited Warranty and Liability........................... i Trademark Acknowledgements............................... i Limited Software License................................. ii Shareware Distribution................................... iii Technical Support........................................ iv Association of Shareware Professionals Membership........ iv Table of Contents........................................ v Introduction............................................. 1 A Brief Relational Database Primer....................... 1 The DBSM Advantage....................................... 2 Practical Applications................................... 3 Features Summary......................................... 4 Urgent Information DBSM System Files...................................... 5 Unique Data Field Names................................ 6 Database Structure Generation.......................... 6 dBASE IV Database File Format.......................... 6 Memory Requirements.................................... 7 Insufficient Memory Error Message...................... 7 Application Database File Location..................... 7 Multi-tasking.......................................... 7 External Program Execution............................. 7 System Configuration Hardware Requirements.................................. 8 Software Requirements.................................. 8 Runtime Environment Settings........................... 8 Memory Allocation and Use............................ 8 Memory Variable Allocation......................... 9 External Program Execution/Index Buffers Allocation 9 Expanded Memory for Index Buffers.................. 10 Snow Elimination..................................... 10 Recommended Runtime Settings......................... 10 Enabling DOS Command Execution......................... 11 Network File Control..................................... 12 Technical Specifications Maximum Database Specifications........................ 13 Numeric Data Field Length Specifications............... 13 Database File Name Conventions......................... 13 Data Field Database Assignments........................ 13 Corrupted Databases.................................... 14 Installation Hard Disk.............................................. 15 Diskette Drive......................................... 15 System Startup Database System Application Directory.................. 16 Command Line Parameters................................ 16 First-Time Operation................................... 17 Page vi DataBase Structure Manager, Version 2.1 Table of Contents ----------------- System Startup (Cont'd) Hard Drive Operation................................... 17 Diskette Drive Operation............................... 18 Configuration Information Validation................... 19 Ownership/Registration Reminder........................ 19 Menu System Menu Types............................................. 20 DOS Command Execution.................................. 21 Dictionary Maintenance General Dictionary Maintenance......................... 22 Record Maintenance Menu-Bar Commands................. 22 Memo Field Edit Commands............................. 24 Data Field Maintenance................................. 24 Database Descriptions.................................. 27 Database Data Field Memberships........................ 29 Index File Specifications.............................. 30 System Description..................................... 31 Application Database Operations Index File Creation.................................... 32 Database Structure Variance Report..................... 32 Database Structure Generation.......................... 34 System Documentation General Documentation.................................. 39 Documentation Title Page............................. 39 System Description................................... 39 Database Summary Report.............................. 39 Database Extended Comments........................... 40 Index File Specifications............................ 40 Data Field Documentation............................... 41 Database............................................. 41 System............................................... 41 Utilities Printer Menu........................................... 42 Index All DataBase Structure Manager Files............. 43 Configuration Settings................................. 43 Screen Display Settings................................ 47 Show Structure of Database on Disk..................... 47 Compress Database's Memo File.......................... 47 Usage Hints.............................................. 48 Program Error Reporting Procedures....................... 49 Appendicies Appendix A - Full-Screen Edit Command Summary.......... 50 Appendix B - Memo Text Edit Command Summary............ 51 Appendix C - Enhancement Suggestions................... 52 Appendix D - Order Form................................ 53 Index.................................................... 54 Page 1 DataBase Structure Manager, Version 2.1 Introduction ------------ The DataBase Structure Manager (DBSM) is a data dictionary system specifically designed to manage Dbase-type relational database systems. It provides the ability to maintain multiple database data field specifications and to create database structures according to their dictionary specifications. It effectively replaces the dBASE III PLUS CREATE and MODIFY STRUCTURE commands with a more comprehensive and controlled development process. The database structures may be created in the dBASE III PLUS/FoxBase file format or Clipper file format depending on the database type specified in the configuration settings. The DataBase Structure Manager also performs maintenance of index file specifications and creates Clipper-style index files (*.NTX). All data dictionary information may be reported in the comprehensive, predefined documentation reports. A DBSM Structure Import Utility is provided with the DBSM system to automate the process of updating the data dictionary with database structure information from existing databases. A Brief Relational Database Primer ---------------------------------- A primary design goal of relational database development is to reduce unnecessary data redundancy. This is accomplished by subdividing the data into logical components (ie., databases or tables) and specifying any key relationships between those components. The key database relationships are maintained by including a common key data field in each of the related databases. The common key data field then serves as a link between them. A simple example of this design is an inventory system with the data subdivided into an inventory master file and a vendor master file. In this example, the key data field, VENDORID, is used in both databases. The VENDORID field links an inventory item in the inventory master file to its related vendor in the vendor master. This subdivision reduces data redundancy since a vendor may be a supplier for many different inventory items. The relational database design technique of subdividing the informa- tion and substituting the vendor identification data field into the inventory item record is preferable to having only one database which includes all of the vendor information (ie., company name, address, phone number, etc.) in each inventory record. It is preferable because it reduces the amount of unnecessary redundant information which in turn simplifies the database update process. It is, for example, much easier to change a vendor's phone number in one place in the vendor master than it is to seek out all of the inventory item records where it could occur and then change each occurence. Page 2 The DBSM Advantage ------------------ The DataBase Structure Manager maintains two data dictionaries. One is the database dictionary where general information regarding each database is maintained. The other is the data field dictionary where information concerning all data fields is maintained including the assignment of a data field to one or more databases. Data field definitions are checked during data entry to ensure that they comply with the database type specified in the configuration settings. For example, if the database type is dBASE III PLUS, then a character field's length may not exceed 254 characters. The process of developing relational database systems is simplified and controlled by the DataBase Structure Manager. It is simplified by allowing redundant key data field definitions to be eliminated. For instance, in the earlier example, a VENDORID key data field that occurs in the vendor master and inventory databases need only be defined once in the data field dictionary. After the VENDORID data field has been defined, it may then be assigned to the appropriate databases. The development process is more controlled because the singular definition of key data fields ensures consistent definitions in each database where it occurs. For example, it is not possible to assign a key data field to some databases with the data field defined as a numeric data type and assign it to other databases defined as a character data type. It also helps to ensure the data field name is the same in each database by encouraging the assignment of existing data fields rather than requiring that every data field be defined each time a database structure is defined. Updating a data field specification that occurs in multiple databases requires only one data field change in the data field dictionary. Once the data field has been changed, the database structures that contain the data field may be regenerated by selecting them from a point and select window. Please notice that in this process, there is no need to find all the databases that use the data field and the change that is made will be consistent for all related databases. The process of eliminating unnecessary data field definitions need not be restricted to key data fields. Any data fields that are used in the same manner, for instance zipcode, may be defined once and then assigned to as many databases as necessary. The DataBase Structure Manager also provides the capability to document the database system. The data field dictionary allows maintenance of more information than just the mandatory specifications (ie., data field name, type, length, and decimals). Each data field may be documented more fully than the traditional structure maintenance commands allow by including such information as picture format, default value, low range value, high range value, a validation procedure name, description, and an indication as to whether the field is required during data entry. In addition, databases and the general database system may be described in detail using the system's open-ended text processor. All of the information maintained may be reported. Page 3 Practical Applications ---------------------- The DataBase Structure Manager may be used in several different ways. The most obvious use is the controlled development of database specifications and their related database structures as noted previously. Database structures may be created using the dictionary database specifications. Before a new database structure is generated, the dictionary database structure specifications may be compared with a corresponding database on disk. The resulting Structure Variance report will note any differences or similarities. This is especially important when a database structure is being regenerated, since the data from the corresponding database on disk will be appended to the new database structure. The transfer of data from a corresponding database is dependent on the similarity of the data fields. The data fields must be the same name and data type to be transferred. Where numeric and character data fields are similar in name and data type, the length characteristics are also important. For instance, if the dictionary definition of a charac- ter data field's length is less than the similarly named data field in the corresponding database on disk, it is possible to truncate data dur- ing the transfer process. The Structure Variance report makes it easy to identify these situations before generating a new database structure. If there is a corresponding database on disk for a new database being generated, delete status records may be included or omitted in the new database structure according to the user request. If the delete status records are included, they will remain in delete status in the new database! Database system developers may combine the database specification features with the documentation features to provide professional database system documentation to be used in system proposals or for completed system documentation. The major reports are database data field documentation, complete system data field documentation (with database cross-reference), free-form text reports describing the database system and individual databases, and index file specification documentation. The DataBase Structure Manager data dictionary files may be used as an integral part of the application database system. Since the data dictionary files are in a Dbase-type file format, the data field specifications for default value, low and high range value, validation procedure name, and picture format may be directly referenced by the application database system to ensure data integrity. In fact, the application database system may provide procedures that directly maintain the dictionary data field characteristics. If this technique is properly implemented, data field validation parameters may be updated without requiring any changes to the application program code. The DBSM Structure Import Utility may be used to gather database struc- ture information into the data dictionaries from existing databases. This feature is especially useful for anyone who needs to understand an existing database system. Once the basic database structure information is imported, the DataBase Structure Manager may then be used to enter additional information gained through other sources. Page 4 Features Summary ---------------- Documentation ------------- Comprehensive data field documentation grouped by database and by the entire database system (with database cross-references). General database summary information (including free-form extended comments) and index file documentation may also be reported. Informed Structure Generation ----------------------------- Differences between dictionary database specifications and corresponding databases on disk are highlighted using the structure variance report. The report information is determined by comparing the dictionary database specification with a corresponding database structure specification on disk. Controlled File Access ---------------------- In a network environment, only one user at a time is allowed access to a directory's DBSM system files when using the DataBase Structure Manager or the DBSM Structure Import Utility. Regenerating a database structure using DBSM can only occur when the specified database is exclusively accessed. If exclusive access by DBSM is not possible, a message will be displayed noting the situation. (Nantucket Clipper file- and record-locking conventions must be used by all programs concerned to guarantee proper network file access control.) Dictionary Search Capability ---------------------------- Database dictionary information may be searched and reported based on various user-supplied selection criteria. Supports Clipper's Very Large Character Fields ---------------------------------------------- Clipper's support for very large character field specifications (up to 32K) is maintained in a transparent manner. Character data field lengths are specified by simply entering the length into the length specification as opposed to the usual method of using both the field length and field decimals specifications. Customization, Enhancements, and Extensions ------------------------------------------- The DataBase Structure Manager system may be customized, enhanced, or integrated into existing systems only by Progressive Data Systems. If interested, please contact Progressive Data Systems for more information. Page 5 Urgent Information ------------------ DBSM System Files ----------------- USER BEWARE - Your database files may be in jeopardy. All DBSM system files are assumed to be under the exclusive control of the DBSM program. The DBSM system files include the dictionary databases, their associated index files and memo databases, and some temporary files. The DBSM program assumes that it may delete and create these files as needed. Before using the DBSM, please ensure that there will not be any conflicts in the directory in which it will operate. The DBSM system file names have been specifically chosen to avoid conflicts with most file names. Every file name used by this system except for the executable files, will begin with a dash, "-" and has an underscore character, "_", in the fourth position. (For those of you who are versed in wildcard pattern matching, the pattern is "-???_*.*".) If you have any files matching this pattern in the directories where this program will be working, you should examine the list of DBSM files below for conflicts. If there is a conflict, you will need to change your file names or refrain from using this system in the directory with the conflicting names. Otherwise, you risk having your files deleted and this system will not operate correctly. You are responsible for ensuring file compatibility. If you have ANY doubts or are using this system for the first time, I encourage you to install this system in a temporary directory and place a COPY of the databases from one of your systems into it. (Do not simply move the originals into the temporary directory.) Get to know this system before maintaining "live" database information. The names of the DBSM system files are as follows: Databases and Associated Memo Databases ----------------------------------------------------- -DAT_DCT.DBF Data Field Definitions -FIL_FLD.DBF Database Data Field Members -FIL_MST.DBF Configuration Information -FIL_MST.DBT Configuration Information Memo Database -FIL_NAM.DBF Database Descriptions -FIL_NAM.DBT Database Descriptions Memo Database -FIL_NDX.DBF Index File Specifications Index Files Temporary Files ------------ --------------- -CAT_NAM.NTX -SAV_DBF.DBF -DAT_FLD.NTX -SAV_DBF.DBT -FIL_DSC.NTX -TMP_1.DBF -FIL_FLD.NTX -TMP_1.DBT -FIL_NAM.NTX -TMP_1.NTX -FIL_NDX.NTX -FLD_NAM.NTX If you have any doubts about file name conflicts, before executing DBSM, execute the following wildcard DOS directory command in the directory where you expect to work with DBSM: DIR -???_*.* Page 6 Urgent Information ------------------ DBSM System Files (Cont'd) -------------------------- Any files matching the wildcard pattern will be displayed. If the display returns any of your file names, compare them with the DBSM files listed above to ensure there is no file name conflict. Unique Data Field Names ----------------------- Data field names must be unique across all databases in the diction -ary. For example, there can only be one data field named "VENDOR" in the dictionary. It can occur in multiple databases. This ensures a consistent definition in every database where it occurs. Database Structure Generation ----------------------------- When database structures are generated where there exists a corresponding database on disk in the same directory, an attempt will automatically be made to transfer data from the original database. Information will only be transferred where both the data field name and the data field type match. If you have changed a data field name in the database dictionary specification, the information will not be transferred from the original database for that data field. If you are changing field names and you want the old values transferred, retain the old data field name, add the new data field name, and then generate the new database structure. Once the new structure has been successfully generated, transfer the data from the old field into the new field and verify the results. When the transfer is successful, then delete the old data field definition and generate a new database structure. dBASE IV Database File Format ----------------------------- dBASE IV databases without memo or floating point data types are compatible with the DBSM system. Their structure information may be imported into the dictionary using the Structure Import Utility. The full dBASE IV file format is not supported by the DBSM system. Any Dbase databases with memo fields that have been accessed or created by dBASE IV are currently interpreted by the DBSM system as corrupt database files. The reason is due to the new "associated memo file" indicator. Dbase dialects prior to dBASE IV, use the hexadecimal value "83" in the 1st byte of a database to indicate an associated memo file. dBASE IV uses the hexadecimal value "8B" in the 1st byte to indicate an associated memo file. If a database with any memo fields is USE-d by dBASE IV, it will set the 1st byte of the database to its own format. There may be a good reason why databases with memo fields are not backwards compatible... The dBASE IV floating point data type is not recognized by the DBSM system, but databases with the floating point may be imported. The floating point data type will be interpretated as an undefined data type, "U", with field length and decimals set to zero. Database structures may not be generated with undefined data types. Page 7 Urgent Information ------------------ Memory Requirements ------------------- The DBSM requires a substantial amount of memory to run. The DBSM will look for a character string in the DOS environment to determine how it will allocate and use different portions of memory when it loads. It is strongly suggested that the runtime setting be established before attempting to run the DBSM. Please refer to the System Configuration - Runtime Environment Settings documentation section for more information. For a quick start, the following runtime setting should be sufficient for most systems: set DBSMDCT=V007;R000 This command is case-sensitive. Where upper-case letters are indicated, upper-case letters must be used. Insufficient Memory Error Message --------------------------------- An insufficient memory error message and prompt will be displayed in the upper-left corner of your screen if there is not enough free memory available to complete an operation. For more information, please refer to the documentation section that covers the operation which caused the insufficient memory error to occur. Application Database File Location ---------------------------------- DBSM will only generate database structures and index files in the current directory. Therefore, the DBSM must be run in the directory where the application database structure(s) need to be created. Multi-Tasking ------------- Do not run multiple copies of DBSM in a multi-tasking environment (ie. DESQview, etc.) in the same directory. The DBSM uses standard temporary file names which could easily be mixed up when running multiple copies of the DBSM. For the same reason, simultaneous use of DBSM and DBSMIMP in the same directory should also be avoided. External Program Execution -------------------------- DOS commands may be initiated from most menus by pressing "F3". However, running a DOS command is risky. It is risky in the sense that the DBSM system may abnormally terminate if the system memory is not well-ordered. Abnormal termination is not normally detrimental to any files, but it is inconvenient. For more information, refer to the "DOS Command Execution" documentation section. Page 8 System Configuration -------------------- Hardware Requirements --------------------- Minimum 512K system memory (640K suggested). A hard disk is recommended for best operating performance. Floppy disk-based systems may be used, but there may be a considerable amount of diskette swapping required for single-diskette systems. Software Requirements --------------------- * DOS 2.0 or higher (DOS 3.1 or higher for network file control). * CONFIG.SYS The following are minimum specifications for the FILES and BUFFERS parameters in the CONFIG.SYS file: 1) BUFFERS=8 2) FILES=19 * Memory Usage The DataBase Structure Manager requires a minimum of 390K (399,360) bytes of RAM to enable it to manage the largest possible dBASE III PLUS database. See Memory Allocation and Use for more information. Runtime Environment Settings ---------------------------- * Memory Allocation and Use Memory allocation and use may be controlled in three different categories - memory variables, index buffers/external program execution, and expanded memory (LIM 3.2). The amount of memory allocated for each category may be tailored (except for memory variable memory allocation) to meet your specific usage requirements and hardware/software configuration. DBSM.EXE will search for the "DBSMDCT" specification in the DOS environment. The method for designating the memory allocation is through the use of the DOS SET command. The DOS SET command for the "DBSMDCT" specification is as follows: set DBSMDCT=V007[;Rnnn][;Ennn][;S1] Where: V007 = Memory variable memory allocation. Rnnn = External program execution and index buffer allocation. Ennn = Expanded memory allocation for index buffers. S1 = "Snow" elimination. This command is case-sensitive. Where upper-case letters are indicated, upper-case letters must be used. The runtime settings are the same settings as defined for Nantucket's Clipper (Summer '87) runtime settings (ie., set CLIPPER=...). The documentation provided with Clipper (Summer '87) may be useful if a further description of the "set DBSMDCT=" settings is necessary. Page 9 System Configuration -------------------- Runtime Environment Settings (Cont'd) ------------------------------------- * Memory Allocation and Use (Cont'd) 1. Memory Variable Allocation Memory variable memory allocation should always be "V007" to ensure there is sufficient memory available for all memory variables required. 2. External Program Execution/Index Buffers Allocation The optional "Rnnn" parameter indicates memory space (in 1024 byte units) to be allocated for index buffers and external program execution. If the "Ennn" parameter is specified, the "Rnnn" parameter will be used solely to allocate memory for external program execution. This parameter is optional, but it is suggested that a value be determined to ensure that memory is efficiently allocated in a manner that best suits your specific needs. (Please refer to the documentation "Enabling DOS Command Execution" for further information on running external programs.) The "Rnnn" value is only evaluated at the time the program is loaded. At that time, the load process will attempt to provide the amount of memory requested in the "Rnnn" parameter for the external program execution/index buffering. All memory allocated to this area will not be available for loading the main program code and data. If there is insufficient memory left for the program code and data after allocating memory according to the "Rnnn" value, the program will terminate with the message "Not enough memory". If you do not intend to run external programs from inside the DataBase Structure Manager, you should set the "Rnnn" parameter value to zero (ie., "R000") to free up the maximum amount of memory for program data manipulation. If this runtime setting is specified (ie., set DBSMDCT=V007;R000), the minimum amount of RAM required to load the DBSM is 390K (399,360) bytes. There will still be sufficient memory for indexing operations. If external programs are to be run, the minimum "Rnnn" value must be at least 26K bytes (ie., "R026"). This minimum value will allow the running of DOS internal commands (COPY, DIR, etc.) and external programs up to approximately 8K in size. If the runtime setting "R026" is used, the minimum amount of RAM required to load the DBSM is 400K (409,600) bytes. Running larger external programs will require a corresponding increase in the "Rnnn" parameter value and an increase in the minimum amount of RAM required to load DBSM. Page 10 System Configuration -------------------- Runtime Environment Settings (Cont'd) ------------------------------------- * Memory Allocation and Use (Cont'd) 2. External Program Execution/Index Buffers Allocation (Cont'd) If no "Rnnn" parameter value is set in the "set DBSMDCT=..." statement, a default value will be calculated at load time. The default value supplied for this parameter is dynamically determined as a percentage of free memory available at the time the DataBase Structure Manager program is loaded and executed. 3. Expanded Memory for Index Buffers The optional "Ennn" parameter identifies expanded memory space (in 1024 bytes units) to be used for index file buffers. The expanded memory must conform to the LIM 3.2 specification. If this parameter is supplied, the minimum value is "E016" which represents 16k bytes. * Snow Elimination The optional "S1" parameter specification will eliminate "snow" in the screen display. If you use this parameter to eliminate "snow", the display will be cleaner, but the display will operate a little bit slower. * Recommended Runtime Settings The recommended setting for providing the greatest amount of free memory for dynamic program allocation and thereby allowing the largest database structures to be generated is as follows: set DBSMDCT=V007;R000 The above setting does not allow any external programs to be run, but there will be sufficient memory made available for index buffers. The recommended setting for allowing the minimum external program execution and still providing a large amount of free memory for dynamic program allocation is as follows: set DBSMDCT=V007;R026 Both of the above settings assume there is no expanded memory available for indexing operations. Page 11 System Configuration -------------------- Runtime Environment Settings (Cont'd) ------------------------------------- * Enabling DOS Command Execution There are 3 requirements that must be met before external programs may be executed from within the DataBase Structure Manager. (The "Run DOS" command may be initiated by pressing function key "F3" at all menus except the printer port and printer type menus.) The first requirement is the minimum memory requirement needed to run external programs. Before loading the DBSM program, there must be at least 400K (400,600) bytes of RAM available. You may determine the amount of memory available using the DOS CHKDSK command. Secondly, the "Rnnn" parameter of the runtime environment settings must be at least 26K (ie., set DBSMDCT=V007;R026). See the earlier description of runtime environment settings for more information. The last requirement is that the DOS command processor (COMMAND.COM) location must be specified in the DOS environment. This is required even if COMMAND.COM resides in the same directory where the DataBase Structure Manger will be run. The DOS SET command may be used for this purpose. To specify the command processor location, use the following SET command syntax: set COMSPEC=[d:][\<path>]\COMMAND.COM Where [d:] Optional disk drive specification. [\<path>] Optional directory path to COMMAND.COM For more information regarding the DOS SET command, please refer to your DOS manual. Page 12 Network File Control -------------------- DBSM has the ability to coordinate network file access only with those programs using the same network file locking procedures as Nantucket's Clipper-compiled programs. dBASE III PLUS network file- and record-locking procedures are NOT compatible with Clipper's methods. Clipper (Summer '87 version) uses the DOS 3.1 RLOCK command in an unconventional manner. The network file control operates in two different areas. First, it controls the DataBase Structure Manager use so that only one user at a time is allowed to run the program in the same directory. Essentially, this eliminates the need to personally coordinate with other developers who may periodically need to make changes in the same database dictionary. If a user does attempt to run DBSM or DBSMIMP in a directory where either of these programs is already in use, one of the following messages will be displayed: File "-FIL_MST.DBF" is in use. Retry, Wait up to 2 min., or Exit? or File "-FIL_NDX.DBF" is in use. Retry, Wait up to 2 min., or Exit? The new user will have three options. The new user may retry, wait up to 2 minutes for the current user to exit, or exit the program. If the second message is issued (ie., the message containing the reference to the "-FIL_NDX.DBF" file), the new user should exit their attempt to run DBSM or DBSMIMP. The second area of file control concerns the application database files on disk which may need to be accessed by the DBSM to gain information about the database or, more importantly, to regenerate a new database structure. When a database is locked, most attempts to gain information will simply note that the database may not be accessed. In the case where a database structure is being regenerated, the DBSM will attempt to lock the database file for exclusive use. If this is not possible, a message will be displayed noting the situation and the database structure creation process will be exited. ,---------------------, **********************| Special Emphasis! |*********************** '---------------------' Any file/record-locking and checks for file/record locks must comply with Nantucket's Clipper-compiled file/record-locking techniques to facilitate coordinated network file access control with the DBSM. File/record-locking methods that are not compatible may cause unpredictable results. If you are not sure about other program's file/record-locking compatibility with Clipper's techniques, do not rely on the DBSM's network file control features to eliminate network file access contention between programs. Page 13 Technical Specifications ------------------------ Maximum Database Specifications ------------------------------- The maximum database specifications may be achieved by either designating the Clipper database type or the custom database type in the Configuration Settings (See Utility Menu). If the custom database type is specified, the custom database specifications must be entered. In no case will the DBSM be able to generate a database that exceeds the following specifications: Database record length......: 32,766 Number of database fields...: 1,024 Character field length......: 32,766 Numeric field length........: 20 Decimals field length.......: 18 Index key expression length.: 250 Index key expression fields.: 42 The amount of available system memory may be exceeded prior to reaching any of these maximum specifications. If a database structure specification exceeds the maximum dBASE III PLUS database specifications, Nantucket Clipper (Summer '87 version) conventions will be used in interpeting and maintaining the database structure. The database record length values reported and used by this system are calculated by summing the length of all data fields in the database. The database's 1-byte delete status position is not included in the record length. Numeric Data Field Length Specifications ---------------------------------------- Every numeric field specified must include 1 position to the left of the decimal point. When decimals are indicated, the number of deci- mals cannot exceed the numeric field length minus 2. For example, the minimum numeric field length for a number with 2 decimals is 4. A custom database type must be defined in Configuration Settings to allow numeric data fields to be the maximum allowable for dBASE IV databases (ie., field length 20, decimals 18). Database File Name Conventions ------------------------------ In addition to the standard DOS file naming rules, no database or index file name may include spaces, asterisks, or question marks. Data Field Database Assignments ------------------------------- The data field maintenance screen includes a display of the database names a data field has been assigned to. Only the first 36 database assignments will be shown on the data field maintenance screen. Page 14 Technical Specifications ------------------------ Corrupted Databases ------------------- Some procedures test for the presence of a valid database. A database is considered corrupt if some of the database header infor- mation is incorrect. This includes the case where an associated memo database has been designated in the database header informa- tion, but no associated memo database is found with the database. Some dBASE IV database file formats are also interpreted as corrupt databases (See page 6 for more information). Operations which detect the invalid databases will provide a message and will either abandon the current operation or, if possible, continue without it. Page 15 Installation ------------ The first order of business is to make backup copies of the system diskettes. (If you are unfamiliar with this process, please refer to your DOS manual. See the DISKCOPY command.) Before beginning the installation process, please read the READ_ME.1ST file. Assuming the READ_ME.1ST file is in the current drive and directory, it may be displayed a screen at a time by using the following DOS command: TYPE READ_ME.1ST | MORE Hard Disk --------- To install the DBSM system onto your hard disk, simply copy the executable files, DBSM.EXE and DBSMIMP.EXE, into a directory in the DOS executable search path and copy the documentation files, DBSM.DOC, DBSMIMP.DOC, and READ_ME.1ST, into any directory desired. For the less experienced user, you may first have to determine what a DOS executable search path is and if there is an existing specification for your computer. If you are unfamiliar with the DOS executable search path, please reference your DOS manual for further information. See the PATH command. Once the desired drive and directory has been determined, use the DOS COPY command to copy the two executable files to the proper destination. The following DOS directory command, DIR, may be used to find any DBSM system executable files on a diskette in the A: drive: DIR A:*.EXE An example of copying the DBSM.EXE file from drive A: to the subdirectory "\UTIL" in drive C: is as follows: COPY A:DBSM.EXE C:\UTIL Diskette Drive -------------- There is virtually no installation required for operating from a diskette drive. You should ensure that you have made backup copies of the system diskettes. Operation from a single-diskette drive is possible, although it is not recommended for reasons of efficiency. When you are restricted to a single-diskette drive system, you will find a considerable amount of diskette swapping is necessary when frequently moving between different operations. Page 16 System Startup -------------- Database System Application Directory ------------------------------------- The DBSM most conveniently manages a database system's application databases if they are in a single directory. Before executing DBSM, the application database files should be in the current directory. If the configuration master file, "-FIL_MST.DBF", is not found in the current directory, the load process will halt and a prompt message will be issued to determine if you wish to continue. Choosing not to continue will allow you to investigate the "missing" files situation rather than allowing DBSM to continue and generate any missing system files. Command Line Parameters ----------------------- There are three optional command line parameters. Each parameter must begin with a forward slash ("/") and multiple parameters must be separated by a single space. Parameters may be specified in any order. To list the call parameter syntax, you may include either "/H" or a question mark in the command line. All parameters are optional. Usage: DBSM [/Cn] [/Pn] [/F] Where /Cn = Screen type "/C1" through "/C5". Colors = C1 through C4 Monochrome = C5 /Pn = Printer type "/P1" through "/P9". /F = Load program from diskette drive. Sample Use #1: DBSM /P8 /C2 Use the custom printer codes and the color display scheme #2. Sample Use #2: DBSM /F Load this program from the diskette in drive A:. * Screen Display Type There are four different color display schemes available. They are indicated by using the parameters "/C1" through "/C4" (without the double quotes). The monochrome display parameter is designated with the "/C5" parameter. If no screen display type is specified, the display scheme designated in the Configuration Settings (See Utility Menu) will be used. In every case (no matter what settings are specified), if a color monitor card is not detected, the display scheme will be monochrome. If a color card is detected and the primary display device is a monochrome monitor, DBSM will allow color schemes to be selected and implemented. Page 17 System Startup -------------- Command Line Parameters (Cont'd) -------------------------------- * Printer Type The printer type specification has the general format of "/Pn" (without the double quotes) where the printer identifier "n" may be any number from one to nine (See table below.). If no printer is specified in the command line, the printer type indicated in the Configuration Settings will be used. Printer Identifier Printer Type ---------- ---------------------------- 1 Epson FX-86e/286e 2 Epson RX-100 3 NEC 3550 4 Panasonic KX-P1592 5 Brother M-1509 6 IBM Proprinter XL 7 IBM Quietwriter 8 Custom Printer (Requires additional definition) 9 HP LaserJet series II * Diskette Drive Operation This command line option allows DBSM to be loaded from a diskette drive. The command line option is specified with a "/F" (without the double quotes). When this option is used, the program initiation sequence will pause to allow the diskette drive containing the DBSM executable program, DBSM.EXE, to be removed and then be replaced by the diskette containing the system database dictionary files. Diskette drive A: should be used as the primary drive. It is possible to run DBSM using only a single-diskette drive, but as different DBSM program features are selected, it may be necessary to exchange the DBSM system diskette and the system data dictionary files diskette to allow the necessary program code to be loaded. First-Time Operation -------------------- Any time DBSM is loaded and it does not find its system files, it will regenerate them. This will be the case the first time DBSM is executed. If the configuration file is generated, the Configuration Settings procedure will be initiated before proceeding to the main menu. (Refer to Configuration Settings for more information.) Hard Drive Operation -------------------- The DBSM needs to be executed in the directory where the database system files are located. Page 18 System Startup -------------- Diskette Drive Operation ------------------------ DBSM will operate from a diskette drive. The "/F" command line parameter must be used to pause the startup procedure to allow the system disk containing DBSM.EXE to be replaced by the applications database disk. To load DBSM from drive A:, place the diskette containing DBSM.EXE into diskette drive A:, make drive A: the current drive (if necessary), and enter the following command at the DOS prompt: DBSM /F The program will begin to load and execute. Shortly, a message will appear asking you to remove the diskette from the drive and put the data disk in place of it. The data disk should contain the DBSM system dictionary files and/or the application database files in the root directory if they have been created. If they have not been created, place a formatted diskette which you intend to use for the data dictionary information into the diskette drive. Once the diskettes have been exchanged, press Enter to continue. The main menu will then be displayed. At some point, you may cause the program to switch overlays. The first time the program cannot find the DBSM.EXE file to load in the needed overlay, the following message will appear at the bottom of the screen: PLINK86 Overlay Loader - Can't find file DBSM.EXE. Enter file name prefix (X: or path name) or '.' to quit=> The description that follows assumes you have started the program from drive A:. If you have a second floppy drive, place the diskette containing the DBSM.EXE file into drive B: and then respond to the missing file prompt with "B:" (without the quotes) and press enter. From then on, the file will always be found in the B: drive without issuing a prompt. If you have only one drive, you should respond to the missing file prompt with "B:" (without the quotes) and then press enter. You will be prompted to insert the diskette in drive B:. Extract the data disk from drive A: and then place the diskette containing the DBSM.EXE file in drive A:. Once this is accomplished, respond to the prompt by pressing enter. From then on, every time the data disk is needed, you will be prompted to insert the drive A: diskette into the diskette drive and every time the DBSM.EXE file is needed, you will be prompted to insert the drive B: diskette into the diskette drive. As you may imagine, if you only have one diskette drive, you will be doing a lot of diskette swapping. One way to keep the swapping to minimum is to do all your work in one area of the program before moving to another area. Page 19 System Startup -------------- Configuration Information Validation ------------------------------------ Every time DBSM is loaded, it checks for proper configuration information in the configuration database. If there is any invalid information detected, the Configuration Settings maintenance procedure is invoked with an error message indicating the first error that was discovered. All errors must be corrected before exiting the Configuration Settings procedure. Ownership/Registration Reminder ------------------------------- An ownership/registration reminder will be displayed as a part of the system startup procedure the first time the DBSM is run in any directory (as determined by the lack of system database files) and once in each directory the DBSM is run in on Wednesday. Page 20 Menu System ----------- Menu Types ---------- * Main Menu The main menu selections allow one of three standard sub-menus to be displayed. The menu options are selected by number except for the the quit option ("Q") and the "Run DOS" command option ("F3"). * Standard Sub-Menus Standard sub-menus are the menus that may be directly or indirectly called from the Main Menu. Menu options are selected by letter. Pressing the enter key, escape key, or 'Q' will return control to the previous menu. * Quick Menu Traversal At any standard sub-menu, the main menu options are also available. For example, if the current standard sub-menu is the Printer Menu, you may switch to the Maintenance Menu by simply pressing "1". * Database Selection Menus Operations requiring the selection of an application database will use a point and select menu. An example of one such operation is the database structure generation. These point and select menus will display all database file names and description fields in alphabetical order by database file name. If there are more than 17 databases defined in the system, it will be necessary to use the cursor control keys to scroll the display. A single database may be selected by cursoring to the desired database file and then pressing enter. The cursor may be positioned to the first file name that begins with a particular letter by entering the associated letter. All databases may be selected for an operation by pressing the "F5" function key. The cursor control keys for traversing the menu are as follows: Down Arrow = Go to the next database file below the current highlighted database. Up Arrow = Go to the next database file above the current highlighted database. Page Down = Scroll the entire screen down one page. Page Up = Scroll the entire screen up one page. Home = Go to the first database. End = Go to the last database. <letter> = Go to the 1st file beginning with this letter. If there are no database files defined, a usage error message will be displayed in place of the menu. Control will revert to the previous menu after pressing return. Page 21 Menu System ----------- DOS Command Execution --------------------- Running a DOS command is risky. It is risky in the sense that the DBSM system may abnormally terminate if the system memory is not well-ordered. Abnormal termination is not normally detrimental to any files, but it is inconvenient since the program must be re- loaded. The DBSM system code is not rugged enough to consistently correctly manage the system memory under anything less than good conditions. Conditions are most favorable to run DOS commands before extended DBSM use has occurred. With the above in mind.... A DOS command may be executed by pressing function key "F3" at most standard menus except the Printer Selection and Printer Port Selection menus. The DOS Command option is only available if the "Rnnn" parameter of the DBSM runtime environment setting has been properly set. (Please refer to "Enabling DOS Command Execution" for more information.) After the first external run command has been executed, subsequent calls to run a DOS command will allow the previous command to be recalled to the command line by pressing the "F3" function key. If there is insufficient memory available to run the requested program, there are a few possible error conditions that may occur (two of which are unrecoverable). If there is not enough space to load the DOS command processor, the error message "Proc RUNDOS line 0, RUN error" will be displayed and the DBSM program will terminate. If the external program requested is too large for the memory allocation, the message "Program too big to fit in memory" will be displayed and you will be returned to the previous menu. If the program can be loaded, but it attempts to increase its memory usage beyond the allocated bounds, the message "Not enough memory Program aborted" will be displayed and control will return to the previous menu. If this last scenario is executed by the external program in an unruly manner (ie., not using the proper calls to DOS to use more memory), it is possible to lock-up the computer. The only recovery possible for this last situation is to reboot the computer. Another possible error condition is if there is insufficient space for the environment, the following message will appear: "error 2009: Not enough space for environment". Simply press the Enter key to return to the previous menu. Page 22 Dictionary Maintenance ---------------------- General Dictionary Maintenance ------------------------------ * Record Maintenance Menu-Bar Commands A standard horizontal menu-bar is provided for command selection. The commands may be initiated by cursoring over to the desired option and then pressing enter or by entering the first letter of the command option. The left-arrow and up-arrow cursor will move the cursor left one position with wrap-around. The right-arrow and down-arrow will move the cursor to the right one position with wrap-around. The return key or page-down key will initiate the command that is currently highlighted. The escape key will exit the maintenance the same as having initiated the quit option. When moving the cursor from command to command, the line below the command line will provide a brief description of the command. 1. Record Traversal Records are sequenced in alphabetical order using the top field in the screen display. A. Next Display the next record. If there are no more records in the sequence, an appropriate message will be temporarily displayed. B. Previous Display the previous record. If there are no previous records, an appropriate message will be temporarily displayed. C. First Go to the first record in the sequence. D. Last Go to the last record in the sequence. 2. Record Maintenance Both the Add and Edit commands initiate a full-screen edit procedure. For a description of the full-screen edit commands, please refer to Appendix A. A. Add Add a new record. B. Edit Edit the record that is currently displayed. Page 23 Dictionary Maintenance ---------------------- General Dictionary Maintenance (Cont'd) --------------------------------------- * Record Maintenance Menu-Bar Commands (Cont'd) 2. Record Maintenance (Cont'd) C. Delete Toggle If the record is active, the record will be set to delete status. If the record is in delete status, the record will be un-deleted. If there are records that have been left in delete status as a result of using the delete toggle command, then upon exiting from the maintenance section, ALL delete status records from the specific dictionary database will be removed. (Please refer to the specific dictionary deletion procedure for more details.) 3. Search Records Records may be searched using one or more search field criteria. All available search fields will be displayed. Search values may then be entered. Multiple search field selections are AND conditionals. For example, if a character data field type (type = "C") is selected along with a data field length of 15, then all character data fields that have a length of 15 will be retrieved. A selection flag must be provided for each selected search field to specify the type of match. The adjacent selection flag for each selected search field may have one of the following values: Selection Flag Match Designation -------------- ------------------------------------------- = Exact match. > Match values greater than the search value. < Match values less than the search value. # Match values not equal to the search value. A tally of the search matches will be maintained in the lower right-hand quadrant of the display screen. 4. Exiting Maintenance If any records have been left in delete status as a result of using the delete toggle, the delete process will be initiated as a part of the exit process. All delete status records are treated in the same manner in the delete process regardless of whether they set to delete status in the current maintenance session, in a previous maintenance session or by operations in another program. Page 24 Dictionary Maintenance ---------------------- General Dictionary Maintenance (Cont'd) --------------------------------------- * Memo Field Edit Commands 1. Help Use <Alt-H> to display the memo edit help screen. 2. Cursor/Screen Movement and Edit Functions Please refer to memo text edit command summary (Appendix B). 3. Quitting A. Use <Ctrl-W> to save the changes and exit. B. Use the Escape key to quit without saving changes. 4. Print Memo Text Use <Alt-P> to print the memo text. This command must precede any commands that alter the content of the memo text. To print the memo after altering the text, the memo maintenance must be exited and then re-initiated. 5. Write Memo Text to ASCII Files Use <Alt-W> to write the memo text out to a disk file. This command must precede any commands that alter the content of the memo text. To write the memo text out to disk after altering the text, the memo maintenance must be exited and then re-initiated. Data Field Maintenance ---------------------- * Mandatory Specifications All mandatory specifications are validated according to the database type specified in the Configuration Settings. 1. Field Name A data field name must begin with an alphabetic character and may not exceed 10 characters. The name may contain letters, numbers, or the underscore symbol (_). It may not contain blanks (except for trailing blanks). Under no circumstances will the DBSM system allow two separate data fields to be defined with similar data field names. Separate data field definitions require unique data field names. This means that data field names must be unique across all databases in the database dictionary. For example, there can only be one data field named "VENDORID" in the data field dictionary. It can be assigned to as many databases as required. 2. Field Type The field's data type must be character, numeric, date, logical, or memo. The first letter of the data type, in uppercase, is used to indicate the data type (ie., C, N, D, L, or M). Page 25 Dictionary Maintenance ---------------------- Data Field Maintenance (Cont'd) ------------------------------- * Mandatory Specifications (Cont'd) 3. Field Length The field length specifies the length of the data field. Standard field lengths will be assigned to date, memo, and logical field types without regard for the length entered. Every numeric field specified must include at least one position to the left of the decimal point. A special note for Clipper programmers - The DBSM allows the specification of character fields exceeding 999 characters by simply entering in the entire value in the data field length specification. There is no need to use the data field's decimal specification field to designate the number of 256 byte units in the character field. 4. Field Decimals Enter the number of decimal positions. The value entered will only be recognized if the field type is numeric. All other field types will automatically be set to zero. The number of decimals cannot exceed the numeric field length minus two. For example, the minimum numeric field length for a number with two decimal positions is four. This allows for the mandatory minimum one position to the left of the decimal point, the decimal point, and the two decimal positions. * Optional Data Field Documentation 1. Required? This character field may be used to indicate mandatory data entry for the associated data field. An affirmative indication can be used to indicate that when the data field appears in a data entry screen, it must have a value entered. 2. Picture Format The PICTURE clause used in a display or data entry statement. 3. Default Value The standard value for the data field. For example, in a membership system, the STATE field may have a default of 'WI'. 4. Low Range Value The lowest possible valid value for the data field. 5. High Range Value The highest possible valid value for the data field. 6. Validate Procedure Specifies the data field validation procedure name. Page 26 Dictionary Maintenance ---------------------- Data Field Maintenance (Cont'd) ------------------------------- * Optional Data Field Documentation (Cont'd) 7. Sequence Code The sequence code is the major sort field used to control the data field order in reports and structure generation. The minor sort field is the data field name. Any ASCII characters may be used. Remember - Upper case alphabetic characters have higher precedence than any lower case alphabetic characters. (See Database Structure Generation - Data Field Order for more information.) 8. Description The data field description. This is quite obvious. What may not be obvious is that it is actually two fields. It is possible to use the first field for the field decsription (up to 55 characters) and the second field (the line below the first) to describe a report heading for the field. The report heading specification can be especially useful in dynamic report generation. * Data Field Database Assignments Data fields may be assigned to zero, one, or more databases. The data fields may be assigned to a maximum of 36 databases using this feature. If more than 36 database assignments are necessary, the Data Field Membership Maintenance feature must be used. If the database assigned does not exist, a prompt will appear asking whether the non-existent database should be added. If the missing database isn't added, an error message will indicate an illegal database assignment. If a request is made to add the missing database, the database add procedure will be invoked. If a data field is assigned to a database that is in delete status, the database will be transparently undeleted and the data field will be assigned. * Searching Data fields may be searched on several different fields. These search fields may be specified individually or in combination. If they are specified in combination, the selection method requires that all selection criteria be satisfied to produce a match. For more information on searching, please refer to page 23. * Exiting Active records may be set to delete status and delete status records may be activated using the "Delete Toggle" command. If records are set to delete status during a maintenance session, all delete status records will be removed upon exiting the data field maintenance. Page 27 Dictionary Maintenance ---------------------- Database Descriptions --------------------- * Maintenance 1. Database Name A legal 8-character DOS file name with the additional restriction that the file name may not contain any asterisks, question marks, or embedded blanks. If an existing database name is changed, the necessary changes to the dictionary will be automatically changed (ie., database data field assignments and index file specifications). Also, if there is a corresponding database on disk, a prompt will be issued to determine if the database on disk should be renamed. If the database is locked, a message will so indicate. Repeated attempts may be made to access the locked database or the disk file rename operation may be abandoned. 2. Database Title The database title will be used for report titles and as part of the menu option description for all database point and select menus (See Menu Types). 3. Last Structure Update The last structure update refers to the date the DataBase Stru- ture Manager last generated the database structure. This date will automatically be entered each time the associated database structure is generated. The date may also be entered manually. 4. Extended Comments Use the text processor to enter extended database comments. The database extended comments may be reported individually by using the documentation menu. The extended comments may also be written directly to an ASCII text file or printed while inside the text processor. The text processor output functions are only available prior to making any changes in the edit session. If changes are made and printing or writing to a file is desired, you must first exit the edit session and then re-enter the extended comments text processor. On writing extended comments out to ASCII disk files, all soft carriage returns are replaced with hard carriage returns. 5. Import Database Structure Report Whenever database structure information is imported into the DBSM using the Structure Import Utility, the option of retaining a copy of the structure import report with the database description is available. The copy is assigned to a memo text field and may not be changed (although it may be deleted). The import report copy will provide a static view of the database structure for future reference. The maintenance of the above fields is not a complete full-screen edit routine. Once the maintenance has progressed into the Extended Comments, the fields above it may not be re-edited. The same restriction also applies to the Import Report viewing. Page 28 Dictionary Maintenance ---------------------- Database Descriptions (Cont'd) ------------------------------ * Deletions The database description deletion process will be initiated upon exiting the database description maintenance if there have been any database descriptions set and left in delete status. The database decriptions deletion process is governed by the "Automatic dictionary updates" designation in the Configuration Settings (See Utility Menu). If automatic dictionary updates have not been specified, the following prompts will appear: Remove the deleted databases from database descriptions? Remove the data fields unique to the deleted databases? Remove the deleted database's index file specifications? No dictionary information related to the deleted database description will be deleted unless an affirmative response is entered for the associated removal prompt. If the automatic dictionary updates have been designated, no prompts will be issued before invoking the deletion process. The database descriptions and dictionary information related to the database descriptions will be removed (ie. data fields unique to the deleted databases, the associated data field database assignments, and index file specifications). Please note that if delete status databases are specified to be removed, all delete status databases will be removed regardless of whether they were set to delete status in the current maintenance session. In no case will any database on disk be deleted by setting database descriptions to delete status. * View Database Structure The dictionary database structure for the current database description may be viewed using this option. * Corresponding Disk Database Information If there is a database on disk in the current directory with a name that corresponds to the current database description, an attempt will be made to access the database file to obtain summary information. If the database file is not locked, the summary information will be displayed here. If the database file is locked, a message will appear indicating the lock. If the database is found to be corrupted, a message indicating a corrupted database will be displayed. Please refer to pages 6 and 14 for information concerning corrupt databases. Page 29 Dictionary Maintenance ---------------------- Database Data Field Memberships ------------------------------- The central purpose for the Database Data Field Memberships Maintenance feature is to provide a method for assigning a data field to a database. The Database Data Field Memberships Maintenance is not normally required. Under most conditions, this function may be accomplished more conveniently in the Data Field Maintenance. However, the maximum number of database assignments in the Data Field maintenance is 36. If more database assignments need to be made than the Data Field Maintenance feature allows, this procedure will provide the ability to make the database assignments. * Adds To assign a data field to a database, enter the name of the database and the name of the data field. Both the database and the data field must be defined in the dictionary before a data field may be assigned to a database. * Edits Data field assignments may be changed by either modifying the data field name, the database name, or both. The only requirement is that the assignment may not duplicate an existing data field assignment to the same database. That is, a data field cannot be assigned twice to the same database. Also, any data fields or databases entered must already be defined in the database dictionary. Changing a data field name during the edit process is the equivalent of deleting a data field assignment and adding a new data field assignment. * Deletions Data field assignments may be deleted by setting the delete toggle for non-delete status data field assignments. The delete status data field assignments are not physically removed until the command to exit the Database Data Field Membership Maintenance is selected. Until that time, delete status assignments may be reinstated to active status by selecting the delete toggle. Page 30 Dictionary Maintenance ---------------------- Index File Specifications ------------------------- Index file specifications may be used to generate Clipper-compatible index files and may be reported in the documentation. * General Index Specifications Maintenance All index file names must be unique. Index key expressions are only edited for length. The length of the key expression must comply with the specifications associated with the database system type designated in the Configuration Settings. The index key expressions are not edited to ensure the proper syntax and data fields are used until DBSM is called upon to generate a new index using the index key expression. If an invalid index key expression is used by DBSM to generate a new index file, the DBSM program will terminate and display an error message on the top line of the display screen. The error message will begin with the following: Proc INTINDEX line 0, The remaining portion of the error message will be determined by the type of incorrect key expression. * Adds When adding index file specifications, if the associated database file name is left blank, a point and select database menu will be displayed. (Please refer to the Menu Types: Database Selection Menus documentation for information on point and select database menus.) Once the proper database file has been entered, the database field names assigned to the database will be listed below the key expression data entry field. The number of data fields assigned to the database may exceed the capacity of the screen area allocated to display the database's data fields. The entire database structure may be displayed using the <Alt-V> command. * Edits The edit procedure is very similar to the add procedure except that no database point and select menu is provided for selecting a database name. * Deletions Index file specifications may be deleted by setting the delete toggle for non-delete status index file specifications. The delete status index file specifications are not physically removed until the command to exit the Index File Maintenance is selected. Until that time, the delete status specifications may be reinstated to active status by selecting the delete toggle. Page 31 Dictionary Maintenance ---------------------- System Description ------------------ This is a standard memo text field where general system comments may be entered. The text entered here may be reported using the Documentation Menu. The system description text may be printed or written out to an ASCII file. These two output features may only be executed prior to making any changes in the current edit session. Please refer to Memo Field Edit Commands documentation under General Dictionary Maintenance for a more complete description of the memo edit commands. Page 32 Application Database Operations ------------------------------- Application database operations test the databases for corrupt header information before attempting to use them. If a database is found to be corrupt, the requested operation will be not be performed. Please see pages 6 and 14 for more information about corrupt databases. Index File Creation ------------------- Clipper-compatible index files may be generated according to the index file specifications. The database's index files are selected using the point and select database menu. (Please refer to the Menu Types: Database Selection Menus documentation for information.) All database files are listed in the point and select database menu whether the database has any associated database index file specifications or not. Once a database file has been selected, all associated index files are generated for the database. The index file specifications are not validated prior to generating the index files. If incorrect index key expressions are used to generate index files, it will cause the DBSM program to terminate and display an error message on the top line of the display screen. If the database indicated for an indexing operation has been locked by another program, a message and prompt will be displayed on the top line of the screen. Repeated attempts may be made to access the locked database. The index request will not be accomplished if the database cannot be accessed. Database Structure Variance Report ---------------------------------- Differences between dictionary database specifications and the corresponding databases on disk are highlighted using the structure variance report. The report information is determined by comparing the dictionary database specification with the corresponding database structure specification on disk. If the corresponding database on disk is locked by another program, a message and prompt will be displayed on the top line of the screen. The three options available are to retry gaining access, waiting up to two minutes for the file to become free, or to exit the request for the locked file. If the locked file is not accessible, the report will be produced without the disk database information. The structure variance information is especially useful to know before generating a new database structure for an existing database. For instance, if a character data field's length has been reduced in the dictionary specification and a new database structure is generated using the specification, it is possible to lose truncated character data that no longer fits in the character field's reduced length. Page 33 Application Database Operations ------------------------------- Database Structure Variance Report (Cont'd) ------------------------------------------- The structure variance report will list the structure of the corresponding database in the current subdirectory on disk on the left side of the report. If there is no corresponding database found, a message will be displayed instead of the corresponding structure. The database dictionary specification will be listed on the right side of the report. All data fields are listed in alphabetical order. Where there is a corresponding database structure, the data fields with similar data field names are aligned on the same line with each other. The middle column of the report is used to indicate similarities and differences. If the matching data field names have data type, length and decimals that are exactly equal, a double equals sign ("==") will be placed in the middle column of the report. If the matching data field names differ in definition by type, length, or decimals, an inequality symbol ("<>") is reported in the center column. Structure variance comments will appear in the far-right column of the report when there is a difference in the data field names being maintained. The variance comments are provided from the perspective of the database dictionary being the most up-to-date information. For instance, if there is a data field defined for the database in the dictionary, but the data field does not exist in the corresponding database on disk, the structure variance comment is that the data field has been "ADDED." The database structure information for each database is summarized at the end of the report. If there were any differences between the two databases, an inequality symbol is reported in the center column on the summary line. If there were no differences, the double equals characters are reported in the center column. It is possible to exceed the system's available memory when generating structure variance reports for databases with many data fields. If this error occurs, more system memory will need to be allocated for the DBSM program. Please refer to the documentation section on Memory Allocation and Use to control memory allocation. If there are any RAM-resident routines loaded, they may need to be purged to free-up the necessary system memory. Page 34 Application Database Operations ------------------------------- Database Structure Generation ----------------------------- * Database Specification Validation Before a database structure is generated, the database structure specification is checked in 3 areas to ensure it conforms to the type of database designated in the Configuration Settings. If the database exceeds the maximum number of data fields or the maximum database record length requirement, or if an undefined data field type is found, an appropriate message will be issued and the database will not be generated. Please note that this validation process will allow data fields with specifications different from those associated with the database type in the Configuration Setting to be generated. Data field specifications are only validated during data field maintenance. * Data Field Order The order of the data fields in the new database structure is determined by the ASCII sort order of the catenated sequence code and data field name as specified in the Data Field definition. For instance - if the following data fields are being processed: Sequence Data Field Code Name --------- ---------- z Address d CustName d CustId The data fields would be generated in the database in the following order: Data Field Name ---------- CustId CustName Address * New Database Structure Validation Once a new database structure has been generated, it will be immediately tested to verify the record length and number of fields is equal to the dictionary specification's record length and number of fields. It will also be tested to see if it is corrupt as evidenced by an illegal record length or illegal number of fields. If it does not match the specification, an appropriate message will be issued and the original database will be restored. Possible reasons for incorrect database structure generation include insufficient system memory or insufficient disk space. Page 35 Application Database Operations ------------------------------- Database Structure Generation (Cont'd) -------------------------------------- * Appending Data from a Corresponding Database on Disk If there is a database on disk in the current directory with a name that corresponds to the database being generated, data from the corresponding database on disk (herein referred to as the "original database") will be appended to the new database structure once it has been generated. Only those data fields whose field name and type match across both databases will have information transferred. Delete status records in the original database may be designated to have their records included. If the delete status records are included, the record will remain in delete status in the new database. Where there is an original database for the database structure generation, the original database will be renamed to "-SAV_DBF.DBF" at the start of the process. If there is an associated memo database, it will be renamed to "-SAV_DBF.DBT". The database structure generation procedure tests for the existence of these temporary file names before beginning the regeneration of a database structure. The procedure will not regenerate a new database structure if it detects a file in the current directory with a temporary save name (ie., "-SAV_DBF.DBF" or "-SAV_DBF.DBT"). The existence of either of these temporary files signifies the possibility that a previous structure regeneration process was prematurely terminated. If that is the case, the temporary files may contain the "best" original copy of the database before the structure regeneration process. If you are changing field names within a database structure and you want the current values transferred, you should leave the original data field name and add the new data field name when you generate the new structure. Once the structure generation is complete, place the data from the original data field into the new data field for each record in the database and verify that the placement worked correctly. When the operation is successful, delete the old data field definition from the dictionary and then generate a new structure. The DBSM also verifies numeric value transfers from corresponding databases. Numeric data field values that correspond in field name and field type, but do not have the same numeric field length and/or decimals length may need to be altered to fit the new data field definition. You may designate in the Configuration Settings that automatic numeric value changes may be supplied. In this case, if the original data field value does not "fit" into the new definition, the highest or lowest possible value (whichever is closest) will be placed in the field. If automatic value changes are not allowed by the Configuration Settings and any incompatible numeric value is encountered in the data transfer, an appropriate message will be displayed and the structure generation process is terminated with the appropriate rollback to restore the original files. Page 36 Application Database Operations ------------------------------- Database Structure Generation (Cont'd) -------------------------------------- * Appending Data from a Corresponding Database on Disk (Cont'd) The numeric data field value validation process requires extra processing time. The amount of processing time required is directly related to the number of fields in the new database. A database with many records and many fields per record will take a significant amount of time to accomplish the transfer of information. The progress will be detailed on the screen. If the new database specification doesn't have any data fields in common with the original database, the appending of information from the original database will result in the creation blank records. * Application Database Memo File Deletion If a new structure is generated without a memo field specification, but there used to be a memo field in the original database, DBSM will delete the old memo database after successfully generating a new database. * Memory Requirements If DBSM runs out of memory during the structure generation, a message will be displayed at the top-left corner of the screen with a continuation prompt. The message will appear as follows: "proc MAKESTRC, out of memory Continue?" OR "proc APPENDIT, out of memory Continue?" There is no way to continue the structure generation. Respond with an "N" and press return. The program will terminate after responding to the prompt. If this occurs during a database structure regeneration where there is an existing database on disk, some manual file maintenance to restore the original database files may be required. A brief description of the structure generation process is in order. Before a database is regenerated, the corresponding database on disk and if necessary, the associated memo database will be renamed to "-SAV_DBF.DBF" and "-SAV_DBF.DBT" respectively. Once the new database structure has been generated with the true database name, there is an operation to transfer the corresponding information from the original database to the new. If the new database(s) are created, but the original data has not been completely transferred when the error occurs, a directory of database files should show the new database(s) under the true name and the original database under the save name(s). Page 37 Application Database Operations ------------------------------- Database Structure Generation (Cont'd) -------------------------------------- * Memory Requirements (Cont'd) To restore the original file name(s) in the case where both the saved databases and the newly created databases exist, first delete the newly created database(s). Once the delete has been accomplished (or if the new databases were never created), rename the saved databases back to their original names. For example, suppose you are in the process of regenerating a vendor master database, "VENDMAST.DBF", which also has an associated memo file named "VENDMAST.DBT". Let's assume the regeneration procedure renamed the vendor master databases to "-SAV_DBF.DBF" and "-SAV_DBF.DBT", respectively, and has created the new database structures under the true database names. Now the system runs out of memory. After responding "N" to the insufficient memory message prompt, run a directory of your database files (ie., "DIR *.DB?"). A portion of the directory should show the saved files and another portion should show the newly created database structures under the original names. The next step is to delete the newly created database files with the following two DOS commands: DEL VENDMAST.DBF DEL VENDMAST.DBT The next step is to rename the saved databases back to their original names. This is accomplished with the following two DOS commands: REN -SAV_DBF.DBF VENDMAST.DBF REN -SAV_DBF.DBT VENDMAST.DBT To solve the problem of insufficient memory, more system memory must be allocated or system memory requirements must be reduced. In some instances, more system memory may be allocated by changing the runtime setting (See Runtime Environment Settings). It may be necessary to free up more system memory by eliminating some RAM- resident programs. System memory requirements may be reduced by changing the structure specification or eliminating the need to transfer original information to the new database structure. Page 38 Application Database Operations ------------------------------- Database Structure Generation (Cont'd) -------------------------------------- * Disk Space Requirements If insufficient disk space is determined, an appropriate message will be displayed and the structure generation process will be gracefully exited. A conservative approach is used when determining whether sufficient disk space is available to generate a new structure. The disk file cluster size is assumed to be 4,096 bytes. If a database with an existing structure on disk is going to be regenerated, it is assumed the new database will require the same amount of space. The associated memo database is included in the calculation if one exists. There must also be an additional 8,192 bytes available for two temporary files. For example, if the existing database on disk is 2,000 bytes. The amount of free disk space must be at least 12,288 bytes. This breaks down as follows: 8,192 bytes for two temporary files and a 4,096 byte cluster to hold the assumed 2,000 byte new database file. * Network File Locks If the database identified for structure generation has a corresponding database on disk, an attempt will be made to gain exclusive access to the database with a file lock. If the corresponding database file cannot be locked, a message will be displayed noting the situation. The structure generation operation will automatically be abandoned after the prompt is acknowledged. For further information regarding the file-locking technique and compatibility, please refer to the "Network File Control" documentation section. * Corrupt Databases If the database identified for structure generation has a corresponding database on disk and the database is determined to be corrupt, the structure generation will not proceed. The corrupt database must either be fixed, deleted, or renamed before another structure can be generated for the database structure defined in the dictionary. Please refer to pages 6 and 14 for information regarding the interpretation of corrupt databases. Page 39 System Documentation -------------------- All documentation reports may be either displayed or printed. Whenever the print option is selected, a reminder will be issued to ensure the printer is ready to print. In most instances, if the print option is indicated, a prompt will be issued to determine if near-letter quality printing is desired. A prompt will not be issued if the active printer is a laser printer or if the Custom Printer is the active printer and no print control codes have been defined for the custom printer. If you want to eliminate the prompt to determine near-letter quality printing, you may set the active printer to be the Custom Printer and then ensure that no print control codes are defined for the Custom Printer. With this setting, no matter what printer is receiving the report, no prompt will be issued. A reminder will still be issued to ensure the printer is ready. General Documentation --------------------- * Documentation Title Page The documentation title page provides the cover page for the documentation reports. It includes the company name and the database system name centered on the page. The DataBase Structure Manager copyright notice is provided in the lower-left corner of the page. * System Description The System Description report includes all text entered using the System Description option from the Dictionary Maintenance menu. The output from this option is restricted to screen or printer. However, the information may be transferred to an ASCII file using one of the System Description maintenance features. * Database Summary Report The Database Summary report lists all database file names defined in the database dictionary. In addition to the database file name, the report always includes the database description and date of last structure update by the DBMS system. If there is no corresponding database in the current directory, it will be noted in the report. If there is a corresponding valid database file in the current directory, the date of the last update of any kind (data or structure), and the total number of records will be be listed. If a corresponding database is in the current directory, but the database is determined to be invalid, a message noting the corrupt database will be provided instead of reporting the database information. Please refer to pages 6 and 14 for information concerning corrupt databases. Page 40 System Documentation -------------------- General Documentation (Cont'd) ------------------------------ * Database Extended Comments The Database Extended Comments report lists the Extended Comments entered in the Database Descriptions maintenance. The report is restricted to screen or printer output, however the Extended Comments may be written to an ASCII file using one of the Extended Comments maintenance features. When selecting the Database Extended Comments option from the System Documentation menu, a point and select database menu is provided. The menu consists of all database names and database descriptions and allows databases to be selected individually or as an entire group. For more detailed information regarding the point and select database menu, please read the Database Selection Menus documentation (See Menu Types). * Index File Specifications The index file specifications are reported in alphabetical order by database file name. All index file specifications for each database are presented in alphabetical order by index file name. The detail format for each database includes a line to identify the database. This line includes both the database file name and the database description. Each index file specification is listed on the lines following. The first line for any index specifica- tion includes the index file name, the first 50 characters of the index key expression, and an indication as to whether the index key is unique. The index key expression will be continued on subequent lines if necessary. If the index key expression exceeds the maximum length allowed according to the database type specified in the Configuration Settings, an appropriate error message will also be listed. Page 41 System Documentation -------------------- Data Field Documentation ------------------------ * Database Each database documentation report lists the data fields alpha- betically by data field name within sequence code. That is, the sequence code is the major sort field and the data field name is the minor sort field. For the abbreviated format, the following information is listed with each data field: field name, type, length, decimals, description, and sequence code. The complete format includes all of the information entered in the data field maintenance. When selecting the database data field documentation option (either the abbreviated or complete format) from the System Documentation menu, a point and select database menu is provided. The database menu consists of all database names and descriptions and allows databases to be selected individually or as an entire group. For more detailed information regarding the point and select database menu, please read the Database Selection Menus documentation (See Menu Types). * System The system data field documentation (either abbreviated or complete format) includes all data fields from every database in the dictionary. The data fields are listed alphabetically by data field name. For the abbreviated format, the following information is listed with each data field: field name, type, length, decimals, description, and sequence code. The complete format includes all of the information entered in the data field maintenance. Both report formats cross reference each data field to the database(s) it has been assigned to. Page 42 Utilities --------- Printer Menu ------------ * Printer Selection Printer type selections are provided to allow the proper near-letter quality print control commands to be sent to the printer before a report is printed and to reset the printer after the report is printed. A printer type may be specified by using the appropriate command line call parameter. The Configuration Settings option of the Utility Menu will allow a default printer type to be specified. If no printer type is specified in the command line, the printer specified in the Configuration Settings will be selected. The current printer type may be changed at any time by using the Printer Selection option of the Printer Menu. If there is no printer type to match your specific printer, you may be able to select a printer type that your printer will emulate. If this is not possible or convenient, the Custom Printer type may be selected. Once the Custom Printer type is active, the printer control codes defined under the Custom Printer Definition option of the Printer Menu become effective. * Custom Printer Control Character Specifications Custom printer control codes (up to 10 characters in length) may be defined. These codes are used to set and reset the printer for near-letter quality printing whenever a near-letter quality report is requested and the Custom Printer type has been selected. Each character of the print control command must be entered as a 3-digit number with leading zeroes. The 3-digit number is the decimal value of the ASCII character. One space is automatically maintained between numbers during the data entry process. A maximum of 10 ASCII characters may be represented in this manner. To delete control characters, the delete or backspace key must be used; using the space bar will not delete characters. * Printer Port Selection Printer port selections change the active output device. Reports may be directed to one of three parallel ports (LPT1, LPT2, or LPT3) or to one of two serial ports (COM1 or COM2). Page 43 Utilities --------- Index All DataBase Structure Manager Files ------------------------------------------ This option may be run at any time to ensure the integrity of the DBSM system index files. Configuration Settings ---------------------- * Company Name The company name is used for screen display headings and documentation reports. * Database System Name The database system name is used for screen display headings and documentation reports. * Default Screen Type The Default Screen Type is used to control the display screen type if no valid display screen type was specified on the DBSM execution command line. If no valid screen type is specified on the DBSM execution command line and the Default Screen Type has not been specified, the screen type will be #1 for color monitors and #5 for monochrome monitors. The monitor type (color or monochrome) is automatically detected by examining the system for the presence of a color card. This automatic detection can be "fooled" if there is a color card on the system, but the primary display device is a monochrome monitor. * Default Printer Definition The sole purpose of selecting printers is to allow the system to send printer control codes to switch the printer into near-letter print mode when requested by the user and to reset the printer at the end of the report. The Default Printer Definition is used to provide a printer definition when no valid printer definition was specified on the DBSM execution command line. If no valid printer definition is specified on the DBSM execution command line and the Default Printer Definition has not been specified, the system will "force" a printer selection before directing output to the printer. If the Custom Printer is specified, the near-letter quality printer control code sequence (defined in the custom printer definition section of the Printer Menu) will be sent to the printer when near-letter quality printing is indicated. Page 44 Utilities --------- Configuration Settings (Cont'd) ------------------------------- * Default Printer Port Valid printer ports are: LPT1 through LPT3, COM1, and COM2. If no setting is indicated, the default is LPT1. This option allows a Default Printer Port to be specified. The Default Printer Port specification is mandatory. It will be the active printer port at startup. The active printer port may be changed at any time by using the Printer Port Selection option of the Printer Menu. * Automatic Dictionary Updates This configuration setting controls whether a manual affirmation is required when deleting database descriptions. Normally in the database description deletion procedure, all dictionary information related to the delete status databases should be deleted. This includes the data fields unique to the delete status databases, related index file specifications, and the database descriptions themselves. However, if automatic dictionary updates are denied through the use of this setting, these dictionary elements must be individually specified to be deleted. Please refer to the Database Descriptions - Deletions for more information. * Automatic Numeric Value Adjustments Automatic numeric value adjustments may be designated to automatically adjust numeric values when a database structure is being generated and corresponding data field values from an existing database on disk are being transferred. If there is a database on disk in the current directory with a name that corresponds to the database being generated, data from the corresponding database on disk will be appended to the new database structure once it has been generated. Only those fields whose field name and field type match across both databases will have information transferred. Values for numeric data fields that correspond in field name and field type, but do not have the same numeric field length and/or decimals length may need to be altered to fit a new numeric data field definition. You may designate in the Configuration Settings that automatic numeric value changes may be supplied. In this case, if the original data field value does not "fit" into the new definition, the highest or lowest possible value (whichever is closest) will be placed in the field. If automatic value changes are not allowed by this setting and an incompatible numeric value is encountered in the data transfer, an appropriate message will be displayed and the new structure generation process is terminated with the appropriate rollback to restore the original files. Page 45 Utilities --------- Configuration Settings (Cont'd) ------------------------------- * Include DataBase Structure Manager's Database Files The Structure Import Utility has a database directory feature and a feature to import all databases in the current directory. If this DBSM database inclusion setting is set to include DBSM files, the DBSM files will be included in the Structure Import Utility feature operations. Otherwise, DBSM databases will be ignored. Normally, there is no need to include DBSM databases in the database import operation (unless the DBSM databases are being maintained and documented by DBSM). * Index DataBase Structure Manager Files at Startup As a precautionary measure, all DBSM system index files may be indexed each time DBSM is executed. This is not normally necessary, however if the DBSM dictionary databases are being maintained outside of the DBSM program, it may be necessary and convenient to use this option to ensure valid system index files. * Database System Types The Database System Type designation is used to validate the database, data field, and index file specifications. The data field specifications will be checked during the data field maintenance. The database record length and number of fields will only be checked before attempting to generate a database structure. Data field types are also checked for validity before generating a database structure. The index file specification length will be checked during index file maintenance. 1. dBASE III PLUS/FoxBase The dBASE III PLUS database specifications will be applied when validation procedures are performed to ensure correct database, data field, and index file specifications. The FoxBase specification is considered equivalent to the dBASE III PLUS specification. 2. Clipper - Summer '87 The Clipper (Summer '87 version) database specifications will be applied when validation procedures are performed to ensure correct database, data field, and index file specifications. Page 46 Utilities --------- Configuration Settings (Cont'd) ------------------------------- * Database System Types (Cont'd) 3. Custom Database Specifications The custom database specification allows more flexible control over the database specifications. With this selection, the following database criteria must be specified: maximum record length, maximum number of database fields, maximum character field length, maximum numeric field length, maximum number of decimals, and the maximum length for an index file specification. The Custom Database specifications will be applied when validation procedures are performed to ensure correct database, data field, and index file specifications. Data field specifications will be applied during Data Field Maintenance, general database specifications (record length, number of database fields, and data types) will be applied during database generation. When the custom database maximum specifications are set, the DBSM gives you free rein to enter database specifications based on the custom specifications. However, when it comes to generating databases, no database may be generated that exceeds the following maximum specifications: Database record length......: 32,766 Number of database fields...: 1,024 Character field length......: 32,766 Numeric field length........: 20 Decimals field length.......: 18 Index key expression length.: 250 The amount of available system memory may be exceeded prior to reaching any of these maximum specifications. The database record length values reported by this system are calculated by summing the length of all data fields in the database. The 1-byte position in databases for the delete status is not included in the record length. A custom database type must be defined in Configuration Settings to allow numeric data fields to be the maximum allowable for dBASE IV databases. * Universal Database Filename Suffix The database filename suffix is used to allow database filename suffixes other than the standard "DBF". All operations involving databases on disk will make use of this specification. This includes, but is not limited to, operations of database structure generation, database structure variance reporting, database memo file compression, database directory displays, and importing database structure information into the DataBase Structure Manager. Page 47 Utilities --------- Configuration Settings (Cont'd) ------------------------------- * Column Heading/Detail Divider Line The character used in the line that separates the column heading(s) from the column's detail information may be designated by supplying the ASCII decimal value of the character. The character's ASCII decimal value must be in the range of 33 through 254, inclusive. The currently selected characters are displayed just to the right of the ASCII code decimal value. The Screen Heading/Detail Divider character is used for reports directed only to the screen. The Printer Heading/Detail Divider character is used for any reports when the printer output option is requested. Screen Display Settings ----------------------- The current screen display setting may be changed to any one of 4 different color schemes (if the DBSM detects a color card) or to monochrome. If no color card is detected, this option simply reports that a monochrome monitor has been detected and no further settings are available. Show Structure of Database on Disk ---------------------------------- Any database files in the current directory may be specified to report their structure information. The report may be directed to the display screen or the printer. Compress Database's Memo File ----------------------------- Some database systems (Clipper - Summer '87 included) do not always reclaim memo field space that has been used and then deleted. Over time, it is possible to accumulate a significant amount of wasted space in the memo database. This feature will eliminate the "dead" space by re-creating the database and appending the data from the original files. Databases determined to be corrupt will not be compressed. See pages 6 and 14 for the definition of a corrupt database. When using the memo compress feature, it is possible to run out of system memory. If this happens, find your original database files under the saved names of "-TMP_1.DBF" and "-TMP_1.DBT" and rename them to their original names. Before doing the rename, first determine whether the new database files with the original names have been created. If this has already been done, then you should delete them and then rename the saved files back to their original names. Page 48 Usage Hints ----------- Pseudo-Database Definitions --------------------------- Databases may be defined that will never be used as application databases. Instead, the database serves to consolidate a specific set of data fields. For instance, if you want to document all the key data fields, you can define a database called KEYFLDS and assign all the key data fields to it. Program memory variable documentation may be maintained and reported by defining the memory variables as data fields in a special database. Data Field Headings ------------------- The data field description is maintained in two data fields in the data field dictionary. You may find it convenient to use one of the description data fields for maintaining a data field report heading. The data field report heading could be used in dynamically generating reports. Dynamic Structure Variance Information -------------------------------------- The ability to read the system dictionary files that are in Dbase format allows the application programmer to determine if the actual application database structures on disk are defined the same as the application database definitions in the DBSM database dictionary. If an application database is defined differently from the dictionary definition, special actions in the database application may need to be performed. For instance, if a dynamic report generation application notices a difference in the actual database structure and the dictionary definition, it may be appropriate to alert the user that the database specification has been redesigned. Application Program References to DBSM System Files --------------------------------------------------- Database applications programmers may develop semi-standard validation code in their applications that reference the DBSM data field definitions. For instance, the application's validation code could reference the corresponding data field in the DBSM data field dictionary. If there is a low-range value specified, the data entered may be checked to maintain the range specification. The technique listed above will probably not provide the fastest possible data entry validation, but when the technique is used properly, there is the ability to make changes to the validation criteria without having to change the program source code and recompile the program(s). In some cases, this may be a primary concern. In fact, you may find it desirable to design procedures in your application system to control the maintenance of the dictionary data field validation criteria. Page 49 Program Error Reporting Procedures ---------------------------------- Progressive Data Systems gratefully accepts any suspected program error (ie., bug) reports from any users. Program error reports will be accepted in verbal or written form, although a written copy is preferred. Please include as much detail as possible in describing the program error to allow the program error to be validated. Progressive Data Systems will respond to written program error reports from registered users when the user provides a self-addressed, stamped envelope. The following information should be included along with a detailed description of the suspected program error: 1. DBSM license registration number (If a registered user.). 2. DBSM version. 3. DOS version. 4. CONFIG.SYS and AUTOEXEC.BAT file contents. 5. Available system memory before executing the DBSM program as reported by the DOS CHKDSK command. Registered users will be advised of any significantly serious program errors and will be entitled to one free maintenance release of the DataBase Structure Manager if it should become necessary. A main- tenance release may be issued at the sole discretion of Progressive Data Systems if there is an excessive accumulation of program errors or if there is a sufficiently serious progam error. (Please take note that a discretionary maintenance release is not the same as a revision to upgrade the program.) Registered users will be notified when a new release to upgrade the program is available and the upgrade policy. Page 50 Appendix A Full-Screen Edit Command Summary Full-Screen Edit Movement Keys ---------------------------------------- ------------------------------- Move up one line........................ UpArrow or <Ctrl-E> Move down one line...................... DownArrow, <Ctrl-X>,Return, <Ctrl-M> Move to the left one character.......... LeftArrow or <Ctrl-S> Move to the right one character......... RightArrow or <Ctrl-D> Move left to the next word.............. <Ctrl-LeftArrow> or <Ctrl-A> Move right to the next word............. <Ctrl-RightArrow> or <Ctrl-F> Beginning of edit field................. Home End of edit field....................... End Beginning of first edit field........... <Ctrl-Home> Beginning of last edit field............ <Ctrl-End> Full-Screen Edit Actions Keys ---------------------------------------- ------------------------------ Delete character at cursor position..... Del, <Ctrl-G> Destructive backspace................... Backspace, <Ctrl-H> Delete word right....................... <Ctrl-T> Delete from cursor to end of edit field. <Ctrl-Y> Reset edit field to original value...... <Ctrl-U> Full-Screen Edit Modes Keys ---------------------------------------- ------------------------------ Toggle insert/overwrite mode............ Ins, <Ctrl-V> Full-Screen Escape Actions Keys ---------------------------------------- ------------------------------ Terminate current edit field............ Return, <Ctrl-M> Terminate edit & save current edit field PgUp, PgDn, <Ctrl-W>, <Ctrl-C> Terminate edit w/o saving current field. Esc The escape key can be used at any time to cancel an add or an update. Page 51 Appendix B Memo Text Edit Command Summary Screen/Cursor Movement Key ---------------------------------- ------------------------------- Move up one line.................. UpArrow or <Ctrl-E> Move down one line................ DownArrow or <Ctrl-X> Move to the left one character.... LeftArrow or <Ctrl-S> Move to the right one character... RightArrow or <Ctrl-D> Move left to the next word........ <Ctrl-LeftArrow> or <Ctrl-A> Move right to the next word....... <Ctrl-RightArrow> or <Ctrl-F> Beginning of current line......... Home End of current line............... End Beginning of current screen....... <Ctrl-Home> End of current screen............. <Ctrl-End> Previous screen................... PageUp Next screen....................... PageDown Beginning of memorandum........... <Ctrl-PageUp> End of memorandum................. <Ctrl-PageDown> Toggle insert/overwrite mode...... Ins, <Ctrl-V> Destructive backspace............. Backspace, <Ctrl-H> Edit Functions Key ---------------------------------- -------- Delete the current line........... <Ctrl-Y> Delete word right................. <Ctrl-T> Reformat text in edit screen...... <Ctrl-B> Output Functions Key ---------------------------------- -------- Print the memo text............... <Alt-P> Write the memo text to a disk file <Alt-W> The Print and Write options may only be executed prior to making changes to the memo text. Page 52 Appendix C Enhancement Suggestions ----------------------- Progressive Data Systems is interested in your comments and suggestions regarding the performance of the DataBase Structure Manager system. The areas where you feel the DBSM system should be improved, based on your own specific requirements, is of particlar interest. The feedback we receive from you will help us to determine how to most effectively improve the system to meet your needs. There are many different directions the improvements to this system can take. The emphasis could be on building dynamic reporting and editing based on the dictionary specifications or the improvements could focus on increasing the types of dictionary information being maintained. One improvement that will almost certainly be provided is the ability to do full-screen editing of multiple data fields all belonging to one specific database. Each data field would be given one line on the screen with scrolling as necessary. Any change to a data field specification would automatically be changed for all databases the data field belongs to. This facility would most likely first appear as an independent utility. Do you have other ideas about how this system could be improved? How important is a multi-user capability to you? Please drop us a line and let us know where you think the focus of our development efforts should be. Appendix D Page 53 Order Form Ship To: Name...: ________________________________________________ Company: ________________________________________________ Address: ________________________________________________ ________________________________________________ City...: _______________________ State: ___ Zip: _______ Country: ________________________________________________ Phone Number..: (_____) _______________ Disk Unit Qty Description Medium Price Extension --- ---------------------------------------------- ------ ------ --------- ___ DataBase Structure Manager System (Current 5.25" $45.00 $ _______ version). Includes programs and documentation 360K files on disk and license registration. ___ DataBase Structure Manager System (Current 3.5" $48.00 $ _______ version). Includes programs and documentation 720K files on disk and license registration. ___ DataBase Structure Manager System (Current 5.25" $10.00 $ _______ version). Includes programs and documentation 360K files on disk. Registration not included. ___ DataBase Structure Manager System (Current 3.5" $13.00 $ _______ version). Includes programs and documentation 720K files on disk. Registration not included. ___ DataBase Structure Manager System - Registration only. $35.00 $ _______ ___ Printed, bound documentation manual. $12.00 $ _______ Subtotal $ _______ Wisconsin residents add 5% sales tax $ _______ Total $ _______ Remit to: Progressive Data Systems P.O. Box 631 Middleton, WI 53562 Phone (608) 836-5075 Please pay by check or money order in U.S. currency only. We cannot accept credit cards or COD orders. Please add $8.00 for orders outside the U.S.A. Registration includes technical support for one year. Your comments or suggestions are gratefully received and appreciated. Page 54 Index ----- Subject Subject ------------------------------------- ------------------------------------ Appending Data 12,35 Database (Cont'd) Application Database File Location 16 File Name Suffix 46 Application Database Operations 32-34 File Name Syntax 13, 27 Create Index Files 32 Name 27 Report Structure Variance 32 Record Length 13, 45 Generate Database Structures 34 Selection Menus 20 Applications 3, 48 Specification Validation 34, 45 Assoc. of Shareware Professionals iv Structure Generation 34 Column Heading/Detail Divider Line 47 Structure Variance Report 32 Command Line Parameters 16 Structure Validation, New 34 Diskette Operation 17 Structure Viewing 28 Display Screen Type 16 System Application Subdirectory 16 Printer Type 17 System Name 43 Compress Database's Memo File 47 System Types 45 CONFIG.SYS 8 Title 27 Configuration Settings 19, 43-47 Database Extended Comments 40 Column Dividers 47 Database Summary Report 39 Company Name 43 Database System Description 39 Database File Name Suffix 46 DBSM Database File Recognition 45 Database System Type 45 DBSM Error Report Procedures 49 DBSM Database Inclusion 45 Decimals Field Length 25 DBSM File Indexing 45 Delete Toggle 23 Dictionary Updates 44 Deletions 23 Numeric Value Changes 44 Dictionary Maintenance 22 Printer Definition 43 Dictionary System Files 5 Printer Port 44 Dictionary Updates, automatic 44 Screen Type 43 Disk Space Requirements 38 System Name 43 Diskette Drive Operation 17, 18 Validation 19 Documentation 39 Corrupt Database 6, 14, 38 Data Fields 41 Cursor Movement 50, 51 General 39 Full-Screen Edit 50 Documentation Title Page 39 Memo Field Edit 51 DOS Command Execution 11, 21 Custom Database Specifications 46 Edit Command Summary 50, 51 Custom Printer 42 Enhancement Suggestions 52 Data Field Error Report Procedures 49 Database Assignments 13, 26 Exiting Maintenance 23 Maintenance 24-26 Expanded Memory for Index Buffers 10 Mandatory Specifications 24 Extended Comments 27, 40 Order 26, 34, 41 External Program Execution 11, 21 Required Data Entry 25 Features Summary 4 Specifications 13-14, 24-26 File-Locking 12 Database First-Time Operation 17 Corrupt 6, 14, 38 Full-Screen Edit Command Summary 50 Hard Drive Operation 17 Data Field Maximum 46 Hardware Requirements 8 Data Field Memberships 26 High Range Value 25 Descriptions 27 Import Database Structure Report 27 Documentation 40, 41 Extended Comments 27 Page 55 Index ----- Subject Subject ------------------------------------- ------------------------------------ Index Quitting 20 Buffers Allocation 9 Record-Locking 12 DBSM Files at Startup 45 Record Maintenance 22 File Creation 32 Registration Reminder 19 File Specifications 30, 45, 46 Relational Database Primer 1 Key Expression Length 45, 46 Runtime Environment Settings 8 Key Fields 45, 46 Screen Display Settings 16, 43, 47 Specifications Maintenance 30 Searching 23 INSTALL Batch File 15 Selection Flag 23 Installation 15 Sequence Code 26 Introduction 1 Shareware Distribution iii Last Structure Update 27 Shareware Professionals, Assoc iv Low Range Value 25 Snow Elimination 10 Main Menu 20 Software License ii Mandatory Specifications 24 Software Requirements 8 Maximum Database Specifications 13 Standard Sub-Menus 20 Memo File Deletion 36 Structure Maintenance Memo Text Fields Dictionary 22 Edit Commands 51 Data Fields 24 Printing 27, 51 Database Descriptions 27 Writing to Disk File 27, 51 Database Data Field Members 29 Memory Index File Specifications 30 Allocation and Use 8 System Description 31 Requirements 8, 36 Application Databases 32 Usage 8 Create Index Files 32 Insufficient 36, 47 Report Structure Variance 32 Memory Variable Allocation 9 Generate Database Structures 34 Memory Variable Documentation 48 Structure Report 41 Menu System 20, 22 Structure Variance Information 32 Menu Quick Traversal 20 System Configuration 8 Multi-Tasking 7 System Description 31 Multi-User 12 System Dictionary Files 5 Network File Control 12, 38 System Startup 16 Numeric Value Adjustments 35, 44 Table of Contents v Optional Data Field Documentation 25 Technical Specifications 13-14 Order Form 53 Technical Support iv Ownership Reminder 19 Trademark Acknowledgements i Picture Format 25 Urgent Information 5 PLINK86 Overlay Loader 18 Usage Hints 48 Print Memo Text 27, 51 Utilities 42 Printer Validate Procedure 25 Custom Definition 42 Warranty and Liability i Menu 42 Write Memo Text to Disk 27, 51 Port Selection 42 Selection 42 Pseudo-Database Definitions 48