"FMTDOC" -- Documentation for FMTLEX, HP-71 String Format lexfile Lexfile by Hewlett-Packard Documentation by Joseph K. Horn FMTLEX is an HP-71 language extension file. When present in memory, a new BASIC keyword is available (IMAGE$), and two native keywords become enhanced (PRINT and USING). This documentation describes how to use these features. +--------+ ! IMAGE$ ! +--------+ Although USING is a powerful feature of HP-71 BASIC, its execution is very slow. The HP-71 design team had no choice. Since USING can take a string variable as its image (as in PRINT USING I$), there is no way to pre-tokenize the image. This means that the image must be "figured out" during the run, instead of when the program line is typed. This slows down program execution. FMTLEX adds the IMAGE$ function to overcome this problem. If you plan on using an unchanging image in a program, you can use IMAGE$ to "pre-tokenize" it into a variable, for example I$=IMAGE$("3dc3d.2d"). Then, when this pre-tokenized image is used (e.g. PRINT USING I$), FMTLEX recognizes it as pre-tokenized, and skips the usual tokenization, thus speeding up program execution considerably. Note: IMAGE$(A$) is always longer than A$, so if you wish to store it in a variable you must dimension it to be big enough. Here's a simple way to do it: DIM I$[LEN(IMAGE$(A$))] I$=IMAGE$(A$) Here's a simple example of IMAGE$ in use in a program: 100 A$="3dc3d.2d" 110 DIM I$[LEN(IMAGE$(A$))] @ I$=IMAGE$(A$) 120 FOR X=1 TO 20 130 PRINT USING I$;RND*1E6 140 NEXT X This prints 20 random numbers between 0 and 999,999.99 in tabular form with embeded comma and decimal point. Notice how fast it runs. To compare it with "normal" speed, delete line 110 and change the I$ in line 130 to A$. Using IMAGE$ produces approximately a 30% increase in speed. +---------------------+ ! PRINT TO (variable) ! +---------------------+ FMTLEX upgrades the native PRINT command, allowing its output to be directed to a string variable. This is done by using the syntax PRINT TO (variable). The rule is: set up the PRINT statement exactly like normal, but put TO A$ (or any string variable) immediately after the PRINT. The output will be identical to normal, but will be directed into the variable. For example, PRINT 153;18;"HELLO" normally prints " 153 18 HELLO" on the printer (or display). PRINT TO A$ ;153;18;"HELLO" puts the same output into A$, with trailing carriage-return and line-feed. Just remember to put a semicolon (;) after the target string variable, to separate it from the list of things to be printed. You may use semicolons or commas between items in the list in the same way as in normal PRINTing. You may combine PRINT TO with PRINT USING: PRINT TO A$ USING I$;1,2,3 prints 1,2,3 into A$ using the I$ image, which may be pre-tokenized by using IMAGE$ as described above. Of course, you may also use a literal image string or a line number to specify the IMAGE, as in PRINT TO A$ USING 100 or PRINT TO A$ USING "#,k/". Since PRINT normally sends the ENDLINE sequence at the end of its output, PRINT TO does also. Defeating this is done for PRINT TO the same way as it is for PRINT. If you are using a plain PRINT TO, follow the last item with a semicolon (;). If you are using PRINT TO A$ USING I$, then the only way to suppress the ENDLINE sequence from being sent is by having "#," at the beginning of the image string (see HP-71 Reference Manual, page 138). For example, PRINT TO A$ ;153; suppresses the trailing carriage-return and line-feed. Also, PRINT TO A$ USING "#,6z";153 does too. BUG NOTICE: Although a line number may be used as the image specifier, this should be avoided, because FMTLEX does not handle the RENUMBER poll. This means that RENUMBER does not renumber the line numbers in a PRINT TO USING instruction. Even worse, it does not handle the decompile poll (pZERPG), which zeros out invalid offsets. This means that modifications to the program after it has been RUN do not decompile, which can result in erroneous offsets embedded in the code. The result of this is the "Invalid IMAGE" error, even though the actual IMAGE line is perfectly valid. There are two remedies: (1) FETCH the lines containing the PRINT TO USING commands, and press ENDLINE, thereby forcing them to decompile (one at a time); or (2) don't use line numbers with PRINT TO USING, but use literal or variable strings instead. In short: PRINT TO A$ USING 100;X;Y;Z; is BAD! (line number 100) PRINT TO A$ USING B$;X;Y;Z; is OK! (variable image) PRINT TO A$ USING "2d.4d";X;Y;Z; is OK! (literal image) jkh 11 Aug 89