------------------------------------------------------------"Form Input Subroutine" from March, 1990------------------------------------------------------------ For years, I have been begging you readers to write to me. Ihave closed almost every column with an invitation to sendin your questions, comments, and special requests. Althoughit took a while, I am happy to report that those letters arefinally starting to arrive. The idea for this month's column can be attributed to JohnKirstein of Cassel, California. In fact, the letter Johnwrote to me was inspired by another letter written by ElmerAllison, published in the "Letters to the Editor" section ofthe August 1988 (Volume 3, Number 8) issue of ONE THOUSAND. In that first letter, Mr. Allison asked for some help increating "a form on the screen to input data to a disk file.That in itself is no problem. The problem is that one wouldlike to be able to move either backward or forward throughthe fields for editing purposes, like you can do with dBasefiles. Once ENTER is pressed, you can't back up and makechanges. Also, you have to enter all data in the specifiedorder instead of skipping around in the fields." A Little Background ------------------- I know just what Mr. Allison means, but just in case you donot, let's stop for a moment and discuss some backgroundmaterial. First of all, the problem he described is onlyimportant if you write (or if you are thinking of writing)your own programs in BASIC. Most of the programs which haveappeared in this column in the past have been complete andself-contained. However, the main feature of this month'scolumn is a BASIC subroutine; as such, it is only the"foundation" for a more complete program which you mustdesign and build. Mr. Allison asked for help in writing the portion of theprogram which accepts information from the user. He haschosen to enter that information using a "form on thescreen". Do you know what that means? Programs using thattechnique display a number of questions or prompts on thescreen. Those prompts are typically things like "FirstName", "Last Name", or "Address", although they might bequestions which require a number, a single letter, or a"yes-or-no" answer. Following each prompt is a series ofboxes, blanks, or some other kind of placeholder characters. Those placeholder characters show where answers are expectedand must be supplied by the user; they also show the maximumnumber of characters which can be entered in response toeach question (or in each "field"). Ideally, Mr. Allisonwanted the user to be able to use the four arrow keys tomove the cursor around the screen at will -- adding ordeleting a character into one field, backing up or movingforward to correct a typo in another field, and jumping upor down the screen as the need arises. Mr. Allison also mentioned dBase. In case you have notheard of it, dBase is a popular commercial program which isideal for creating data bases of information. Owners ofdBase can write "programs" to create customized input screenforms for specific applications, but programming options arerather limited and one must learn a whole new "language" towrite those programs. Another Letter -------------- Seeing Mr. Allison's letter inspired John Kirstein to write.His letter was published in the "Letters to the Editor"section of the June 1989 (Volume 4, Number 2) issue. Infact, he provided even more details in a follow-up letterwhich was forwarded to me several months later. Accordingto his letters, Mr. Kirstein has been looking for a screenform input subroutine for years to use in programs he haswritten. He thought he had found a workable subroutine in a book forthe Apple II computer, "The Apple II User's Guide, SecondEdition" by Lon Poole, Martin McNiff, and Steven Cook;published by Osborne/McGraw-Hill in 1983. (By the way, Ican recommend that book highly. I recently had to convertsome of my Grandy programs to operate on the Apple II.Although the version of BASIC built into the Apple is one ofthe worst ever developed, the book by Poole et al. explainseverything you need to know to make the conversion from PCBASIC to Apple BASIC.) Unfortunately, there were some problems with the subroutineMr. Kirstein found. As good as it was, the subroutinepublished for the Apple and converted to run on the Grandystill lacked some features. One key missing featureKirstein found was the inability to use the up arrow to"back up" to fields higher on the screen. But mostimportantly, the subroutine was copyrighted -- which meanthe could not use it in any of his programs without expresswritten consent from the McGraw-Hill publishing company. Here is what John Kirstein wrote: "This is ... one of mychoice gripes. I have spent over $200 to buy books for thispurpose. Then I find out when I want to use the concepts(in them) that (they) are copyrighted! It just seems to methat when an author is published in a book that has beenwritten to teach that the author is paid for his effortunder the publishing agreements. The user should be free touse the concepts." Mr. Kirstein is correct. If you find a good subroutine in abook and you want to include it in a program you arewriting, be sure to write to the publisher for permission.Check the fine print in the front of the book. You willprobably find a disclaimer or some kind of notice reservingall rights to the BASIC code found in that book. No Strings Attached ------------------- I certainly sympathize with Mr. Allison and Mr. Kirstein.Believe me, I have been in the same spot! So what is aprogrammer to do? Well, in this instance, he or she can usethe subroutine found in this month's program. I do notclaim to be the world's greatest programmer, but hopefullythe subroutine that I have written will meet most of theneeds described above. And here is the kicker -- you can use this subroutine in anyprogram you wish. You need not contact me nor the magazinefor permission. You certainly do not owe us any money! Allthat we ask is that somewhere in the program (maybe in aseries of REM statements inside your program) you include aline or two explaining where the subroutine came from. Ifyou would like, an on-screen message mentioning my name andthe magazine's name and address would be even better. But,it is entirely up to you; there are no strings attached tothis offer. How does the program work? After typing RUN, you will seeprompts for five different fields: first name, last name,street address, city and state, and zip code. A series ofsquare "dots" act as placeholders behind each prompt. Startby entering your first name. Use the left and right arrowkeys to move around the field. Experiment with the INSERT,DELETE, and BACK SPACE keys. Once you are ready to move on,press ENTER and the cursor will move to the second field;enter your last name. You can use the up arrow to move backto the "first name" field, then use the down arrow key tomove to the "last name" field. [Note: Those of you with the new enhanced keyboard -- andthat includes all SL and TL owners -- will have troubleusing the up arrow. There is a bug in either Tandy BASIC orthat keyboard which makes it impossible for BASIC to detectthe up arrow. On that keyboard, you have the option ofusing PAGE UP to move up and PAGE DOWN to move down.] Every time you press ENTER, you will move to the next field.When you are on the last field on the screen and you pressENTER, you will exit the "form input" subroutine and returnto the main program. (You can also press ESC at any time toforce a quick exit from the subroutine.) The main program Ihave written is a real "bare bones" program. It allows youto make entries, offers the chance to go back and makechanges, then erase those entries and make new ones, orquit. As such, it serves no useful purpose EXCEPT toillustrate the use of the "form input" subroutine. When youdo decide to quit, the screen will clear and you will returnto the "OK" prompt. If you want to return to DOS, typeSYSTEM and press ENTER. Self Service ------------ How do you use the "form input" subroutine in your program?You will be pleased to discover that it does not require anycomplicated setup on your part. You must dimension severalarray variables used in the subroutine. Look at line 160;variables FX and FY contain the starting screen locationsfor each field. Variable FL contains the maximum allowablelength for each field. String variable F$ contains the textentered for each field. Array Q$ is a dummy variable usedonly in the subroutine. I have used a dimension of 10; as aresult, you can have no more than 10 fields on the screen atonce. If you need more, simply use a larger dimensionnumber. Whenever you use the "form input" subroutine, youmust dimension these variables. In line 210, variables FC and BC establish the foregroundand background colors, respectively. The variable DOT isset equal to 254; that signifies that CHR$(254) will be usedas the placeholder character. You can change the value ofDOT, but be sure you use an ASCII value less then 32 orgreater than 127. You must always supply values for FC, BC,and DOT. Variable NF holds the number of fields; in this example, itis set equal to five. Lines 220 through 310 set up each ofthose five fields. For example, line 220 prints a promptingmessage for first name. In line 230, FX(1) signifies thatthe first field will begin in column 28, FY(1) signifiesthat it will begin in row 6, and FL(1) signifies that itmust be 20 characters or less. Notice how the other fourfields are defined as well. You must supply your ownprompting messages as well as values for FX, FY, and FL. Line 320 calls on subroutine 1000 -- the special "forminput" routine. Lines 360 through 410 are just fordemonstration purposes; they allow the user to go back andmake a change in the fields. The same thing is true oflines 450 through 510; they allow the user to erase theexisting fields and start making a new set of entries. As my "bare bones" main program illustrates, all you have todo to use the subroutine is follow the rules listed above:dimension the proper variables; define FC, BC, and DOT;display your prompting messages in the proper locations;define the number of fields in NF; define FX, FY, and FL foreach field; and load array F$ with any pre-existing textvalues for each field. To display the present values of allfields, you can use GOSUB 1430. To allow the user to inputand/or edit the present field values, use GOSUB 1000. Of course, if you plan to use this subroutine in a programyou develop, you should type DELETE 100-510 to remove mydemonstration program. Add your program using line numbersbelow 970 or after 1460. When you SAVE it to disk, use anew disk file name. Programming Details ------------------- Let's look more closely at subroutine 1000. Line 1000immediately calls subroutine 1430 to display the fieldvalues. Variable CF keeps track of the current field; thatis, which field is being input and/or edited. Variable CPis used to keep track of the cursor position; the initialvalue of zero means the cursor is positioned at the firstcharacter in the field. Lines 1010 and 1020 position the cursor, reverse the videocolors, print the character in the current field and at thecurrent cursor position, print a CHR$(29) to back the cursorup one space (to put it back on top of the currentcharacter), and restore the video colors. A keystroke isaccepted in variable I$ in line 1030. When BACK SPACE is entered, lines 1080 or 1090 are enacted.The ENTER or ESC keys lead the program to lines 1100 or1110. Normal letters, numbers, and punctuation marks arehandled in lines 1130 and 1140. Pressing ENTER in the finalfield or pressing the ESC key leads to lines 1180 through1200. In those lines, the DOT characters are removed fromthe field values held in dummy string array Q$. Once theyhave been cleaned up, they are placed back into array F$. Lines 1240 through 1370 handle a variety of specialcharacters and keystrokes. The up arrow leads to lines 1260through 1290. The left arrow is handled in line 1300. Theright arrow leads to lines 1310 and 1320. The down arrow ishandled in line 1330. When the INSERT key is pressed, lines1340 and 1350 squeeze in an extra space. When the DELETEkey is pressed, lines 1360 and 1370 remove the characterunder the cursor. Wrapping Up ----------- If you write your own programs -- especially ones whichmaintain mailing lists, address databases, or membershiprolls, for example -- then you will probably find subroutine1000 in this month's program very useful. Consider it agift from me to you. I ask only two things in return:first, remember to give credit to ONE THOUSAND magazine inyour program. Second, I would love to hear from you. Writeand tell me how it works in your program. As always, writeto me with questions, comments, or suggestions on any topicrelated to BASIC programming. See you next month!
