Programmer 7500

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

/ Programmer 7500 / MAX_PROGRAMMERS.iso / PASCAL / MADTRB1.ZIP / TSIPP1.DOC < prev next >

Wrap

Text File | 1986-03-04 | 40.5 KB | 989 lines

USER'S MANUAL ------------------------------------------------------ TURBO SCREEN INPUT PRE-PROCESSOR TOOLKIT Version 1.07 ------------------------------------------------------ Written by Chris E. Maeder March, 1986 This toolkit is PUBLIC DOMAIN. It is being distributed with the intended purpose of other Turbo Pascal users implementing all or part of it into their programs. It is free to anyone that wishes to use it with the hope that they also will contribute programs to other Turbo users. This toolkit is being continually updated. If you would like updates of this toolkit or other free Turbo Pascal software please feel free to contact me through: Madison IBM-PC Users' Group Turbo Pascal Special Interest Group P.O. Box 2598 Madison, WI 53701-2598 I would also like to invite you to join our users' group. We are an extremely active Turbo Pascal group and meet one night every month. If you have any urgent questions you can reach me at my home, at (608) 251-4967. Happy computing!! TABLE OF CONTENTS ----------------- Introduction...............................................1 Overview...................................................1 Software Engineering.......................................6 Shell Environments.........................................9 Notation..................................................10 Description of Toolkit Subprogram Files...................11 Description of Toolkit Utility Files......................16 Description of Files Used in the Example Application......17 Program Control...........................................19 Child Program Execution...................................20 Description of Screen Templates...........................20 Screen Template Generators................................26 Pre-Processor Alterations.................................28 Miscellaneous Notes.......................................33 Final Notes...............................................33 Page 1 I. INTRODUCTION I am a structural engineer. I found that every time I wrote another engineering program I would spend a week or two on the input routines. I thought that if I were to write a generalized input pre-processor that I could use over and over again then I could spend more time on writing engineering programs and not rehashing through the same input routines for each new program I wrote. This input pre-processor toolkit is the current result of my work. The example application in which the pre-processor is set up for is a composite beam analysis and design program that I am presently working on. II. OVERVIEW Good interactive input/output (I/O) routines make a program fun to use and also make a program reliable. For example, the user should not have to worry about crashing a program by making a simple typing mistake. Although it is impossible for the input routines to detect all input errors, careful input routines should catch the more common ones. A good strategy for a "user-friendly program" is to detect input errors as soon as possible and make it easy for the user to the correct mistakes. An input pre-processor helps a program become "user-friendly" by taking care of of all the input handling between the user and a application program. A input pre-processor can be thought of as one component of an application program. See the following diagram. Page 2 DIAGRAM OF A SIMPLIFIED APPLICATION PROGRAM _________________________________________________________ | | | PROGRAM SHELL | |_________________________________________________________| ^ ^ ^ | | | | | | | | | ______v______ ______v______ ______v______ | | | | | | | INPUT | | CORE | | OUTPUT | | PRE- | | PROGRAM | | POST- | | PROCESSOR | | | | PROCESSOR | |_____________| |_____________| |_____________| ^ ^ | ^ | | | | | | | | | | | | __v_____ | | __v_____ _|______ | | | _|______ | _|______ | | | | _|______ | | | INPUT | | |-------------- ------------>| OUTPUT | | | | DATA | |_| | DATA | |_| | FILES |_| | FILES |_| |________| |________| Observe from the above diagram that the input pre-processor is the visual interface between the user and the core program. The input pre-processor is used by the user to input data into an application core program. The core program then executes on that input data. A post-processor is used by the user to view the results of the core program's output. I should note that I am presently working on a post-processor for this toolkit. Page 3 I have listed below some of the advantages in using an input pre-processor in an application program like that depicted in the previous diagram: 1. To start with, breaking up a program into smaller and easier to understand subprograms is usually the single most important contribution to a program's quality. By using a separate subprogram to handle user input you then separate the application program into smaller, more manageable chunks. You will find that by separating the user interface from the actual core program, the entire application program begins to become more modular. 2. You will discover that your application program becomes more portable once you have separated the user interface from the actual core program. By "portable" I mean that the program can easily be made to run on a variety of systems. The core program can usually be transferred to another computer system quite easily. The user interface usually cannot be easily transferred, because of the machine specific routines that are generally used. Due to the rapid advancements in technology, today's personal computers will no doubt be obsolete within a few years. Thus a "portable" program will have a better chance of running on future personal computers as well as those of today, as opposed to a very machine specific program. Simply by separating the user interface from the core program one then needs to write a new user interface, not an entirely new program, when transferring his program to a new computer system. 3. Input error checking is easily implemented using an input pre- processor. More specifically, this particular pre-processor can check for: a. Specific character types for an entry (i.e., positive integer, positive real, etc.). b. Entry is within specific defined boundaries or the entry is one of a few select choices. c. Newly entered boundary conditions do not corrupt previously entered data. Page 4 4. Probably most important, an input pre-processor makes the application program extremely user friendly and fun to use. The user does not have to be concerned about crashing the program if he enters a bad piece of data, the input pre-processor will catch it for him and allow him to return to the bad entry and change it without having to restart the program. 5. Finally, a input pre-processor can furnish a visual interpretation of the user's entered data. For example, a bar chart or graph could be displayed by the input pre-processor as the user inputs data. This allows the user some visual feedback as he enters his data, helping him to spot input errors, trends, etc. What makes this pre-processor so powerful is that it is written and structured so that it can be quickly altered for a completely different application program. A few constants require changing, the screen template files have to be designed and written, and before you know it you have a beautiful input pre-processor for your own application program. Page 5 To help give you an idea how this program is structured I have shown in the diagram below one possible configuration for this input pre-processor in an example application. DIAGRAM OF A TYPICAL CONFIGURATION OF THE INPUT PRE-PROCESSOR ___________________________________________________________________________ | | | MAIN INPUT PRE-PROCESSOR PROGRAM | |___________________________________________________________________________| ^ ^ ^ | | | | | | | | | | _________ ____v_____ _____v____ _________ | _|_______ | | | | | _|_______ | | _|_______ | | | INPUT | | MENU | _|_______ | | | |INPUT | | |--->| PAGE |<-->| SUB- |<---|MENU | | | | |PAGE | |_| | SUB- | | PROGRAM | |TEMPLATES| |_| | |TEMPLATES|_| | PROGRAM | | | | |_| | |_________| |__________| |__________| |_________| | ^ ^ ^ | | | | | ------------ | ------------- | | | | | _____v____ ____v_____ ____v_____ | | | | | | | | | SCREEN | | ERROR | | FILE | | | I/O | | CHECKING | | I/O | | | SUB- | | SUB- | | SUB- | | | PROGRAM | | PROGRAM | | PROGRAM | | |__________| |__________| |__________| | ^ | | | | | | ____v_____ __v_____ | | _|______ | | INITIL- | _|______ | | | IZATION | | INPUT | | | | SUB- | | DATA | |_| | PROGRAM | | FILES |_| |__________| |________| Page 6 Notice in the previous diagram this input pre-processor toolkit is broken down into subprogram files. These subprogram files are mainly made up with program modules to afford program modularity. III. SOFTWARE ENGINEERING Let me talk a little bit about program modules and why they are so useful in writing code for a large program. One can think of a module as a type of black box, it does one thing and one thing alone and does it very well and everything it requires is contained within it. A module should be a small, single purpose unit within the program, with a narrow interface to the rest of the program. I say this because it is much easier to understand and change a small, single purpose module than a large, multipurpose, widely-interfaced one. Also, a should module hide its design from the rest of the program, so that only the module is affected if the programmer decides to revise the module's design. There is only one way to access a given module and that is through it's header. A specific set of parameters are passed to a module and a specific set of output parameters are returned. Note that functions and procedures within a module cannot be accessed externally. Also, modules allow the use of internal global variables within that particular module alone. Page 7 A module is constructed by encapsuling all the procedures, functions, and internal global variables for that module within one main procedure (using one lexical level). See below diagram. EXAMPLE MODULE Procedure DoItModule( FirstParameter, SecondParameter, Var ThirdParameter:ParameterType); Var InternalGlobalVar:VarType; Function DoItQuick; Begin { DoItQuick } . . . End; { DoItQuick } Procedure DoItGood; Begin { DoItGood } . . . End; { DoItGood } Begin { DoItModule } . . . End; { DoItModule } Page 8 Notice in the previous example that the module's input parameters were "FirstParameter", "SecondParameter", and "ThirdParameter". Similarly, the module's output parameter was "ThirdParameter". The above module has it own internal global variable called "InternalGlobalVar". This variable is only active within the module and is global to all the functions and procedures within the module. Observe also that the functions and procedures within the module can only be accessed when the module as a whole is accessed. Modules offer some very nice advantages when writing code for a large program. 1. First, modules help to minimize the amount of code the programmer needs to understand at one given instant. A module can be studied and changed without examining and/or re-writing the rest of the program. This is a great aid in debugging and modifying a program since once a module is debugged it usually can be treated as a "given" while the rest of the program is examined. 2. One will find that many times major changes are necessary in a program due to errors, changes in requirements, etc. These changes can have a widespread effect on the program if they were not anticipated ahead of time in the original program design. Thus we see that modularity helps to limit the "rippling effect" through a program as other parts in the main program change. 3. Finally, modularity usually results in decreased programming time for programs written later on. Some modules often can be reused in a number of programs, thereby preventing having to "re-invent the wheel". A word of wisdom--try to keep modules as flexible as possible so they will remain usable in a variety of situations, not just for the one for which they were first written for. For those of you who are interested, we've been talking about one small area in the subject of software engineering, a new and very exciting computer science subject. Page 9 IV. SHELL ENVIRONMENTS I would like you to note that you can use this pre-processor as part of a shell environment (like TopView without the multi-tasking capability). This toolkit contains routines that allow this pre-processor to operate as part of a parent program written in Turbo Pascal, calling another program (written in a different language, i.e. C, Fortran, compiled Basic, etc.) as a child program. Control is passed to the child program and then returned back to the Turbo program, (see the previous diagram of a simplified application program). I will give an example. There are many good, debugged structural analysis and design programs written in Fortran. Usually though, the user interface in Fortran programs are pretty bad. Thus, I could write a Turbo shell program (called the parent program) that incorporated this pre-processor and a post-processor (yet to be written), and a Fortran program. I would then use the pre-processor in this shell environment to generate the proper input files for the Fortran program (called the child program) and then pass control to that Fortran program. The user would be totally unaware that control was passed to a different program. The Fortran program would then read the input file, execute on it, and write the output to a file. Control would then be passed back to the Turbo program, specifically to the next line of Pascal code. The post-processor might take over now and graphically display the Fortran program's results. Thus there would never be any need to re-write the existing debugged Fortran program into Pascal. One simply would have to be certain that the input file was written in the proper format for the Fortran program to read and what the Fortran output file format was for the post-processor to read. One could also place several existing programs under the same shell environment, treating them all as "core programs", passing control back and forth between various core programs as deemed necessary. Some sort a data management would probably be required for transferring the data in the proper format to the various core programs. Page 10 V. NOTATION A few notes on my variable naming notation: "G_I" means General Input "S_I" means Scrolling Input All constants are in uppercase with underscore characters between words. All variables, functions, and procedure names are in lower case with a capital letter at the start of each word within the name, with no underscore between words. I recommend that you adopt a similar notation if you already haven't. It is very helpful to be able to look at your code and be able to tell what identifiers are constants. A few notes on my file naming notation: "Col" means Color "Doc" means Documentation "Frm" means Form "Gen" means Generator "Inc" means Include File "Mon" means Monochrome "Pas" means Pascal "Tpl" means Template "Tsipp" means Turbo Screen Input Pre-Processor Page 11 VI. DESCRIPTION OF TOOLKIT SUBPROGRAM FILES Below is an alphabetical list of the pre-processor subprogram include files you will find in this toolkit along with a short description on what each subprogram does. File Description ----------- ----------------------------------------------------------- Display.Inc This include file contains a subprogram for displaying the input data in the scrolling input pages in a more meaningful way. The example application of the input pre- processor is set-up so that a model of the user's entered beam load is displayed. You may want to implement a similar type of display to represent your user's entered data. For example, you may want to display a graph, bar chart, etc. I wrote this subprogram so that the user could see a visual representation of the input data as he was entering it. This enables the user to be able to spot input errors more easily, trends, etc. This subprogram file tries to help to reduce the possibility of "Garbage In = Garbage Out". Error.Inc This include file contains the input error checking subprogram. This subprogram contains two modules which are called after a user has entered a data entry. One module is for input error checking for the general input subprogram, the other is for input error checking for the scrolling input subprogram. Both of these two modules can determine if a specific input data entry is within the prescribed bounds allowed or is one of a few predetermined choices. These modules also make certain that newly entered boundary conditions do not corrupt previously entered data. This subprogram file tries to prevent "Garbage In = Garbage Out". You may want to write similar modules for your application program to check the user's input data as it is entered. Note that specific error character type checking is performed in "G_Input.Inc" and "S_Input2.Inc", not in this subprogram. It is always good strategy to check for input errors as soon as possible. That is why character type checking is linked with the screen templates and general input subprogram or scrolling input subprogram. Page 12 Execute.Inc This include file contains the subprogram that allows you to run child programs directly from Turbo Pascal, get the return codes from DOS when those child programs terminate, and be able to temporarily exit your Turbo program to issue DOS commands. One could write a Turbo shell program to execute other programs using these routines, thereby relieving the user from having to deal with DOS. These routines are very powerful for a large application program, especially if you want to take existing programs and get them running all under the same program shell. File.Inc This include file contains the file I/O subprogram. This subprogram contains three modules of interest. One module takes care of the reading of previously prepared input data files. The second module takes care of the writing of the input data to a data file. The input pre-processor was setup to allow the user to work on his input data for a while, store it under a file name and come back to it later to make changes, etc. You may, for example, want the input data to be written in a specific format (such as if you wanted the input file to be read by a Fortran program). In this subprogram you should write a small procedure to write a temporary ASCII text file with the proper format for the core program to read and execute on. This file should be separate of the user's input data file. The last module controls the displaying and listing of the disk directory. This allows the user to query the input pre-processor for a list of previously prepared input data files. One final note, the user is not allowed to specify the input data file name extension. This was done to simplify the file I/O routines for the user. That way the user does not have to guess what files are input files since the program will only recognize those data files with the proper extension. The pre-processor will only read, write, or display input data files with the same file name extension. Page 13 Init.Inc This include file contains the initialization subprogram for the input pre-processor. This subprogram senses what type of monitor and video card is installed, controls the reading of the screen template files, screen page files, initializes all data entries and variables, and sets up the proper screen colors for the type of monitor being used. G_Input.Inc This include file contains the general input page subprogram. This subprogram controls the entering of data into the general input pages. This subprogram will support as many general input pages as you require. Notice that there is only one general input page in the example application of the input pre-processor. This subprogram checks data entered by the user to make certain it is of the type defined in the screen template for that entry. For example, if only a positive integer is to be allowed for a particular entry, only that data type will be allowed to be entered from the keyboard. All other characters will be discarded with an error sounded also. Entry descriptors (or prompts) are easily added, deleted, or altered using "G_I_Tpl.Gen" to generate or change a screen template. Descriptor locations, entry locations, entry types, etc. are set up in the template file and the general input page subprogram then abides by the template you have defined. Global constants, types, and variables specific to this subprogram are also defined within this file. Menu.Inc This include file contains the menu page subprogram. This subprogram controls the display and handling of menus. This subprogram's routines allow you to manage as many menus as your particular application requires. Notice that there is only one menu page in the example application of the input pre-processor. You may, for example, want to implement a menu to allow the user to transfer control to another part of the application program or to an entirely different program (as what could be done with the overlay, chain, or execute statement, or with the included subprogram "Execute.Inc"). Page 14 Menu prompts are easily added, deleted, or altered using "Menu_Tpl.Gen" to generate or change a menu screen template. Menu prompt locations, menu prompts, etc. are setup in the template file and the menu subprogram then abides by that particular menu page screen template which you have defined. Global constants, types, and variables specific to this subprogram are defined also within this file. S_Input1.Inc These two include files contain the scrolling input page S_Input2.Inc subprogram. This subprogram controls the entering of data into the scrolling input pages. This subprogram will support as many scrolling input pages as you require. Notice that there are 4 scrolling input pages in the example application of the input pre-processor: uniform beam loading, concentrated beam loading, prismatic beam loading, and applied moments to a beam. Notice that the routines within this subprogram allow many more entry rows and entry columns to be displayed within the scrolling input window than can actually physically fit. It does this by scrolling the rows up and down and the columns left and right within the scroll window. Thus the scrolling input window acts much like a view port onto a spreadsheet. Column headings (or prompts) are easily added, deleted, or altered using "S_I_Tpl.Gen" to generate or change a column heading template file. Input data type definitions for each particular scroll column are also defined in the column heading template. The size and/or placement of the scrolling input window can be easily changed. This subprogram also checks the input data as it is entered by the user, sounding an error when characters of the wrong type are entered. Global constants, types, and variables specific to this subprogram are defined within "S_Input1.Inc". Page 15 Screen.Inc This include file is a subprogram (or library) of some very sophisticated screen I/O routines. These routines vary from zooming a window onto the screen to taking a snapshot of the screen and storing it in the heap for later display. Below is an alphabetical list of the functions and procedures contained in this subprogram include file. Date1 Date2 DisplayScreenPage DrawHorizWindowLine2 DrawHorizWindowLine1 DrawWindow1 DrawWindow2 HideBlinkingCursor InitTextScreenPointers MonitorType ReadScreenPagesFromFile RecallTextScreen SetCursorSize ShowBlinkingCursor SoundAttention SoundError SpeedPrint SpeedPrint2 StoreTextScreen Time WaitUntilKeypressed WriteCenterText WriteScreenPageToFile ZoomWindow1 ZoomWindow2 Note that some of these routines are not used in the pre- processor. You can therefore reduce the size of your "Com" file by only including those routines within this include file that you are going to use in your program. Tsipp1.Doc The toolkit documentation files. Tsipp2.Doc Tsipp.Pas This file should be the one you start compilation with. This is the main program file which makes all the include calls for the other subprogram files and the required forward references to later functions and procedures. Some global constants, types, and variables are defined in this file. "Tsipp" stands for "Turbo Screen Input Pre- Processor". These include files are modular in design. Thus you should exclude those files from compilation that you do not need. For example, if your particular application of this pre-processor does not require scrolling input windows, then do not include the files "S_Input1.Inc", "S_Input2.Inc", and "Display.Inc". Page 16 VII. DESCRIPTION OF TOOLKIT UTILITY FILES Below is an alphabetical list of the pre-processor toolkit utility files you will find in this toolkit along with a short description on what each utility does. File Description ----------- ----------------------------------------------------------- G_I_Tpl.Frm This is a template form that you can use to help plan out your general input page screen template. It lists out all the items that need to be inserted into the template file in the proper format. Simply print the template form out with your printer. I recommend that you set your printer to print in compressed mode before printing out this file since the template form is 125 characters wide. G_I_Tpl.Gen This is a short program that is used to generate the general input page screen templates. The general input page screen template stores all the data input descriptors and related information for a particular general input page. Menu_Tpl.Frm This is a template form that you can use to help plan a menu screen template. It lists out all the items that need to be inserted into the template file in the proper format. Simply print the template form out with your printer. I recommend that you set your printer to print in compressed mode before printing out this file since the template form is 125 characters wide. Menu_Tpl.Gen This is a short program that is used to generate the menu screen templates. The menu screen template stores all the menu prompts and related data for a particular menu page. S_I_Tpl.Frm This is a template form that you can use to help plan out your scrolling input page column heading template. It lists out all the items that need to be inserted into the template file in the proper format to display individual column headings. Simply print the template form out with your printer. I recommend that you set your printer to print in compressed mode before printing out this file since the template form is 125 characters wide. Page 17 S_I_Tpl.Gen This is a short program that is used to generate the scrolling input column heading template file for all the scrolling input windows. Notice that only one scrolling input column heading template file is required to store the required information for as many scrolling input pages as you require, while all the other templates (i.e. General Input, Menu) are for only one specific page. VIII. DESCRIPTION OF FILES USED IN THE EXAMPLE APPLICATION Below is an alphabetical list of the files used in the example application of the input pre-processor you will find in this toolkit along with a short description on what each file is. File Description ----------- ----------------------------------------------------------- Example.Com A compiled and ready to run example application using the turbo screen input pre-processor toolkit. It has complete error checking and windows implemented. G_I_01.Col A color screen file for general input page 1 in the example application program. G_I_01.Mon A monochrome screen file for general input page 1 in the example application program. G_I_01.Tpl This is a general input page screen template file that I generated using the "G_I_Tpl.Gen" to give an example on how the input pre-processor works. Menu_01.Col A color screen file for menu page 1 for the example application program. Page 18 Menu_01.Mon A monochrome screen file for menu page 1 in the example application program. Menu_01.Tpl This is a menu screen template file that I generated using the "Menu_Tpl.Gen" to give an example on how the input pre-processor works. S_I_01.Col A color screen file for scrolling input page 1 in the example application program. S_I_02.Col A color screen file for scrolling input page 2 in the example application program. S_I_03.Col A color screen file for scrolling input page 3 in the example application program. S_I_04.Col A color screen file for scrolling input page 4 in the example application program. S_I_01.Mon A monochrome screen file for scrolling input page 1 in the example application program. S_I_02.Mon A monochrome screen file for scrolling input page 2 in the example application program. S_I_03.Mon A monochrome screen file for scrolling input page 3 in the example application program. S_I_04.Mon A monochrome screen file for scrolling input page 4 in the example application program. S_Input.Tpl This is a scrolling input page column prompt template that I generated using the "S_I_Tpl.Gen" to give an example on how the input pre-processor works. Notice that this one template file stores the required information for as many scrolling input pages as you require, while all the other templates are for only one specific page. Page 19 Test1.Inp A sample input data file for the above example application. Test2.Inp A sample input data file for the above example application. Now let me explain a little more on the specifics of how the Turbo Screen Input Pre-processor works and what you need to know to easily alter it for your own application. IX. PROGRAM CONTROL During execution of the input pre-processor program control is passed between three subprograms--general input, menu, and scrolling input. For the input pre-processor main program to know which input subprogram currently has control, the enumerated page control variable CurrentPage is used. Type PageType=(Menu,G_I,S_I,Exit); { Enumerated data type used to tell the main program which } { of the below page type subprograms is currently in } { control: } { Menu Subprogram } { General Input Subprogram } { Scrolling Input Subprogram } { Exit back to the operating system } Var CurrentPage:PageType; { A variable used to tell the main program what } { input page subprogram is currently in control. }