* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * P R N T X T * * * * A Console/Printer Message Utility Program * * * * by * * Terry Hazen * * 21460 Bear Creek Road * * Los Gatos, CA 95030 * * (408) 354-7188 * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * Latest Revision --------------- Version 1.5 - 11/22/88. See RENAMZ15.Z80 for revision details. ================================================================= Overview -------- PRNTXT is a message display utility designed to assist in the creation of 'instant' text display COM files which send text added to PRNTXT.COM by the user with a word processor such as WordStar or contained in the command line tail to the console or printer. A 'switch' character may be used to direct portions of the text to either the console or the printer. Text directed to the console is automatically paged every 23 lines, or a 'paging' character may be inserted into the text to create more specifically formatted displays. Whenever PRNTXT finds '$' in the message text, it will substitute the command line tail, if it exists, which will be processed just like the message text, and may include the same special characters. In the same way, PRNTXT will substitute the first parameter in the command line tail when it finds '$1' in the message text and will substitute everything in the command line tail after the first parameter when it finds '$-1' in the message text. When PRNTXT finds '$' in the command line tail, however, it will only display it and not interpret it. The display of command line tail text on the console and printer may be toggled between upper and lower case. Non-printing characters, such as ESC (^[) and BEL (^G) may be synthesized for use in terminal or printer control sequences. Some Applications of PRNTXT --------------------------- PRNTXT can be used to help create: - "README" files that can be run instead of typed, with built in paging and video attribute formatting. - Help files. - STARTUP instruction message files - Test files to display and check the layout of menus and display screens under development as parts of assembly language programs. - Console and/or printer programming files. - Console and/or printer "Echo" utilities. - Status reporting message files which can accept a command line tail parameter such as a filename or video attributes. These might be resident in a message file library, and called from within ZCPR3 aliases. Using PRNTXT To Create a Message File ------------------------------------- PRNTXT is supplied in two different forms, each designed to be used in a different way. PRNTXT.COM is designed to be loaded into a word processor such as WordStar, where the desired message text can be inserted. ******************************************************************* *** Text editors such as VDE and LZED that reset the high *** *** bits in the text as it is loaded cannot be used to load *** *** PRNTXT.COM, as they will destroy the .COM part of the file! *** ******************************************************************* To use text editors such as VDE and LZED to create your message text files, you can use PRNTXT.TOP and PRNTXT.BOT They are PRNTXT fragments designed to be concatenated with the message text to form a working .COM file. PRNTXT.TOP is the first part of PRNTXT up to the place the message text is inserted. PRNTXT.BOT contains the trailing NULL that ends the message display. If you have a message text file, TEXT, you can create a file named MESSAGE.COM from these pieces using PIP or an equivalent to concatenate them: PIP MESSAGE.COM=PRNTXT.TOP,TEXT,PRNTXT.BOT You can also use WordStar's ^KR command in either Document or Non-document mode to read in the three files into a new blank MESSAGE.COM file as described in more detail below. Inserting Text -------------- If your text message is extensive or complicated, use your word processor or text editor to create and save your text in a file ahead of time. If you are using WordStar, you may use the Document mode or Non-document mode, as PRNTXT will ignore any high bits that may be set. Create a copy of PRNTXT.COM named to whatever you like, such as MESSAGE.COM, and call it up with your word processor. You will see something like the following display: Cb PRNTXT vers 1.5 - Copyright (c) 1988 by Terry Hazen [more] ^@^H^H^H^H^H^H^H...and lots of other junk... - Insert your text starting on the next line. RETAIN THE ENDING ^@: <<-----------------------------. ^@ | | | Insert your text on this line -' (This dotted line and arrow are not in the actual PRNTXT display, but are for illustration only.) If you have prepared your text in a separate file ahead of time and are using WordStar, place the cursor at the beginning of the line where the arrow points, and use the ^KR command to insert your prepared text file. Otherwise, you may create your text directly at this point. You may insert as many extra lines as you need for your text as long as you leave the last line containing the ^@ intact. This is a NULL (the end-of-file marker), and without it, PRNTXT won't quit at the end of the text, but will continue to display junk until it encounters a NULL somewhere along the line. Save your new file and run it. Another method of inserting text is to use WordStar to create a new blank file such as MESSAGE.COM. Use the ^KR command to read in the file PRNTXT.TOP . Create your text message following PRNTXT.TOP or read in your text message file. Go to the bottom of the file and read in PRNTXT.BOT. Save the file and run it. If you are running ZCPR3, you can automate this process by creating a ZEX script. Directing Your Text To It's Proper Destination ---------------------------------------------- PRNTXT normally displays text on the console, but text may be toggled between the console and the printer by the use of a 'switch' character inserted into the text. Prefix the portion of the text you wish to send to your printer with the printer 'switch' character '\'. Note that this is the BACKSLASH character, not the normal slash (/). To switch the display back to the console, end the printer portion of the text with another '\'. A carriage return (^M) before the second '\' is necessary if you wish the printer to print the final line of text immediately. A normal word- processing carriage return is actually a carriage return-line feed combination, and will cause the printer to advance the paper a line, while a separate carriage return (^M) will not advance the paper after printing. Any text following the second '\' will be sent to the console. Text may be alternately displayed on the console or printed on the printer, but can not be sent to both at once. You can do the same thing, however, by using two copies of each line, sending one to the console and the next to the printer. The following sample text is an example. In this example, text in CAPS will be printed on the printer: This line will be displayed on the console. \WHILE THIS LINE WILL BE SENT TO THE PRINTER \and this line will appear on the console directly below the first line.\THIS WILL BE ALSO BE SENT TO THE PRINTER.^M **************************************************************** *** If you are sending text to your printer *** *** AND YOUR PRINTER IS NOT READY *** *** YOUR SYSTEM MAY HANG UP UNTIL YOUR PRINTER IS TURNED ON! *** **************************************************************** Paging The Console Display -------------------------- PRNTXT automatically keeps track of the number of lines of text displayed on the console and pages the display every 23 lines, printing '[more]' at the bottom of the screen and waiting for any key to be pressed before continuing the display. The console display may be paged at any other desired point by inserting a paging character, defined as '~' in the distribution version of PRNTXT, into the text. Whenever PRNTXT sees a the '~' (tilde) character in text sent to the console, it will page the display and wait for any key to be pressed. The line counter is reset any time the display is paged. Text sent to the printer will not be paged, nor will lines sent to the printer affect the line count for the console display. Synthesizing Non-Printing Characters ------------------------------------ Non-printing characters, such as ESC (1BH or ^[), which cannot be directly added to the text message by WordStar can be synthesized using a two-character string. The first, or intercept character is defined as '^' in the distribution version of PRNTXT. The intercept character cannot appear anywhere in the text except when a non-printing character is to be synthesized. If your text must include '^' (as this one does), you must define another intercept character, which won't be used in your text, and modify PRNTXT as described below. When PRNTXT is run, the intercept character will be recognized, discarded, and the next character will have 40H subtracted from it in order to synthesize the non-printing character. Thus, if you wanted to say ESC you would write: ^[ (which is: '[' - 40H = 1BH (ESC)) In other words, write the non-printing character as its equivalent control character (^G for bell, ^J for line feed, ^M for carriage return, etc). The word processor normally ends each line of text with a carriage return, line feed combination. The following text will set Emphasized Print on an EPSON MX-80, display what it is doing on the console, and ring the bell: Setting the printer to EMPHASIZED... \^[E^M\^G This sends the following sequence to the printer: ^[ (ESC), 'E', ^M (carriage return). The '^[E' is the EPSON control sequence for setting Emphasized Print. The carriage return (^M only, not a CR-LF combination) tells the printer to accept the text, but since there is no line feed, it won't advance the paper a line. If the final '\' is put on the next line instead, the paper will move. Try it out using the control codes for your printer. Note that each non-printing character takes up two spaces in the text file that will not appear in the display, so that the number of spaces in a line containing non-printing characters may need to be adjusted when reverse video or other special effects are used in the message text. Including Text From the Command Line ------------------------------------ PRNTXT looks for the character '$' in the message text. If it is found, PRNTXT examines the command line buffer to see whether a command line tail (everything you typed after the program name) exists. If it does, PRNTXT will substitute the command line tail for the '$' in your message text, and if no command line tail exists, PRNTXT will simply display the '$'. In the same way, PRNTXT will substitute the first parameter (any number of characters ending in a space) in the command line tail when it finds '$1' in the message text and will substitute everything in the command line tail after the first parameter when it finds '$-1' in the message text. When PRNTXT finds '$' in the command line tail, however, it will only display it and not interpret it. PRNTXT will process the command line tail message in the same way it does the regular message text, so that you can include control sequences to be synthesized and can send strings to your printer. The commmand line text display may be toggled between upper and lower case by using the switch character '%' followed by '>' to toggle the display to lower case, or by '<' to toggle the display to upper case. Characters will continue to be displayed in the same case until another toggle sequence is encountered. Only the characters A-Z are affected by the toggle. In you are using ZCPR3, PRNTXT and an appropriate command line tail may be included in an ALIAS or ZEX file to display messages during an automated process. The following message text might be from a file called SAMPLE.COM: * Stand by -- Assembling the file "$" ... If you were to call up SAMPLE at the system prompt by typing: A0>sample t%>estprog.z80 you would get the display: * Stand by -- Assembling the file "Testprog.z80" ... Note that if the command line tail is long, it might push part of the message text following the command line tail text off the right hand side of the screen, as no reformatting is done. A PRNTXT file, perhaps named MSG.COM, and containing only a '$' as the message text will simply echo your command line tail to the console. A similar file that might be named PRNT.COM and containing '\$^M^J\' as the message text will echo your command line tail to the printer, advancing the paper a line. There are some limitations to the use of command line tail message text, however. The command line tail is limited in length. The practical limit is what you can type on one screen line. PRNTXT will simply display any '$' characters it finds in the command line tail and will not attempt to interpret them. Operator Interaction -------------------- If you want to display a message on the console and wish to give the operator the option to continue or to abort, use the paging character (~) to page the display (as shown in the previous example). Note that if you used '^C' instead of 'CTRL-C' in the following display, it would be interpreted instead of being displayed. Try it out using a control sequence for your own printer: Press RETURN to set the printer to EMPHASIZED or press CTRL-C to abort: ~\^[E^M\ Done...^G If ^C is pressed in response to '[more]', the program will be aborted. If RETURN is pressed, the printer will be set to emphasized, 'Done...' displayed on the console, and the bell will be rung. Modifying PRNTXT ---------------- If you wish to customize PRNTXT, you may do so by modifying PRNTXT.Z80, then assembling and loading it, or if you only wish to change one of the defined characters or the number of lines per paged display, you may change PRNTXT.COM quickly and directly with DDT, PATCH, or another debugging type editor. The characters which may be modified in this way, their locations, purposes and their default values are listed below. Note that several of the characters must be changed at two locations each: Location Default Purpose ================================================================= 0209H '\' Switch character. Toggles text display between console and printer. 0219H '^' Intercept character for synthesizing non- printing characters. 0232H '~' Manual paging character. 016DH 16H (22D) Maximum number of lines per console display 0298H 018AH '$' Command line tail intercept character. 01A2H 01BDH '%' Command line tail case switch prefix. 01C6H '>' Upper to lower case switch character. 01D3H '<' Lower to upper case switch character. =================================================================