Power-Programmierung

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

/ Power-Programmierung / CD1.mdf / xbase / tools / delite / dlite.doc < prev next >

Wrap

Text File | 1991-06-01 | 110KB | 2,831 lines

dLITE 2.0 User's Guide Copyright (c) Ward Mundy, 1988-1991. All Rights Reserved. Ward Mundy Software 4160 Club Drive Atlanta, GA 30319 USA Chapter 1 Preliminaries 1.1 What Is dLITE Anyway? dLITE is a memory resident ("pop-up") desktop utility which gives a user access to up to 10 dBASE III-compatible applications from within virtually any other text-based program on a DOS-based personal computer. All the user does is press one of 10 "hot-keys" to pop-up a dLITE application at any time anywhere! dLITE provides the most common data base functions (as well as some fantastic new ones) from a pop-up, light bar menu which displays on the top few lines of the screen. These include: Adding, updating or displaying records in any dBASE III-compatible data base using up to 7 dBASE III-compatible indexes. Creating a custom dBASE III-compatible data entry screen using a dBASE-standard .FMT file. Creating a dLITE PASTE-IT template to extract any information from a dBASE III- compatible data base. Then you can instantly "paste it" into your favorite foreground word processing or spreadsheet application in seconds. Say goodbye to file conversion routines! Creating customized lists, labels, or reports using selection and sort criteria you specify. These, too, can be "PASTEd" into your favorite word processor or spreadsheet, if desired. All the coding for output may rely upon standard dBASE III commands and functions. So you can finally learn dBASE programming. Up to 10 different dBASE-compatible applications can be popped up by touching any of 10 different dLITE "hot-keys." A fantastic mailing list manager application worth hundreds in the commercial market is included! In addition to the standard mailing list functions, you also can "PASTE" a complete name, address, and salutation from your data base into a letter in your word processor in seconds! 1 1.2 Special Thanks! Much of dLITE's magic is the result of a phenomenal program called FrontRunner, developed by Jeff Cooper and Gary Wisniewski of Apex Software Corporation. The program now is marketed by Ashton-Tate. dLITE includes a complimentary copy of FrontRunner's run-time module. It provides the data base engine for dLITE much like a BASIC interpreter provides the engine for many BASIC programs. So, our special thanks goes to Apex Software Corp. for allowing us to distribute their run-time module as part of the dLITE package. If you like dLITE, tell your friends about it and put in a good word for FrontRunner while you're at it! 1.3 About This Manual This manual is organized into sections describing both the functionality of the program from an end user's perspective and a developer's perspective. Before you develop your own dLITE applications, we recommend that you review the end-user sections of the User's Guide and familiarize yourself with the basic operation of the software. The Mailing List Manager application will acquaint you with all the basic building blocks for designing your own custom applications. Make sure you read the README.DOC file on the distribution diskette for late-breaking enhancements. 1.4 Legal Stuff The world is not a simple place any more, so we have to tell you a few things you need to know before you start using dLITE. First, a few disclaimers are in order. We provide the same, fine software warranty that all the big-boys do: NONE! In short, you use dLITE at your own risk. We make no representations regarding its fitness for any particular purpose or its merchantability. Nor do we provide any warranties, express or implied, that the software will work. That is solely for you to decide! The good news is the price is definitely right! You do not have to shell out $600 only to find that the software doesn't meet your needs. Everything mentioned above with respect to Ward Mundy Software applies in spades to Apex Software Corporation. They don't make a nickel from the sale of dLITE. Hence, don't blame them if dLITE smokes! It's probably the result of our lousy programming rather than theirs. 2 1.5 A Word About ShareWare This version of dLITE is marketed as ShareWare. This is a unique marketing concept which permits you to "try before you buy." It doesn't mean FreeWare! All versions of dLITE are copyrighted works for which we retain all rights. The shareware version of dLITE is licensed for use up to 90 days to give you ample time to evaluate its usefulness. The software is not crippled, nor is the documentation. This allows anyone to determine whether dLITE meets their requirements at a very nominal cost. If it does, then registration to obtain a software license is required. A complimentary copy of the latest Developer's Version and a soft-bound User's Guide are provided without charge (other than the shipping and handling costs) to everyone who registers their ShareWare copy. You may pass this ShareWare version of dLITE along to others so long as it is distributed in exactly the form received. The ShareWare documentation describes the required files. If you are a shareware distributor, you may distribute dLITE and charge a modest copying fee not to exceed $6 U.S. provided you first obtain written permission from us to do so. 1.6 Credits Names of computer hardware, software, and computer companies are used solely for the purpose of identification. With the exception of dLITE and WAMPUM, all remaining references to products and companies are trademarked by their respective companies. dLITE and WAMPUM are trademarks of Ward Mundy. IBM, IBM-PC, and PC/AT are trademarks of IBM Corp. dBASE, dBASE III, dBASE III Plus, RunTime and Ashton-Tate are trademarks of Ashton-Tate. FrontRunner is a trademark of Apex Software Corp. SideKick is a trademark of Borland International. MS-DOS is a trademark of Microsoft Corporation. PKXARC is a trademark of PKWare, Inc. 3 Chapter 2 Getting Started 2.1 System Requirements dLITE is a memory resident program which runs on an IBM-compatible PC, PC/AT, or DOS-based 386 or 486 machine. It requires DOS 2.1 or higher and approximately 160K of memory; however, under 100K of memory is required if you have at least 64K of expanded memory free which conforms to the Lotus/Intel/Microsoft Expanded Memory Specification (versions 3 and 4). To "pop-up" dLITE from within your favorite word processor typically requires a 512K or 640K machine with few other memory resident programs. If you have adequate memory, dLITE can coexist with all your favorite TSR's. 2.2 Installing the Software Insert the distribution diskette in Drive A of your computer and type A:INSTALL for instructions on installation of the software. 2.3 Loading the Software into Memory dLITE can be loaded into memory by typing the following commands at the DOS prompt: CD \DLITE <ENTER> DLITE <ENTER> If you have at least 64K of EMS memory, type DLITE /X to load the program and you will save about 64K of conven- tional memory. This means dLITE will consume only 90-95K of conventional memory. If you have a color monitor, you may increase screen performance by loading dLITE with the command: DLITE /F. If snow appears on your screen, this option should be avoided. If you will be using dLITE with a graphics mode program, then install it with the command DLITE /G. Multiple switches can be used in loading dLITE. For example, DLITE /X /F /G is acceptable. The FrontRunner run-time module then will be loaded, and dLITE will display its opening screen. Read the screen to ascertain which version of dLITE you have and what the terms of your license are. Then press any key to make dLITE memory resident. 4 You now can "pop-up" dLITE at any time by pressing ALT-1 through ALT-0 regardless of your default drive or directory. When dLITE's menu appears, you can make it disappear at any time by pressing the <ESC>ape key. Please note that dLITE does not work well with graphics mode programs. You should not pop-up dLITE while using a program which is in graphics mode. While dLITE's PASTE function will work, its menus will not be readable. Because dLITE is a memory resident program, a few words of caution are in order. With the exception of SideKick, dLITE should always be the last memory resident program loaded. This assures two things: (1) that dLITE will work and (2) that you can remove it from memory without rebooting your computer. Should you wish to change the "hot-key" settings used to pop-up dLITE, type out the DLITE.CFG file by typing the following command: TYPE \DLITE\DLITE.CFG. Instructions for changing the hot-key assignments are contained in this file. 5 Chapter 3 End-User Functions 3.1 Overview of dLITE's Mailing List Manager All versions of dLITE are bundled with a complete Mailing List Management application which is ready to use. It provides all of the major functions of the $200 commercial mailing list managers with extra bells and whistles: pop-up functionality and the ability to "paste" information from your mailing list directly into your word processing or spreadsheet applications with just a couple of keystrokes. This chapter walks you through every function on dLITE's pop-up menu. While the Mailing List Manager is certainly a useful product, it is only the beginning for dLITE. dLITE has been designed to allow anyone who can read the capability to add 9 more dBASE III-compatible, custom applications to meet your unique requirements. Any of these 10 applications then can be popped up with a single keystroke. YOU DO NOT HAVE TO OWN dBASE III TO BUILD ANY dLITE APPLICATION! 3.2 Navigation Keys for dLITE's Main Menu Once you have pressed one of dLITE's "hot-keys" and the light bar menu appears, you simply highlight the option desired by using the <LEFT> or <RIGHT> arrow keys on the numeric keypad. Then press <ENTER> to execute your choice. Pressing <ESC>ape allows you to exit from dLITE and return to your foreground application. Typing the first letter of the desired choice also works. The <HOME> key moves the light bar to the first option on the menu. The <END> key moves the light bar to the last option on the menu. 3.3 EDITing records When dLITE is first popped up, the default choice is EDIT if an application has been configured with a default data base file. To execute this choice, make sure EDIT is highlighted. Then press <ENTER>. Once the EDIT option is selected, you will be prompted for the record to retrieve based upon the lead index then in effect. The Mailing List Manager application is distributed with one record in the data base. The default LEAD INDEX is FULLNAME. To recall the sample entry in the file, type Mundy when prompted for the FULLNAME and press <ENTER>. To move to top of file, press <ENTER> with no entry. 6 Even with large data bases, a typical retrieval time for indexed data bases is approximately one second. When the Mundy record is displayed, you can move between the various fields by pressing the <Up> and <Down> cursor keys. <ENTER> also will move you to the next field. SAVING an entry occurs when ANY of the following occur: (1) <ESC>ape key is pressed; (2) <PgDn> or <PgUp> key is pressed; (3) <Up> key is pressed in upper most field (top left); (4) <Down> key or <ENTER> is pressed in the lower most field (bottom right); (5) Lower most field (bottom right) is filled with newly typed characters. All of the EDITing functionality of dLITE is virtually identical to dBASE III Plus with the exception that the <ESC> key will SAVE an entry with any changes while dBASE III Plus would not. This is a limitation of the current FrontRunner run-time package which cannot be avoided. If you need more error checking in the data entry process, use WAMPUM-D from Ward Mundy Software. Its data bases and indexes are fully compatible with dLITE. dLITE also supports the CTRL-U delete toggling function found in dBASE III. While a record is displayed in edit mode, you may mark the record *DELETED* in the data base by pressing CTRL-U. You may recall a deleted record (unDELETE) by pressing CTRL-U again. In case you are curious: YES, you can tailor the data entry screens to look exactly as you desire. More on that later! 3.4 ADDing new records Highlighting the ADDREC option and pressing <ENTER> causes dLITE to prompt whether to add a new record. Type Y to add a new blank record to the data base, and a data entry form will appear for you to complete. Type in your entries using the function keys described in the EDITing section above to maneuver. When you have completed all the entries (assuming you have not filled in the last field completely), then press <PgDn> to SAVE your data. 7 If you have entered <ADDREC> mode by mistake, you can press <ESC> to exit. The blank record is NOT deleted from the data base; however, it is marked DELETED whether data has been entered in the various fields or not. The significance of this is outlined below in the DELETing records section of the User's Guide. 3.5 PASTE records Perhaps dLITE's most powerful and unique function is its PASTE option. This permits you to pop-up dLITE from within another application, such as a letter being written in your word processor, select a record from the data base, and then "paste" a name, address, and salutation into the letter. If you would like to follow along, start up your favorite word processor or editor and open a new document (if required). Now press ALT-1 to pop-up dLITE's Mailing List Manager application. Highlight the PASTE option and press <ENTER>. You will be prompted for the FULLNAME to find. Type Mundy and press <ENTER>. The data entry screen will appear. On the top line, you will be asked whether to PASTE this record. Notice the default is N for No. You must type Y to paste the information into your document. At this juncture, you can move through the records in the file by pressing <PgDn> or <PgUp>. The records will be ordered alphabetically according to the lead index. For now, type Y to PASTE the Mundy entry into your word processor or editor. At this point, you should see the following: Ward Mundy ATTN: dLITE Support 4160 Club Drive Atlanta, GA 30319 USA Dear dLITEful one: As you add your own data into the Mailing List Manager application, the true simplicity and utility of dLITE should become apparent. In case you are curious: YES, you can tailor the PASTE command to paste anything you want from your data base in any format you desire. More on that later! If you need to just write quick letters, then the existing PASTE file specification should be perfect to meet your needs. 8 3.6 DELETE records For those new to the world of dBASE, you need to know that DELETING a record really doesn't delete it. It simply marks it as *DELETED*. The beauty of this approach is that you can later change your mind and *UNDELETE* a deleted record. Deleting a record does have effects. First, deleted records cannot be output with dLITE's OUTPUT menu option. Second, deleted records are permanently erased when a dBASE- compatible data base is packed (rebuilt). Prior to packing a file, however, deleted records can be restored using the *UNDEL* option on dLITE's menu. To DELETE a record, highlight this option and press <ENTER>. Then enter the FULLNAME of Mundy when prompted. The data entry screen then will appear with the prompt DELETE this record? on the top line. As with pasting records, the default answer is N for NO. If you really do want to delete the record, type Y. Prior to typing Y, you can <PgDn> or <PgUp> to move through the data base. If the beginning or end of the file is reached, the DELETE function is terminated and dLITE's Main Menu reappears. 3.7 UNDELETE records dLITE's UNDELETE function permits you to RECALL records marked deleted as active records in the data base so long as they are undeleted BEFORE the file is packed. Once the file has been packed, deleted records are lost forever! To UnDELETE a record, highlight this option and press <ENTER>. Then enter the FULLNAME of Mundy when prompted. The data entry screen then will appear with the prompt UnDELETE this record? on the top line. As with deleting records, the default answer is N for NO. If you really do want to undelete the record, type Y. Prior to typing Y, you can <PgDn> or <PgUp> to move through the data base. If the beginning or end of the file is reached, the UnDELETE function is terminated and dLITE's Main Menu reappears. Once a record has been recalled with the UNDELETE function, it is an active record in the data base once again. This means it can be output with dLITE's OUTPUT function. 9 3.8 SELECT records The purpose of entering data into a data base typically is to be able to output reports which SELECT (or narrow down) the data to only a specific group of records based upon user- defined criteria. dLITE provides this functionality through the SELECT option. When SELECT is chosen, a listing of the first 98 fields in the data base will display. Then the user is prompted to Enter dBASE Selection Criteria. In dBASE lingo, this is a filter. This filter can be 78 characters long. If a longer filter is desired, it can be stored in the OUTPUT file specification discussed below. For those that have forgotten college Algebra and Boolean logic, here is a brief refresher course. If you need more, visit your local library or buy a dBASE III Plus handbook. Typically a dBASE filter consists of three parts: (1) Field name (2) Relational operator (3) Value The FIELD NAME is the exact name of the field from your data base, i.e. it is one of the field names displayed at the top of the screen. The RELATIONAL OPERATOR is one of the following: (1) = (EQUALS) (2) <> (NOT EQUALS) (3) > (GREATER THAN) (4) < (LESS THAN) (5) >= (AT LEAST) (6) <= (AT MOST) (7) $ (CONTAINED IN) (8) .NOT. $ (NOT CONTAINED IN) The VALUE is just that, the value to find for the field specified by field name. 10 Here are some examples to get you started. English: FIND ALL THE RECORDS IN ZIP CODE 30319. Expression: ZIP="30319" Comments: Notice that the zip code is in quotes since ZIP is a character field. English: FIND ALL THE ENTRIES WITH AUGUST 1988 CONTACT DATE Expression: CONTACTDT >= CTOD("08/01/88") .AND. CONTACTDT <= CTOD("08/31/88") Comments: More than one expression can be joined with .AND. This means BOTH expressions must be TRUE for a record to be output. Notice that spacing doesn't matter. English: FIND ALL THE CODE1'S CONTAINING THE WORD "CLONE" Expression: "CLONE"$UPPER(CODE1) Comments: Since clone could be in upper, lower, or mixed case, we want to find them all. By using the dBASE function UPPER(), we can convert the CODE1 entries temporarily to upper case and then search for entries containing the word "CLONE." Since CODE1 is a character field, the value must be enclosed in quotes. English: FIND ALL THE ENTRIES WITH NO CONTACT DATE Expression: DOW(CONTACTDT)=0 Comments: The easiest way to check for a blank date field is to search for those where the day of the week is 0. In dBASE, a 0 day of the week is a blank date. The DOW() function returns a number corresponding to the day of the week of a date field. 11 English: FIND ALL ENTRIES WHERE CATEGORY CONTAINS THE WORD dBASE OR THE IDCODE IS dLITE Expression: "dBASE"$CATEGORY .OR."dLITE"$IDCODE Comments: Here we are looking for terms which could have appeared anywhere within the two fields. Thus, the CONTAINS operator is better than EQUALS. Notice that when two expressions are joined with .OR., a record will qualify for output when EITHER expression is True. 3.9 OUTPUT records When the OUTPUT records option is chosen, the SELECT record option will first appear if no selection criteria are active. You can tell whether selection criteria are active by looking in the lower right corner of the screen after the name of the current data file. If selection criteria are in effect, the word *SEL* will appear after the file name. If you want to select all records, leave the selection criteria field blank by pressing the <ESC> key. Once selection criteria have been entered or if all records output has been chosen, then dLITE will process the request and produce a listing of the active records which meet the defined selection criteria. If no active records exist in the data base, an error will be displayed indicating that the file is empty. If no active records qualify for output, then a blank report will be produced. You can tailor the OUTPUT command to output virtually any information you want from your data base in any format you desire. This may be a simple list, a more complex report, or a paste specification to paste multiple records or even mailing labels into a word processing document. You also may select printed output or write the output to an ASCII file, if desired. 12 3.10 UTILITY Option In this version of dLITE, the UTILITY option provides the following functions: (1) Changing the Lead Index (2) Reindexing (3) Creating dBASE III-compatible index files (4) Listing the file structure of any dBASE III data base (5) Simulated dot prompt to enter many other dBASE commands In addition to the functions listed above, a developer also may create new dBASE III-compatible data bases by specifying an asterisk (*) as the file name choice in the FILE option of dLITE's Main Menu. File creation is explained in more detail in that section of the guide. 3.10.1 Changing Lead Index Changing the LEAD INDEX determines the key by which records are retrieved in EDIT, PASTE, DELETE, and UNDELETE modes. It also defines the sort order for OUTPUT unless a different index is specified in the OUTPUT file specification. For example, if the LEAD INDEX is FULLNAME, then record output is ordered alphabetically by full name (last name first). It also means that all or part of an existing full name must be entered to retrieve a record in EDIT, PASTE, DELETE, and UNDELETE modes. If the LEAD INDEX is ZIP, then record output is ordered by zip code. Retrieval of data for EDIT, PASTE, DELETE, and UNDELETE requires that you enter all or part of the zip code for an existing record in the data base. Selecting NATURAL ORDER means that record output will be in the same order that the records were entered into the file. To retrieve a record requires entry of a record number which is automatically assigned when each new record is added to the data base. 13 For those unfamiliar with dBASE indexes, a word of explanation is in order. dBASE indexes take the place of the sorting step which typically is used on larger computer systems to order a file in a certain way. The advantages of indexes are many. First, they are automatically updated whenever a new record is added to a file or an existing record is changed. Thus, the end-user need do nothing to assure that the data base is properly sorted. Second, because indexes are always current, any output can be produced in the order of any existing index without the need to sort the data base. This saves a tremendous amount of time with large data bases. Third, indexes permit retrieval of information in many different ways almost instantaneously. Simply change the lead index, and enter all or part of an existing key value. dLITE supports up to 7 simultaneous indexes which can be defined to meet the needs of virtually any application. 3.10.2 Reindexing REINDEXing is a function which probably will not be necessary unless you experience a power failure while actively changing records in a data base. To protect against file damage, dLITE automatically closes ALL data bases whenever the user returns to dLITE's Main Menu. HINT: Return to the Main Menu whenever you finish updating a file. Don't leave the computer sitting on a data entry screen! A good clue that reindexing is necessary is not being able to retrieve a record which you know is in the file. Because dLITE is a memory resident program which is intentionally stingy in its use of memory, it is possible with very large data bases with complex indexes that you may exhaust your computer's memory allocated to dLITE. In such cases you will get an error. These indexes can easily be rebuilt with WAMPUM-D, an inexpensive, menu driven data base management system which is dBASE III and dLITE-compatible. WAMPUM also is distributed as shareware. 3.10.3 Creating New Indexes If you want to create a new dBASE III-compatible index, simply mark the CREATE NEW INDEX option True by inserting a Y in the field and <PgDn>. You will be prompted to enter a name for the index file and an index expression. See the Devevloper's Section of this guide for additional information on creating dLITE indexes. 14 3.10.4 Listing File Structure To list the file structure of the current data base in use, mark the LIST FILE STRUCTURE option True by inserting a Y in the field and <PgDn>. A listing of the current file structure will be displayed one screen at a time. These screens can be printed using the Shift-PrtScrn keys on your computer. 3.10.5 Simulated Dot Prompt This version of dLITE includes an option allowing the developer to enter "dot prompt" mode. This mode simulates the dBASE dot prompt and permits entry of many standard dBASE commands at a simulated dot prompt. The commands supported are listed in the appendix to this guide. Simply mark the dot prompt option Y to enter dot prompt mode. To return to the menu, type QUIT at the dot prompt and press <ENTER>. *** See the README.DOC file for late-breaking revisions of the method for activating this option. This is for your own protection. 3.11 FILE Select Option dLITE allows you to work with virtually any dBASE III data base with up to seven dBASE III-compatible indexes. With the exception of MEMO fields, all dBASE III field types are supported. Before using additional data bases, you first must create at least a data entry screen to display the contents of the file. The MenuMaker screen generator program from Ward Mundy Software allows you to quickly build dBASE III-compatible format files for use with dLITE. With MenuMaker, you simply draw the screen the way it should look, and MenuMaker writes the code for your dLITE or WAMPUM application. Or you may create your own format files manually using standard dBASE @ SAY and @ GET commands. Consult any dBASE III reference book for detailed instructions. A sample format file supporting the Mailing List Manager is included to give you something to clone. Simply print the file MAILLIST.FMT. It was generated using MenuMaker. In addition to selecting files, the FILE select option allows a developer to create new dBASE III-compatible data bases. This is explained in the Developer's Section of this guide. 15 3.12 CLEAR dLITE The CLEAR option allows you to remove dLITE from memory. Two prerequisites are necessary before this will work reliably: (1) dLITE must have been the last memory resident program loaded into memory (2) You must be at the DOS prompt when you select the CLEAR option If dLITE cannot be cleared from memory when you select this option, an error will report this to you with an explanation why. DR-DOS 5.0 does not support this option. Generally, you will only need to clear dLITE from resident memory for one of the following reasons: (1) You need to run an extremely large program such as WAMPUM which needs the memory reserved by dLITE; or (2) You need to run another dBASE program or clone which will be using the same data base used by dLITE. 3.13 QUITting dLITE QUITting dLITE means that the program remains memory resident but disappears from view until you need it again. This can be accomplished by highlighting QUIT and pressing <ENTER>. Or you may simply type Q when dLITE's Main Menu is displayed. Or you may press the <ESC>ape key. To pop-up the Mailing List Manager again, press the hot- key assigned to this application, ALT-1. In case you are curious, ALT-2 through ALT-0 are reserved for use by you in building your own future dLITE applications. 3.14 Unexpected Errors Because dLITE is squeezed into a small amount of memory, its error handling capacity is necessarily limited. Typically, it will report one critical error, wait for you to acknowledge the error, and then execute a QUIT command automatically. It is up to you, the end-user, to fix the error before popping up dLITE again. 16 With the Mailing List Manager, an error should not occur unless your data base becomes so large that you run out of disk space. The Mailing List Manager application has been stable for nearly three years and should cause no problems. dLITE also provides very sophisticated error handling for dLITE Developer-induced errors. These typically are syntax or typographical errors which creep into new applications you decide to build. The scope of this error handling functionality is covered in more detail in the following chapters. If you get an error which appears strange or confusing, please give us a call Monday through Thursday evening between 6 and 9 p.m. EASTERN time. The number is 404/237-9420. 17 Chapter 4 Developing dLITE Applications 4.1 Overview dLITE was designed to provide even novice computer users with a powerful application development tool. Virtually everything in dLITE's rich assortment of functions can be customized to meet your individual needs. A partial list of tailorable options follows: (1) Screen colors and screen sizes (2) Error tones to assist end-users (3) Up to 10 dBASE-compatible data bases (.DBF) (4) Up to 7 dBASE-compatible indexes per file (.NDX) (5) dBASE-compatible data entry screens (.FMT) (6) Virtually complete control of dBASE-like environment through SET commands (7) Customized PASTE file spec for each file provides unlimited flexibility in extracting data from .DBF files for use in other applications (8) Customized OUTPUT file spec for each file provides many options for tailoring output to meet individual requirements. This output could be a list, a complex report, or a PASTE file spec to extract labels from an entire data base. Output can be displayed, printed or written to an ASCII fie. (9) Customized data entry screen for 10 applications 18 4.2 Steps in Building a dLITE Application To create a new dLITE application involves a number of steps. None are difficult, but all are required! This chapter will walk you through the dLITE development process by describing everything you need to know about each step in creating a new dLITE application. The steps shown are those that were used to build the Mailing List application. A few words of definition also may be in order. A dLITE application typically consists of the instructions necessary to execute all nine of the functions outlined in section 4.1 above. You can execute up to 10 different applications within dLITE. It should be noted that these applications may use 10 separate data bases or all 10 applications may use the same data base with 10 different data entry screens, paste file specs, and/or output file specs. Which approach you take to dLITE application development obviously depends upon the data base requirements you are endeavoring to meet. The basic steps in building a dLITE application are listed below. Each step then is covered in detail in a separate section of this chapter. The next chapter then walks you through all of the steps which went into building the Mailing List Manager application which accompanies dLITE. The steps are the following: 1. Creating a dBASE-compatible data file 2. Creating any necessary indexes 3. Creating dLITE's initialization file 4. Creating the application initialization file 5. Creating the data base configuration file 6. Creating the data entry screen (format file) 7. Creating the paste file specification 8. Creating the output file specification 9. Creating output initialization and reset files 19 4.3 Creating a dBASE-compatible data base In creating new dLITE applications, you may use existing dBASE III-compatible data bases or you may create new ones. FoxPro no longer creates data bases which can be recognized by dLITE. We recommend using dLITE or WAMPUM to create your data bases. The only limitation is that manipulation of MEMO fields from within dLITE currently is not supported. This is a FrontRunner limitation. If you need sophisticated control over data entry and extraction from MEMO fields, then we recommend WAMPUM-D (the dBASE index compatible version) from Ward Mundy Software. To create a new dBASE data base, start dLITE and press any one of the 10 "hot-keys." When dLITE's Main Menu appears, move the light bar to the FILE option and press <ENTER>. Then type an asterisk (*) for the file name and press <PgDn>. This tells dLITE you want to create a new dBASE-compatible data base. You will be prompted to enter a file name for the new data base. Enter a file name up to 8 characters long with no embedded spaces or punctuation. Then press <ENTER> unless the file name was 8 characters long. dLITE now will prompt you for the file structure. In dBASE lingo, this means you must describe every field (piece of information) to be captured in your data base. These field descriptions include the following four pieces of information for each field: (1) Field name - Up to 10 characters long. The first character must be a LETTER. All remaining characters can be LETTERS, NUMBERS, or the UNDERSCORE character. No other punctuation or spaces are allowed. (2) Field type - Choose one of the following: C - Character (Use this except as noted below) N - Numeric (Use this for data on which you need math) D - Date (Use for capturing dates) L - Logical (Use for Yes/No, True/False fields, e.g. MARRIED) 20 (3) Field length - Specify the maximum size of entries for the particular field specified. Character - 1 to 254 Numeric - 1 to 13 (Count the decimal point also) Date - 8 Logical - 1 (4) Field decimals - For numeric fields, specify the number of decimal positions to be captured. When you have completed entry of all desired fields, press CTRL-End to terminate the file creation process and build an empty dBASE-compatible data base. If you change your mind about building the new file, press <ESC>ape to abort the file creation process. If you decide to insert a new field between two existing fields, use the <Up> cursor to position to the place where the new field should be inserted. Then press CTRL-N to insert the field. 4.4 Creating a dBASE-compatible index In creating new dLITE applications, you may use existing dBASE III-compatible indexes or you may create new ones. To create a new dBASE index, start dLITE and press any one of the 10 "hot-keys." When dLITE's Main Menu appears, move the light bar to the FILE select option and press <ENTER>. When prompted for the file name, type in the name of the data base for which you want to build a new index. Then press <PgDn> to return to the Main Menu. Now highlight the UTIL option and press <ENTER>. Then select the CREATE NEW INDEX option by marking it Y (for YES). Also mark the LIST FILE STRUCTURE option Y so that you can write down the names of the fields in your data base you wish to index. You will be prompted for two pieces of information: (1) Index File Name (2) Index Expression 21 The Index File Name is the DOS file name for the index file. It always has a file extension of .NDX. Simply enter a file name to associate with this index. Typically, it would be the name of the field to be indexed unless you are creating an index from multiple fields. In any case, the file name must conform to all DOS file naming conventions, i.e. up to 8 characters long with no imbedded spaces. The Index Expression is the dBASE expression describing what is to be indexed. For simple indexes, this would be the name of the field (character, numeric, or date) to be indexed. For complex (multi-field) indexes, it can be any dBASE character expression. Complex indexes are explained in more detail below. Enter the desired index expression and press <ENTER> to build the new index. Please note that dLITE is necessarily light on memory. Therefore, building indexes on extremely large, existing data bases is not dLITE's strong suit. It is possible to specify an index expression so complex with a file so large that dLITE lacks the memory to build it. It also is possible that you will run out of memory attempting to index even simple fields on very large data bases. In either case, use WAMPUM- D to create the original index. dLITE then can handle updating of very complex indexes with ease! Hundreds of pages could be written on complex indexes. For those wanting to know everything, consult a good dBASE reference text in your public library or favorite bookstore. For new dBASE enthusiasts, several examples of complex indexes are included below to provide you with something to clone to meet your needs. Find an example that is close and experiment. dLITE will give you a second chance if you make a mistake. We've all been there! Problem: Indexing multiple character fields such as LASTNAME and FIRSTMI to assure secondary ordering on first names. Solution: SUBSTR(TRIM(LASTNAME)+","+TRIM(FIRSTMI)+SPACE(30),1,30) Comments: The trick here is to make sure every entry in the index is a fixed length. This is handled by adding 30 blank spaces onto the trimmed character string and then using SUBSTRing to extract a fixed length entry (in this case the first 30 characters). TRIM() is a function which strips spaces off the end of fields. SUBSTR() has three parts: the expression, the starting point, and number of characters to extract. 22 Problem: Indexing multiple fields of mixed types such as a character field LASTNAME and a date field FILINGDT. This typically would be done to assure that entries are ordered within a given date field. Solution: DTOC(FILINGDT)+LASTNAME Comments: The trick is to convert every field to character type. Date fields are converted using the DTOC() function. Numbers are converted using the STR() function. An example of a numeric conversion would be STR(COST,7,2) where COST is the numeric field, 7 is the total length of the string, and 2 is number of decimals. Problem: Different fields need to be indexed depending upon the current value of yet another field. For example, for a college newsletter, you probably would want to use a maiden name rather than their current last name if the person were now married. Solution: IIF(MARRIED,MAIDENNAME,LASTNAME) Comments: One of the most powerful functions in the dBASE language is the IMMEDIATE IF function. It has three parts: the condition, what to do if the condition is TRUE, and what to do if the condition is FALSE. Here, we are assuming that MARRIED is a logical field. Thus, the word MARRIED means "if MARRIED is true." The second expression says if married is true, index on the MAIDENNAME field otherwise index on LASTNAME. NOTE: Both the MAIDENNAME and LASTNAME fields must be the same length or you will get a mess! If they aren't the same length, use the SUBSTR() function to make sure you index on the same size field. 23 4.5 dLITE Configuration File Overview The heart of the dLITE system is a unique system of configuration files. These are standard ASCII files which can be created with any editor. The configuration files are used to tell dLITE exactly how you want your application to function. Within any configuration file, you can enter virtually any dBASE command or function. All entries in the file will be executed when the user selects the desired application or function. There are two basic types of configuration files: initialization files and function files. The two main initialization files are the following: (1) dLITE's Main Initialization File (DLITE.CFG) (2) Application Initialization File (DLITE.1 through DLITE.0) In addition to initialization files, dLITE relies upon function file specifications to generate virtually all options on the Main System Menu. A brief description of each of these file specs, its function, and default value are outlined below: The FILE CONFIGURATION SPEC is the file to which dLITE looks for the default configuration for any data base file. The default name for this file is the FILENAME entry with a .CFG file extension. This file name can be modified by setting the CFG_SPEC within the application initialization file (DLITE.1 thru DLITE.0). The FORMAT FILE SPEC is the file to which dLITE looks for the data entry screen for an application. The default value is the FILENAME entry with a .FMT file extension. The default format file spec name can be changed by setting the FMT_SPEC variable within the APPLICATION or FILE CONFIG SPECs. The PASTE FILE SPEC is the file to which dLITE looks for the paste function commands to execute when the PASTE option is chosen. The default value is the FILENAME entry with a .PST file extension. The default paste file spec name can be changed by setting the PST_SPEC variable within the APPLICATION or FILE CONFIG SPECs. The OUTPUT FILE SPEC is the file to which dLITE looks for the output commands to perform when the OUTPUT option is chosen. The default value is the FILENAME entry with a .OUT file extension. The default output file spec name can be changed by setting the OUT_SPEC variable within the APPLICATION or FILE CONFIG SPECs. 24 The OUTPUT INITIALIZATION and RESET FILE SPEC's are the files which dLITE executes immediately before and after the OUTPUT FILE SPEC. The default file names are the data base FILENAME with an .INI and .RST file extension, respectively. The default names can be changed by setting the INI_SPEC and RST_SPEC variables within the APPLICATION or FILE CONFIG SPECS. 4.6 dLITE Configuration File Execution A word about when and how configuration files are executed may be helpful. As noted, there is a main configuration file (DLITE.CFG) which is executed only once, when dLITE is first started from the DOS prompt. Commands in this file typically should initialize the entire dLITE programming environment for all 10 of your applications. Commands which apply only to one or a few of your appli- cations should not be placed in DLITE.CFG. Each of your 10 applications also has its own configuration file. These files are named DLITE.1 through DLITE.0. Which file gets executed depends upon which hot-key is pressed to invoke dLITE. If hot-key ALT-8 is pressed, DLITE.8 gets executed. The rest should be fairly obvious. Commands in these files should establish the exact environment in which dLITE should function for the given application. Typically, you would have an entry in this file for the name of the primary data base and the name of the data base configuration file to execute. Each data base also may have one or more configuration files which define the environment in which the actual data base will be used. Typically entries in this file would include the names of all indexes to be used, the name of the lead index, and the names of the format file spec (data entry screen), paste file spec, and output file spec. These are discussed in more detail in subsequent sections of this manual. For now, the critical point to master is which commands should be stored in which config files. Both the application configuration file and the data base configuration file get executed whenever a hot-key is pressed to pop-up dLITE. All configuration files must be in the DOS PATH or errors will result. Function file specs are executed whenever the specified function is performed. For example, MAILLIST.PST is executed when the mailing list data base application is active and the PASTE option is chosen from the Main System Menu. 25 4.7 dLITE Configuration File Errors Whenever an error is found in a command or function within a configuration file, dLITE will display an error message highlighting the error and displaying the problem line of code and the name of the configuration file in which it was found. When the user presses a key, the offending command is ignored and processing continues as if that line of code did not exist. The consequences of ignoring errors obviously depend upon the gravity of the mistake in the configuration file. For example, if there is a typographical error in the name of the data base or in the name of the data base configuration file, obviously this dLITE application may not function at all. The advantage of ignoring such errors is that it gives the first-time developer a fighting chance of identifying and curing mistakes. All the developer needs to do is edit the offending line of code in the configuration file which was identified by dLITE's error trapping routine. Because dLITE is a pop-up program, the developer can run an editor with the configuration file as the foreground task then immediately test the configuration file by pressing one of dLITE's hot- keys. If an error occurs, simply <ESC>ape back to the editor, change the offending line of code, save the changes, and pop-up dLITE again to test it. This process can be repeated until all the errors disappear. 4.8 dLITE Commands and Functions As indicated above, virtually any FrontRunner-supported dBASE command or function can be included in dLITE's configuration files. Obviously, to include commands and functions, you first need to know what they are and what they do. For those familiar with dBASE syntax, IF commands and DO WHILE loops are not supported in configuration files. The appendix to this User's Guide outlines all supported commands and functions. Read the README.DOC file on your distribution diskette for any late-breaking news! Typically, dLITE takes its cue in executing certain internal program functions based upon the values set in the config files. For example, the value stored in FILENAME becomes the main data base file for a given application. What follows is a brief description of dLITE's internal variables and their functions: 26 VARIABLE PROGRAM FUNCTION EXAMPLE -------- ------------------------------ ------------ FILENAME Stores default data base name "MAILLIST" INDXNAME Names of all index files "IDCODE,ZIP" LEADINDX Name of default lead index "ZIP" OUTINDX Name of lead index for output "ZIP" WINLIN No. lines in edit window "21" WINCOL No. columns in edit window "80" TONES Whether beeps are audible .T. or .F. SPECCOLOR Whether custom color is used .T. or .F. COLORS Custom color specification ",, /W" LPTINIT Printer initialization string "" LPTRESET Printer reset string "" LPTDEVICE Name of print or output file "LPT1" CFG_SPEC Name of file config spec "MAILLIST.CFG" FMT_SPEC Name of format file spec "MAILLIST.FMT" PST_SPEC Name of paste file spec "MAILLIST.PST" INI_SPEC Name of output init spec "MAILLIST.INI" OUT_SPEC Name of output file spec "MAILLIST.OUT" RST_SPEC Name of output reset spec "MAILLIST.RST" 4.10 Creating the Custom Data Entry Screen In addition to configuration files, every dLITE application also requires a custom data entry screen, designed to meet your own requirements. For dBASE enthusiasts, this can be a standard dBASE-compatible format file (.FMT). In addition, dLITE format files may contain any command or function which could be included in a configuration file. If you are new to the world of dBASE, a format file is simply an ASCII file with commands which tell the interpreter where to place prompts and data entry fields on the screen. An example may assist in visualizing what we are talking about. A typical format file entry would look like the following: @ 1,0 SAY "Applicant name:" GET FULLNAME PICTURE "XXXXXXXXX" @ 3,0 SAY "Enter birthday:" @ 3,16 GET BIRTHDAY PICTURE "99/99/99" There are four parts to any typical format file command: 1. Screen coordinates (@ 1,0) 2. Screen prompt (SAY "Applicant name:") 3. Data entry field (GET FULLNAME) 4. Field format (PICTURE "XXXXXXXXX") 27 The screen coordinates and either a SAY or GET command are required. You may have both a SAY and GET command on one line. And you may have an optional picture specification which tells the interpreter what type of data to accept in the data entry field. The order of GETS in the format file determines the order in which the user will be prompted for input in ADDREC and EDIT mode. A GET command always must include the actual field name of a field in your active data base. Use the UTIL/LIST STRUCTURE option to get a list of your field names. There are a number of ways to "draw" data entry screens. The easiest way is to use a screen generator program such as MenuMaker from Ward Mundy Software. With this program, you simply type the screen the way you want it to look, and MenuMaker writes the code for the format file. An alternative is to draw your screen out on ruled paper. Then use an ASCII editor to enter the commands necessary to format the screen the way you want it to look. The critical requirement, of course, is to make sure you provide a GET command for every field in your data base in which you want the user to be able to enter information. This need not be every field in the data base. However, if there is no GET for a field in the data base, obviously the end-user cannot enter data into that field. The default format file for any data base is the FILENAME specified in the application configuration file (DLITE.1 thru DLITE.0) plus the .FMT file extension. If you specify a format file spec value (such as FMT_SPEC="MAILLIST.FM2") in the appli-cation or file configuration, then the format file will be the file name you specify for the memory variable FMT_SPEC. This permits the developer to design multiple data entry screens for a single data base. These screens then can be used to create dif- ferent "views" of the data base when end-users select different application hot-keys. The following PICTURE template characters are supported by dLITE. Typically, you would type one PICTURE character for each character position in the data entry field. 9 Allows entry of numbers only # Allows entry of numbers, blanks, and signs A Allows entry of letters only L Allows entry of logical data only Y Allows entry of Y or N only N Allows entry of letters and digits only X Allows entry of any character ! Converts any letter to upper case 28 All other picture template characters including all lower case letters are treated as constants. These are automatically entered for the end-user and cannot be changed. dLITE also supports a number of GET FUNCTIONS within the picture statement. The correct syntax is as follows: @ 1,0 GET FIELDNAME PICTURE "@Z XXXXX" All functions begin with the @ symbol followed by one of the following characters: C Displays CR after positive numbers X Displays DB after negative numbers ( Encloses negative numbers in parentheses B Left-justifies numeric data Z Displays zero value as blank field D American date format E European date format A Alphabetic characters only R Literals in template are not part of data ! Upper case only dLITE also supports field-level data validation using a VALID clause which contains a logical expression. If the data entered for such a field does not evaluate to TRUE when tested against the VALID expression, then the user cannot leave that field. A few examples may help explain this functionality. @ 1,0 GET FILINGDATE VALID FILINGDATE<=DATE() This VALID clause would assure that any FILINGDATE entered by the end-user was a date less than or equal today's date. @ 1,0 GET STATE PICTURE "!!" VALID STATE$"AL GA FL CA" This VALID clause would assure that the STATE entry contained the correct state abbreviation for Georgia, Alabama, Florida, or California. 29 4.11 Creating the Custom Paste Specification Perhaps dLITE's most unique feature is the ability to "cut-and-paste" information from a pop-up data base into your foreground application. This forever ends the tedious business of exporting and importing files from one environment to another. This functionality is implemented with a FrontRunner command called "PASTE." The PASTE command allows you extract one or more pieces of information from your data base and insert them into your foreground application. A typical PASTE command looks like the following: PASTE LASTNAME + CHR(13) This tells dLITE to paste the LASTNAME field (from the selected record) and a carriage return into your foreground application. More complex PASTE commands also are possible. For example, PASTE TRIM(FIRSTMI)+" "+TRIM(LASTNAME)+CHR(13) This tells dLITE to "trim off" the trailing spaces and paste the FIRSTMI (first name, middle initial) field, then paste a space, then "trim off" the trailing spaces and paste the LASTNAME field, and then paste a carriage return into the foreground application. In addition to being able to paste fields, ASCII characters, and string expressions, you also can paste and thereby simulate virtually any keystroke or combination keyboard entry which could be made using the PC keyboard. This permits flexible pasting of information into spreadsheets which typically require cursor key entries between data elements. The proper syntax for pasting such entries requires knowing the "extended code" for the keystroke. An extended code consists of CHR(0) + an additional ASCII code. For example, to paste the HOME key, the proper command is PASTE CHR(0)+CHR(71). The other extended codes are listed below. 30 Code Keyboard Key ------ ---------------------------------- 15 Backtab, Shift-Tab 16-25 ALT-Q, W, E, R, T, Y, U, I, O, P 30-38 ALT-A, S, D, F, G, H, J, K, L 44-50 ALT-Z, X, C, V, B, N, M 59-68 Function Keys F1 through F10 71 <Home> 72 <Up> Cursor 73 <PgUp> 75 <Left> Cursor 77 <Right> Cursor 79 <End> 80 <Down> Cursor 81 <PgDn> 82 <Insert> 83 <Delete> 84-93 Shifted Function Keys F1 through F10 94-103 Control Function Keys F1 through F10 104-113 ALT Functions Keys F1 through F10 114 Ctrl-PrtSc 115 Ctrl-<Left> Cursor 116 Ctrl_<Right> Cursor 117 Ctrl-<End> 118 Ctrl-<PgDn> 119 Ctrl-<Home> 120-131 ALT-1 through ALT-0, ALT-hyphen, ALT-= 132 Ctrl-<PgUp> 31 4.12 Creating the Output File Specification dLITE's Output File Specification is the template used to produce file output when the end-user selects the OUTPUT option on the Main Menu. If SELECTION CRITERIA (a dBASE filter) have been specified, then the output is generated for every record matching the selection criteria. If no SELECTION CRITERIA have been specified, then the user is first prompted to enter them. If the CRITERIA field is left blank or <ESC>ape is pressed, then output is produced for every active (not deleted) record in the data base. Three different commands may be used within the OUTPUT file spec: DISPLAY, PRINT, and PASTE. Display simply lists the data requested by the developer. Print functions much like display except that you may generate printed output or reroute output to a file. Paste allows the transfer of information on multiple records to the foreground application. The DISPLAY syntax is shown in the following example: DISPLAY LASTNAME,FIRSTMI,CITY,PHONE WHILE .NOT. EOF() OFF Notice that the command DISPLAY is followed by a list of fields to be displayed, each separated by a comma. The words "WHILE .NOT. EOF()" tell dLITE to process the DISPLAY command for every record meeting the selection criteria until end-of-file is reached. This expression is mandatory. The "OFF" keyword is optional. If included, dLITE will display the records numbers for each qualifying record on the left margin immediately preceding the first field in the field list. If the SET HEADING ON expression is included in either the output file spec or the output initialization file spec, then the field headings will be displayed at the top of the listing. The syntax for PRINTed output is as follows: PRINT LASTNAME,FIRSTMI,CITY,PHONE Note that with the PRINT command the WHILE .NOT. EOF() condition is implicit. Specifying it is not required although using it will not generate an error. 32 PRINTed OUTPUT always is routed to the device or file specified in the LPTDEVICE memory variable. If the memory variable is not specified in your default configuration file, then printed output is automatically routed to PRN. If a file name is specified for LPTDEVICE rather than a printer device name, then output will be routed to that file when the PRINT command is issued. The final output file spec option is PASTE. The PASTE syntax to extract data from multiple records into a foreground application is shown in the following example: PASTE FULLNAME+CHR(13)+ADDRESS+CHR(13) WHILE .NOT. EOF() The PASTE syntax here is identical to that used in the PASTE file spec for single record output except the expression "WHILE .NOT. EOF()" is added to tell dLITE to process the PASTE command for every record in the file which meets the selection criteria until end-of-file is reached. 4.13 Creating the Output Initialization File Specification The OUTPUT initialization file is used to set up the output environment before the output is generated. Typically, this would include commands to set the lead index (which assures proper sorting of the output) and to set the display headings on or off for the display command. To set the lead index for output, enter a line in the output initialization file spec similar to the following where LASTNAME is the actual file name of the lead index desired: OUTINDX="LASTNAME" To turn column headings on for display output, enter the command SET HEADING ON in the output initialization file spec. The default file name for the output initialization file spec is the name of the data base with a file extension of .INI. This can be changed by including a line in the application file spec similar to the following where "MAILLIST.INI" is the desired file name: INI_SPEC="MAILLIST.INI" 33 4.14 Creating the Output Reset File Specification The OUTPUT reset file spec is used to reset dLITE's operating environment after the output is generated. Typically, this would include commands to reset a printer. The file is optional! The default file name for the output reset file spec is the name of the data base with a file extension of .RST. This can be changed by including a line in the application file spec similar to the following where "MAILLIST.RST" is the desired file name: RST_SPEC="MAILLIST.RST" 4.15 Setting Custom Colors for dLITE Applications For those with color monitors, you may prefer different color settings than the defaults provided with dLITE. These can easily be set either for all applications (within DLITE.CFG) or for individual applications (within DLITE.1 through DLITE.0). Two commands are necessary to set custom colors. Edit the configuration file desired and change the SPECCOLOR logical field to True by typing SPECCOLOR=.T. The enter your custom color spec using the COLORS memory variable. The color spec consists of three color values separated by commas and enclosed in quotes. The three values are as follows: 1. Standard Color for all displays except GETS 2. Enhanced Color for GETS (data entry fields) 3. Border Color for borders Each of the three values consists of two parts separated by a slash (/): the foreground color and the background color. A table of all supported colors and their alphabetic codes follows: 34 Code Color ------- ------------- (space) Black (space)+ Grey N Black N+ Grey B Blue B+ Light Blue G Green G+ Light Green BG Cyan BG+ Light Cyan R Red R+ Light Red BR Magenta BR+ Light Magenta GR Brown GR+ Yellow W White W+ Bright White X Hidden As an example, the default color settings provided by dLITE are as follows: "W/B,B/W,W/R". This means standard text is displayed in white letters on a blue background, enhanced text is displayed in blue letters on a white background, and borders are displayed in white letters on a red background. 35 Chapter 5 Building the Mailing List Manager Application 5.1 Creating the MAILLIST Data Base We first must start dLITE and make it memory resident. First position to the directory in which dLITE and its supporting files are stored by typing CD \DLITE. Then type dLITE at the DOS prompt. Now press the <ENTER> key when prompted to make dLITE memory resident. To create a new application, simply press one of dLITE's hot-keys which is not already in use. Since dLITE comes bundled with the Mailing List Manager on hot-key ALT-1, just press ALT-2. You will be warned that the DLITE.2 configuration file does not exist. Press <ENTER> to continue. Now move to the FILE option and press <ENTER>. Type an asterisk (*) for the Filename and press <PgDn>. You will be prompted for the name of the new data base. Since we already have a MAILLIST data base, let's call this file MAILLIS2 if you want to follow along. After typing the file name and pressing <ENTER>, you will be prompted for the field names, types, and lengths for the various data elements in the data base. Press <ENTER> to move to each new field. Type in the following field list: NUM FLD NAME TYPE FLD LEN FLD DEC --- ----------- ---- ------- ------- 1 LASTNAME C 18 0 2 FIRSTMI C 17 0 3 IDCODE C 15 0 4 CATEGORY C 20 0 5 SALUTATION C 30 0 6 COMPANY C 30 0 7 TITLE C 30 0 8 ADDRESS1 C 30 0 9 ADDRESS2 C 30 0 10 CITY C 20 0 11 STATE C 10 0 12 ZIP C 10 0 13 COUNTRY C 20 0 14 PHONE C 12 0 15 CONTACTDT D 8 0 16 CODE1 C 15 0 17 CODE2 C 15 0 18 CODE3 C 15 0 19 COMMENTS C 40 0 When you finish typing in all the field information, check your work! Then press <CTRL-End> and type Y to save the file. 36 5.2 Creating the MAILLIST Supporting Indexes From dLITE's Main Menu, select the FILE option and press <ENTER>. When prompted for the name of the data base, type in MAILLIS2 and <PgDn>. When the Main Menu reappears, choose the UTIL option and mark CREATE NEW INDEX true by typing Y. Then <PgDn>. The Mailing List application is distributed with three index files: FULLNAME, ZIP, and IDCODE. We obviously cannot name our new index files with the same names although what they index can be identical. Therefore, let's use FULLNAM2, ZIP2, and IDCODE2 for the file names. We will need to repeat the CREATE NEW INDEX process three times to create three indexes. The FULLNAM2 index is the more complex, so let's do it first. When prompted for the index file name, type FULLNAM2 and press <ENTER>. When prompted for the index expression, type the following: SUBSTR(TRIM(LASTNAME)+", "+TRIM(FIRSTMI)+SPACE(30),1,30) A word of explanation seems appropriate here. We need this index to be by last name, then a comma and space, then first name, middle initial. Therefore, we need to "trim" trailing spaces off the fields so we don't end up with entries like MUNDY WARD. The SUBSTRing function is used to make sure every entry in the index is exactly 30 characters long. Since it is possible that a person may be named SMITH, JOE we also need to "pad" the trimmed fields with a bunch of spaces to assure the INDEX will always have at least 30 actual characters to work with. For the other indexes, enter the file names ZIP2 and IDCODE2. For the index expressions enter the actual names of the fields to be indexed, i.e. ZIP and IDCODE. Note, we do NOT enter ZIP2 for the index expression since there is no ZIP2 field. 5.3 Creating the Main dLITE Initialization File Using any ASCII editor, you can review the contents of the dLITE initialization file, DLITE.CFG. The contents are as follows: WINLIN="21" WINCOL="80" *SET PATH TO C:\DLITE SET EXACT OFF TONES=.T. SPECCOLOR=.F. COLORS=",, /W" LPTINIT="" LPTRESET="" 37 Note that you do not pick a data base in the dLITE initialization file. That entry belongs in the application configuration file discussed next. Command lines which begin with an asterisk (*) are comments and are ignored by dLITE's interpreter. If you want to hard-code dLITE's PATH rather than using the DOS PATH as dLITE's PATH, then you could remove the asterisk from that line, assuming you have stored all the dLITE files in C:\DLITE. This would require that you move to the C:\DLITE directory to start dLITE at the DOS prompt if this directory is not also in the DOS PATH. The WINDOW specifications provide for the maximum size window for data entry in ADDREC and EDIT mode as well as for data display in DELETE and UNDELETE mode. This should be left alone. If you want to make the window smaller, do it within the application configuration file. However, if you do it in one application, you will need to specify the WINDOW specs in every other application configuration file to assure that the WINDOW is reset to the proper size in each application. TONES is set to .T. which means dLITE's beautiful music is ON. If you want to turn it off, change this entry to .F. SET EXACT OFF means that comparisons in finding matching records are evaluated up to the length of the data in the search field rather than the total length of the field. For example, entering John as the search specification for LASTNAME to find would retrieve Johnson. Custom colors are described in another section of this documentation. The line printer initialization and reset variables allows entry of a string to be sent to the printer before and after print jobs. Additional SET commands could be added to this file to meet your individual requirements. See the appendix for a complete listing of available commands. 5.4 Creating the Application Initialization File You will need to use an ASCII editor to create this file. Or you can type it from the DOS prompt by opening a DOS file with the following command: COPY CON DLITE.2 <ENTER>. When you have finished typing in the lines below, press CTRL-Z <ENTER> to save the file. Which application initialization file you create determines which hot-key this application will reside on. Since we mentioned ALT-2 previously, let's stay consistent. 38 This means the file name will be DLITE.2. Crank up your friendly editor, and enter the following commands. Then save the file naming it DLITE.2. FILENAME="MAILLIS2" WINLIN="21" WINCOL="80" SET EXACT OFF TONES=.T. 5.5 Creating the MAILLIST Configuration File The Mailing List Configuration File defaults to the following name: MAILLIS2.CFG. We could have changed this by adding a line in the application initialization file which said something like CFG_SPEC="MAILLIS2.XYZ". Using your favorite editor, type the following commands into the MAILLIS2.CFG file: INDXNAME="FULLNAM2,IDCODE2,ZIP2" LEADINDX="FULLNAM2" Note that we have set up the indexes here rather than in the application configuration file. This is pretty much up to you. It is probably more desirable to at least set the LEADINDX in the file configuration spec since you may have multiple applications using the same data base with different lead indexes. 5.6 Creating the Data Entry Screen The data entry screen's file name defaults to MAILLIS2.FMT. This, too, could have been changed by including the FMT_SPEC memory variable in the application configuration file with a file name of your choice. You may type the following information into your MAILLIS2.FMT file or merely copy the MAILLIST.FMT file which is where this data came from: 39 @ 0,0 SAY "Record "+LTRIM(STR(RECNO(),5))+" of"+ LTRIM(STR(RECCOUNT(),5)) + IIF(DELETED(), '** DEL **','') @ 1,0 SAY " dLITE Mailing List Manager" @ 3,0 SAY " Last Name: First Name MI:" @ 5,0 SAY " ID Code(s): Category Code(s):" @ 7,0 SAY " Salutation Title" @ 9,0 SAY " Company: Phone:" @ 11,0 SAY " Mail Addr:" @ 13,0 SAY " City State Zip " @ 15,0 SAY " Contact Dt Comments" @ 17,0 SAY " Code1 Code2 Code3" @ 3,17 GET LASTNAME PICTURE "XXXXXXXXXXXXXXXXXX" @ 3,53 GET FIRSTMI PICTURE "XXXXXXXXXXXXXXXXX" @ 5,17 GET IDCODE PICTURE "XXXXXXXXXXXXXXX" @ 5,53 GET CATEGORY PICTURE "XXXXXXXXXXXXXXXXXXXX" @ 7,12 GET SALUTATION PICTURE "XXXXXXXXXXXXXXXXXXXXXXXXXX" @ 7,50 GET TITLE PICTURE "XXXXXXXXXXXXXXXXXXXXXXXXXX" @ 9,12 GET COMPANY PICTURE "XXXXXXXXXXXXXXXXXXXXXXXXXX" @ 9,53 GET PHONE PICTURE "XXXXXXXXXXXX" @ 11,12 GET ADDRESS1 PICTURE "XXXXXXXXXXXXXXXXXXXXXXXXXX" @ 11,46 GET ADDRESS2 PICTURE "XXXXXXXXXXXXXXXXXXXXXXXXXX" @ 13, 6 GET CITY PICTURE "XXXXXXXXXXXXXXXXXXXX" @ 13,34 GET STATE PICTURE "XXXXXXXXXX" @ 13,50 GET ZIP PICTURE "XXXXXXXXXX" @ 13,67 GET COUNTRY PICTURE "XXXXXXXXXX" @ 15,12 GET CONTACTDT PICTURE "99/99/99" VALID CONTACTDT<=DATE() @ 15,34 GET COMMENTS @ 17,10 GET CODE1 PICTURE "XXXXXXXXXXXXXXX" @ 17,34 GET CODE2 PICTURE "XXXXXXXXXXXXXXX" @ 17,58 GET CODE3 PICTURE "XXXXXXXXXXXXXXX" A few words of explanation may help. First, if a PICTURE command is nothing more than X's, then it can be left out since that is dLITE's default. The screen above was generated using MenuMaker which automatically includes the PICTURE command for every field. Second, every line must begin with @. The second line is merely a continuation of the first line which would not fit correcly in this manual. Finally, note that the GETs could have been included on the same line as the SAYs. In this case, the location of the data entry field will be one space to the right of the last character of the SAY prompt. 40 5.7 Creating the PASTE File Specification The paste file spec file name defaults to MAILLIS2.PST. This can be changed by including the PST_SPEC memory variable in the application configuration file with a file name of your choice. Type the following information into your MAILLIS2.PST file or merely copy the MAILLIST.PST file which is where this data came from: PASTE TRIM(FIRSTMI)+" "+TRIM(LASTNAME)+CHR(13) PASTE ADDRESS1+CHR(13)+ IIF(ADDRESS2<>SPACE(30),ADDRESS2+CHR(13),"") PASTE TRIM(CITY)+", "+TRIM(STATE)+" "+TRIM(ZIP)+" "+ TRIM(COUNTRY)+CHR(13)+CHR(13) PASTE "Dear "+TRIM(SALUTATION)+":"+CHR(13)+CHR(13) KEYBOARD CHR(27) Note that all lines in the PASTE file should begin with the word PASTE. The continuation lines are necessary only for purposes of printing in this User's Guide. We already have discussed use of the TRIM() function to remove trailing spaces from fields. The only new function used here is the immediate IF function, IIF(), which is used to determine whether the second line address is blank and whether to paste this field into the foreground specification. The last line stuffs the keyboard buffer with an ESCape code to make dLITE disappear after the paste is completed. 5.8 Creating the OUTPUT File Specification The output file spec file name defaults to MAILLIS2.OUT. This can be changed by including the OUT_SPEC memory variable in the application configuration file with a file name of your choice. Type the following information into your MAILLIS2.OUT file or merely copy the MAILLIST.OUT file which is where this data came from: DISPLAY LASTNAME,FIRSTMI,CITY,PHONE WHILE .NOT. EOF() OFF Note that the selection criteria are NOT entered into the output file spec. These are provided by the user at run- time. dLITE itself will set the necessary filter before executing the output file spec. The WHILE .NOT. EOF() instructs dLITE to process the DISPLAY command for every record meeting the search criteria until end-of-file is reached. 41 The OFF keyword instructs dLITE not to display record numbers for the records which qualify for output. Removing the word "OFF" would add a display field for record numbers of each record which qualifies for output. Note that the OUTPUT file spec could also be used to PASTE information for multiple records into a foreground task. In this case, the developer would substitute the word "PASTE" for the word "DISPLAY." Do not use the OFF command with PASTE. In addition, the WHILE .NOT. EOF() expression is required if multiple record output is desired. 5.9 Creating OUTPUT Initialization and Reset Files The output initialization file name defaults to MAILLIS2.INI. This can be changed by including the INI_SPEC memory variable in the application configuration file with a file name of your choice. Type the following information into your MAILLIS2.INI file or merely copy the MAILLIST.INI file which is where this data came from: OUTINDX="FULLNAME" SET EXACT OFF SET HEADING ON The initialization file is used to "set up" the output job before it is run. The OUTINDX memory variable allows the developer to set the lead index for the OUTPUT job without disturbing the current lead index used for data entry. If no OUTINDX is specified, then the current LEADINDX will be used to order the output. SET EXACT OFF determines the type of record matches which are made with the selection criteria. SET HEADING ON specifies that field name headings will be displayed above the DISPLAY output. If the developer specifies SET HEADING OFF then no field headings are displayed. 42 APPENDIX A -- Listing of dLITE-Supported Commands @ row,col SAY <expr> PICTURE <expr> ACCEPT <prompt> TO <memvar> AVERAGE <fieldlist> FOR <expr> WHILE <expr> TO <memvarlist> CLEAR CLEAR GETS CLOSE DATABASES CLOSE WINDOW <window name> CONTINUE COUNT <scope> FOR <expr> WHILE <expr> TO <memvar> DELETE <scope> FOR <expr> WHILE <expr> DIR <path><filespec> DISPLAY MEMORY DISPLAY STATUS DISPLAY STRUCTURE FIND <char string> GO <record number> GO TOP GO BOTTOM INDEX ON <expr> TO <filename> INPUT <prompt> TO <memvar> KEYBOARD <expr> LOCATE <scope> FOR <expr> WHILE <expr> PRIVATE <memvarlist> PUBLIC <memvarlist> READ RECALL <scope> FOR <expr> WHILE <expr> REINDEX RELEASE <memvar> REPLACE <scope> <field> WITH <expr> FOR <expr> WHILE <expr> SEEK <expr> SELECT <workarea/alias> SET <parameter> <value> (See Appendix B) SKIP <numeric expr> SOUND <freq>,<duration> STORE <expr> TO <memvar> STORE <exprlist> TO ARRAY <memvar> SUM <scope> <exprlist> TO <memvarlist> FOR <expr> WHILE <expr> USE <filename> INDEX <indexname(s)> ALIAS <aliasname> WAIT WAIT TO <memvar> 43 APPENDIX B -- Listing of dLITE-Supported SET Commands SET BELL ON/OFF SET CENTURY ON/OFF SET COLOR TO <std>,<enhanced>,<border> SET DECIMALS TO <numeric expr> SET DELETED ON/OFF SET EXACT ON/OFF SET FILTER TO <expression> SET FIXED ON/OFF SET HEADING ON/OFF SET INDEX TO <file list> SET KEY <numeric expr> TO <char expr> SET KEYS ON/OFF SET ORDER TO <numeric expr> SET PASTEDELAY TO <numeric expr> SET PATH TO <directory path list> SET STATUS ON/OFF SET WINDOW TO <char expr> POSITION <row,col> SIZE <hght,width> SET WINDOW NEXT 44 APPENDIX C -- Listing of dLITE-Supported Functions ABS(numeric expr) ASC(char expr) AT(exprA,exprB) BOF() CDOW(date expr) CHR(numeric expr) CMONTH(date expr) COL() CTOD(char expr) DATE() DAY(date expr) DBF() DELETED() DOW(date expr) DTOC(date expr) EOF() EVAL(char expr) EXP(numeric expr) FIELD(numeric expr) FILE(filename) FOUND() GETENV(char expr) IIF(logicexpr,exprA,exprB) INKEY() INT(numeric expr) ISALPHA(char expr) ISDIGIT(char expr) ISLOWER(char expr) ISUPPER(char expr) KEYEXP(numeric expr) LASTKEY() LEFT(char expr,numeric expr) LEN(char expr) LOG(numeric expr) LOWER(char expr) LTRIM(char expr) LUPDATE() MAX(numexprA,numexprB) MEMORY() MIN(numexprA,numexprB) MOD(numexprA,numexprB) MONTH(date expr) NDX(numeric expr) RADIX(numeric expr,radix,width) RAWKEY() READKEY() RECCOUNT() RECNO() RECSIZE() REPLICATE(char expr,numeric expr) RIGHT(char expr,numeric expr) ROUND(numexprA,numexprB) ROW() 45 RTRIM(char expr) SPACE(numeric expr) SQRT(numeric expr) STR(numeric expr,length,decimals) STUFF(char expr,start,num,newdata) SUBSTR(char expr,start,num) TIME() TRANSFORM(expr,picture) TRIM(char expr) TYPE(char expr) UPPER(char expr) VAL(char expr) WCOL() WHEIGHT() WROW() WWIDTH() YEAR(date expr) 46 OTHER PRODUCT OFFERINGS WAMPUM 4.2 -- The Ultimate dLITE Companion "A picture is worth a thousand words" goes the old adage. Unfortunately, adding pictures to data bases always has been a $1000 proposition ... until now! We are pleased to announce the marriage of industry-standard, dBASE- compatible data bases with industry-standard .PCX-compatible graphics. WAMPUM 4.2 allows even novice computer users to incorporate pictures, signatures, or any other graphics images in a standard dBASE data base. And WAMPUM can be loaded as a 20K TSR keeping it one keystroke away from your favorite text-based applications. Single-user licenses remain $50 while unlimited-user network licenses are $150. Registration entitles users to 90 days free technical support by phone, mail, or BBS plus the latest WAMPUM version of their choice. Considering that WAMPUM 4.2 was developed and runs in a non-graphics software environment today, we hope you will give it a careful look. There is no other data base product for under $1,000 that even comes close in terms of features or graphics support much less the ability to load as a 20K TSR. A detailed product summary follows. One of the data base granddaddy's of the ShareWare revolution, WAMPUM provides the richest assortment of data base management functions for the lowest cost of any data base product in the world! With version 4.2, WAMPUM can be loaded as a "pop-up" TSR occupying less than 20K of RAM while your other favorite programs remain active in the foreground. It provides fully-relational, menu-driven data base manage- ment using dBASE III-compatible data bases. Virtually all features of the dBASE language are supported including dBASE-compatible reports and labels. Plus WAMPUM adds a host of features of its own including PowerBrowse (a spreadsheet- like data base manager), Form Letters, a Phone Dialer, and many other original touches too numerous to mention. And now WAMPUM supports creation of GRAPHICS DATA BASES with picture fields using .PCX-compatible graphics files. Computer Shopper hailed WAMPUM as "a gift-horse you can afford to look in the mouth." WAMPUM's form letter generator was rated by Data Based Advisor as the "only tool you'll ever need." And PC World rated WAMPUM as "comparable to dBASE III in features and power." System requirements: 512K PC with DOS 2.1 or higher and a hard disk. Automatic record and file locking network support is provided with 640K and DOS 3.1 or higher. Display of graphics fields requires a VGA, EGA, or Hercules-compatible graphics card and monitor. 47 WARD MUNDY SOFTWARE, 4160 CLUB DRIVE, ATLANTA, GA 30319 C U S T O M E R I N V O I C E +----------------------------------------------------------+ |Customer: |Order Date: | | |----------------------| | |Shipped Dt: | | |----------------------| | |Invoice No: | | |----------------------| | | | +----------------------------------------------------------+ +----------------------------------------------------------+ |QUANTITY |DESCRIPTION |UNIT PRICE| AMOUNT | |---------|-------------------------|----------|-----------| | | dLITE License Fee perPC | 25.00 | | | | | | | | | MenuMaker for dLITE | 20.00 | | | | | | | | | dLITE Developer's Vers | | | | | & Developer's Guide | N/C* | | | | | | | | | dLITE 2.0 ShareWare Disk| 5.00 | | | | | | | | | WAMPUM-D Single User | 50.00 | | | | | | | | | WAMPUM-D Network Lic | 150.00 | | | | | | | | | WAMPUM Soft-Bound Manual| 20.00 | | | | | | | | | WAMPUM ShareWare Disk | 5.00 | | | | | | | | | Foreign Shipping Surchg | 5.00 | | | | | | | | | Shipping & Handling | 5.00 | 5.00 | | | |----------|-----------| | | | TOTAL | | +---------------------- Thank You!-------------------------+ TERMS: Please make checks payable to Ward Mundy, 4160 Club Drive, Atlanta, GA 30319. Checks in U.S. dollars drawn on U.S. banks only please. VISA/MasterCard orders must include card type, card number, expiration date, and signature. * Latest Developer's Version and Documentation are free with registration provided the correct shipping and handling fee accompanies order.