WRITHEAD DOCUMENTATION The WRITHEAD program was written by Michael Markov to carry out one of the most tedious task that HP-71 assembly programers will face, once they begin writing long LEX files with dozens of keywords: preparing the LEX file header, to include the Text Table, the Main Table, the Speed Table and the VER$ poll handler. WRITHEAD will be especially useful whenever your token assignments are not sorted in any particular order because it will eliminate the risk of inverting the order of various instructions, and the dangers associated with such mistakes. WRITHEAD and this documentation are hereby placed in the public domain, for non-commercial use. WRITHEAD overcomes the above mentioned difficulties by automating the creation of HP-71 LEX source code files. It starts by asking a few question, and depending on the responses provided, it begins creating the desired header. At the appropriate time, you will be asked to provide information about the keywords you wish to include in your LEX file. This information may be read from a suitable token assignment file, if available. If not, the information may either be added to an existing token assignment file, or it may be stored into a file that will be automatically created. The program will prompt you with questions until all the required information has been provided. The resulting header will be found in a text file named ASMHEAD. At this point, all you have to do to get a nice LEX file is to append your assembly code and run the Assembler... If the code for each individual keyword has been previously tested successfully, then the only problem you are likely to encounter is that of duplicate labels, something that can be fixed with relative ease with a suitable text editor. THE ADVANTAGES OF BIG LEX FILES A single monolithic LEX file has several advantages over a collection of smaller LEX files that have been linked together to provide the same set of keywords. The potential reduction in memory utilization can justify the additional time and effort it takes to prepare the source file, even when you use the rather slow HP-71 Forth Assembler ROM. Also, the monolithic LEX file will help significantly improve the performance of your HP-71, for both keyboard and program run time utilization. Improved performance (faster response) is due to the facts that A) the operating system has to pass control to only one poll handler, as opposed to a poll handler for each and every one of the linked LEX files, B) the operating system can find keyword entry points much faster when it has to process only one or two items in the bLEX (LEX file address) buffer, and C) the process of scanning through Text Tables can be significantly speeded-up with the introduction of a Speed Table. It is important to understand that the time saved is the time spent finding each individual LEX and determining the entry point address of the code to be scaned or executed. This takes just as much time for a small LEX as it does for a large LEX. I have found that combining many small LEX files into one not so small LEX can have the same impact as a speed-up of my HP-71. THE TOKEN ASSIGNMENT FILE The Token Assignment file is a standard HP-71 Text file that contains in free-format the description of the keywords. This is the heart of the problem, since all other portions of the LEX file header are fixed, following the rigid stucture that is required of all LEX files. Each line must provide the following information for each given keywork, separated by one or more spaces: 1) The Token number, in HEX. 2) The characterisation nib, also in HEX. 3) The label for the entry point 4) The keyword itself Any information that follows will be ignored. EXAMPLE, from MMTOKENS: . . B9 F ATBIN$ ATBIN$ BA F BTA$ BTA$ BB F BTD BTD BC F CHR2$ CHR2$ BD F DTBIN$ DTBIN$ BE F INT$ INT$ BF F NUMR NUMR C0 F NUMX NUMX C1 F BINCMP BINCOMP$ C2 D chirp CHIRP C3 F COUNT COUNT C4 F cursor CUR$ C5 F Start DT2DOT$ C6 F ESC ESCP$ | | | | | | | |_ The keyword, exactly the way you want to spell it | | | | | |________ The label for the keyword's entry point | | | |__________ The characterization nib (CHAR #F) | |_____________ The token number in hex NOTE: When WRITHEAD first creates a token assignemnt file, the information is entrered sequentially by token number. This minimizes the likelyhood of duplicate token assignments, duplicate lables or duplicate keywords. The information is entered begining with columns 1, 4, 6 & 13. This format is not mandatory (you only need one space between the entries) but it has the important advantage of allowing you to easily sort the file by token #, entry label or keyword name with SUB QSORTF, by Tapani Tarvainen, which is included as part of WRITHEAD. WRITHEAD carries out a bare minimum of testing insofar as the validity of the contents of the assignment file are concerned. It is assumed that the user will provide correct information. USING WRITHEAD Before WRITHEAD creates the desired header, it will ask a number of questions. The purpose and proper response to these questions is describe below. 1) Compatible with ASSEMBLE ?(Y/N) The default response is "N". This means that the default header format will be compatible with HP's Series 200 (Iapetus) assembler, and with SASM, by Hand Held Products, Inc. If you wish to use the header with the HP-71 FORTH-Assembler ROM's ASSEMBLE, you must respond with a "Y". The main differences are that a) the pseudo-ops LEX, ID,.... are not recognized, and b) reverse slashes are used to delimit strings, instead of single quotes. See the HP-IL IDS if you want to take a look at a sample of Series 200 compatible code. 2) Next, you will be asked to provide a title for your LEX. This will be used to select a name for the resulting LEX file, and to document the source code. Note that current date information is taken from the HP-71 system. You should use SETDATE to make sure that the information that is entered in your documentation is correct. 3) You will then be asked to provide the VER$ identifier for you LEX. The default provided is " DIR:a". Note the leading space. This space must be provided to separate your response from the response of other LEX files. 4) Finally, we get around to the important stuff, starting with the LEX ID. The default provided is #5E, the last scratch ID, which I use for my personal resource allocation scheme. At this point, you will be prompted for the name of your personal resources allocation document. The default provided is MMTOKENS, where MM represents my initials.. feel free to substitute any other file name you may prefer. Keep in mind that you must provide a file name even if you wish to enter data manually. This is where the data will be stored for future use. Next, you will be asked to provide the token number for the first and last keyword to be include in the LEX file you are currently writing. If the information, or any portion thereof, is missing, you will be asked to provide it from the keyboard. 5) Once all the above information has been provided, you will be asked if you want to include a Speed Table with your LEX, and whether there is a Message Table to be included. Insofar as a Message Table is concerned, WRITHEAD simply includes a REL(4) MSGTBL or a CON(4) 0, depending on your response. You now have done your share of the work, and it is your HP-71's turn to become very busy. There is quite a bit of sorting to be done in order to make sure that the entries in the Text and Main Tables are entered in the proper order, so that it will take a while. When the PRGM indicator turns off, you can take a look at the result by listing ASMHEAD. A couple of point before I quit: 1) A Speed Table takes some 78 nibs of memory. This is quite a lot of overhead for short LEX files. It is wasted overhead unless your LEX includes enough keywords to insure that the time spent on scanning the speed table is significantly less than the time spent scanning the entire Text Table. 2) You are reminded that WRITHEAD assumes that the information you provide is valid. WRITHEAD does only a minimum of testing to weed out invalid entries. Checking the validity of your data is up to you. WRITHEAD could be improved in many ways: it has yet to be optimized for both speed and code size. I would like to add a routine that could generate Message Tables. Also, in this version, I have avoided the use of keywords not found in the HP-71 mainframe / HPIL ROM / FORTH Assembler ROM. Other keywords, and TRIM$ in particular (from the HP User Library STRINGLX LEX), could be used to great advantage. This should, I hope, make the program immediately useful to all users. I hope you will find this pogram useful, and that it will help you save time. Michael Markov, P.O. Box 17, Lockwood, New York 14859