Simtel MSDOS 1992 December

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

/ Simtel MSDOS 1992 December / simtel1292_SIMTEL_1292_Walnut_Creek.iso / msdos / turbopas / turbogen.arc / TURBOGEN.MAN < prev

Wrap

Text File | 1988-01-28 | 39KB | 935 lines

Background After sorting through several Turbo-Pascal libraries (to many at that), and adding some custom utilities I came up with several standard libraries for myself. Then I purchased Turbo DataBase Toolbox and was very impressed with its ease of use. After incorporating my libraries and completing about one third of the first full sized DBMS application I realized that the code I was writing would have to be written over and over for every application I would generate in the future. Somewhere in my early computer days I was taught that computers are best used for any repetitive tasks. Sooo, I took that first DBMS and used it's format to create the TurboGenerator. There are many routines contained in the Library that are not called from TurboGen. You could cull them out of your finished products. I have tried to keep the original code as intact as possible, but modified to work within the structure of TURBOGEN. At any rate you should study the libraries and become aware of what is there so you don't end up reinventing the wheel. Some people have commented about the time required to convert function keys into their common names as opposed to using the decimal or other non-string values. I have used this method in the interest of finished code readability. Mainly for the person using TurboGen and needing to study his final code. The technique used here makes the code read like a novel even to a non-pascal programer. 0 Introduction Having worked with several 4th level development packages I stole the best (to me at lest) features of each and included them into this package. TurboGenerator will create Turbo Pascal source code to handle - User IO, File IO and error checking the format of which is defined by way of a user designed screen. During the screen design phase the user paints the screen with background and field descriptors. The TurboGenerator takes over and creates record structures, variables, procedures and functions for displaying background, current data, as well as data entry/updating. The file IO handlers create code designed to maintain keys, locate records, add new records etc. One of the utilities that I developed/modified is designed to allow real time processing of function keys. The concept is one of a data screen format which allows the user to wander to any AVAILABLE field on the screen for entry/update. During this interaction function keys are used to perform such task as cursor movement, calling help, paging forward or backward through the file, etc. The data entry routine handles some of the basic input/editing function. You can write custom code to allow function keys to trigger any type of procedure or function desired. The crossreference utility was a standard lister/crossref utility but I was always waiting for the crossref to print even when I didn't need a new one. So while I was making that selectable I worked out a VERY BASIC handler for indenting. This works for the way I indent, and can be very useful in locating errors. This is not a complete indenter. However if the capabilities are kept in mind while writing custom code it will work very well. I know many of you will turn a eyebrow at the wide print option. I just can't stand trunicated lines on a listing, wasting all that blank paper on the right margin. And it makes many sections of INDENTED code easier to read. When I was forced to do windows (I fought like crazy, we all make mistakes) I turned to the Public Domain PibTerm library I got somewhere. Sorry but I really can't remember where for sure so I better not give somebody false credit. At any rate the routines in PibMenus and Pibscreens are really not bad to work with. They execute smoothly and are not hard to finger-out. So I used them when designing my Menu generator, after some modification. So now lets say you have created code for a data file, with a menu, and help screen. 1 How to put it all together. Either use include commands or block copy/read them into one file. It really matters little except if working with more than one data file. You will notice that each data code file created has the compiler directives, include statements, etc. in it. Well we cannot duplicate that and some other work. Well rather than complicate your life at run time we simply create everything you might need and let you delete or selective copy as you wish. This selective copy was used to solve the OUTPUT/ Report generator needs. Which you will notice are missing from the system. I have two problems with every report generator I ever look at: 1. They are so basic they don't let you do the job. 2. They are so complex you spend to much time designing your report. a. When done they run very slow. After considerable thought hairpulling and other inspiring efforts I have concluded that I can do no better than anyone else has todate. Therefore I will continue to write my reports in source code for speed and flexibility. We can expedite things here a bit though. If you look at the procedures generated for displaying records on the screen you can see that you can copy fields as needed and change the output device as needed. Well that's some help anyway. The libraries provided are the same code used to develop TurboGenerator. You could use it to develop your own generator just in case my idea of good is not your idea of good. I have tried to keep the routines in the libraries intact with regard to author and giving credit. Please look carefully at these files and give credit where credit is due. 2 Requirements You will require the following in order to run TurboGen. 1. IBM-PC or Clone. 2. Dos 2.11 or above (MS or PC) 3. RAM .?? depends on how many fields you have defined. 4. Turbo Pascal Version 3.x 5. Turbo Database Toolbox. Files used TurboGen.com - Main program TurboGen.000 - Main program overlay *.TGS - TURBOGEN Screen file (ASCII) *.FLD - Screen field list. *.GEN - Output file from TurboGen (Data) *.MNU - Output file form TurboGen (Menu) *.HLP - Output file from TurboGen (Help) CrossRef.com - CrossReference Main Program CrossRef.000 - CROSSREFERENCE overlay *.FMT - Output from crossref formated output. Starting TurboGenerator Copy TurboGen onto harddisk directory or onto a working diskette. At harddisk directory or with working floppy in default drive enter. TURBOGEN <cr> TurboGen will comeup with its signon screen.... You will have to provided a file name and indicate the type of code you wish to generate. When the screen is complete turbo will do it's stuff. You will have to check each chapter for what kind of stuff will be done. After completeing a task the program will return to a system prompt. 3 Data file code generation After providing a file name and pressing <D> for Data for the type of code TurboGen will clear the screen and wait for you to design your screen. Do not be alarmed about seeing only a cursor on this screen. We have granted you the entire screen to work on. This eliminates TurboGen from having anywhere to display current cursor coordinates, helps, etc. If you feel the need for online help just press F9 the help key. You will be presented a list of control keys and their purpose. We will describe these keys in just a few moments. BACKGROUND TEXT: Simply move the cursor (with the arrow keys) to the starting location for your text. Then type the text you wish. You will see it appear on the screen. DEFINE FIELD: (F1) After moving the cursor to the exact starting location for a field press F1 to define a field. A window will open into which you will describe the field being defined. As such: Field Name: You are given 10 characters to create a unique field name ( unique for this record). If not using record structure then it is your job to know about dups from other code you may want to use. If 10 spaces is not enough then make do and edit the finished code. Record Name: This is really for future expansion of the system. We hope to allow building more than one record construct on the screen and the proper fields will be listed within the proper record(s). Right now all fields are listed under one record. Which is the contents of record name in the first field on the screen. 4 Type: x,X are strings; X force uppercase on entry; I is integer; R is real; B is Boolean; Ok so I don't have very many data types available, but when you think about it compound structures are made up of these simple ones. And what we are really wanting out of TurboGen is the housekeeping code anyway. Just make a dummy for any compounds you need then edit code before creating that data file. We do expect to modify the system in the future to allow more flexibility in this area. Length: The number of characters allowed. Must be greater than 0. For boolean this will be set to 1 for you and this field skipped. Decimals: The number of decimals for real fields. Only used if type is R. Confirm: Does user have to press a key to indicate field completion or does the system advance to next field after receiving LENGTH characters? After completing the last data item on this window the system will save your field somewhere in it's confines and remove the window showing your original screen with a new addition. You will see a line of underscores representing your defined field. There are LENGTH number of underscores starting at the location you placed the cursor on before pressing F1. 5 EDITING FIELDS: Field editing is very limited with this version. I hope to return to this issue and greatly enhance. But for now you place your cursor on the FIRST underscore of a defined field and press F1. This will display the field as last defined. You are able to alter any data item....but you cannot alter the screen location for a field. (I said I'd get back to it). Well your field is now added to the list and you may proceed to another location on the screen for background or field design work. You may have already noticed that the system checks for duplicate names FOR THE CURRENT SCREEN only. This means that if you are incorporating several other sections of code, TurboGen has no way of knowing variable usage in the foreign code. REPLICATING FIELDS; If you are doing a row(s) or column(S) of fields within a screen. We have provided a vehicle for quickly creating all the fields necessary IF THE FIELDS WILL HAVE EXACTLY THE SAME TYPE (r,i,x,X,b). You can also use this technique to create the fields then alter the type declarations to be arrays, then search&replace the field names with the array names. In any event you place the cursor on the first underscore of the field you wish to replicate. Pressing CTRL-F1 will reward you with a window asking which direction and count you require. Then fields appear on the screen. If you look at these fields TurboGen has used the cursor location appended to the first char of the source field as the field name.... DELETING FIELDS; Move the cursor to the first underscore of field to delete and press F1 as if you were going to edit the field. Blank out the field name and press <ESC> key. LISTING FIELDS (F2); Pressing F2 will open a window into which is printed a list of the currently defined fields. 15 fields at a time are listed. SAVING SCREEN (F3); 6 System will write the background text to filename.TGS and any fields defined will be written to filename.FLD. Filename being the filename provided at startup. You will see the underscores for defined fields disappear from the screen. When they reappear the process is complete and you may proceed. LOADING SCREEN (F4); This function key will present a small window with the current filename in it. If the filename is correct press return. If not correct then enter A EXISTING *.TGS file. You do not enter the extension. The filename given becomes the current default file. The TGS files are ASCII files but the system only loads files with TGS extensions. After finding (or not finding) the background screen file, TurboGen looks for the filename.FLD (fields) file. If found that is also loaded and the fields therein will appear as underscores on the screen. This IF EXISTING construct allows you to create ASCII screen files with any editor. Then pick up that file with TurboGen and add fields as needed. PRINTING SCREEN DOCS; This will print the background screen text (screen dump). It then lists all defined fields showing cursor locations, name, type, length, decimals and confirm to the current list device. INSERT NEW LINE (Ctrl-S); Ctrl-S creates a new blank line at the current cursor location. All lines on or below the current cursor location are moved down one line with the bottom line moving into that big lost line in the sky (text and fields). DELETE LINE (Ctrl-D); Ctrl-D moves the current cursor line to that big lost line in the sky and raises all lines below, up one. Which of course creates a blank line on the bottom of the screen. ERASE (BLANK) SCREEN (F8); Want to start all over, Press F8. The current file and code type remain the same. 7 HELP (F9); BUSINESS GRAPHICS (F10); This is a toggle. The bottom (25th) line will show a new definition for the function keys. Pressing arrow keys to move the cursor will draw a line in the Double Line Graphics characters. Pressing the proper function key will provide the corners, junctions etc. INS / DEL CHARACTERS; The INS and DEL keys are to Insert / Delete the character under the cursor. These keys can allow you to move a field somewhat on the screen. When used along with Ctrl- S and Ctrl-D you can do quite a bit of screen editing. But still not the best it can be. DESIGN OF SCREEN COMPLETE: When you are happy with your creation and want to generate some code, press the End key. I hope you have saved your creation. Although not a requirement it will save time if you have to modify a screen for some reason. If you find yourself modifying a screen don't forget to adjust for any custom code you may have provided to the first version. Or simply block copy the new background, display and get procs into the old code. Your code will be found in the file filename.GEN. ABORTING: If you find yourself at the design screen and wish to abort without writing code to a file. Just press CTRL-END. NOTICE: TURBO TOOLBOX CONSTANTS: The TOOLBOX requires several constants be declared and before compiling you should extract the record structure, create a short program to report the SIZEOF(record) as described in the TOOLBOX manual. Then take this size to the SETCONST.PAS program and create an include file for the constants needed. I just block read this into the 8 program file just before the ACCESS.INC include statements. If you are fuzzy about what is going on here you had better read your TOOLBOX manual a bit more. These constants are VERY IMPORTANT to the proper execution of your program. Turbogen creates a file of *.SIZ which you can use for the above sizeof task. However, this file has it's own record structure and if you have changed the record constructs in your main code then those same changes have to be made here. I use this SIZ file only on the simple one record one file screen I set up. Another note of interest is to run this SIZ file through Turbo (RUN) for any system you create which will deal with more than one data file. In other words check the sizeof on all record constructs and keys for those records. You'd be surprise the number of times systems have gone out to lunch because someone added that little extra data file and it dictated a change to the b-tree constants but was not actually checked...... MAKING DATA FILES: There are different schools of thought on this and my mind is made up. At least this is what I find safest. You see the Toolbox manual and most database environment provide you with a method of opening files and if the file does not exist then one is created. Well I have had some problems with clients losing large data files because some off the wall error caused the application to think the file was not there and made a new empty one. OUCH! Yeah I know the program is suppose to know the difference between no file and drive not ready or some other such error, and why not ask the user for permission before making that new file. I have tried them all and still some fluke causes an accident. From: the programer never expected a FAT table error so didn't trap it, to the user didn't know, when he answered your prompt, that the file would be erased. In light of these hairpulling (I ain't got much hair left.) sessions I have adopted the following for my file creation and opening procedures. First time a piece of code is run the open command is altered to a make command. Then the command is changed to an open command. If the make is nowhere in the code how can we remake a file? Now after initial debugging and testing the make is again reissued to create blank empty usable data files. Then a decision has to be 9 made. Do we give the user blank files to work from or, create a special utility program which will make files as needed but NOT BE AVAILABLE during normal running. There are times when you may need one or the other and times when some other course will be needed but I have written hundreds of DBMS applications and have found the need to create data files in only one application. And that creates to a scratch file for independent processing and later merging into the master file. Therefore we still never make the master file within the runtime code. KEYS: Another of those things that I want to cleanup is the methods employed to handle keys. I made a decision to handle only strings in this version. Too many other functions to cleanup. Then I would go back and allow integer as well as string key fields. Well I haven't gotten back in yet, but I will. So here are the rules for now. 1. The first field on the screen is assumed to be your key. 2. The key field should be string type only. Now that I have laid those limitations on ya lets take a closer look at them. Number 1 is not carved in solid rock as you are generating source code so if you want multiple fields in your key then just move things around in the source a bit. 10 Number 2 says you should define it as string type. Once again you can go into the source and tickle any way you like. JUST KEEP YOUR KEYS STRINGS. If you take a look at the source you will see Turbogen created a global variable called <filename>KEY of the length of field number 1. This is the real file key and any changing you make to field IO should end up here as string data before file IO. COMPILING: Now with your source code generated, the toolbox constants set (correctly), load turbo and compile & run the code (hint: <filename>.GEN). Then don't forget to change the make to an open or just leave it until initial testing is complete in case you have to change your record structure. If you do that then you didn,t do your homework. MULTIPLE DATA FILES; Generate each one separately. Then write or pick one piece of code as the main program. Modify the Generated code so as not to duplicate the includes etc, make it an overlay and include into the main program. Then use TurboGen to generate a MENU to control access to each datafile overlay. This works if you do not need common access to each. If common access is needed then proceed as above because you still will do data entry/updating on a file by file basis for most files. Like the customer file. You will add/update/delete customers from this overlay. But during Invoice entry you may need access to the customer record by customer number to properly address invoice and check customer balance or status. In this case you can do basic file maintenance from the overlay. Except you should pull out the CUSTOMER_FIND procedures, and the customer record declarations and place them in the global area of the main program. Now when you need to locate a customer simply input customer number pass it to the customer find proc which either loads the record or clears out the customer record buffer on a not OK condition. This way you have file records global to all your code and still allow individual file updating to be off on overlays. 11 TYPICAL PROGRAM STRUCTURE; Toolbox Constants; Toolbox includes; TYPES; File1type record = field1 : string[??]; . . fieldN : end; File2type record = field1 : string[??]; . . fieldN : end; Var; file1 : file1type; file1key : string[??]; file1file : datafile; file1index: indexfile; file2 : file2type; file2key : string[??]; file2file : datafile; file2index: indexfile; (*$I Globtype.GEN *) (*$I LIBRARY1.GEN *) (*$I PIBSCREN.INC *) (*$I LIBRARY2.GEN *) (*$I PIBMENUS.GEN *) Any specialized record location and retrival for files 1 & 2 that might be needed by all. Overlay file1.gen overlay file2.gen begin (* main menu driver here *) end. 12 Error Handler The error handler is located in the Library2.GEN file. It is broken into two different procedures. Ioerror and Data entry error sections. There is an interrupt 24 error handler that pibscreen uses but I have not had time to make full use of this great vehicle. Now the two error handlers are broken up so you can tickle the data entry errors as you see fit. You should not have to do much to the file IO handler. But for each application you should change the application dependent error messages as you see fit then call showerror pointing to the proper numbered message. Take a quick look at the code and this should be clear. 13 Menu Generation This is about as straight forward as we can get. Enter your filename at the signon screen and press M for menu type code. Then simply fill in the menu data screen. MENU TITLE This is the menu title text string which appears within the box frame surrounding the menu. If you do not wish a title just leave blank. HOW MANY MENU ITEMS: This sets up lots of different loops both during code generation and during menu runtime. It is simply the number of items on the menu. DO NOT COUNT QUIT. The quit is handled for you by the system. MENU ROW/COL: Just the upper left corner of the menu window. The width and height are automatically handled by Pibmenus. BUT you do have the ability to override this by altering the HEIGHT & WIDTH variables within the finished menu code. If you make these variables non zero then Pibmenus will use your values and not it's own. DEFAULT MENU ITEM: Which menu item to highlight when menu is first called. You may notice that the code resets this default value within it's own loop. Well this is because of a problem with a not so close clone in my domain. That machine does not allow my full use of the screen saving options in Pibscreens. Since I can't stack screens, and need windows, I just reactivate windows already on the screen. This only makes sense if the menu picks-up where the user left off. 14 This brings up a point the library provided can be modified to do some real impressive windowing and screen saving work. But this is real RAM expensive so you may want to try it before you commit yourself. This system assumes a RAM shortage and does not stack screens. This is in keeping with a DBMS which needs data area not stacked screen RAM. But since RAM is cheap why not. Check the help screen chapter for more information on saved screens. After completing the Menu Data Screen press <END> and you input the menu text for each menu item followed by the actual call made for that menu item. You do this for each menu item up to your number of menu items. YOU DO NOT HAVE TO INCLUDE OR ALLOW FOR <QUIT>. The quit option on menus is automatically handled for you as the Menu count +1 item on the menu. When you have entered the last menu item and associated call, TurboGen will write your menu to Filename.MNU. Which you include as necessary. You should take a short look at the menu code before including or using. You should note that TurboGen has created a DUMMY procedure for every menu call you provided. A dummy procedure is simply the procedure name with a begin/end. This is to allow the proper compliation of the menu code and apparent oper DATA but no real work is done until the dummy procs are replaced or completed. CALLING A MENU: The menu you created will be in the file filename.MNU. With filename being the file name you entered at startup. That same file name is used in creating the menu procedure. Example: Assume you entered MAIN as a filename at TurboGen startup. Your menu code would be located in the file MAIN.MNU. The main procedure within that file is called MAIN_MENU. So to use you simply include into your application with: (* $I MAIN.MNU *) Then when needed, you access your menu by: MAIN_MENU; Help Screen Generating; I am one of those programers who feels strongly that a software package should carry it own help ONLINE. Well there are several was to do this and most of the time you can give one hell of a lot of help with an entire screen of data. This help screen generator is just that ONE SCREEN. If you want pages or scrolling then use some of the text file access methods mentioned in many of the books and articles on Turbo. Or use TurboGen to make a datafile of help records. Which are displayed in a window.... This is a add-on that helps with that one page help screen. Just start TurboGen and after giving a file name press H for help code generation. You will be presented a blank screen. You may not define any fields here. Just enter background text as in data file generation. When screen is complete you press <END> and your code will be written to filename.HLP. The procedure is called HELP_filename. This procedure will handle the display of and processing of - Press any key to continue. Which is used to allow the user time to digest the help screen.