Pegasus Graphics Universe 1

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

/ Pegasus Graphics Universe 1 / Pegasus_Graphics_Universe.iso / p11 / system / help / manual.doc < prev next >

Wrap

Text File | 1992-10-15 | 202.9 KB | 5,317 lines

DOCUMENTATION FOR VERSION 7.32 (October 15th, 1992) OF P11 A GRAPHICS PROGRAM WRITTEN BY: RUSSELL D. HOFFMAN P.O. Box 188006 CARLSBAD, CA 92009 (800) 551-2726 (619) 720-7261 America Online:RUSSELL DH CompuServe:70743,1226 THE AUTHOR ASSUMES NO RESPONSIBILITIES AS TO THE APPLICABILITY OF THIS PROGRAM TO YOUR NEEDS OR THE ACCURACY OF ITS FUNCTIONS. PLEASE NOTIFY THE AUTHOR OF ANY INACCURACIES FOUND AND OF ANY DESIRED NEW FEATURES. CONCEIVED, DESIGNED, WRITTEN AND PRODUCED BY RUSSELL D. HOFFMAN IN THE UNITED STATES OF AMERICA. PROGRAM COPYRIGHT (c) 1984 to 1992, DOCUMENTATION COPYRIGHT (c) 1985 to 1992 by RUSSELL D. HOFFMAN. ALL WORLDWIDE RIGHTS RESERVED. This document is copyrighted. No portion may be reproduced, copied, duplicated or stored in an electronic access system for retrieval by persons other than the rightful owner and/or user of this product without prior written permission of the author, except small portions may be taken for purposes of review or training. This version supersedes all previous releases of this document and the P11 family of graphics products. This version is SHAREWARE and is dedicated to the thousands of users who have contributed to this product over the years, in so many ways. Thanks to all of you, past, present,... and future! Proudly manufactured in the United States of America. First printing: Version 3.00.00, October, 1987. (Some prior limited distribution. (Program versions 3.20 & 3.21, 3.50 & 3.51) Second printing: Version 4.80.00, March, 1989. Third Printing: Version 6.00.00, May, 1990. (Main program release was 6.40 (editor) and 6.41 (runtime) Fourth "Printing": Version 7.22.00, Aug. 4th, 1992 (Shareware) Fifth "Printing": Version 7.24.00, Aug. 9th, 1992 (Shareware) Sixth "Printing": Version 7.26.00, Aug. 14th, 1992 (Shareware) Seventh "Printing": Version 7.30.00, Oct. 9th, 1992 (Shareware) This technical reference and it's accompanying tutorial and addenda have been completely revised and updated for use with the current version of P11 and P11RUN. Additional addenda to this document may be included for subsequent releases of P11 and/or P11RUN. The manufacturer reserves the right to make changes to the programs and/or documentation without prior notice or obligation. Numerous companies produce products that are important to the satisfactory use of this product. Throughout this manual these products are mentioned. Many of these product's names are trademarked and we have attempted to list the owners of these trademarks below. I.B.M., PC, PC/XT, PC/AT, PS/2, and PC-DOS are all registered trademarks of International Business Machines Corporation. Softgraf is a registered trademark of AutoScribe Corp., Rockville, MD Compaq is a registered trademark of Compaq Computer Corporation. Summagraphics is a registered trademark of Summagraphics Corp. MS-DOS is a registered trademark of Microsoft Corporation. Manager Mouse is a registered trademark of The Numonics Company. HP Laserjet is a registered trademark of the Hewlett-Packard Company. RADIO SHACK and TANDY are registered trademarks of Radio Shack, Inc. ATI WONDER CARD and WONDER MOUSE are trademarks of ATI, Canada QEMM is a trademark of Quarterdeck Office Systems, Santa Monica, CA GRAPHICS MASTER is a registered trademark of TECMAR. Additional trademarks belong to the companies listed herein. TABLE OF CONTENTS COMMANDS AND SYNTAX ................... 1 Alphabetical Listing Of All Commands ACTIVATE ............. 2 ADD .................. 3 APPEND ............... 4 AUTHORITY ............ 5 BEEP ................. 6 BLANK ................ 7 BREAK ................ 8 BUILD ................ 9 BUTTON ............... 10 CALL ................. 11 CALLM ................ 12 CIRCLE ............... 13 CLEAR ................ 14 CLOCK ................ 15 CLOSE ................ 16 CONNECT .............. 17 CONVERT .............. 18 CRAWL ................ 19 CURSOR ............... 20 DATA ................. 21 DELETE ............... 22 DIGITIZER ............ 23 DISPLAY .............. 24 DIVIDE ............... 25 DOT .................. 26 DRAW ................. 27 ELIMINATE ............ 28 ELSE ................. 29 END .................. 30 ENDIF ................ 31 ERROR ................ 32 EXCHANGE ............. 33 EXECUTE .............. 34 FRAME ................ 36 HEIGHT ............... 37 HUE .................. 38 IF ................... 39 IN ................... 40 JOYSTICK ............. 41 JRCOLOR .............. 42 JUMP ................. 43 KEY .................. 44 LENGTH ............... 45 LINE ................. 46 LOCATE ............... 47 LOAD ................. 48 MARQUE ............... 49 MEMORY ............... 50 MOUSE ................ 51 MOVE ................. 52 MULTIPLY ............. 53 NAME ................. 54 ON ERROR ............. 55 ON KEY ............... 56 OPEN ................. 57 OUT .................. 58 OVERLAY .............. 59 PAINT ................ 60 PASSWORD ............. 61 PEN .................. 62 PRINT ................ 63 QUESTION ............. 64 READ ................. 65 RESTORE .............. 66 RETURN ............... 67 ROTATE ............... 68 ROUNDS ............... 69 RUN .................. 70 SAVE ................. 71 SCREEN ............... 72 SCROLL ............... 73 SET .................. 74 SHOW ................. 75 SOUND ................ 76 SPRINT ............... 77 SPRITE ............... 78 SUBTRACT ............. 79 TEXT ................. 80 THEN ................. 81 WAIT ................. 82 WIDTH ................ 83 WRITE ................ 84 X .................... 85 ZING ................. 86 * .................... 87 " .................... 88 + .................... 89 \RUN Information Displays....... 90 Picture and Font File Formats... 91 Format for the Auxiliary File... 92 Format for the Hue File......... 93 Space Considerations............ 94 Tips On Making Your Program Faster 95 Uses of the "escape" key........ 96 F10-"Instant" commands & DOS functions 97 Future Enhancements............. 98 Of Mice and Joysticks and Digitizers 99 Timing Considerations........... 100 Converting Images Between Screen Modes 101 Executing DOS from within the program 102 About the Author................ 103 COMMANDS AND SYNTAX Commands in this language are based on ENGLISH words. All commands have a backslash in column one and then the command. You may have one or more spaces between the backslash and the command word. If the command has parameters these should follow AT LEAST ONE SPACE after the command word. You may have multiple commands on a single line, but the first character of each command must be a backslash. The \", \+, and \* commands if used must be the last command on the line. \ON KEY commands, which allow the user to move around within the text file, are only checked between lines (except during \", \X, \MARQUE, \SHOW and \RUN). \ON KEY checking will not occur between lines if the last command on the previous line is \+ (see that command for more information). Temporary suspension of key checking (except for the ESCAPE key) enhances the usefulness of the \ON KEY command and is explained in more detail in the command description. Usually only the first 1, 2, 3 or (sometimes) more letters are evaluated when the program decides what word (command) you have specified. Some commands must be coded exactly as they appear in this manual, particularly \END, \ELSE, and \ENDIF. All commands must have enough of them coded to distinguish them from all other commands. Since future releases will include additional commands, the use of abbreviations is NOT AN APPROVED TECHNIQUE. It is mentioned here "for documentation purposes only." PARAMETERS Some commands can have a varying number of parameters following them. Some may or may not have any parameters at all. Most expect commas to separate a series of values. Parameters may be positional or keywords, depending on the command. As an example of positional parameters, assume you have issued a command to draw a MARQUE (such as they have on Broadway) on the screen. This program has such a command. Here is an example: \MARQUE 20,24,40,50 This will display a moving rectangular marque with opposite corners at dot 20,24 and dot 40,50. The syntax of this command (so far) is \MARQUE #,#,#,#. KEYWORDS Some commands have "KEYWORD=" parameters. \MOUSE and \SPRITE are good examples. A typical \MOUSE command might look like this: \MOUSE LOCATION=180,100 WINDOW=33,53,188,130 ROUNDS=30 This will display a mouse cursor at location 180,100 (near the middle of the screen), in a window with opposite corners at 33,53 and 188,130. It will display for 30 rounds (see \MOUSE for an explanation of the ROUNDS option). Parameters, whether positional or keyword, may be specified with numeric literals, auxboxes, variables, or mathematical expressions. MATHEMATICAL EXPRESSIONS Let's say you don't want to say dot 20,24 as the upper left corner of the MARQUE, but rather, dot (10 + 10),(8 + 16). This is actually the SAME DOT! 10 plus 10 is twenty, and 8 plus 16 is twenty-four. You may use parenthesis and variables just as you would in high-school algebra. You can use operators for addition, subtraction, multiplication and division (+,-,/,*) with or without using parenthesis. The order of evaluation, as with algebra, is parenthesis first, then multiplication and division equally (left to right), and then addition and subtraction equally (left to right.) AUXBOXES Suppose you don't want to specify an exact place for the MARQUE, but rather, you want to use values contained in your auxboxes. The \MARQUE command, using auxboxes, (short for "AUXilliary storage BOXES" and we pronounce it "OX BOXES") 1, 2, 3 and 4, would look like this: \MARQUE #1,#2,#3,#4 If auxbox #1 contained the value 20, #2 contained 24, #3 contained 40, and #4 contained 50, then this would do the EXACT SAME THING as in the previous examples. Syntax requires that auxboxes be described with a pound sign (#) in front of them, unless you had previously named the auxbox, in which case you could specify the name instead of the number. There cannot be any signs (+,-) between the pound sign (#) and the auxbox number. If the pound sign is not present, the program thinks it is seeing a numeric literal if the first character is a number (0 through 9) or the plus (+) and minus (-) signs. If the first character is a letter, it assumes you are using a named auxbox, unless the name is ONE AND ONLY ONE character long. In this case the program assumes you are referring to one of 26 special numeric variables (see below). The auxboxes don't have to contain numbers. They can also contain "literals" (alphanumerics). For example, TIME&DATE is an alphanumeric literal, not a number. Alphanumeric auxboxes can be up to 80 characters long. If you try to use an auxbox that has non-numeric data in it when you need a numeric value...it's an error. Also, if you have not set an auxbox to a value before trying to use it, that's an error too (auxboxes don't actually exist until you put something in them.) Auxboxes can be switched back and forth from numeric to alphanumeric values or removed entirely to make room for new ones. VARIABLES When the program encounters a solitary letter where a value is expected it is interpreted as a variable, which is always numeric, and the value in that variable is used in the command. These are very much like algebraic variables except for variables A through F. The program AUTOMATICALLY puts values in those six, so don't try to use them to store anything! Some other commands will put values in additional variables (for example \SET.) Here are some more examples of valid command syntax: \ADD (8 + 16) TO Q \LINE (M*3),(N+80),(O-160),(P+ #434),#23 \READ GREETING.PIC \BUILD #23="Today is ",TIME&DATE[1,8] \" SYNTAX Wherever a pound sign (#) appears in the following command listing it can mean several things. If it is where a numeric value should be, it can be an auxbox, variable, number or mathematical expression containing any of these elements. If it is where an alphanumeric value should be it must be an auxbox (not a variable), or in most cases can be an alphanumeric literal inside quote marks. Start alphanumeric literals with a single or a double quote and end them with whichever (single or double) you started them with. To specify a numeric literal just type the number. To specify an auxbox type the number of the auxbox with a pound sign (#) in front of it, such as #123. If the auxbox is named you may use the name. A number of commands (such as \DISPLAY) allow either numeric or alphanumeric values in each position. Braces ({,}) are used in this manual to indicate that several different things can be put there, or that optional parameters may be included. Do not code the braces. Brackets ([,]) on the other hand should be coded when indicated. They refer to characters within alphanumeric auxboxes. A mathematical expression must be constructed entirely of mathematical parts. You may use any combination of parenthesis ( ( ) ), operators (+-*/) and operands (auxboxes, numbers or variables). Evaluation is standard: things inside of parenthesis are evaluated first, then multiplication and division operators are evaluated with equal precedence, then addition and subtraction equally. Aside from these rules, evaluation is left-to-right. Internal calculations are handled as signed double-word values. This means the intermediate results can be signed values up to 31 bits long. The final total should be between -32K and +32K to be handled properly. The following statement would be valid if auxbox #323 contained a numeric value and variable R was not 0: \MOVE (M*N)+O+#323-P+(Q/R) TO S **** ACTIVATE **** FORMAT: \ACTIVATE {SCREEN #} Screen 0 is the actual screen while screen 1 is the normal background screen. By activating screen 1, all \SHOW, \RUN, \LINE, \CIRCLE, \DOT and other pixel-writing commands write to the background screen. Also all text displayed with the current font is written to the activated screen. The only things that are NOT written to the activated frame are text which uses the DOS font (including numeric display, lines displayed and entered by the user with the \QUESTION command, and text displayed for the \WAIT RETURN command and when the ESCAPE key is pressed.) This function is especially useful for designing complex images which you will want to display all at once. You can create them while the user is reading something else on the screen. The background frame is also used for MASK operations. The image that is brought forward during the \SHOW of a masked frame is taken from the background screen and then the merged frame and background are moved to the screen. Therefore although most image display commands can write to any screen (0,1...), masked frame should only be written to screen 0. Otherwise unexpected results may appear. Any error, even if trapped, will activate screen 0. **** ADD **** FORMAT: \ADD # TO # Must be numeric. The first # can be a mathematical expression. The second # must be a variable or auxbox. The result will overlay the second value. EXAMPLES: \ADD #24 TO #8 \ADD #24*#43 TO #12 (The second example multiplies the contents of auxbox 24 by the contents of auxbox 43 and adds the product to the contents of auxbox 12, putting the result in auxbox 12.) **** APPEND **** FORMAT: \APPEND NNNNNNNN.PIC #,# The specified frames from the named picture file on disk are appended to the current file in RAM or EMM. This means they are tacked on to the end of the file. The frames can all be shown in one animated sequence. It is a good idea to \APPEND as many frames as possible at once. It is faster, and whenever you add single frames DOS has to give the program smaller, more wasteful chunks of RAM. This can fragment the use of your computer's memory if you continually are \APPENDing and \DELETEing frames. Instead, \READ in a new picture file when possible so the program will return all the previous allocations of RAM or EMM to DOS and start fresh. After your \APPEND frames you will need to refer to the frame #'s as they exist in RAM or EMM--not by their numbers in the original file. If the second value is -1 the program will read the entire picture file. The # of frames that were actually read will be in variable "A". When creating/testing a text file this command will execute each time it is encountered. Therefore, your picture file can get very big very quickly. You will have to get around this, perhaps by commenting out the line temporarily by inserting an asterisk (*) in the second column while you test your text file. Don't forget to remove the asterisk when you save the text file! \APPEND can be used to salvage damaged files. If a picture file is invalid for any reason it cannot be \READ but it may be possible to \APPEND some or even all of the frames. Dust particles on a diskette or "head crashes" could all create invalid file conditions. Do not expect \APPEND to solve anything! Maintain multiple backups! **** AUTHORITY **** FORMAT: \AUTHORITY {HIGH} In order to use the \OUT command you need to set the AUTHORITY LEVEL to high. This merely allows the \OUT command to execute. OUT is very powerful--you should KNOW WHAT YOU ARE DOING BEFORE USING THE \OUT COMMAND. IT IS NOT REPEAT NOT TO BE PLAYED WITH. It will write directly to the hardware. You can crash the system or even BREAK THE MONITOR and other parts if you \OUT garbage. I'm SERIOUS. DON'T USE \OUT UNLESS YOU UNDERSTAND WHAT IT WILL DO. That's why you have to enable \OUT with \AUTHORITY. **** BEEP **** FORMAT: \BEEP #{,#} Beeps the speaker for the duration specified in the first number. The first number represents a unit of time equal to that used with the SPEED option of the \ROUNDS command and other commands. A value of 584 will be about one second. A value of zero clicks the speaker. Maximum value is 10,000. Duration is preset to 23. If the \CLOCK speed has been set differently from the default, the length of the beep will be proportionately changed. The optional second number is the tone in cycles- per-second. If present it must be greater than 20 or it will be ignored. Tone is preset to 988 cycles/second. \SOUND OFF will override this command. **** BLANK **** FORMAT: \BLANK #,#,#,# Will blank a rectangle on the screen from the first two values (X-low, Y-low) to the second two values (X-high, Y-high). **** BREAK **** FORMAT: \BREAK {ON} or \BREAK OFF This command is a debugging tool and is not expected to ever be used in a finished tutorial. It turns "single-step" mode on and off. You can also begin single-step operation by pressing ESCAPE and following the prompts. To turn single-step mode off again, press ESCAPE and don't turn the option on. In single-step mode the next line to be executed will appear at the bottom of the screen. If multiple commands appear on the same line they will all be shown and THEY WILL ALL BE EXECUTED in the next cycle. After displaying the line the program waits for you to press a key. That key goes into the program as if you had pressed it in the normal course of running the tutorial--it is NOT absorbed by the "single-step" operation. Macros are NOT single-stepped. During single-step mode all \ON KEY jumps and calls will be taken except the "global" option. However, the \X NNNNN (paragraph) that the command jumps to will NOT be shown, nor will any commands on that line or connected by \+. This is because lines are only displayed when user keypresses would be checked for. This is also true for \CALL's and \JUMP's--the paragraph name lines (\X NNNNN) will not be shown. **** BUILD **** FORMAT: \BUILD #=#{,#,# etc.} This command creates an alphanumeric auxbox out of other auxboxes, or even pieces of other auxboxes, or numbers, or literals (in quotes). The maximum total length is 80 characters. Separate each element with commas. EXAMPLE: \MOVE "HELLO " to #4 \BUILD #3=#4,"THERE!" \DISPLAY #3 ;(HELLO THERE! is displayed) **** BUTTON **** FORMAT: \BUTTON 1=# 2=# 3=#...7=# or 0 Gives an alternate key value for any of seven button codes used by the mouse, joystick, or digitizer. The normal (default) key value for all buttons is 7181, the return key. Values do NOT have to correspond to actual key values. If the input device supplies a button value greater than seven it is automatically assigned the keycode 7181. \BUTTON 0 (zero) will ask the user to enter button presses and press a key. This gives them an opportunity to adjust the buttons to what is most convenient for them. The button presses that the user responds with will be remapped to the first 3 button values and to no (0) buttons pressed. NOTE: For codes corresponding to multiple button presses, the program will "probably" respond to the first button first, as it is almost impossible to press the buttons at the exact same time. Similarly when releasing multiple buttons, an indication of other combinations is likely to occur. Thus single- button functions are most reliably reported. **** CALL **** FORMAT: \CALL NNNNN NNNNN is a name of a place in your text file (see the \X command). The name can be one to 30 characters long with no imbedded spaces. The name must be exactly the same, including capitals and all other characters, in all places it appears or you will not be able to reference it correctly. The difference between \CALL and \JUMP is that \RETURN will return processing to the instruction that follows the \CALL. The instructions that the program does between the \CALL and the matching \RETURN are called a subroutine. A subroutine may call other subroutines, and the current call could in turn have been called... You can go thirty-two (32) deep before you get in too deep and the program can't process. (An error message appears.) **** CALLM **** FORMAT: \CALLM NNNNN Use this special form of the \CALL command to call paragraphs within macros from text files. Within all macros, you are expected to eventually \RETURN to the calling text file, or return with an \ON KEY or \READ command. Once inside a macro use the regular \CALL command to call other paragraphs within the macro area. When you read in a new text file all nested \CALL's, \CALLM's and \IF's are reset, and processing begins at the start of the text file. This will happen even if the program does not actually read the file because it is already in RAM (see \READ). **** CIRCLE **** FORMAT: \CIRCLE {ANGLE=#,# COLOR=# LOCATION=#,# RADIUS=#,#} Draws a circle, oval, or arc by one of two methods. ANGLE=#,# If specified the program will use a lookup table of sine values to calculate the endpoints of 1-degree connected line segments. If you draw a complete circle by not specifying any angle (not by specifying 0,360) it calculates the dots mathematically using the Pythagorean Theorem. COLOR=# If in XOR mode when executed, will produce a speckled circle because some dots are drawn more than once. LOCATION=#,# Is the location of the center of the circle. It need not be on the screen. RADIUS=#,# Is the length of the radii on the X, Y axis. ANGLES are only "correct" (circular, not oval) for radii of 10:12 ratio--the ratio of the individual dot's width to height on a standard CGA monitor with a 4:3 ratio. Other ratios will affect the actual angle that a specified angle is drawn at. Maximum radius on either axis is 2000. **** CLEAR **** FORMAT: \CLEAR {KEYBOARD, MACROS, NAMES, ON KEYS, PICTURES, SCREEN, SHOW, SPRITES, SPRITE #} Resets parameters to "standard" values. Use only one option at a time. KEYBOARD Clears all keys out of the keyboard buffer. The key values are lost. The program always gets ONE keypress (if available) between each command line or cycle of animation and puts it in variable "B". It is therefore unlikely that the keyboard buffer will ever fill up, except when executing commands that take a long time to process. \DRAW with the PAINT option and \READ are both candidates. Of course, the user would have to be pressing a lot of keys or holding one down. MACROS Clears the macros you have read so far and their names. The program stores up to nine macro filenames that have been read as well as the macros themselves. This command clears out both the names and the macros. You can read more than nine macros without \CLEARing if they will fit in the 10k (approximate) available, but the names will not be stored. \READ will reread the macro if it encounters a name it hasn't stored, possibly filling up your macro area. You can use \DELETE to remove specific macro filenames without \CLEARing the macro area. This command also clears any \ON KEY specifications that refer to paragraphs in the macro area. MOUSE Sets mouse options to default values. See \MOUSE for what these values are. The \SCREEN command, if it changes the current mode, will execute a \CLEAR MOUSE command automatically. NAMES Clears all symbolic auxnames that you have created. No auxbox data is cleared; it may still be referred to by auxbox number. Reading new text files and using the editor does NOT clear auxbox names. ON KEYS Clears all \ON KEY specifications either for macros or for text depending on where the command appears (it clears only the one it's in). You need not specify which one to clear. The program clears the macro specs if you are in a macro and the text specs if you aren't. ON ERROR Clears the \ON ERROR command, making the program stop on any error again (That's the default.) PICTURES This removes all pictures in RAM or EMM from memory. Use before changing screen modes because you cannot change to incompatible modes (different resolutions) while you have pictures in RAM or EMM. You cannot use this option if you have changes to the current file or if you are in the picture editor at the time. SCREEN This is a fastest way to clear the screen. Will clear the background screen if it is currently active. SHOW This clears the parameters set up with the keyword options of \SHOW. WINDOW is set to the full screen, AND=NO, OR=NO, XOR=NO, PATH=NO, LOCATION=0,0 and MOTION=0,0. The \SCREEN command, if it changes the current mode, will execute a \CLEAR SHOW command automatically. SPRITES Clears all sprites that have been set up with \SPRITE and \SPRINT and resets all the \SPRITE parameters to the default values listed in \SPRITE. SPRITE # Clears one sprinted frame or resets the \SPRITE values to their defaults without clearing any frames. To use this option to clear a single sprite element you must keep track of which frames were set up with \SPRINT and in what order. To clear the first sprinted frame use 1, the second, 2 etc. A value of zero (0) will reset the \SPRITE parameters but will NOT clear the elements you have already set up. **** CLOCK **** FORMAT: \CLOCK SPEED=# CURSOR=#,# FORMAT={MM:SS, HH:MM:SS, HH:MM,SS} Clock serves several functions. It can be used to set the number of times that the PC Asynchronous Clock interrupt occurs each second (SPEED= option), or to display the current time somewhere on the screen. When displaying the time only the digits that change are updated, except the hours digits are updated with the minutes digits. If you place a drawing or text over the clock it will not completely reappear immediately. If a \CLEAR SCREEN or similar command is executed the entire clock display will be rewritten. SPEED=# Specifies the number of times the asynchronous clock should cause an internal software interrupt, per second. Values are from 1 to 6 where one is the standard DOS amount, about 18.2 times per second, and each unit above (2, 3 etc.) is twice as often. The default is 5, or about 584 times per second. This provides enough control for most applications without taking too much "overhead" in CPU usage. This value is temporarily reset to the standard value, 18.2, during the \EXECUTE command. It is also reset on exit. CURSOR=#,# Specify the position of the on-screen clock on the screen. Values are in characters on the X, Y axis, where 0,0 is the upper left corner of the screen. FORMAT={MM:SS, HH:MM:SS, HH:MM,SS} Lets you specify how much of the current time you would like to display. The format HH:MM will blink the colon every second, other formats update the hours and minutes only once a minute. **** CLOSE **** FORMAT: \CLOSE NNNNNNNN.EXT or LPT#: This closes a named file or turns off access to LPT#: (the system printer). NNNNNNNN is the file name. The extension can be DAT, PIC, or PRN. The file must have previously been opened with \OPEN. Errors in processing will cause these files to be closed automatically when processing stops. They will also be closed if you exit to DOS. Files must always be closed if they have been written to, so that the file directory information that DOS maintains will be properly updated. For all manual operations with the editor and when writing auxiliary files, this program automatically closes files after it writes them. Closing LPT#: (where # is 1, 2, or 3) does not actually signal the printer in any way, it simply disables access to it with \PRINT. You might do this so that you can use the statement to write print files to disk. EXAMPLES: \CLOSE LPT1: \CLOSE SOANDSO.PRN **** CONNECT **** FORMAT: \CONNECT {ON or YES} or {OFF or NO} This will cause vector images to be drawn with connected dots in the picture editor and with \SHOW. To draw connected dots with sprites use the CONNECT=YES option of \SPRITE. The color of the line that is drawn will be the color of the upcoming dot. The starting dot of each line segment will not be drawn after the first one in the image. The connect option is initially OFF. \CONNECT with no parameters defaults to turning connected mode ON. The lines are clipped if the endpoints are off the screen. In Version 7.24 if the endpoints are more than 32767 dots apart on any axis a sign conversion error may occur during internal calculations, and the line will not be drawn properly. This separation corresponds to more than 100 times the width of the screen in the CGA mode and over 150 times the CGA height of 200 dots. EXAMPLES: \CONNECT NO ;turns it off \CONNECT YES ;turns it on **** CONVERT **** FORMAT: \CONVERT # This will convert an auxbox from an alphanumeric to a numeric or from a numeric to an alphanumeric. It is up to you to know which way you are going. If you are going from an alphanumeric to a numeric and the alphanumeric starts with numbers, it will convert the numbers only. Numbers that become greater than 32767 or less than -32768 will produce an error. The alphanumeric auxbox produced when you convert from a number is six bytes long and will contain "leading" (left-hand) spaces in place of high-order zeroes, with a minus sign (-) if needed next to the leading character. Non-numeric auxboxes are displayed with the current font at a location set by the \LOCATE command. Numeric auxboxes are displayed with the DOS font, and the cursor position is then set with \CURSOR. EXAMPLES: \MOVE 328 TO #80 \CURSOR 0,0 \DISPLAY #80 ;328 is displayed as a numeric \CONVERT #80 \LOCATE 0,10 \DISPLAY #80 ;328 displayed in the current font \DISPLAY #80[4,2] ;32 is displayed. **** CRAWL **** FORMAT: \CRAWL #{,X or A or O,#} This sets text display mode to CRAWL from right to left. The first number is the speed of the crawl, the second parameter if included should be an X to XOR the text onto the screen, or an A or O to AND or OR the text. If the text is to be XORed, ANDed or ORed, then a third value should be included as the color to XOR, AND or OR the text with as it is placed on the screen. Like \SCROLL and unlike \OVERLAY it does not XOR, AND or OR the text with what is already on the screen. The area to be crawled is set with \LOCATE for the upper left corner, and \WIDTH. All \CRAWLed text is one character high. Anything in the crawl area that was there before will be shifted off the screen. This command gives the effect of an electronic news banner crawling through a window from right to left. AND, OR, and XOR are most useful for fonts designed with just black (background) and the highest numeric color available for the screen mode. Special considerations for BITPLANE modes: With \SCROLL and \OVERLAY, in bitplane modes you can only XOR, AND, or OR with color 1. Use \TEXT PLANE= for effects similar to what other color values would give you in bitmapped modes. OR has no effect in bitplane modes (will work the same as XOR). AND with 0 has no effect in ANY mode. **** CURSOR **** FORMAT: \CURSOR #,# {,#,#} This sets a cursor for user input and numeric data output. The screen in this case should be thought of as being cursor positions. See the \SCREEN command for a table of character dimensions for each screen mode. The upper left corner is position 0,0. In CGA mode, which is 320 by 200 dots, there are 40 X 25 cursor positions. The first value is the column (0-39) and the second value is the row (0- 24). The bottom right position of the screen is not available because DOS would scroll the entire screen if a character is placed there. The second two numbers, if present, create a window for user input and numeric data output. The cursor will be set to the upper left corner (the place specified by the first two numbers.) Text lines that are too long for the available window will be automatically scrolled for the user. **** DATA **** FORMAT: \DATA #{,#,#...} This command reads ASCII data into auxboxes in P11. The file should be delimited by commas for each field and by 13,10 (carriage return, line feed) for each record. Each \DATA statement reads ONE record. Maximum record length is 512 bytes including the 13,10. Each field is placed in the corresponding auxbox, by position. You should \ELIMINATE the auxbox(s) you will read data into before executing the \DATA statement. That way if the auxbox(s) still don't exist you know you read the last record or a blank (empty) record. **** DELETE **** FORMAT: \DELETE {FRAME #} {MACRO NNNNNNNN} The FRAME option of this command will delete the frame requested from the current picture file in RAM provided there are no changes to that file since the last save. This command will only return the space to DOS if the frame being deleted is the sole user of the associated chunk of RAM. See Appendix "E", Space Considerations, for more information. The MACRO option will delete the macro name from the list of stored names. IT WILL NOT DELETE THE MACRO! This is so you can more easily control which macro names are stored. When a \READ statement is encountered and the name matches one of the nine stored macro names, the read is skipped. You may use \CLEAR to remove all the macro names but that also removes the macros. EXAMPLES: \DELETE FRAME 23 \DELETE MACRO SETNAMES **** DIGITIZER **** FORMAT: \DIGITIZER {OFF}, {INITIALIZE #,#{,#{,#,#}}}, or {?} INITIALIZE Turns the digitizer on. The first two numbers for X, Y axis resolution are not adjusted before being passed to the digitizer so be sure to account for any rounding that the digitizer will do. The default values (in CGA mode) are 328 on the X-axis and 298 on the Y-axis. Refer to your digitizer's manual for more information. The third number if present should be a two or a one (2 or 1). If two, COM2 rather than COM1 will be used. (The communications port COM1 is located at address 3F8h, while COM2 is at 2F8h.) The fourth and fifth numbers are the X-offset and the Y-offset, if you don't want offset 0,0. The offset is added to the screen X,Y position to get the minimum axis values. You may prefer a border on the right as well as the left. OFF Turns the digitizer off if it was on. ? Returns the current state of the digitizer. 0 is off, 1 is off, but had previously been on, and 2 is currently on. Value is returned is variable "A". Turning on the digitizer turns off the mouse or joystick if they are on. If you change screen modes you should reset the digitizer, because the maximum X- and Y- axis values may be incorrect for the new screen mode. **** DISPLAY **** FORMAT: \DISPLAY #{,#,#...} Will display text or numbers on the screen. Numbers are displayed using the DOS standard font, and always on the actual screen, wherever \CURSOR set the cursor. Alphanumerics, including literals in quotes, are displayed using the current font wherever \LOCATE set the text cursor, on the active screen (see \ACTIVATE.) Additional items can be displayed when separated by commas. Any literal auxbox can have just a portion of it displayed by immediately following the name or # with brackets and two numbers: \DISPLAY #45[12,23] The first number in the brackets is the starting position to display and the second is the length. These numbers can be variables or even numeric auxboxes. Do not use the tab character within a \DISLAY sequence. EXAMPLES: \DISPLAY "Today is ",TIME&DATE[1,8] \DISPLAY A,B,C,#1,#45,#32767 In the second example, first the variables A, B, and C will be displayed using the DOS character set at the current numeric cursor location, and the numeric cursor location will be advanced by seven places for each variable displayed. If there is not enough room (seven characters) the cursor will be advanced to the next line and to the top of the screen if at the bottom. The placement of auxboxes #1 and #45 in this example would depend on whether they were numeric or not. Auxbox #32767 (TIME&DATE) would be displayed wherever the non-numeric cursor is set (in the current font) and would advance the cursor according to the width of the font. (See \LOCATE.) **** DIVIDE **** FORMAT: \DIVIDE # by # {REMAINDER #} Don't divide by zero, of course. The second number can be a numeric literal, mathematical equation, numeric auxbox or variable. The first number must be a numeric auxbox or variable. The result (aside from the remainder) goes in the first value, and the remainder (if specified) goes in the third value. REMAINDER is optional. If used only the first few letters (REM) are actually needed. REMAINDER must follow the second number by at least one space. EXAMPLES: \MOVE 32000 TO #48 \DIVIDE #48 BY (34*55) +16000 REM A \DISPLAY #48,A 1 and 14130 are displayed on the screen. First, the portion referenced by the word BY is evaluated so that the program knows what to divide #48 by. (34*55)+16000 is equal to 17870. Dividing 32000 by 17870 gives 1 with a remainder of 14130. **** DOT **** FORMAT: \DOT #,#,#{,X or A or O} The first two numbers are the X, Y location for the dot. The third number is the color of the dot, where zero is the background color. The optional ,X (comma X) will XOR the dot onto the screen. ,X will also turn on XOR mode for future \DRAW and \LINE commands. Similarly, A will turn on AND mode and O will turn on OR mode. Another \DOT command is needed to turn off XOR, AND and OR. To just turn on XOR or OR without actually drawing anything, draw a background dot: This command writes a dot but background (0) XORs to produce no change. To just turn on AND, write a foreground dot (whatever the current screen mode allows as the highest value dot.) If the third option is a question mark (?) the color of the dot at the location specified is put in variable "A". In this case do not use XOR, AND, or OR. \PEN can also be used to turn on XOR, AND, and OR mode. **** DRAW **** FORMAT: \DRAW {UDLREFGH}#, C#, J#,#, M{+,-}#,{+,-}#, P #,{UDLRHVA}, S{X,Y or A} All parameters here are one letter and then some numbers or letters or whatever. The options that belong to each parameter follow that parameter immediately without spaces, except P (Paint). Commas are not necessary to separate the elements providing the syntax is still understandable. For example the two values that follow the "J", "P", and "M" options must be separated by commas, but options need not be. \DRAW functions more or less as a series of line segments. J#,# will Jump to that spot on the screen without drawing. UDLREFGH# will move # dots in the direction specified- -Up, Down, Left, Right and E, F, G, and H which go at angles. For example one dot to the left and one up is H while one dot to the right and one down is F. C# is a Color, but C followed by just a comma (C,) sets the current color to clear (which is not the same as blank.) S{X, Y or A}# is the Scale amount. X changes the scale for the X-axis, Y changes the scale for Y-axis, and A changes them both. A number follows X, Y or A. 8 is unscaled, so 4 is half scale and 16 is double scale. The X, Y or A must immediately follow the S with no spaces. P is the only draw command that should be followed by one or more spaces after the letter. It stands for Paint and IS the Paint command, but use only one letter to describe it. (See \Paint). M {+,-}#,{+,-}# is Move. M will draw from the current cursor location to the spot named by the coordinates #,# that follow the M. The line will be in the current color If you precede the numbers with a + or a -, the move will be relative to the initial cursor position. Both X and Y must be specified even if they are 0. EXAMPLES: \DRAW P 2,D,C2R33M+20,-35J40,43C,R22 IS THE SAME AS: \DRAW P 2,D,C2,R33,M+20,-35,J40,43,C3,D4,C,R22 In the above example, Paint mode is first set to a border color of two (2) (red in palette 0 of CGA 4- color mode), and aimed down. Then the color is set to two (2) and the cursor is moved to the right 33 units, painting as it goes. The starting position was not specified so the command would use the current position. Then the cursor moves to a point 20 dots to the right AND 35 dots down, still painting as it goes. Next it jumps to location 40,43 WITHOUT DRAWING ANYTHING. Then we set the color to 3 (yellow in CGA palette 0) and draw down four dots. Then the color is set to clear and we move right 22 units, perhaps so that another draw command can do something there. **** ELIMINATE **** FORMAT: \ELIMINATE #,#,# TO #,# TO # etc.. Eliminates auxboxes from the auxfile in RAM. You can delete one (1) or all (except the 32767th, which is TIME&DATE). Commas are used to separate boxes to be removed. When the word TO separates the auxbox numbers, the range, inclusive, is removed. It is important to remember two things about this command: First, you cannot use symbolic names or math equations or variables to specify the locations to be eliminated. The expressions must be #23, #45 TO #87, and so on. They are NOT evaluated--the first one just listed would remove auxbox 23, not the one represented by the value stored in 23. Second, the symbolic name is NOT removed. It still refers to this box. (Names are removed with \CLEAR NAMES.) A \READ will NOT read the aux file if it is the exact same name as the aux file already in RAM. EXAMPLES: \* this command clears all auxboxes except, \* of course, the TIME&DATE auxbox. \ELIMINATE #1 TO #32766 **** ELSE **** FORMAT: \ELSE Part of IF-THEN-ELSE statements. See \IF. When \IF statements are evaluated, they are either TRUE or FALSE. If they are false, they go to the corresponding \ELSE statement (skipping any subordinate \IF's and the \THEN's and \ELSE's that accompany them). Either the \THEN or the \ELSE clause and any accompanying actions can be left off, but to leave both off would be totally useless. EXAMPLES: \IF #34 = 233 \ELSE \JUMP NEXT_CHECK \ENDIF \IF #54 = "5" \MOVE 4 TO G \ENDIF \X NEXT_CHECK \IF T = 76 \THEN \MOVE 6 TO Q \ELSE \MOVE 4 TO Q \ENDIF **** END **** FORMAT: \END Stops processing and returns you to the editor, or returns processing to DOS if using the runtime version. When the program returns to DOS it passes a return code as follows: 0--Normal exit--either with this command or interactively through F6. 1--An error occurred (errors are listed in the back of this manual). 2--A critical error occurred--most likely a disk error, but possibly a character device error. 3--Both an error and a critical error occurred. This is difficult if not impossible to achieve. **** ENDIF **** FORMAT: \ENDIF Ends an IF-THEN-ELSE statement. See \IF. This statement must come before an \X command (paragraph name) coded in-line (sequentially) in the text file. However, you can \JUMP and \CALL your way out of an \IF statement or even read in a new text file or \END the program. \ENDIF ends all nested \IF statements that have been coded in-line. It does NOT end \IF statements that were in process when a call occurred, only the one's SINCE the last call. EXAMPLES: \IF #32<999 \ADD 1 TO #32 \ELSE \MOVE 0 TO #32 \IF C=3 \MOVE 0 TO C \ELSE \ADD 1 TO C \ENDIF **** ERROR **** FORMAT: \ERROR ? Places the last (most recent) error code in variable "A". It has no other purpose. Use \ON ERROR for error trapping. **** EXCHANGE **** FORMAT: \EXCHANGE SCREENS If you have saved a screen with \SAVE SCREEN you can exchange (swap) the current screen with the saved screen using this command. The screen is saved to the background screen, screen 1. (See \ACTIVATE.) The background screen is used for raster frame mask operations. If you have set B:0 in the environmental variable P11FLAGS= or in the startup parameters on the command line, then the screen will be exchanged with a previously saved version on disk, in the \P11\TEMP directory. That directory MUST exist and a screen must be saved in it before using \EXCHANGE SCREEN. This will toggle the name of the current saved screen between SCRNDUMP.SV1 and SCRNDUMP.SV2, so there must be enough disk space for two entire screen images in order to use \EXCHANGE SCREEN. **** EXECUTE **** FORMAT: \EXECUTE DOS> and then anything you would type at the DOS prompt, or \EXECUTE > and then a program you wish to load and execute (run). This command does not "exit" to DOS. Instead it will load and execute the named program or load a second copy of the COMMAND PROCESSOR (DOS) and give it the command (if any) that follows the greater than (>) sign. Legitimate commands could be anything that will fit in memory. See Appendix "N" for a complete discussion of this powerful command. What you code after the > is not evaluated for variables or auxboxes. It is given directly to the second copy of DOS, or simply used to load and execute a program. Therefore drive specifications are NOT variables or auxboxes. Drive "A" is drive 1, drive "B" is drive 2 and so on. Use forward slashes (/) for pathnames: this program will reverse them automatically (up to the first space). A backslash would indicate another command on the same line for this program. If you want to use a backslash after a space, you can use an auxbox to specify the command line: Use a parenthesis and specify the auxbox within the parenthesis: \EXECUTE >(#454) As of version 7.30 you can do an \EXECUTE with a PRN, DAT, or PIC file open, but you should be sure to consider the consequences of this before you do it: If a file is open and you change disks or delete the file, you may mess up DOS's idea of the current file status', damaging that file. It is advised that you never do an \EXECUTE without closing all files unless you HAVE TO have them open, in which case you should try not to let the user have control during the \EXECUTEd operation. Just do what you have to do, like an HPRASTER print for example, and come back. During an \EXECUTE you can do anything that will fit in RAM, including formatting disks. However you should only format diskettes or execute Terminate, Stay Resident programs if absolutely necessary as it is likely to take some base RAM to do this, and that memory will NOT be returned until you reboot. When executing the command processor, use the command EXIT there to return to this program (either at the DOS prompt or from a batch file). DOS returns a code upon completion of an executed program. You will find this code in variable "A". The executed program may return it's own code. This will be in variable "C". Both these variables will be changed by \EXECUTE. If the command fails for some reason variable "A" will contain -1 and variable "C" will contain the error code returned by DOS. Possible reasons would be disk errors, file not found, etc. **** FRAME **** FORMAT: \FRAME #,#,#,#{,M or O or OM or MO} or \FRAME # or \FRAME ? Specifies that a frame should be added to the end of the current picture file. You must already have a picture file in RAM or EMM. This command will only add a single frame at the end. If you specify four numbers this will add a raster frame. If you specify just one number a vector frame of that number of dots will be added. It will have "random" dot values at the start. A question mark (?) will place the current total number of frames in variable "A". Specify four numbers to get a raster image from the screen. The first two are the upper left X, Y location on the screen. The third and fourth numbers indicate the size of the frame. This command will round the first value, the X- coordinate, down to a byte boundary. In CGA mode there are four dots per byte so values of 0, 4, 8, 12 etc. would not be changed but 1, 2 and 3 would all be rounded down, having the effect of saving from the zero position on the X-axis. 5, 6 and 7 would all round to the fourth dot position and so on. The right-hand edge will be adjusted accordingly so that the width will remain unchanged. See the \SCREEN command for a table of dots per byte for each available screen mode. ,M will add a masked frame, while ,O will add on onion skin frame. ,MO or ,OM will add a masked onion skin frame. Of course, onion skin mode is not available in monochrome modes! The base location stored in the header of the new frame will be 0,0 as will the base time value. Therefore, you will need to use the location specified in the \FRAME command when you display the frame, for it to be in the same location. You can save up to a full screen--in CGA mode that would be 320 on the X-axis and 200 on the Y-axis. When testing a text file that contains this command, the command will add a frame each time it is encountered, so you may find you picture file getting very big very quickly! If you need to allow more than the default maximum of about 1000 frames, use the P11FLAGS= environment string option or command line parameter: F:# (where # is between 10 and 8,000.) **** HEIGHT **** FORMAT: \HEIGHT # Specifies the height of a text window on the screen. Used with \LOCATE and \WIDTH to define the area text will appear in. Text can be \SCROLLed or \OVERLAYd in the window you define and place with \HEIGHT, \WIDTH and \LOCATE. (\CRAWL does not use \HEIGHT.) **** HUE **** FORMAT: \HUE {COLOR=#,#} {SET=#,#,#} {INCREMENT=#,#,#} {HOLD={YES or NO}} {CY=YES or NO} GRAY={Y or N} Hues are preset for all colors, but on VGA systems you can reset each color to a choice of 262,144 hues. Each of the three portions of each color-- red, green, and blue, can be set to numbers from 0 to 63. By using this command repeatedly in a text file you can do "color cycling." You can set the internal hue table and not actually set the hue hardware registers by using HOLD=YES. INCREMENT= will modify the current hue values of a color. The increment values can each be positive, negative, or 0. The COLORS= values are the low and high color numbers that are to be changed. CYCLES=YES does color cycling. It moves the color down 1 within the range and flips the bottom to the top. Can be added to \RUN too. GRAY=YES the colors are changed but NOT the color table. To go back to non-grayscale, use \HUE C=#,# without any other parameters. If C=#,# is included with GRAY=Y, only those colors would be gray scaled. For gray scaling, S, I, and H are ignored. **** IF **** FORMAT: \IF # {=><} # {{AND or OR} # {=><} #} This command is used to compare two operands or two sets of two operands. The expression is evaluated and if true the \THEN clause is executed, then the \ELSE clause is skipped. If it evaluates to false the \THEN portion is skipped and the \ELSE clause is executed. These can be nested 32 deep, and should be ended with \ENDIF. If the two #'s represent numbers they are compared arithmetically. If they represent auxboxes with alphanumerics in them they are compared as ASCII strings with the exception that lower-case letters are capitalized for the comparison. If the two strings are of unequal length the shorter one is "padded" with spaces. The ASCII value of a single character in quote marks (single or double) can be compared arithmetically. You may use two operators together (<=, <>, or >=) if desired. You may connect two sets of comparisons together with either AND or OR, but only one such connection can be made (only one keyword AND or OR will be evaluated per \IF command). EXAMPLE: \IF (A + 4) < B\THEN\IF #44 <= #54\THEN\MOVE 44 TO #87 \ELSE\IF S <> 99 OR V=88\THEN\CALL LOOP1\ELSE \JUMP LOOP2\ELSE\MOVE "APPLES AND ORANGES" to #989\ENDIF NOTE: the THEN command is always optional. Spaces after the backslash are ignored and can sometimes make program logic easier to follow. You may want to consult the section on programming and the \ELSE, \THEN, and \ENDIF commands for further descriptions of "if" statements. **** IN **** FORMAT: \IN # {BYTE or WORD} IN will let you receive data from a hardware device, often called a PORT. The byte or word input will be placed in variable "A". Generally, # is between 0 and 255 and refers to a device in the system. **** JOYSTICK **** FORMAT: \JOY (or \JOYSTICK) {OFF, ?} {INITIALIZE {CENTERED=#,# RESOLUTION=#,# SAMPLES=#}} {ZERO} {ACCURACY=#,#} If INITIALIZE is used, the same thing happens as when you press <CTRL>+j while creating drawings except values for RESOLUTION, SAMPLES, and CENTERED are taken from the command and not asked of the user. A message appears near the bottom of the screen instructing the user to move the joystick around and press a key. These keypresses do NOT go into variable "B". The numbers that the joystick returns are products of the current cursor location plus values that correspond to the joystick positions. \JOYSTICK ON or \JOYSTICK with no parameters will get joystick information and if the joystick was off but had been previously initialed, will turn it on again. OFF will inhibit use of the joystick but does not actually send any signal to the input device. A question mark (?) will put the status of the joystick in variable "A". Any other parameters would be ignored. The status is as follows: 1 - port assumed to be available, not on. 2 - port used, so definitely available. 3 - currently in use (active). Initializing the joystick turns off the digitizer but not the mouse if on. Use \MOUSE OFF if you do not want both on. RESOLUTION is the maximum variation from the current position that the joystick can return (maximum deflection by the user) and is a number from 0 to 50 (0 means no movement on that axis.) SAMPLES are the number of times to read the joystick value that is returned before automatically summing the numbers, throwing out the highest and lowest values, and averaging the rest. Sampling is a number from 4 to 50. The Centered option will cause the joystick to move the cursor around the point specified. It will be able to move the distance specified in the RESOLUTION= parameter. In this mode deflection will always be from the centered point, not from the last value returned. ACCURACY is the units of variation. For example, A=5,5 will return values of -15,-10,-5,0,5,10,15, etc. within RESOLUTION maximums (plus and minus.) The accuracy rounds towards 0 to a multiple of these settings. The joystick will simply invert the #'s if the joystick is held upside down and initialized, but if at a 90 degree angle, you will get an error message (Error Code 3585.) **** JRCOLOR **** FORMAT: \JRCOLOR #,#,#,#,# The IBM-PCjr, as well as most TANDY (Radio Shack) PC-compatibles have the ability to display any four of 16 colors in CGA mode. To set these colors, use this command. Set the background with the first value, then the three foreground colors. The fifth value is for the border, which can also be set to one of the 16 available colors. On TANDY machines you may have to execute the DOS command MODE with the option COLORMAP before executing this program for \JRCOLOR to work. **** JUMP **** FORMAT: \JUMP NNNNNN NNNNNN is a named place in your text file. See the \X command. The name can be one (1) to 30 bytes long and cannot contain spaces. \JUMPs are different from \CALLs because they do not retain a return address (the address of the command after a \CALL statement is saved for a corresponding \RETURN statement to use.) Jumps just go somewhere and processing continues from there. The usual thing to code after a \JUMP is an \X command for some other \JUMP, \CALL, \ON KEY or \ON ERROR command to go to, or if the \JUMP was within the \THEN portion of an \IF statement, an \ELSE or \ENDIF command may also follow a \JUMP. Example: \* This routine waits forever for ANY key and then displays it's value. \MOVE 0 TO B \X NO_KEY_PRESSED_YET \IF B=0 \ JUMP NO_KEY_PRESSED_YET \ENDIF \DISPLAY B **** KEY **** FORMAT: \KEY CYCLE=# DECREASE=# END=# FORWARD=# INCREASE=# MINUS=# NEXT=# PLUS=# REVERSE=# SINGLES=# Lets you assign keyboard codes for various \SHOW and \RUN options. The numbers correspond to DOS scan codes for various keypresses. CYCLE=# Assigns a key which will cause animation to stop at the end of the cycle. Only used for \SHOW. DECREASE=# Assigns a key for slowing down animation. END=# Assigns an alternate key for the ESC key. Pressing the real ESC key three times in a row will override this and force the keycode anyway. You cannot code the RET (return) keycode (7181) for this key. FORWARD=# Assigns a key for single-stepping forward through the frames. Only used for \SHOW. INCREASE=# Assigns a key for speeding up animation. MINUS=# Assigns a key for making animation run backward. Only used for \SHOW. NEXT=# Assigns a key for ending animation and advancing to the next command. Only used for \SHOW. PLUS=# Assigns a key for making animation run forward. Only used for \SHOW. REVERSE=# Assigns a key for single-stepping backwards through the frames. Only used for \SHOW. SINGLES=# Changes the single-dot cursor movement toggle key. Initially the "5" key on the numeric keypad serves this purpose on XT-style keyboards. Setting this will toggle it to single-dot. A value of 0 will inhibit changing the dot travel distance. NOTE: + and - (plus and minus) on the numeric keyboard are already assigned to PLUS= and MINUS=. For some of these keys we recommend using the following keys: DESCRIPTION KEY KEY VALUE CYCLE........SPACE BAR...................14624 DECREASE.....DOWN ARROW..................20480 FORWARD......RIGHT ARROW.................19712 INCREASE.....UP ARROW....................18432 NEXT.........RETURN KEY.................. 7181 MINUS........MINUS KEY...................18989 PLUS.........PLUS KEY....................20011 REVERSE......LEFT ARROW..................19200 SINGLES......"5" KEY ON KEYPAD (XT-STYLE)19456 0 coded in any parameter turns off that option. NUM LOCK ON NUM LOCK OFF KEY VALUE PG DN........20787.......................20736 PG UP........18745.......................18688 HOME.........18231.......................18176 END..........20273.......................20224 LEFT ARROW...19252.......................19200 RIGHT ARROW..19766.......................19712 UP ARROW.....18488.......................18432 DOWN ARROW...20530.......................20480 **** LENGTH **** FORMAT: \LENGTH # Gets the length of the specified auxbox and puts it in variable "A". Numeric auxboxes are always two bytes long. If the auxbox does not exist the length will be zero (0). Example: \MOVE "EAT MORE CHILI!" TO #32 \LENGTH #32 \DISPLAY A ;15 would be displayed \MOVE 324 TO #33 \LENGTH #33 \DISPLAY A ;2 would be displayed **** LINE **** FORMAT: \LINE #,#,#,#,#{,B or ,BF} or \LINE ,#,#,#{,B or ,BF} Draws a line on the screen. The first two numbers are the X, Y coordinates of one end of the line, the next two are the other end. The fifth number is the color. The second position given will become the "current" endpoint (see below). If you use the second option (three values preceded by a comma) a line will be drawn from the current endpoint (set by a previous \LINE or \DRAW command) to the endpoint given in the first two values. The third value is the color. The current endpoint will be updated to the new endpoint. ,B (comma B) will draw a rectangle with corners as specified, while ,BF will draw a filled box. The ,BF option will NOT be affected by the status of the XOR switch nor will it affect that switch. All other options of \LINE are affected by the current state of the XOR switch (set with \DOT). Some lines are not clipped properly. Specifically, if the total separation on either axis of the two endpoints is greater than 32767 and both endpoints are off the screen the displayed line may not be correct, or incorrect lines are displayed that should have been completely off the screen. This does not occur except on widely separated endpoints. These long lines are excessive values that cannot be coded in vector draw mode, and are unlikely to be coded in \LINE or \DRAW commands. But since it's documented, don't be surprised when--and if--it ever happens to you. Don't utilize it though--it may be inconsistent! **** LOAD **** FORMAT: \LOAD NNNNNNNN.PIC This works as a combination of \OPEN and \READ. You can \READ and \LOAD at the same time. You CANNOT \OPEN and \LOAD at the same time. Load will not decompress the file, but nor will it use EMM. So, if you are working in base RAM, this can save space, BUT, and this is a big but, it will only do the things \OPEN can do - it won't work with \RUN, only with \SHOW. **** LOCATE **** FORMAT: \LOCATE #,# #,# is the X and Y position for the text cursor to put text lines, alphanumeric auxboxes and literals on the screen. The X-axis number may be rounded down, because resolution is every byte on the X-axis and every dot on the Y-axis. For example, in CGA mode there are 4 dots per byte on the X-axis. In all bitplane modes, there are 8 dots per byte. **** MARQUE **** FORMAT: \MARQUE #,#,#,#{,#{,#}} This forms a moving multi-colored rectangle on the screen. The first four numbers are the X, Y upper left corner and the X, Y lower right corner. The fifth number is the number of colors to use in the marque. If a sixth number is included, then the fifth and sixth numbers are the "from" and "to" numbers for the marque. The marque will remain running on the screen until any key is pressed or until the value set with \ROUNDS is exceeded (see \ROUNDS). Speed of each cycle is set with the SPEED option of \ROUNDS. If ROUNDS is exceeded, -1 will be in variable "B", otherwise the value of the key pressed will be there. A mouse button press will also exit this routine. Variable "C" will have the number of completed cycles. A good use of this command might be to indicate where the user is to enter a response--it doesn't "absorb" the keypress. If the very next command were \QUESTION coded on the same line the key pressed would go into that routine. \MARQUE gets the key value and puts it in variable "B" but does not get the key from the keyboard. Pressing a mouse button would simply exit the \MARQUE command and enter the next command. EXAMPLES: \MARQUE 20,27,44,78,2 \QUESTION #33 The above example would give the keypress (if one occurred before either the time ran out or a mouse button was pressed) to \QUESTION because they are coded on the same line. \MARQUE 11,13,99,122,3 \QUESTION W The above example would NOT give the key that ended \MARQUE to \QUESTION. **** MEMORY **** FORMAT: \MEMORY {?} {EMM} Places the size of the largest piece of memory left for pictures, executing subprograms, etc. in variable "A". This does not include space used by any pictures already in RAM, so it is indicative of space left to \APPEND frames with. The value returned is in K (1024 bytes). The question mark (?) is optional. If the second option, EMM, is used, this will return the total number of NEVER-USED 16K (16384 byte) pages that have been allocated to the program. It is NOT necessarily the available amount, but is certainly less than or equal to the amount available. When pages of EMM are taken by the program, they are not returned until exiting the program. Therefore, for example, if you read in a very large picture file and then a very small picture file, the number of pages returned by this function will be quite a bit less than what is actually available at the time, since once you had read in the large file, the amount never used will be less. **** MOUSE **** FORMAT: \MOUSE {INITIALIZE, OFF, or ?} {AND={YES or NO} ACCURACY=#,# END=#,#,#,# FRAME=#,# KEEP=Y (or anything for no) LOCATION=#,# OR={YES or NO} RESOLUTION=#,# ROUNDS=# SPEED=# WINDOW=#,#,#,# XOR={YES or NO or AUTOMATIC}} \MOUSE allows input of the cursor location and buttons pressed from the active input device, and displays a cursor (either a frame, or crosshairs, or both) at the current position. Raster frames, if used as a cursor, are positioned with their center on the current cursor position. \MOUSE executes until exited by one of several methods. To exit, the timer can run out (which is set with the ROUNDS= option); the user can press any mouse button; they can press any active \ON KEY key; they can enter any active END window; or they can press RETURN. The user can use the cursor keys and the number keys to move the cursor. The joystick, keyboard or digitizer can be substituted for the mouse. (Hardware limitations do not allow the digitizer and the cursor keys to both work at the same time.) To some extent, the joystick and the mouse may be used together. If you want the user to use the mouse buttons (or RETURN) to end the mouse activity then don't set any END= parameters after a \CLEAR MOUSE command. If you want action to end the moment they enter a "forbidden zone" (or zones) then END is the choice. You may not need to know how the \MOUSE command was exited, but that can be discerned by examining the appropriate variables. Variable "F" will contain the input device button value that was pressed if that is how the routine was exited, or it will have zero and variable "B" will have the last key pressed. If variable "F" is zero and variable "B" is unchanged from a non-valid key value that you had previously set it to, AND variable "C" indicates that ROUNDS= had not completed, then the end MUST have been due to the mouse entering an "END" window. In any case "D" and "E" will have the mouse X- and Y- axis positions. INITIALIZE INITIALIZE can only be used if no editing changes exist to any files in RAM, or the mouse has previously been initialized. However, since the program initializes the mouse immediately after loading, this problem should never occur. The reason the program will not let you initialize the mouse if changes exist is that if mouse software is not installed you may have to "reboot" if you try to initialize the mouse! This in not very likely, perhaps not even possible, but there is no way for the program to be absolutely sure. The program checks for a valid (non-zero) address where the mouse software address should be. If it's non-zero, the program "dips it's toe in the water" and sends a request to the mouse. See Appendix "K" and Appendix "N" for more information. ? ? (Question mark) will put the current status of the mouse in variable "A". The meanings are as follows: 0 - mouse software definitely not installed yet, can't initialize. 1 - can initialize, but are not connected yet. 2 - mouse is already initialized. NOTE: ? sends a reset message to initialize the MOUSE. IF THAT SOFTWARE IS NOT INSTALLED, THE PROBLEMS MENTIONED EARLIER MAY OCCUR. OFF Will turn the mouse off if it is on. The other options can be entered in any order. For any that are not included the previous settings are maintained. AND=YES or NO AND will place the image on the screen with AND. It will leave a trail. \CLEAR MOUSE sets AND to NO (off). ACCURACY=#,# Sets the X and Y accuracy in dots. Useful when block-highlighting text. To do this, set the mouse WINDOW= parameter width to 1 dot and the height to a multiple of the text font height. Set ACCURACY= to the text font height. Make a frame the inverse color of the text you will use, the size of the text box to be highlighted and use it as a cursor. Use the XOR=AUTOMATIC option. You could make a grid of text boxes this way too. \CLEAR MOUSE sets ACCURACY to 1,1. The ACCURACY= calculations are done as if the starting location was 0,0 then the X and Y offsets are added to get the "actual" current cursor location. COLOR=# Allows you to set the color of the cursor crosshairs. Valid colors in CGA mode are 1, 2 or 3 (not 0). In MCGA mode the highest color values are not available (above 247). In all modes, color cannot be 0. END=#,#,#,# This defines a window that will end the mouse routine if the mouse ever enters it. You may have up to 10 active END windows. \CLEAR MOUSE sets this to 0 (no end-windows). Order is X-low, Y-low, X-high, Y-high. These parameters are not checked against each other for equivalency, so don't code the same one 11 times--you'll get a CAN'T PROCEED error the 11th time. To avoid this, issue \CLEAR MOUSE prior to setting up the END parameters. FRAME=#,# The first value sets the size of the cursor crosshairs and the second value sets a frame to use as a cursor. If both are zero the cursor will be a single dot, but if the frame # is not zero and the crosshair value is zero, then there will be no crosshair. \CLEAR MOUSE sets this to 4,0. KEEP=Y or anything else Only useful if XOR=AUTO. Leaves the last frame (and/or crosshair) on the screen when \MOUSE is exited (regardless of what causes the exit). LOCATION=#,# This option sets the starting location for the mouse. If not included, the position is decided by the current mouse location if the mouse is active or by the location set by \DOT or several other commands. OR=YES or NO OR will place the image on the screen with OR. It will leave a trail. \CLEAR MOUSE sets OR to NO (off). RESOLUTION=#,# Is the maximum variation from the current position that can occur per cycle. First value is the minimum change and the second value is the maximum change. \CLEAR MOUSE sets RESOLUTION to 1,-1. ROUNDS=# Sets an upper limit for how long the mouse will be active. The number of rounds executed will be in variable "C" at the end. A round is defined as a new location or one cycle, initially about 1/20th of a second. If you set this value to -1 the mouse will run forever unless one of the other exit methods occurs. \CLEAR MOUSE sets this to -1. If you set it to 0 the mouse cursor will not be displayed or used at all. SPEED=# Sets the timing for each ROUND. Initially it is set to 29, which is about 20 cycles per second. At that rate the number of ROUNDS divided by 20 is approximately equal to the number of seconds that the mouse will be active. Zero (0) here means "as fast as possible". Program updates the mouse location once per cycle. \CLEAR MOUSE resets this to 29. This is the speed of the screen image update. WINDOW=#,#,#,# This sets maximum and minimum values for the cursor in the form X-low, Y-low, X-high, Y-high. The cursor will appear whole even if parts of it are outside of this window but the cursor location will stay within these values (inclusive). By using narrow values for one of the axis you can make the cursor move only up and down or back and forth, useful for choosing menu options. \CLEAR MOUSE sets this to the full screen. XOR=YES, NO, or AUTOMATIC The frame used as a cursor can be permanently placed at every point it touches if so desired (NO) or it can be automatically XOR'ed onto the screen and XOR'ed off again when moved (AUTO). It can also be set to be XORed onto the screen but not XORed off (YES). The crosshair is not affected by this option--it is always removed. Set to auto-xor by \CLEAR MOUSE. EXAMPLES: \MOUSE INIT \MOUSE R=4444 W=33,44,104,199 L=12,13 \MOUSE ROUNDS=44 WINDOW=0,22,319,23 \MOUSE R=-1 A=10,1 W=33,10,33,190 (The last example would run forever until one of the exit methods discussed above is taken). **** MOVE **** FORMAT: \MOVE #{[#,#]} TO # The first # can be a literal in single or double quotes. The # after TO can be a variable or an auxbox. Of course if it's a variable the first # has to be numeric data. This command creates the auxbox if it has not been created yet and changes it to numeric or alphanumeric as needed. The destination auxbox will always become the same type as the source. You can move variables to auxboxes and you can move auxboxes to variables if the auxbox is numeric. You can move a portion of an alphanumeric auxbox by immediately following the auxbox name or number with brackets and two values separated by commas. The values are the starting position within the source auxbox and the length in characters to move. If the starting string is shorter than the "destination" as defined by your offset and length values, it will pad with spaces. When moving a literal (in single or double quote marks) to an auxbox the maximum length of the literal itself is 254 characters. EXAMPLES: \MOVE 343 TO W \MOVE TIME&DATE[1,8] TO #32 \MOVE "Hi! " TO #1 **** MULTIPLY **** FORMAT: \MULTIPLY # BY # Both values must be numeric. The second number can be an expression that evaluates to a value and the result goes in the first value, which must be a variable or auxbox. EXAMPLES: MULTIPLY G BY 23 MULTIPLY W BY (#33 * 22)-44+(X*Y*Z) **** NAME **** FORMAT: \NAME # = NNNNNNNN Defines a symbolic name which can then be used to refer to an auxbox, instead of using its number. NNNNNNNN is a name that starts with three (3) capital letters and is at least three (3) characters long. It ends with a capital letter and is a maximum of 30 characters. It cannot contain any spaces. The only other legal characters are the numbers 0 through 9, the ampersand (&) and the underline (_). Each auxbox can have no name or one symbolic name, and a name can refer to only one auxbox. \NAME does NOT establish the existence of an auxbox, only its name. Use \MOVE to create the auxbox. The name TIME&DATE is already assigned to auxbox #32767. All other names can be cleared with \CLEAR NAMES. EXAMPLE: \NAME #2346=SAVE_THE_PLANET \MOVE "YES" TO SAVE_THE_PLANET **** ON ERROR **** FORMAT: \ON ERROR [JUMP or CALL or CALLM] NNNNN FORMAT 2: \ON ERROR This will do a jump or call to the paragraph specified as NNNNNN if any error occurs other than those listed as SEVERE errors (see below.) The line number where the error occurred will be in variable "A". To get the actual error code that occurred (or the last one if multiple errors occurred on the line) use \ERROR. If nothing is specified after \ON ERROR then error trapping is turned off (format 2). Error trapping is a one-shot: once used, it is set off until another \ON ERROR jump or call is issued. Therefore if an error occurs, you must issue another \ON ERROR command to inhibit any errors again. You may want to do this in the error trap routine itself. IMPORTANT NOTE: Some errors, documented elsewhere in this manual, indicate that a reboot may be necessary after they occur. Although these errors SHOULD be impossible to get, it is noted here for completeness that the controlled recovery capabilities of this command may not work in these cases. All efforts have been made to make the program "bulletproof", that is, it should not be possible to crash your computer while using this program. However despite all the effort this may not be the case! The active screen will be the real screen (screen 0) after ANY error, even if it was trapped. The real purpose of this command is not so that you can always restart but rather it is to provide a mechanism to handle things like file-not-found, disk-full and so on. Errors in the runtime version that cannot be restarted (whose SEVERITY LEVEL is too high) include: 3562 & 3563 (wrong screen mode errors.) 32767 & 32765 (load errors.) Both these errors can only occur during the initial program load, before any files have been read. Other errors that cannot be restarted involve attempting to change .i.screen modes; while picture files for other modes exist in RAM or EMM. The following additional errors are severe because they would result in overlaying edit changes. They can only occur in the editor version: 5, 7, 525, 2624, 4522 & 9218. And these errors are also severe, and indicate you wrote your program with syntax errors: 4 and 4004. (paragraph names not found.) **** ON KEY **** FORMAT 1: \ON KEY= {YES or NO} Sets the program to jump to the second command of a text file. Format is an equal sign (=) followed by YES or NO. FORMAT 2: \ON KEY F# {{JUMP or CALL or CALLM} NNNNNN} This format sets \ON KEY specifications for function key values. Code an F immediately followed by a number 1 thru 10 (NOT something that evaluates to a number, an actual number) with no space. Follow with CALL or JUMP and then a paragraph name (NNNNNN) to set \ON KEY processing. Use just the function number to shut off a previously set \ON KEY specification. FORMAT 3: \ON KEY # {{JUMP or CALL or CALLM} NNNNNN} \ON KEY # {JUMP, CALL or CALLM} NNNNNN where # is the decimal value of a key and NNNNNN is a paragraph name to jump to or call when that key is pressed. Leave the name blank after the key value to turn off the specification. Fifteen (15) individual key specifications can be active at one time, plus function key specifications. \ON KEY=YES Means any keypress (except ESCAPE) will cause a jump to the second command of the text file. It will NOT jump to the second line of the command file unless the first line has only one command. =NO turns off this function. You will find the key value in variable "B". ON KEYs are used to control branching within a text file based on user input. An ON KEY command remains in affect until it is set off (or a new text file is read in.) A maximum of 15 specific keys (format 3) plus 10 function keys (format 2) can be set at one time. An important fact to keep in mind when using \ON KEY is that all \CALL, \CALLM, and \IF nesting is lost with execution of an \ON KEY JUMP but NOT when an \ON KEY CALL occurs. An \ON KEY...JUMP works just like a \JUMP command but occurs when the user presses the appropriate key, while an \ON KEY...CALL behaves like a \CALL or \CALLM command. There are only two ways to get back to a text file after an \ON KEY jump into a macro file. You could have coded an \ON KEY in the text file that would still be active, or you could issue a \READ command to read a text file and processing will go to the start of the text file. Other than these two ways, you will be stuck in macros forever. It is possible to code values which do not represent any possible keypress. You can code a value which represents ESCAPE to the program (283) but if the user presses that key three times in a row an escape option WILL BE PROCESSED. You can use \PASSWORD to prevent unauthorized exiting. The global \ON KEY specification (format 1) is NOT ACTIVE during \QUESTION. All other \ON KEY's are checked with each key the user presses. If an \ON KEY jump occurs while the user is editing a line the line is accepted as is and then the \ON KEY process occurs. Global \ON KEYs are also not active during "single-step" (debugging) mode. If both global and specific \ON KEYs are active the specific \ON KEYs take precedence. ON KEY...CALL's exit the current command or text line and will not reenter \MARQUE, \SHOW, \MOUSE and \RUN. \RETURN will be to the command following the current command. If you changed fonts and locations and so on in the \ON KEY called routine these will remain as changed. Paragraphs that are called with \ON KEY...CALL should IMMEDIATELY turn off the \ON KEY condition that called them, on the same line as the paragraph name (or on a line connected with a \+ command). Otherwise if pressed again it will "re- call" the paragraph! Just before the \RETURN (on the same or a connected line) turn the \ON KEY condition on again. Since \ON KEY's are NOT checked after a \RETURN command this will mean that processing will have a chance to return to the original calling area before doing another \ON KEY...CALL. In general, \ON KEY...JUMP's are quite a bit simpler to use and are recommended whenever possible. Using \ON KEY # CALL NNNNN can result in a CAN'T PROCEED error code 3 (Too many calls), especially if taken via a mouse or other user input device button. This is because the program checks for the pressing of the button very rapidly; it can do it many times before the button is released. To avoid this, turn OFF the \ON KEY CALL (\ON KEY # will do it) as soon as you get to the called paragraph (on the same line as the paragraph name or connected to it with a \+ command.) Also be sure to connect the line that turns \ON KEY back on with the \RETURN that matches the call. Or, have the entire called paragraph be connected with \+ commands. ON KEY's are checked once between each command line in the text file. For text lines, once between each row or column placed on the screen. The actual number of checks that will occur per text line would depend on the height or width of the font. Checking will NOT occur between multiple commands on the same line, except prior to \" commands. You can temporarily "inhibit" \ON KEY checking by coding commands on the same line. This can be significant help in insuring that several processes all occur if the first one occurs. It also executes faster. You can inhibit \ON KEY checking between command lines if the last command on the previous line is \+. See that command for more information on it's use and restrictions. \ON KEY's are always checked after a \JUMP has occurred. EXAMPLES: \ON KEY=YES \ON KEY F8 ;Turns off a specification for F8. \ON KEY #3071 JUMP BEGIN \ON KEY 16424 CALL SPACE_BAR_PRESSED \ON KEY F3 JUMP SOME_PLACE_NICE \ON KEY 7181 ;Turns off \ON KEY for the RETURN key. \ON KEY 7181 JUMP UP_AND_DOWN **** OPEN **** FORMAT: \OPEN {NNNNNNNN.PIC} {NNNNNNNN.DAT} {NNNNNNNN.PRN {ADD}} {LPT1:} {LPT2:} {LPT3:} {LPT?:} {IGNORE} Use NNNNNNNN.PIC to open disk-based animation files. These are animation sequences for use by the \SHOW command. It is a way to animate sequences of frames that are larger (perhaps much larger!) than available RAM or EMM. File should be closed after use. Use NNNNNNNN.DAT to open text-style data files for use with the \DATA command. File should be closed after use. For print files (output ASCII files), \OPEN can specify either a disk file (extension PRN), or the system printer; LPT1, LPT2, or LPT3, or any printer, LPT?. Either LPT#, or a print file MUST be opened before any \PRINT statements attempt to write to them. You can use the option IGNORE after the LPT#: to ignore the return code--the printer will be considered opened regardless of what the status value is. We recommend you DO NOT use this option without advising the user explicitly that the system could hang if the program tries to access a printer that is not available. You can only have one print file open at a time. Use the \CLOSE statement to close them. A disk file may be reopened after being closed, for additional \PRINT statements to use, by using the ADD option of \OPEN. The "file pointer" will be at the end of the file, of course. Any CAN'T PROCEED errors in processing will cause print, data, and disk-based animation files and/or LPT1, LPT2, or LPT3 to be closed. Opening a print file will destroy an old one on the disk with the same name unless you use the ADD option, so only do this with files you want this to happen to! When you open LPT1, LPT2, LPT3, or LPT? a reset code is sent through the BIOS to the printer and the printer's return status code is placed in variable "A". The meaning of this code is documented in BIOS technical references. The program will wait up to about 12 seconds for the printer to return a valid (not busy) code. Picture files shown with \OPEN can use significantly less RAM since they use only the decompress area and take no additional RAM or EMM of their own. Note: Any \ON KEY jumps leave the opened file open, so have the jumps go to places that close the opened files or don't use \ON KEY jumps with \OPEN, or set it up so it expects files to be opened, or store the status of the file and behave accordingly. Or something... **** OUT **** FORMAT: \OUT #,# {BYTE or WORD} The first value is the port, usually 0 to 255, and the second value is the amount to be \OUTed. The second value can be \OUTed at the address given in the first value as a byte or word, depending or which parameter you use. As a byte it must be between 0 and 255 and as a word, -32K to +32K. To use this command, you MUST know what you are doing! This can directly affect the hardware of your system and even cause damage to your system or that of your users! You could actually harm a monitor, disk drive, or other device with this command! Of course, you are much more likely to just need to reboot if you use it without understanding it, but... DON'T USE \OUT UNLESS YOU UNDERSTAND WHAT IT DOES. Therefore, you must use \AUTHORITY HIGH to enable this command. Do not, REPEAT DO NOT use this command unless you are absolutely sure that you understand the purpose of ports, hardware devices, the ASSEMBLER LANGUAGE OUT command (which this executes), and anything else that might be important, depending on which port you plan to OUT data to! And don't come crying to us if you disobey these cautions and ruin your system! THIS COMMAND IS DANGEROUS DON'T USE IT WITHOUT UNDERSTANDING IT FIRST. **** OVERLAY **** FORMAT: \OVERLAY #{,X or O or A} Sets the text display mode to OVERLAY (as opposed to SCROLL or CRAWL). The number is the speed at which to overlay text. If a question mark (?) is used, text mode is changed to overlay and the current speed is placed in variable "A". IF ,X is included the text is XORed onto the screen, if ,A ANDed, if ,O ORed. AND, OR, and XOR are most useful for fonts designed with just black (background) and the highest numeric color available for the screen mode. In bitplane modes you can AND, OR, and XOR with color 1 only. Use TEXT PLANE= to get similar effects to what this would have given with XOR, AND, and OR in bitmapped modes. **** PAINT **** FORMAT: \PAINT #,{UDLRVHBA} The # specifies the border color to paint up to. The program will paint in the current color (perhaps set with \DOT until it reaches the border. The UDLRVHBA indicates in which direction to paint (up, down, left, right, vertical, horizontal, both (vertical and horizontal) and all). Painting occurs from the current position. When called from \DRAW just the P should be used (not the AINT). The option Small Square, available in the picture editor, is not available as a command. Painting will take place in the current color set with \LINE, \DOT, \DRAW, etc.. Except for option "A" \PAINT will remain active until turned off. Only one direction can be used at a time. \PAINT without any parameters turns OFF paint mode. For the "A" option, the next dot drawn acts as the "seed" and painting occurs within an area bounded by the border color specified or the paint color. This option shuts off after one use. This option uses the same storage area that "tilt" (in the editor's draw mode) uses, so if you want to use a tilt line repeatedly, do NOT paint in between uses. (See tilt.) The paint "all" option utilizes a temporary storage area in RAM to accomplish it's task. It is possible to use up this area in a very "complex" paint job. If this happens, some areas will not get filled completely. The position of the original "seed" can have some effect on the result in this case. If this is a problem, try to divide the area to be painted into two or more individual sections to paint. **** PASSWORD **** FORMAT: \PASSWORD EXIT=# {or "NNNN" or 'NNNN'} TIME=# This allows you to control runtime user's ability to return to DOS from within an application. The maximum password length in single or double quotes is 10 characters. It may be an alphanumeric auxbox or literal in quotes but NOT a variable or numeric auxbox. A password of a space or spaces clears the option. Password checking occurs when ESCAPE (or a key assigned to ESCAPE) is pressed. The full length is taken even if a wrong key is pressed. Passwords are only used in the runtime version. The editor version will parse the command but will not actually set up a password protection scheme. Time is specified in 584ths (approx.) of a second units. The minimum value of 118 is equivalent to about 1/5th second. Time is per character. Return must be pressed after the password is entered. **** PEN **** FORMAT: \PEN {AIRBRUSH={NO or #{,#,#...}}} {COLOR=#} {WIDTH=#} {XOR={YES, NO, ON, OFF}} {CYCLE={NO or #{,#,#...}}} Sets pen options for \DOT, \DRAW, \LINE and \CIRCLE. AIRBRUSH=NO or #{,#,#...} Turns airbrush mode on or off for subsequent \DOT, \DRAW, \LINE and \CIRCLE commands. Strength of the spray is set with the WIDTH option. You can specify up to ten different colors and these override the COLOR option (see below). Use NO to turn off the airbrush. COLOR=# Sets pen color for subsequent \DOT, \DRAW, \LINE and \CIRCLE commands. Valid options are 0 through the maximum color for the screen mode (3 in CGA mode). Use any negative number for clear. No value will also evaluate to clear, but only if this is the last option in the command. (Otherwise the keyword for the next option will be evaluated as the number!) CYCLE=NO or #{,#,#...} Turns color cycle mode on or off for subsequent \DOT, \DRAW, \LINE and \CIRCLE commands. You can specify up to ten different colors. Use NO to turn off the color cycle option. Since C= would set a color, you must type at least the CY= portion of this parameter. WIDTH=# Sets pen size for subsequent \DOT, \DRAW, \LINE and \CIRCLE commands. Valid options are 1 through 5. XOR=YES or NO, ON or OFF, AND, OR, XOR Sets XOR, AND, or OR on or off for subsequent \DRAW, \LINE and \CIRCLE commands. \DOT is not affected by this command's XOR setting. Through the current release 7.24, XOR is not compatible with wide pen lines. Only a one-dot wide line will be drawn properly in XOR mode. YES/ON and NO/OFF are exactly equivalent. **** PRINT **** FORMAT: \PRINT #{,#,#,#...} Writes to a print file or LPT#:. You must first \OPEN the file or use \OPEN to initialize the system printer. The format of \PRINT's parameters work just like \DISPLAY, except you may specify numeric values to print with brackets ([#]). If you have a trailing comma the program will NOT add a carriage-return/line-feed after whatever you print, but if the comma is not there, then it WILL add the CR and LF characters (13,10). Numeric values except those in brackets ([ ]) are converted to a string of ASCII characters and then the string is printed Those inside of brackets are sent as 1-byte unsigned numbers and cannot be less than zero or greater than 255. If you have not opened LPT#: \PRINT writes to a disk file previously \OPENed and does not write to the printer. It will actually write the record to disk whenever 512 bytes have been printed. When the file is closed the rest, if any, is written. One way to print this file later might be to issue a command to do so from DOS with \EXECUTE. You must close the disk file before you do this. EXAMPLES: \PRINT [27],' Prints the escape character, which has a decimal value of 27, and then prints this message followed by a cr/lf.' \PRINT #232,TIME&DATE," HAVE A NICE DAY", The second example would print whatever is in auxbox #232 immediately followed by the TIME&DATE auxbox, followed by the phrase HAVE A NICE DAY which starts with a space. No cr/lf is added since the command ends with a comma. **** QUESTION **** FORMAT: \QUESTION #,#{,#{,LOWER}} Gets keyboard input from the user and places their response in a variable or auxbox. If the value of the second number is 0, this asks for a number from the user and puts it's value in the location mentioned in the first number, which must be an auxbox or variable. Otherwise it gets an ASCII string of the length specified by the second number (1 thru 80) and puts it in the auxbox specified by the first number. If the auxbox already contains alphanumeric data its contents will appear in the user's edit window for them to make additional changes to. The user's edit window location is set with the \CURSOR command. \WAIT LIMIT sets how long, in seconds, this command will wait for user input. The user exits \QUESTION by pressing the RETURN key or any mouse button (unless the button has been reassigned to a different key.) \QUESTION uses the DOS standard font for user input, and the actual screen. It will not use the background screen. The third parameter is the cursor position when the routine begins. If not specified it will be on the first character in the line. After getting numerics the cursor will be advanced seven positions. If you specified a text window with \CURSOR #,#,#,# then the line will be kept inside that window with automatic scrolling if necessary. After getting alphanumerics the cursor position will be set to the beginning of the line. When entering alphanumerics users can only enter capitalized letters unless LOWER has been specified as the fourth parameter. The third parameter must be included to use this fourth parameter. Numeric data outside the valid range (-32768 to +32767) will be forced into the valid range. Numbers entered which are less than -32768 will be returned as -32768, and numbers greater than 32767 will become 32767.. In both instances, the speaker will beep if the sound is not toggled off. When getting numeric data, this will blank the six (6) characters forward from (to the left of) the current cursor position FIRST. **** READ **** FORMAT: \READ {drive:}{/path/}NNNNNNNN.EXT Reads a picture, font, text, macro, hue, or auxiliary file into RAM or EMM. The filename (NNNNNNNN) can be proceeded by a numeric literal, variable or auxbox and a colon (:). This will force a new default drive. You are probably used to referring to the drives as "A", "B", and "C". Within this program use numbers-- Drive "A" is 1, "B" is 2, etc. You may optionally include a path specification, this will change the default path. Since the program uses the backslash (\) for commands you cannot use that slash for pathnames in command lines! Use the forward slash (/) for pathnames instead. EXT determines most of what this command does: TXT will read in a new text file and start executing that file from the beginning. Your previous text file is overlaid. (You cannot overlay edit changes, of course.) Any \ON KEY specifications that were active for text will be eliminated when this command is executed, but NOT any macro \ON KEY specifications. FON will read a font file into the font area, overlaying any previous font. It will NOT move the font into the picture area. This can only be done manually. The font area is normally 20K bytes, but can be set before loading P11 to any value from 3K to 63K bytes with a parameter in the P11FLAGS= environment string (or on the command line). To do so, use: FONT:# (# is from 3 to 63) HUE will read a hue file into the hue table area, overlaying any hue information that was already there (you cannot overlay changes in the editor.) Each screen mode has it's own hue table where the hue data will go. You should only read a HUE file for the mode you are in. AUX will read an auxiliary file into the aux area overlaying any auxfile that was already there. PIC reads a picture file providing no changes were made to the current one. The picture will be read into RAM, or EMM if available. The number of frames read in will be in variable "A" after this option is executed. If the picture is in a different mode from the current one the screen mode will be changed to the new picture mode. EMM usage can be disabled or limited by setting the P11FLAGS= environment string or the command line parameter: EMM:# (0 to inhibit EMM, or any desired # of EMM pages.) MAC reads a macro file if the name is not one of the nine (maximum) stored names. Reading a macro does NOT clear \ON KEY specifications for other macros. \CLEAR MACROS will. All paragraph names in all macros in memory at any one time must be different or the program will only access the first one it encounters. This will not necessarily be the first one in the file. It may be the closest, the first, the next, etc. The easiest way to insure that the proper name is found is to give all the paragraph names in each macro a unique prefix. You may specify the drive as a variable, number, or numeric auxbox. You can specify the path and filename (with the extension) as auxboxes too. To do this, put the auxbox in parenthesis. The path must ALSO be within slashes (NOT backslashes). Within the auxboxes, put the period and the extension with the filename (example: HORSE.TXT). Within the pathname auxbox include slashes (forward- or back-slashes are okay within auxboxes). You may use a single auxbox which includes drive, path and filename. NOTE: These commands will only read the file off the disk if the file is not already in RAM. EXAMPLES: \READ #3:/(#4)/(#5) \READ 3:/FROG/(#6) \READ /FROG/PIG.PIC \READ (#7) In the first example all three elements--drive, path and filename with extension--are specified symbolically through the use of auxboxes. In the next example the path and drive are "hardcoded" and the filename.ext are in auxbox #6. In the third example the current drive is used and the path and filename are "hardcoded". In the last example auxbox #7 may contain the entire drive, path and filename, or the path and filename, or the drive and filename, or just the filename. Current values will be used for unspecified elements. **** RESTORE **** FORMAT: \RESTORE {SCREEN} The entire screen can be stored in a background area. This will get a screen previously saved with \SAVE SCREEN. The background area is the same area used by the raster frame mask option. You can also restore the screen from disk by setting B:0 in environment variable P11FLAGS= or on the command line. This will cause the entire screen to be read from a file called SCRNDUMP.SV# (#=1 or 2) in the directory \P11\TEMP. **** RETURN **** FORMAT: \RETURN Will cause processing to return to the command immediately after the last call. A call can be established with \CALL, \CALLM, \ON KEY...CALL or \ON ERROR...CALL. The place returned to could be in the midst of an \IF statement, but the \RETURN itself cannot be between an \IF statement and \ENDIF. No \ON KEY processing or input device checking occurs between a \RETURN command and the next command. **** ROTATE **** FORMAT: \ROTATE {ANGLE=# FRAME=# LOCATION=#,#} Lets you rotate a vector frame anywhere from 0 to 90 degrees. The parameters can appear in any order and should be separated by at least one space. Location refers to the center dot location about which the rotation should take place. The location must be between -2000 and +2000 inclusive on each axis. Angle is degrees of clockwise rotation. **** ROUNDS **** FORMAT: \ROUNDS # {SPEED # or [#{,REPEAT}] {FIXED} {REVERSIBLE} {WAVING}} {RANGE #,#} {RETRACE} Sets the number of cycles that \MARQUE, \SHOW or \RUN will execute. SPEED refers to the time for each cycle. Each unit represents a small fraction (about 1/584th) of a second. The larger the number the longer the pause. If a question mark appears in SPEED or RUN, the current value will be placed in variable "A". When the program starts ROUNDS is set to -1 (cycle forever), and SPEED is set to [0] (use frame speed controls). If the speed value is enclosed in brackets ([ ]) then the frame number specified will be used to control the speed. If non-0, frame must be in RAM or EMM: it cannot be part of a disk-based picture. This must be a vector frame. The Y-axis values will be the timing units for each frame. The first and last dots will not be used. If the frame number is followed by the word REPEAT then the cycle will be repeated. Otherwise the last value will be used repeatedly after cycling through the frame once. A value of 0 in brackets ([0]) will use the base timing values for each frame This is the default when the program starts. Base timing values of -1 will wait for a keypress or mouse press. The following additional words may be included after the SPEED parameter. They do not affect \MARQUE. FIXED (F) When specified the user CANNOT change the animation speed with the up and down arrow keys (or any other keys that might have been set with the \KEYs command.) The default is not FIXED. REVERSIBLE (R) Allows the user to reverse any animation that following \SHOW commands display (not used with \RUN). To do this they must press "-" (minus). "+" (plus) makes animation run forward again. These keys may be reassigned with \KEY. The default is not REVERSIBLE. WAVING (W) Used with \SHOW. Animation goes from the first frame to the last and then back down again a frame at a time. The default is NOT waving. RANGE (RA) The user can speed the animation up to as fast as the first number and as slow as the second number. The defaults are 0 (as fast as possible) and -1 (stopped). Whatever you set these to will remain in effect until the next \ROUNDS command, where it will be set to the defaults unless reset by you. Note that a "wrong" initial value for SPEED in terms of being OUTSIDE the max/min speeds in RANGE will NOT be checked - but the first time speed is CHANGED by the user - POOF! it must fit in the boundaries! RETRACE (RET) For \SHOW, this will start placing each frame on the screen at the START of the next vertical retrace period. This MIGHT make some bitplane animations smoother. The default is NOT paying any attention to retrace timing. **** RUN **** FORMAT: \RUN {FROM #} {TEXT} {MOUSE} {HUES} {NUMBERS or FACTS {#}} Runs animation sequences set up with \SPRITE and \SPRINT for \ROUNDS number of cycles unless an exit, such as an \ON KEY keypress, occurs. The user can adjust the speed if the FIXED option of \ROUNDS has not been issued. FROM # causes the \ROUNDS cycle counter to start at the value specified rather than at zero. No actions, such as string or position increments etc. prior to that cycle will take place. The cycle counter counts up until it reaches the number specified in \ROUNDS. With each cycle of \RUN animation, vector images with \SPRITE XOR=AUTO will XOR off the previous one before XORing on the new frame. With raster images it does these two operations concurrently. HUES will execute the previous HUES command once with each cycle. This is for use with CY=YES in the \HUES command. MOUSE will execute a previous \MOUSE command concurrent with the sprite activity. The ROUNDS= and SPEED= options of \MOUSE are ignored in this case. This lets a mouse cursor be moved around on the screen with the \RUN animation, but can leave unusual pieces of images on the screen in some cases. TEXT will cause lines of text to be displayed concurrently. The lines to be shown follow \RUN in the text file, and will be placed on the screen according to the current text display mode. If a command line is encountered the text display will stop and the \RUN command will finish it's cycles. If on the other hand the \RUN cycles finish first, the text line display will complete before going on to the next text line or command. The number of cycles completed will be in variable "C" when this command is exited regardless of how the exit occurred (finished, \ON KEY pressed, etc.) Through the current release, if more than 32767 rounds have passed negative numbers will be used, counting up from -32768. NUMBERS and FACTS are debugging aids available only in the editor version. If either is included with a FROM parameter, FROM must be coded first. NUMBERS will display five numbers on the bottom of the screen. The first is the \SPRINT number being shown. The second number is the frame number in the picture file. The next number is the current round, and the last two numbers are the current position of the sprite. FACTS displays the current values for sprite motion. It shows two number columns and one character column. The top line on the screen is the same as that displayed by the NUMBERS option at the bottom of the screen. See Appendix "A" for a complete listing of what each value refers to. Press Pg Dn to show more numbers for the same frame and HOME to go back to the first screen of information. Use the left and right arrow keys to see other sprite values without advancing to the next frame. Press any other key to advance to the next frame. \ON KEY jumps and calls are partially inhibited in this mode. You may have to press the key repeatedly or hold it down to get it to "take". FACTS and NUMBERS can be followed by at least one space and a number. If present then facts/numbers will not be displayed until after that round has occurred. If left in a RUNTIME version, these must be the last parameters on the line and will be ignored. It is better to remove them after use. EXAMPLES: \RUN FROM 23 NUMBERS 44 \RUN MOUSE FACTS \RUN \RUN TEXT MOUSE FROM 23 NUMBERS 30 **** SAVE **** FORMAT: \SAVE {SCREEN} The entire screen can be copied to its own storage area. The screen can then be restored with \RESTORE SCREEN. This uses the same area that is used for raster pictures with masks. You can also save the screen to disk by using the option B:0 in the environment variable P11FLAGS= or on the command line. This will cause the entire screen to be "dumped" to a file called SCRNDUMP.SV# (#=1 or 2) in the directory \P11\TEMP. This directory MUST exist to use this option! The disk name will end in either a 1 or a 2. \EXCHANGE SCREEN will toggle the name since it first writes out a new screen dump, then reads the old one. **** SCREEN **** FORMAT \SCREEN #,#{,#} or MODE=# or ? The first number is the background color, the second is the palette, and the third number, if present, is the screen mode. The default screen mode is 4, CGA. If the parameter form is used, only the mode number is changed. Since only CGA uses the background and palette values, MODE=# is sufficient for all other modes. Note: Do NOT use the MODE= option in the environmental variables or on the command line. It is not able to parse that option. Use the three #'s version instead. If a question mark (?) is used the current mode is placed in variable "A". This command can be entered from the P11FLAGS= environment string or from the command line, in brackets. If it is found there, the mode will be set before any files are read in. In the editor you can use this option to convert images from one screen mode to another. Enter the mode you want the picture to end up as in the environment string and then read the picture file into the editor. SCREEN:#,#,# In CGA there are two palettes, 0 and 1, and 16 background colors, 0 through 15. Background and palette values are passed to DOS, which changes the screen. If the screen mode is actually changed by this command, \CLEAR MOUSE and \CLEAR SHOW commands are executed automatically. It is a good idea to re- initialize the digitizer if it is being used, because the dimensions may not match the current screen mode. Valid modes are: Screen Dot Character Mode Dimensions Colors Dots/byte Dimensions Comments 4.......320 X 200.4..4.....40 X 24 CGA-the original P11 mode. 5.......320 X 200.4..4.....40 X 24 CGA, but a different palette. 6.......640 X 200.2..8.....80 X 24 CGA monochrome mode. 9.......320 X 200.16.2.....40 X 24 PCjr or TECMAR depending on hardware. 10.......640 X 200.4..4.....80 X 24 TECMAR 4-color mode. 13.......320 X 200.16.2.....40 X 24 EGA 16-color low-res mode. 14.......640 X 200.16.2.....80 X 24 TECMAR 16-color mode. 16.......640 X 350.16.8.....80 X 24 EGA 16-color high-res mode. 17.......640 X 480.2..8.....80 X 30 MCGA high- density monochrome mode. 18.......640 X 480.16.8.....80 X 24 VGA 16-color mode. 19.......320 X 200.2561.....40 X 24 MCGA rainbow mode. NOTE 1: With third party software, mode 4 can be run in monochrome on HERCULES hardware. NOTE 2: PCjr modes are also called extended CGA and available from many TANDY machines. **** SCROLL **** FORMAT: \SCROLL #{,{AOX},#} Similar to \OVERLAY and \CRAWL but sets the text display mode to scroll all text up the screen. The first parameter sets the speed of the scroll. The second parameter, if included, will cause text to be XOR'ed, AND'ed, or OR'ed with the color specified in the third parameter before it appears on the screen. Unlike \OVERLAY this will not XOR, AND, or OR with what is already on the screen--that gets scrolled up and lost. AND, OR, and XOR are most useful for fonts designed with just black (background) and the highest numeric color available for the screen mode. As with \CRAWL and \OVERLAY in bitplane modes, you can only XOR, AND, or OR text with color 1. Use TEXT PLANES= to get additional colors. **** SET **** FORMAT: \SET COLOR=# DOT={# or ?} FRAME=# LOCATION=#,# MODE={GET or SET} Lets you manipulate individual dots of a vector drawing from within a command file. COLOR is the dot's new color. DOT is the dot number. FRAME is the frame number the dot belongs in. LOCATION is the new X-axis and Y-axis values for the dot. MODE lets you choose to GET information about the current dot's location and color, or SET it. (SET is the default. If GET is used it must be specified for EACH \SET command.) IF the DOT=? option is used, then the MODE= option will be ignored, the current dot will be set to dot 1 (the first dot in the file) and the total number of dots in frame specified in the FRAME=# option will be placed in variable "A". The vector image will NOT be changed at all. If you use this command on a RASTER image it results in an error. This command does not create a frame or insert or delete dots. It only changes dots within an existing frame. Use \FRAME to create a vector frame. You cannot execute this command if changes exist to the picture file currently in memory. You can let values default. Any value not specified will default to the value in a previous \SET, except DOT will increment by 1 if not specified explicitly. **** SHOW **** FORMAT 1: \SHOW #,#,#,#{,A}{,O}{,X}{,S} FORMAT 2: \SHOW AND={YES or NO} FRAME=#,# LOCATE=#,# MOTION=#,# OR={YES or NO} PATH=#{,#} SAVE={YES or NO} WINDOW=#,#,#,# XOR={YES or NO} Does animation on the screen, saves a frame whose space has already been allocated, or AND's, OR's, or XOR's a frame onto the screen. For raster drawings accuracy is to the nearest byte boundary on the horizontal axis. In CGA mode it is every 4 dots, 8 dots in monochrome modes, etc. See \SCREEN for a table of dots per byte. For vector drawings the location specified is NOT offset by the first dot's value. If a disk-based animation file is open, \SHOW will use it, but any vector paths or timing frames must be in RAM or EMM. In format 1, the first two values set the location on the screen. The next values are the "from" and "to" frames, and the fifth value if present is A (and), O (or), X (xor) or S (save). These options are valid only when the "from" and "to" frames are the same. See the descriptions in format 2 to understand how each of these options function. If you just want to show one frame on the screen without AND, OR, or XOR you can just use three numbers (the X and Y locations and the frame number). In format 2, parameters are specified with keywords. Their meanings follow: AND={YES or NO} When placing only one frame on the screen (both FRAME= values are the same) you may use AND. This is a mathematical function which ANDs the picture into the screen. FRAME=#,# Indicates the "from" and "to" frames, respectively, to animate. If the second number is less than the first, the animation will run in reverse order unless the second number is -1, which means to animate all frames from the first number to the last frame in the file. LOCATE=#,# The upper left corner of the animation. For raster frames add the base offset to get the actual location, rounded to a byte boundary. (In CGA mode, every 4 dots.) MOTION=#,# Indicates X- and Y-axis increments to the beginning location. Incrementing occurs each cycle. OR={YES or NO} When placing only one frame on the screen (both FRAME= values are the same) you may use OR. This is a mathematical function which will OR the frame into the screen. PATH=#,# or PATH=NO Indicates a vector frame to use as a path. The second # indicates a dot to start at. Use NO to specify no path. This will repeat from the first active dot (the second dot of the frame) if it gets to the penultimate dot of the frame. SAVE={YES or NO} Saves rather than displays a frame. Only one frame can be saved at a time: FRAME=#,# must indicate only one frame--both numbers must be the same. If the frame dimensions and the location specified cause a portion to be outside the screen or the current window, only that portion visible would be saved. The frame must already exist in the file. This will overwrite it but will not be considered a change for editing purposes. It will not execute if changes exist. WINDOW=#,#,#,# Indicates a viewing window. Lower X-axis values are rounded to byte boundaries. XOR={YES or NO} When placing only one frame on the screen (both FRAME= values are the same) you may use XOR. This is a mathematical function which will XOR the frame with the screen. If you XOR the same image into the screen twice in the same place, the original screen image will be unchanged. Animation runs for \ROUNDS number of cycles unless the user exits by pressing an active \ON KEY or the \KEY NEXT= key. A parameter of \ROUNDS sets the speed. The user can change the speed if the FIXED option of \ROUNDS was not issued. When exited the number of cycles completed will be in variable "C". EXAMPLES: \SHOW 22,88,3,3,X \SHOW 37,45,4,8 Parameters 1 and 2 are screen position. Parameter 3 is the beginning frame. Parameter 4 is the ending frame. This should be the same as parameter 3 for the ,A ,O, ,X and ,S options. Parameter 5, if included, is either A for AND, O for OR, X for XOR or S for SAVE. \SHOW FRAME=7,-1 MOTION=4,0 This example uses the keyword format of \SHOW. It would animate from frame seven through the last frame in the file. These frames would move to the right four dots for each frame shown. **** SOUND **** FORMAT: \SOUND ON or OFF Toggles the sound capabilities on and off. It does not produce any noise but will inhibit \BEEP if \SOUND is set OFF. If you execute \SOUND OFF all beeps will be inhibited including any you issue with \BEEP and any the program would issue itself. **** SPRINT **** FORMAT \SPRINT #{,# TO #...} Indicates the frames to be used with current sprite motion parameters. First, set up the desired motion parameters with \SPRITE. Then indicate which frames should follow those parameters with \SPRINT. After you have set up all the images with their motion parameters, use \RUN to display the animation sequence. The word SPRINT was chosen because the command is similar to \PRINT in syntax, and because SPRITE characters can be made to SPRINT across the screen. To "sprint" animation you must list each frame to be sprinted or use " TO " to indicate a series of frames. EXAMPLES: \SPRITE TYPE=R ANIMATE=3 \SPRINT 1,2,3,4,5,6,7 \RUN \SPRITE T=R A=3\SPRINT 1 TO 7\RUN \SPRITE T=R A=3 \MOVE 1 TO G \X LOOP1 \SPRINT G \IF G<7 \ADD 1 TO G \JUMP LOOP1 \ENDIF \RUN (These three examples produce the exact same image.) **** SPRITE **** FORMAT: \SPRITE AND=YES or NO ANIMATE={# or NO} CONNECT={YES or NO} INCREMENT=#,# END=#,#,#,# FAST={Y or anything} MOTION=#,# OPEN=#,#,#,# TYPE={R or anything} PATH={#,# or NO} ROUNDS=#,# STRING=#,# WINDOW=#,#,#,# WPATH={#,# or NO} XOR={N, A or Y} ZING={#,#,# or NO} Sets up animation parameters for \SPRINT frames to use. The keywords are used to control a wide variety of animation activities. After using \SPRITE and \SPRINT commands to set up the action use \RUN to activate everything. Motion will continue for \ROUNDS number of cycles at a chosen SPEED. EXAMPLE: \SPRITE WINDOW=33,22,37,145 ROUNDS=33,76 Would set a display window that would apply to any frames that are set with subsequent \SPRINT commands. This would change if you issue another window value or a \CLEAR SPRITES command. It would also set the elements to become "active" (be displayed if in the window) at round 33 and become inactive after round 76. Following are the keywords (which can be entered as just the first letter or letters) and their meanings: AND=YES or NO The image can be ANDed, ORed, or XORed onto the screen. This will cause it to be ANDed. ANIMATE=# or NO The value is the number of cycles to hold each frame on the screen. Sometimes you do not want a particular group of animated frames to change as frequently as other action occurs within a cycle, in that case you would use a number greater than 1 here. NO sets this option off. Animation frames must follow one another with no intervening elements when created with \SPRINT. Other elements can appear but each animation sequence must run together and be separated from other animation by at least one non-animated \SPRINT frame. Only one of the frames in the sequence is shown per cycle. If the animation reaches a END= window or the end of a PATH, then if TYPE is not REPEAT but KEEP=YES, the animation will continue in place at the end location until the ROUNDS= ending cycle is reached. MOTION amounts are added only when an element of the animation sequence is displayed, NOT necessarily every round (it depends on the value ANIMATION is set to.) \CLEAR SPRITES sets animation to OFF (NO). CONNECT=YES or NO This turns on the connected dot mode for vector images. Line segments are drawn between each dot: the first dot is drawn and subsequent line segments are the color of their endpoint. Their startpoints (the previous line segment's endpoints) are not redrawn. The lines are clipped to the screen edge then the individual dots are drawn or not drawn depending on whether they are within an active window. END=#,#,#,# If the sprite reaches the window defined by these four values the sprite action ends. Values are X-low, Y-low, X-high, Y-high. (The actual value stored is offset by the values in the first dot of the frame (if vector) or 0,0 (if raster).) If TYPE=R the sprite repeats in place if it gets to the END window. The END= window is initialized to 5000, 5000, 4999, 4999 by \CLEAR SPRITES, which indicates NO end area. FAST=YES or NO This only affects raster drawings. When set to YES (or "Y") images are placed on the screen at byte boundaries for much faster operation. Auto-xor will be treated as XOR=YES if FAST=YES. FAST must be equal to YES to use a frame mask. The mask is automatically ANDed and the image ORed together with the background screen and the combined image displayed on the screen. Use this to move an object across a background image. INCREMENT=#,# When using the STRING= option for displaying vector frames these values will be added to the beginning and ending string values each round. They represent the number of bytes to add. Since each dot takes four bytes in memory a value of four (4) will increment by one dot each cycle. This allows an increment of less than one dot per cycle, for instance a value of 1 will increment by one dot every four cycles while a value of two will increment by one dot every other cycle. \CLEAR SPRITES sets this to 0,0. KEEP=Y or anything else When the sprite reaches an end of some sort (location, round, etc.) it will NOT be xor'ed off if this is set to Yes, even if Auto-xor is on. If the sprite is part of an animation sequence (ANIMATE=#) then the animation will continue to run at the stopped location until the ending round. If the end was achieved by reaching the end of a path or an END= window, animation at the ending location continues. (If TYPE=REPEAT then animation will continue at the starting location or at the first dot of a path.) If not animating, this option is only useful for auto-xor. LOCATION=#,# This sets the starting location. The first dot in the image (if vector) or 0,0 (if raster) is subtracted from this value and then all subsequent dots (if vector) are offset by the resultant amount. For raster images, add the base offset to get the actual location. Set to 0,0 by \CLEAR SPRITES. MOTION=#,# This sets up values to be added to the location X and Y values each round. (If animating, each cycle that an image is changed). With this option things can move in any direction including onto, off, and around the screen. \CLEAR SPRITES sets this to 0,0. OPEN=#,#,#,# This lets you adjust the corners of a viewing window; the four values are the X-low, Y-low, X-high and Y-high amounts to add to the base window values each time the frame is shown. You may want to use negative numbers for the X-low and Y-low increment amounts and positive numbers of the X-high and Y- high increment amounts. If any value becomes below 0 or greater than the screen size it will cease to change. If you use a window path (WPATH=) this option will not be utilized. \CLEAR SPRITES sets it to 0,0,0,0. OR=YES or NO The image can be ANDed, ORed, or XORed onto the screen. This will cause it to be ORed. PATH=#,# or NO This indicates a vector frame to use as a path (or "track"). If the frame is raster it will be caught as an error when you use \SPRINT. The first value is which frame to use as a path. The second value is which dot within that path to start on. If you choose the REPEAT option of TYPE=, repetition along the path will be from the beginning, NOT from the specified dot. Repeat begins when you reach the second-to-last dot in the path frame or an END= window. The second value is ONLY valid for the first time around the path. The starting location will be the sum of the values in the LOCATION= parameters, the current path dot chosen and additionally, if vector, the first dot (the one NOT shown) of the frame (NOT of the path). To start the path at the first active dot (the second dot) of a vector image code a one (1) in the second parameter of this option. To turn off this parameter code the word NO after the equal sign. \CLEAR SPRITES sets this option off. ROUNDS=#,# Sets the starting and ending cycles that a sprite is to be shown from and until, respectively. No string incrementing, motion, etc. will occur until the starting round and the image will not be shown. Once the starting round is passed values will be adjusted once each round based on the options that were set with other \SPRITE keywords. Each \SPRINT frame will be adjusted unless the frame becomes inactive. \CLEAR SPRITES sets ROUNDS to 0,-1. -1 will run forever. If the -1 round is reached it will be ignored and the sprite will continue to be active. STRING=#,# This is only useful for vector drawings. It is the dots (not including the first and last) that are actually to be shown on the screen. The first value is the first dot to show and the second is the number of dots to show. If these values are changed with INCREMENT= and reach the next-to-last dot the string that is shown will work it's way completely off the screen unless TYPE=REPEAT. In that case it will repeat from the first active dot in the image for a length specified, NOT from the initial starting dot. That dot is only effective for the first pass. The first active dot (the second actual dot) is number 1. \CLEAR SPRITES sets this to 0,16384. TYPE={R or anything else} Sets up repeat-sequences. Repeat resets to the beginning values and starts over if the sprinted frame gets to the position given in END=. If a PATH= or STRING= option gets to the last active dot it will reset to the first active dot. Repetition stops if the ending ROUNDS= value is reached. Any character except R sets this option off. WINDOW=#,#,#,# Sets a window smaller than full screen size. Images will scroll out of these windows as if they were scrolling off the screen. Window is reset to the full screen size with \CLEAR SPRITES. WPATH=#,# or NO Sets a path for a window to follow. If you use this option the WINDOW= values will be the base (initial) window location and it's size. You cannot use OPEN= with WPATH. \CLEAR SPRITES sets this to NO. XOR={A, N, X or Y} When set to "N" (NO), objects are simply put on the screen where you say to. If moving, they will leave a trail unless the edges are the same color as what they move across--experimentation will explain this better. When set to "A" (Automatic) the program will XOR off the last position as it is drawing the new position. This has the useful effect of leaving the background image unchanged. When set to "Y" (Yes) or "X" the drawing will be XOR'ed on, but if you want to remove it YOU must XOR the frame onto the screen a second time. XOR=NO is the fastest. \CLEAR SPRITES sets this to NO. You can't mix vector and raster XOR=A animation and get what you might expect. Animation in this mode can be very useful--images are removed as the new ones are put on. If you were to manually XOR frames on and off they will not be XORed concurrently. Auto-xor works fine for all-vector or all-raster groups, but if you mix types in an animation sequence it will XOR off one frame THEN XOR on the next in AUTO mode. ZING=#,#,# or ZING=NO The third value here sets a raster frame to the location specified by the first two values. The frame's base values are added to the X- and Y-axis values specified to determine the actual location of the upper left corner of the image. This does not by itself cause the frame to be displayed--yet. When a subsequent vector frame is passed over the raster frame, the raster frame is displayed rather than the vector dots. Works with XOR but not with AUTO-XOR. ZING works with the FAST option to display a byte at a time (four dots horizontally in CGA mode.) EXAMPLES: \READ GALLOP.PIC\ROUNDS 50 SPEED 33\CLEAR SPRITES \SPRITE M=0,4 F=Y A=1\SPRINT 1 TO 15\RUN This would make a horse gallop across the screen from left to right. **** SUBTRACT **** FORMAT: \SUBTRACT # FROM # The first value can be an expression that evaluates to a number. The answer will be placed in the second value. The first value can be a number, variable or auxbox but the second must be a variable or auxbox. Both values must be numeric. Remember that the maximum and minimum values of a number or 32767 and -32768 respectively, and that results of mathematical operations will "wrap around" in order to stay within this range. Internal calculations are double-word signed values, accurate to 31 bits. EXAMPLES: \SUBTRACT A FROM B \SUBTRACT 99 FROM #767 \SUBTRACT (W-55) FROM Q **** THEN **** FORMAT: \THEN Follows an \IF statement and begins the portion that will be executed when the condition in the \IF statement evaluates as true. The \ELSE statement, which can follow the \THEN clause, starts that portion that will be executed if the \IF statement proves false. Both the \THEN statement itself and/or any accompanying commands to execute, or text to display, are optional. In that case you would code the \ELSE portion directly following the \IF statement. The \THEN statement doesn't actually do anything and is totally ignored, even if it is out of position, but it can sometimes make your program a little easier to read. EXAMPLES: \IF APPLES=ORANGES \THEN \ MOVE "OH MY GOSH!!" TO #21 \ELSE \ IF PIGS_HAVE_WINGS = "TRUE" \ THEN \ MOVE "NO WAY!!" TO #21 \ ELSE \ MOVE "ALL IS WELL" TO #21 \ENDIF \DISPLAY #21 In this example APPLES, ORANGES, and PIGS_HAVE_WINGS are all named auxboxes. **** TEXT **** FORMAT: \TEXT {PLANES=1111} PLANES=is a binary number. It is only applicable to bitplane modes and should contain as many digits as bitplanes. By changing active bitplanes the color of the text will be changed. It is set to all one's (1111 for four plane mode) whenever the screen mode is changed. EXAMPLE: \TEXT PLANE=1011 ;This will set planes zero, two, and three active and plane one will be off. **** WAIT **** FORMAT: \WAIT LIMIT # or NOW # or RETURN # {"NNNNNN"} Sets how long the program will wait for the user to respond (LIMIT), how long to wait for a return key to be pressed (RETURN), or how long to just WAIT (NOW). The larger the number specified, the longer the wait. For LIMIT and RETURN, the time units are in seconds. For NOW, it is the same as for the SPEED option of \ROUNDS--about 1/584th of a second if you have not reset the clock speed with \CLOCK. A value of -1 will wait forever (until a keypress.) \WAIT LIMIT # is the amount of time in seconds to wait for the user to press the return key during user input with \QUESTION. Unless reassigned to a different key any mouse button is equivalent to the RETURN key. For the \WAIT RETURN # option the value (#) can be followed by a comma and an alphanumeric "literal" in single or double quote marks (both quote marks must be the same). This literal will replace the message normally displayed (maximum 78 characters). If two quote marks are coded next to each other, no message will appear (a cursor will still appear, however.) The location of the message cannot be changed (it starts at the left edge of the second line from the bottom.) If \WAIT RETURN exceeds the time specified, -1 will be placed in variable "B", otherwise 7181, the value of the return key, will be there. Pressing any mouse button will also end \WAIT RETURN and in that case variable "F" will hold the mouse button pressed. (Unless reassigned with \BUTTONS, mouse buttons are equivalent to the RETURN key.) WAIT NOW simply suspends all processing for the specified time or until a key is pressed. Use this option to give the user a fixed amount of time to read the screen. EXAMPLE: \WAIT RETURN 20 "SHOW BEGINS WHEN YOU PRESS RETURN" \WAIT NOW 584 ;waits about one second. **** WIDTH **** FORMAT: \WIDTH # {DOTS} {LEFT, RIGHT, BOTH, or CENTERED} {PROPORTIONAL} Sets the width in either characters or dots that will be displayed on the screen when text statements are encountered. Words are wrapped to the next line for \OVERLAY and \SCROLL. If specified in characters the actual width of the text as it appears on the screen will be the product of this value and the width of the current font. You can specify justification other than left justified (the default). When not specified, justification will be LEFT after this command. You can specify the width in dots rather than characters. Proportional font widths should always be specified this way. The number of dots is rounded down to a 2-byte (word) boundary (in CGA mode there are 8 dots per word.) You can use the proportional option even when using a non-proportional font. For example when using BOTH text justification you need to specify proportional so that it will adjust the spacing between words correctly. (BOTH option is not available for non-proportional fonts.) Proportional text processing can be significantly slower than non-proportional, but usually looks a lot better. As of version 7, justified BOTH will justify LEFT if it is the last line (or only line.) Thus, just BOTH only works for lines >1 line. **** WRITE **** FORMAT: \WRITE {drive:}{/path/}NNNNNNNN.EXT The only valid file that can be written with this command is an auxiliary file so the EXT must always be AUX. All other files will be ignored. (Print files are automatically written out 512 bytes at a time with \PRINT.) Text, hue, picture and font files that you create cannot be written to disk this way. They must be written out manually with function key 6. As with \READ, \OPEN and \CLOSE you may specify the filename, path, etc. symbolically. See \READ for examples and explanations. **** X **** FORMAT: \X NNNNNN NNNNNN is a one (1) to 30 byte name. This is a place that \CALL, \CALLM and \JUMP go to. The name must be exactly the same everywhere it is used. \ON KEY and \ON ERROR also jump or call these places. This command cannot appear in an \IF sequence (between the \IF and the \ENDIF). **** ZING **** FORMAT: \ZING AXIS={X,Y or B} CORNERS=#,#,#,# FRAME=# LOCATION=#,# MODE={B, F or X, A, O} Displays all or a portion of a raster frame to the active screen. ZING lets you display a single image with more features than \SHOW or \RUN, but is slower. AXIS={X,Y or B} The area to be shown can be flipped on either or both (B) axis. This can be combined with all other ZING options. CORNERS=#,#,#,# Specifies the upper left and lower right corners within the frame to be displayed. The values are the X-low, Y-low, X-high and Y-high dots. FRAME=# The frame to be \ZINGed onto the screen. Frame must be a raster image. (Before release 7 the parameter LOCATION was ignored if FRAME followed the LOCATION parameter.) LOCATION=#,# Location is the upper left corner of the screen to start placing the image. The base X- and Y- axis values for the frame are added to the location specified to determine the actual location. MODE={X,A, O, B or F} Mode puts this command in XOR mode (X), AND mode (A), OR mode (O), "background" mode (B), or "foreground" mode (F). The X, A, O, B, and F options are exclusive: you may only use one of them at a time (or none). Background means only the non-zero dots will be moved, and only to pixels which are 0 on the screen. Foreground means again only the non- zero dots will be moved, but they will be moved regardless of what is on the screen. In XOR mode the image to be placed on the screen is XOR'ed with whatever is currently on the screen. In both "foreground" and "background" modes only dots in the foreground colors (color numbers greater than color number 0) are transferred to the screen. In background mode these dots are only transferred if the current screen dot is the background color (0). This allows objects to be placed in the foreground or background of a current image. **** * (asterisk) **** FORMAT: \* Any command that starts with \* is a comment and does not affect processing. This command must be the last or only command on the line. Anything after it (until the CR/LF) will be ignored, even a \ (backslash). EXAMPLES: \* this paragraph shows horse gaits. \READ TROT.PIC \APPEND CANTER.PIC 1,9 \APPEND GALLOP.PIC 1,13 \APPEND PACE.PIC 1,12 \X NEXT_HORSE \LOCATE 20,20 \DISPLAY "WHAT GAIT DO YOU WANT TO SEE?" \CURSOR 10,5 \QUESTION #4,0 \IF #4 = 99 \END \ENDIF \IF #4 = 1 \* TROT \SHOW 80,80,1,12 \ELSE \IF #4 = 2 \* CANTER \SHOW 80,80,13,21 \ELSE \IF #4 = 3 \* GALLOP \SHOW 80,80,22,34 \ELSE \* PACE IF NOT 1-3 OR 99 \SHOW 80,80,35,46 \ENDIF \JUMP NEXT_HORSE **** " (double quote) **** FORMAT: \" The double quote mark allows you to display a blank line on the screen in \CRAWL, \OVERLAY or \SCROLL mode. It is preferable to creating a blank line in the text file, which cannot be done anyway using the built-in editor. The program will handle blank lines if it encounters them (presumably created with another text editor). Any text appearing after the quote (") WILL BE DISPLAYED. You can use this command to display any text with a backslash (\) in the first column. For this reason this command CANNOT have other commands following it on the same line. They would be treated as text. \ON KEY checking for this command is the same as for text lines. The number of \ON KEY checks that will occur during execution of this command will depend on the height in dots of the current font. Just blank lines (13, 10) can be used after text lines or after a \" command, but not after other command lines. Therefore, use this command. **** + ((plus sign) **** FORMAT: \+ Indicates that no keyboard check is to occur between command lines. This command is only valid as the last command on a multiple-command line. Therefore it is not compatible with \" and \* commands on the same line. This command causes multiple command lines to "behave" as though they were all on the same line. No \ON KEY jumps will occur between lines connected with \+ so you can guarantee that several processes (commands) will all occur if the first one occurs. If the line after the \+ command is a text line (or a \" command line) \ON KEY or keyboard checking will only be inhibited for the first row or column (one dot high or wide). This command is useful when setting up or turning off multiple \ON KEY specifications. Also it can be significantly faster, particularly if a mouse is active, since calls to the mouse manufacturer's software often take a noticeable amount of time. \RUN Information Displays This program can do very complex animation. You can use combinations of windows, paths, masks, controlled motion, xor and animation sequences to display raster or vector pictures, or strings within vector pictures. \SPRITE information remains set until either you restart your text file (in the editor, from line 1) or use \CLEAR SPRITES. For example if you enter a path for sprites to follow all \SPRINT commands that are executed will be assigned that path until you either reset to a new or no path or execute \CLEAR SPRITES, which sets PATH equal to NO (none). The program uses over 140 bytes of data for each \SPRINT'ed character. The program uses a "work area" to set up the data. This area, called the sprite table, can be viewed when running the editor when \RUN FACTS {#} is used. Some data changes with each cycle. Viewing the data can help you verify that what you want to occur in an animation sequence is actually occurring--at least mathematically. FACTS displays values including the current status of all the parameters you set with \SPRITE. Also, such information as the address of the sprite in RAM, the current location, etc.. Most sprite values, including current location, are "word" (2-byte) values. In the case of location this means that the "virtual" location can be any value from 0 to 32767 and additionally from -32768 to -1 on each axis. The screen only occupies a small portion of this range: for CGA 4-color mode, positive numbers 0-319 on the X-axis and 0-199 on the Y-axis with 0,0 being the upper left corner. If you scroll a sprite far enough off the screen in any direction it will reappear on the opposite edge. You can use the offscreen area to "store" sprites that are active but not located on the screen or to scroll sprites off the screen. If the WINDOW= parameter has been entered for a sprite then the "active" area is defined by the window rather than the screen dimensions. On the following pages is a listing of where the values for each sprite are kept in the data area. The data can be shown with the FACTS option of \RUN, when running the editor version. First the program displays the image (if it is supposed to) and then it displays the first screen of data, which may overlay the sprite. Press any key except the HOME key, the PG DN key, the arrow on the four (left arrow) and the arrow on the six (right arrow) to advance to the next sprite (NOT one cycle--unless you only have one sprite in your table). Information is displayed for each sprite whether "active" or not. Press Pg Dn (the three key on the numeric pad) to see beyond the first screen of data. Pressing it repeatedly will put you past the current frame and on to the next one, but it will NOT "wrap around" after the last sprite-it will just show unrelated areas of memory that follow the "sprite table". Byte values are displayed both numerically and as a character if possible. If an ASCII character cannot be displayed, a period (.) will appear in the third column. If a word value is at the location to be displayed only the first two columns are used. Press the HOME key (the seven key on the numeric pad) to return to the information at the beginning of the current sprite. Press the left and right arrow keys (on the four and the six) to see, respectively, the last and next sprite's information. Values at Sprite Table Addresses Offset Type Meaning 0 Word Offset from RAM base address for this frame. 2 Word X-location of first dot. 4 Word Y-location of first dot. 6 Word X-location of last dot. 8 Word Y-location of last dot. 10 Word X-starting location. 12 Word Y-starting location. 14 Word X-current location. 16 Word Y-current location. 18 Word X-increment amount. 20 Word Y-increment amount. 22 Word picture size. 24 Word X-low ending position (adjusted by first dot value). 26 Word Y-low ending position (adjusted by first dot value). 28 Word Starting cycle. 30 Byte Type. R or anything else. 31 Byte Frame type byte. 32 Word Animation cycles limit plus three (3). 34 Word Animation current cycle (>1 is currently active). 36 Word Scroll horizontal recycle amount. 38 Word Scroll vertical recycle amount. 40 Byte Was this frame onscreen last cycle (n, y)? 41 Byte Is this an animation frame (A or not A)? 42 Word Ending Cycle. 44 Byte Does this frame follow a path (P)? 45 Byte Xor? (not capitalized--is a, o, x, or R for AUTO REMOVE, or n or y). 46 Word Path offset of first dot. 48 Word Path offset of last dot. 50 Word Path offset of current dot. 52 Word Screen address of first byte for Auto-xor (X16). 54 Word Offset of first byte from 52 (Auto-xor). 56 Word RAM base address of frame (X16). 58 Word Frame number for this sprite. 60 Word Window lower-right X-value. 62 Word Window upper-left Y-value. 64 Word Window lower-right Y-value. 66 Word Starting vector string dot number position. 68 Word Ending vector string dot number position. 70 Word Address of path frame (X16). 72 Word Path frame number. 74 Word Window upper-left X-value. 76 Word Previous cycle X-location. 78 Word Previous cycle Y-location. 80 Word Add-amount for vector string starting dot. 82 Word Previous cycle starting position for string display. 84 Word Add-amount for vector string ending dot. 86 Word Previous cycle ending position for string display. 88 Word Height of image to be Auto-XOR'ed off. 90 Word If raster, Auto-XOR bytes to skip (not shown). If vector starting string dot address. 92 Word If raster, Auto-XOR source address of first byte. If vector, ending address for string repeat. 94 Byte Auto-XOR bit mask for the left edge. (Raster.) 95 Byte Auto-XOR bit mask for the right edge (Raster.) 96 Byte Auto-XOR number of bits to shift image.(Raster.) 97 Byte Unused. 98 Word Address of last "active" dot (next-to-last dot). 100 Word X-high end window value (adjusted if vector). 102 Word Y-high end window value (adjusted if vector). 104 Byte Keep? (Y). 105 Byte Connect line segments? (Y) (Vector). 106 Byte Fast display? (Y) (Raster). 107 Byte Zing? (Y). 108 Word Zing offset address. 110 Word Zing base address. 112 Word X-location for Zing. 114 Word Y-location for Zing. 116 Word X-low increment for OPEN or WPATH current dot address. 118 Word Y-low increment for OPEN or WPATH first dot address. 120 Word X-high increment for OPEN or WPATH last dot address. 122 Word Y-high increment for OPEN or WPATH base address. 124 Word WPATH path frame number. 126 Word WPATH X-width of window. 128 Word WPATH Y-width of window. 130 Word WPATH X base window location. 132 Word WPATH Y base window location. 134 Word ZING word width of image. 136 Word ZING dot width of image. 138 Word ZING dot height of image. 140 Word Auto-XOR bytes to show (raster). 142 Word Sprite ZING frame. 144 Byte Pattern-foreground mode (F) or not F. 145 Byte Not used. Reserved. 146 Word Sprite ZING bitplane size. 148 WORD Bitplane size. Picture and Font File Formats Picture and font files are designed with a "header record" of at least 26 bytes followed by the data for the frames themselves. Each picture frame has a sixteen-byte frame header. Proportional fonts have a ten-byte header. Standard fonts have no frame header at all. The font file header is 26 bytes. The picture file header is 26 bytes plus 2 bytes per frame. These additional bytes hold the size of each frame: \APPEND reads this and then calculates the locations in the file of the frames you ask for. If the file is compressed, whether font or picture format, the header will have an additional 2 bytes per frame containing the frame's compressed size. A value greater than or equal to the non-compressed size means the frame is not compressed. Vector frames are not compressed. The format of the 26-byte file header is as follows. Bytes not used are reserved for future use. Offset Type Meaning 0 Word Unsigned low-order word for the total size of this file. If non-proportional font this is the frame X width. 2 Word Unsigned high-order word for the total size of this file. Always zero prior to release 6.00. If non-proportional font this is the Y height. 4 Word Width in words of the last frame used. 6 Word Picture size of the last frame used. 8 Word Total frames in the file. 10 Byte Total number of "sectors" in the file. (This value is not used after release 3.46). 11 Word Size of this header record. 13 Word Size of each frame header record. 15 Byte Bytes per dot for vector frames. 16-19 Bytes Release number of program that wrote the file. 20 Byte Graphics mode the picture file is for. CGA is represented by a 4 and is the only valid mode before release 6.00. 21 Byte Compressed? ("h" before release 4.80, 0 (no) or 1 (yes) after.) 22 Byte Palette for this picture file. 23 Byte Background for this picture file. 24 Byte Dots per byte for raster images. 25 Byte Picture bitplanes. The format of the frame header is as follows: Offset Type Meaning 0 Word Width in dots (0=1 so one less than actual). 2 Word Height in dots (0=1 so one less than actual). 4 Word Width in words (dots per word depends on frame resolution). 6 Word Picture size in bytes (less than approximately 64016). 8 Byte This is a bit-mapped field. The lowest (0th or rightmost) bit is the image type, Vector (1) or Raster (0). The next bit to the left is the mask bit if raster. Next, a bit indicating whether the mask was manually edited. (1 if it was, 0 if it wasn't.) Next is a bit indicating whether the frame is an onion skin frame (1) or not (0). Then a bit which is currently unused but reserved--set to 0. Then, two bits which are also currently not used except by SCRNSAVE-- They indicate that the frame should be a continuation frame or a base frame. The low order bit is set to 1 if a base frame and the high order of these two is set to 0, then the continuation frames are both 1's, then the LAST continuation frame is a 1 in the high order and a 0 in the low order bit. Lastly is a bit used in RAM, indicating that the frame has been changed in the editor. Normally this bit is set to 0. 9 Byte Header size for the individual frames. (16 for pictures, 10 for proportional fonts.) 10 Word Base X-location coordinate. (If picture file.) 12 Word Base Y-location coordinate. (If picture file.) 14 Word Base timing value. (If picture file.) For a vector frame the total size is the number of dots times the bytes per dot, plus the header. For a raster frames with a mask the mask immediately follows the actual frame data. Thus the frame size is the header, plus the picture data size (calculated from the horizontal word value and the vertical height), plus the mask if a mask exists (same size as the picture data). Raster images are normally compressed when written to disk. The program calculates the bytes that can be saved (if any) and if the value is significant it recommends compression. You need not compress but the disk savings can be substantial. Decompression usually takes less time than reading the larger file so it is seldom desirable not to compress if the program recommends it. The compression format is a standard algorithm: If the top two bits (high-order or left-most) of the first byte are both ON (11xxxxxx) then the other six bits indicate the number of bytes that the next byte is repeated. In CGA mode each byte represents four dots. The six bits that indicate the number of times that the next byte is repeated is one less than the actual count. The binary value 11000000 would indicate one byte of data (use the following data byte one time) while 11000001 would indicate two bytes that are the same. If the top two bits are not both on then the byte is an actual data byte. In this case the following byte would then be checked to see if its top two bits are both on. The header portion of each frame and the header for the entire file are never compressed. Format for the Auxiliary File The auxiliary file has a 9 byte header and then the individual auxboxes. Each auxbox also has a header containing the number of the auxbox, it's type and length. The last auxbox is always #32767 and contains the time and date that the auxfile was written out to disk. This auxbox must be included in the auxfile. The format of the header record is as follows: Offset Type Meaning: 0 Word Size in bytes of the auxfile. 2 Word Size of this header record (always 9). 4 Byte Not used in release 6.00. Set to 0. 5 Byte Major release number of program that wrote file. 6 Byte A period (.). 7 Byte Tenth's digit of minor release number. 8 Byte Hundredth's digit of minor release number. The individual auxboxes are stored in the following format: Offset Type Meaning: 0 Word Number of this auxbox (auxboxes are always stored in numerical order). 2 Byte Type of this auxbox. Either # or L in release 6.00. 3 Byte Size of this auxbox. For numeric auxboxes (type #) this is always 2. For alphanumeric auxboxes, it is the length of the data within the auxbox. 4 .... The data follows the 4-byte header info for each auxbox. For numeric auxboxes (type #), this is a signed binary word value. For alphanumeric auxboxes it is the ASCII characters that are stored. Format for the Hue File The hue file (extension .HUE) contains a sequence of hue color definitions. It is specifically for a particular screen mode, and it's maximum size is dependent on the number of colors in that screen mode. The header contains the "from" and "to" colors that the hue file contains. The format of the header record is as follows: Offset Type Meaning: 0 Word Size in bytes of the hue file. 2 Word Size of this header record (always 16). 4 Byte Not used (reserved). Set to 0. 5 Byte Major release number of program that wrote file. 6 Byte A period (.). 7 Byte Tenth's digit of minor release number. 8 Byte Hundredth's digit of minor release number. 9 Byte Screen mode this hue file is for. 10 Byte Dot mask for above screen mode (maximum color number). 11 Byte Palette. 12 Byte Background color. 13 Byte Hue low-color. 14 Byte Hue high-color. 15 Byte Reserved. Set to 0. The individual hues are stored in the following format: Offset Type Meaning: 0 Byte Red component of color. 1 Byte Green component. 2 Byte Blue component. Each component should be between 0 and 63. If any value is greater than 63 that component value will be ignored. Space Considerations When using RAM for pictures, this program uses space for pictures "as needed." When a picture file is read all previously allocated RAM memory is returned to DOS. Whatever amount of memory is needed for the new file is then requested from DOS. Whenever space is requested DOS allocates an additional 16 bytes for it's own use. Also it rounds the request for space up to the nearest 16 byte boundary in RAM. The effect is simply that allocating memory for a lot of frames at once is more efficient than allocating one chunk at a time. When you \APPEND frames to a picture file the frames that are to be appended will be put in as few requests to DOS for space as possible, so you may save a few bytes by appending all the frames you will want at once. You also reduce disk access by not having to access the file as frequently. When creating/inserting/deleting frames in the picture editor the program will return memory to DOS if possible, but if the frame was part of a group of frames the memory will be "lost" until a new picture file is read in, or until all of the frames in that allocation block are deleted. Since the program can use as much memory as DOS can give it (up to 640K), it can take a long time to use up memory in a "loaded" machine. If you start running into errors whose explanation is that you have run out of memory, try writing out your picture file and reading it back in because any changes to the frame count may have wasted space. If EMM memory is available and it's use by the program has not been inhibited though the use of startup variables, the memory is always used in 16K (16384 byte) chunks called pages. Again it is worthwhile to read as many frames at a time as possible to conserve space. Disk-based animation uses two 64K-byte areas to read and decompress the frames. You can use the startup variables to set the maximum font size to the minimum,3K bytes, but then you may not be able to read larger fonts into RAM. (For many screen modes 3K is not enough to read even a very small font.) When the program initially loads the total amount of RAM available for pictures is in variable "A" (in K), and the amount of EMM (if any) is in variable "O" (in 16,384 byte "pages"). You can get some information about how much is still available at any time using \MEMORY. If you still can't get enough memory for the program to run properly, there are several third-party software packages such as QEMM from QUARTERDECK OFFICE SYSTEMS, Santa Monica, CA, which will maximize RAM usage. Tips On Making Your Program Faster Text file design can have a significant effect on how fast a program runs--or appears to run. There are many things to consider. In order to make the program run fast at the right times you might try reading disk files while the user is looking at text or non-moving images on the screen. If you set the text pause length to something other than zero that pause occurs between each line (one dot high) during display of text. \ON KEY commands store the actual address in the text or macro area that the keypress should bring you to and therefore execute very rapidly--except for the "human element" of course! Variables can be evaluated a little faster than auxboxes. Single-digit auxbox numbers (#1, #2, etc.) will evaluate faster than named or high-number auxboxes. Use \+ commands often. The keyboard and input device check can take a noticeable amount of time, especially if a mouse, joystick, or digitizer is active. Turning the input device off when not in use can speed you program significantly. Some mouse software (usually supplied with the mouse) is notoriously slow. \SHOW is generally faster than \RUN. If raster frame widths are evenly divisible into word boundaries they can be displayed especially fast. \SHOW automatically places such frames on the screen at maximum speed. Use \SPRITE FAST=YES to speed \RUN. Masked frames are substantially slower than non-masked images. The speed of animation is largely dependent on the size of the pictures being shown. To increase the speed be sure to use as small an image as possible for the portion being animated. For maximum speed set \CLOCK SPEED= to 1, which is about 18.2 times per second. This will give very coarse speed control but if that's okay, it will use less processor time for the asynchronous clock interrupts because they will occur less often than at the default (584 times per second) or some other speed. The minimum is 18.2. Uses of the "escape" key The escape key performs many related functions. When a text file is running in the editor version or at any time in the runtime version ESCAPE allows you to end the execution of the text file. In the runtime version this will return you to DOS. In the editor version you are given the option of single-stepping the file or you can return to the text editor. The messages displayed are non-destructive of the screen. If you choose to restart the program nothing is changed. Variable "B", which holds the last keystroke, will NOT be changed and no \ON KEY jumps or calls will have occurred. If you choose "single-step" in the editor the program will pause for input before each line is executed. Whatever key you press is treated as a regular keystroke. To stop "single-step" mode press ESCAPE and do not select single-step as the option. In the editor ESCAPE lets you get out of text lines unchanged or resets picture frames. Functions that require answering additional prompts let you use ESCAPE to leave the option unused. While transferring between text and draw mode ESCAPE substitutes the default answer (usually "Y"). In the editor version ESCAPE is for stopping, giving up, changing your mind, backing out, etc. F10-"Instant" commands & DOS functions In the editor version function key 10 gives you access to "instant" commands. Most commands such as \DRAW, \LINE and so on are allowed. Since only one command will be executed, commands that send you to different areas of the program are not valid (\CALL, \JUMP, etc.). Invalid commands will produce an error message. Certain "powerful" commands such as \DELETE are also inhibited. If you press F10 twice in a row you will get a choice of DOS options including Rename a file, Copy a file, change the current drive or path (P), Erase a file, check Space on disk drives, take a directory of a drive, or execute a second copy of COMMAND.COM. Copy, Directory, Erase and Rename can all be stopped before execution by pressing ESCAPE. Directory can also be stopped during execution with ESCAPE. When a directory is being displayed pressing any key will freeze the display. Pressing another key will continue. ? and * ("global" characters) are valid in file names here. When all entries for the current directory have been displayed the total number of files and the total bytes used by those files are displayed. The Copy function copies only one file at a time. The name must be completely specified without "global" characters (* and ?). (Asterisks (*) and question marks (?) may be used in the output file name.) Drive and path specifications may be included. You can change both the current path and drive with 'P'. For the COPY, DIRECTORY, and RENAME commands you can specify ,H (Hidden) ,R (Read Only) and ,S (System) options. This will set or search for these attributes. To include these options separate them from the filename by a comma with no intervening spaces. ,H ,R ,HRS and ,RH are all valid. For input files and directory searches the ,H option will allow the handling of "hidden" files, which normally are not displayable or copyable. If these attributes are not specified for output files they will not be applied regardless of the input file's attributes. Future Enhancements This product continues to evolve. Your suggestions are the most important input for future enhancements. Some expected, or possible, future enhancements include: Decimal numbers are certainly an important future enhancement. The variables and default types of numeric auxboxes will undoubtedly remain whole numbers between -32K and +32K to maintain speed of operation. Greater than 64K pictures. This is partially implemented in the SCRNSAVE utility but then not used in the main program in release 7. Three-dimensional vector images, and object-oriented images. Better mouse cursors. (Mask capabilities for cursor crosshairs.) What would YOU like to see in future versions of this program? Send a letter to the author! (S.A.S.E. preferred.) All requests will be considered plus you'll get on the company mailing list, useful for learning about additional products that may be of interest to our users. Of Mice and Joysticks and Digitizers This program will use any of these devices for input while drawing or for \MOUSE. Even if an input device is active the eight cursor direction keys around the 5 key on the numeric keypad can be used (on PC and XT type machines the 5 key can also be used.) The numeric keys above the QWERTY portion of the keyboard can also be used for faster travel around the screen. If you have installed the mouse software prior to loading this program it will utilize the mouse automatically. Only one input device can be "active" at a time, except that the MOUSE and JOYSTICK can both be used together, although this can require significant amounts of time (overhead.) The mouse uses Microsoft compatible software calls to accomplish it's job. This software should be loaded before loading this program. It can be loaded after processing starts with \EXECUTE but shouldn't be. See your mouse documentation for how to load your mouse "driver" software. In the editor, you cannot initialize the mouse for the first time if changes exist to any files in RAM. The following example would load the mouse software named mouse.com from drive "A": \EXECUTE >A:MOUSE.COM The entire name including the extension has to be specified. Again, mouse software should be loaded first! The reason it is not a good idea to load mouse software from within this program is because mouse software is usually "TSR" (Terminate, Stay Resident) software. Such software will (probably) load in the first available spot in memory and stay there. Thus it will probably divide your computer memory into two chunks if loaded from within this program (until you reboot). Timing Considerations This program utilizes the system clock at an enhanced rate for most timed activities. This way the timings you set will be approximately the same on any machine of any speed. Not all functions are timed. Timing values of 0 and -1 have special meaning. 0 (zero) means "as fast as possible" and will run at different speeds on machines with different speeds. -1 generally means "run forever" (or until ESCAPE or "any key" is pressed). The values you code for timing have different meanings for different commands. Specifically those that are in effect during user input are in seconds, and those that are for animation and other graphics are in small fractions of a second (approximately 584 "beats" per second). In the SPEED parameter of \ROUNDS, and in \OVERLAY, \SCROLL and \WAIT NOW a value of 584 would be about one second. For \WAIT RETURN # and \WAIT LIMIT # the value coded refers to seconds to wait. -1 is forever. Remember two things about creating animation for a wide range of machine speeds: First, when setting up artwork on a fast machine remember to consider how it will look on a slower machine. Second, if creating on a slow machine don't forget that some things will go TOO FAST on a fast machine unless you limit their speed with the various timing controls. For example if a \ROUNDS # SPEED 10 value looks good on a plain PC find out if \ROUNDS # SPEED 20 looks exactly the same. If it does then on a fast machine the action might be twice as fast! This is because you are displaying something that can't be done (on a slow machine) in less than 20 ticks of the timer (each tick is approximately 1/584th of a second.) The speed control values you choose should be the one's you actually want. 0, which is "as fast as possible" may look fine on a PC, but on an AT or 80386 type machine it may be too fast. Converting Images Between Screen Modes Conversion is done by reading a picture of one mode into the program while in another mode. You can specify the mode to become in the P11FLAGS= SCREEN:#,#,# environmental variable or on the command line as [SCREEN:#,#,#]. When moving "down" in number of colors, you can chose the "clipped" or "modulo" method. Clipped makes all colors higher than the maximum color equal to the maximum color, while modulo makes the highest+1=0, highest+2=1, and so on. When converting, the new picture will, as the old one was in it's screen mode, be on a byte boundary on the left edge. Therefore, when going to a higher X-axis resolution, some frames may not match up correctly with other frames and will need to be manually adjusted afterwards. Only frames up to screen size will be converted completely. Vector frames will not be converted, so colors may be unusual when moving "down" from more colors to less colors. Executing DOS from within the program This feature gives you a lot of power, but can cost you dearly if misused. It is best NEVER to use it when you have changes in RAM, especially with earlier (2.X) versions of DOS. You can do anything you have the memory (RAM) available for. You can run any program, execute any DOS command, format disks, etc. etc. etc.. There is NO limit-- you can even run a second copy of this program. (If it will fit.) From DOS, return to this program either by typing EXIT at the DOS prompt or by having that word in a "BATCH" file that DOS executes. You cannot execute a batch file without loading the command processor so you must use the DOS> option of \EXECUTE for batch files. You can also exit to a second copy of the command processor by typing F10 (function key 10) twice from the editor and then pressing "X" (EXIT). When processing returns to this program it will reset the screen mode if necessary. However if some other program changed the palette and/or background, or the hues, the program will not be aware of this change. If this command fails variable "A" will normally contain -1 and variable "C" may contain an error code. The clock, which is speeded up to about 584 ticks per second (or some other value you set with \CLOCK SPEED=), is temporarily reset to normal for \EXECUTE. Any program you run that destroys the current screen memory area would also have destroyed your screen. Therefore you may want to execute \CLEAR SCREEN immediately upon return in those instances. Although you can "theoretically" execute any program with this command you should avoid certain types of programs known as "TSR" (Terminate, Stay Resident) programs. When loaded these programs usually take the next available chunk of memory and remain there until you reboot. The result is that when you return to this program, and evermore until you reboot, you will have your memory divided into two pieces. Keyboard enhancement programs are generally TSR programs, as are most mouse utilities. They should be loaded BEFORE this program. The DOS command FORMAT may act much like a TSR program, dividing memory if executed. FORMAT should not be used from within this program unless you plan to reboot afterwards. Of course, if your only other choice is to loose valuable work, by all means format a disk, save your files, and reboot! About the Author Version 1.0 of Russell Hoffman was released in August of 1956. He has been involved with microcomputers since 1980. In 1984 he started writing P11 in response to a client request for an interactive tutorial about the human heart. Prior to starting P11 he designed randomized computer art programs that create two-dimensional artwork on digital plotters. Each drawing is different from every other. He claims they are examples of "imitation intelligence." By using random numbers to vary the sizes, colors, and other aspects of each drawing, an infinite artistic variation is possible. The software concept behind this art is applicable to engineering, physics, architecture, etc.. For example, row-style housing developments need not all be the same. Random variation-within-a-range can make it more likely that a purchaser will find the exact house they want. About 20,000 random art drawings have been created and given away at computer trade shows throughout the Northeast as of this writing. Completing this project required writing an interactive drawing program (thus it was the precursor to P11) for the NEC 8201-A (a lap-top computer similar to the TANDY 100) as well as many display routines for driving both the LCD display on the NEC and a PANASONIC VP-6801 P30 six-pen plotter. This led to other assignments creating artwork for various devices including monitors, printers, plotters, lasers, oscilloscopes, LED-matrix, etc. etc. In his spare time (something he had a lot more of before starting P11), Russell creates comedy radio routines, which have been played on the Dr. Demento Show and elsewhere (1979, 1986). He is an avid aviation buff and is learning to fly a Cessna 172 Skyhawk, having soloed in 1988. He likes ocean and lake swimming, reading, photography and loud music. Also quiet music, dancing and chocolate. He likes watching Jai Alai, listening to baseball, and playing softball. It goes without saying that he likes playing video games! Over 200 of his commentaries, humorous essays and letters have been published in and out (mostly out) of the computer field. He lectures to computer user groups, as many as 50 lectures/year. He has several listings in various biographical titles for his work, and is a member of the Boston Computer Society and the Connecticut Computer Society. He is also a member of the International Platform Association, WINGS fun club, Debbie Gibson fan club, and The Demento Society. Russ attended the Computer Processing Institute in Bridgeport, CT. in 1980, Connecticut School Of Broadcasting in Stratford, CT in 1979, County School of Tractor Trailer Driving in Bridgeport in 1978, and Penn State University, State College, PA in 1974. (P.S.U. was the only one he didn't graduate from.) He attended (and graduated from) Greens Farms Academy in Greens Farms, CT, where he first made contact with a computer via a Teletype machine. He has dabbled extensively in electronics but claims that everything he builds either smokes, or shocks him, or doesn't work.