Simtel MSDOS - Coast to Coast

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

/ Simtel MSDOS - Coast to Coast / simteldosarchivecoasttocoast2.iso / basic / tsrbas20.zip / TSRBASIC.DOC < prev next >

Wrap

Text File | 1991-04-03 | 76KB | 2,245 lines

TsrBasic, a Terminate and Stay Resident BASIC Interpreter Version 2.0, Copyright 1990-1991 Anthony F. Stuart 1. Introduction TsrBasic lets you write Terminate and Stay Resident (TSR) programs in BASIC. It supports: 1) Pop up applications that are recalled with a user defined hotkey sequence. 2) Background tasks that are recalled after a specified period of time has elapsed. 3) Screen savers that are recalled after a specified period of keyboard inactivity. The entire interpreter can be recalled as well, giving you a powerful programmable calculator at your fingertips. TsrBasic simplifies BASIC programming by relaxing data type checking restrictions. This means you do not have to use special suffixes like $ and # to specify the type of data a variable will hold. Any variable can hold any type of data, either textual or numeric. Conversions are performed when necessary. Structured programming is a snap with TsrBasic's IF/THEN/ELSE/ END IF statement, which supports multiline THEN and ELSE clauses and nested IF's. The conventional form of the IF/THEN/ELSE statement is supported as well. TsrBasic's powerful screen handling functions let you select video attributes, define text windows for input and output, and save and restore portions of the screen. TsrBasic supports direct video access for speed or ROM-BIOS/DOS mode for compatibility with nonstandard video adapters. TsrBasic lets you execute the contents of a character string so that you can evaluate arithmetic expressions on the fly. You can also use this feature to construct powerful user defined functions. TsrBasic compiles your program into intermediate code and interprets the intermediate code. This results in fast and efficient program execution. You can display the intermediate code if you wish. TsrBasic also lets you convert your BASIC program into an executable (.exe) file that can be invoked from DOS. Version 2.0 of TsrBasic features even better video support, including graphics, as well as many new and improved functions TsrBasic Reference Manual Page 1 and statements. If you are familiar with TsrBasic, version 1.0, see the file named changes.doc on the distribution disk for more information on the new features and bug fixes for version 2.0. 2. About this Document... The remainder of this document provides you with the information you need to know to take advantage of the special features of TsrBasic. It is intended for people who have some experience with the BASIC programming language. If you do not have any experience with BASIC, you may wish to consult a more detailed book on programming in BASIC before reading this document. 3. Variables and Arrays TsrBasic variables consist of a letter followed by zero or more letters, digits, underscores, periods, dollar signs, number signs, percent signs or exclamation marks. Variable names are case sensitive, e.g. LastName and lastname are two separate variables. Arrays must be declared using the DIM statement before they are referenced. Arrays may have an arbitrary number of dimensions. The extent of each dimension is from zero to the value(s) specified in the DIM statement. The TsrBasic SORT and SHIFT statements make working with arrays easier and more efficient. The SORT statement sorts a one dimensional array into ascending or descending order. The SHIFT statement shifts the elements of an array up or down one or more positions. Arrays and variables must be initialized before they are used, i.e. a value must be stored in the variable or array element before it is read. Failure to do so will generate an uninitialized variable error message. Note that PARSE, SCREENSAVE, SCREENRESTORE and SUSPEND do not support storing into an array. 4. Constants Numeric constants may be written using any of the following formats: Page 2 TsrBasic Reference Manual Format Example ------ ------- integer 42 decimal 3.14 exponential 314e-2 hexadecimal 0x1b octal 033 TsrBasic boolean logical operations use zero for false and nonzero (usually 1) for true. String constants are written as sequences of characters enclosed by double quotes. The closing double quote is required. A double quote may be included in a character string by concatenating the double quote character, chr(34), to it. 5. Operators TsrBasic supports the standard set of BASIC operators, plus some operators for doing bitwise operations on 16 bit quantities. The following list of operators is organized from lowest precedence to highest precedence. Operators of the same precedence are evaluated from left to right. Operator Precedence Description and 1 logical and or 1 logical or = 2 equal <> 2 not equal < 2 less than <= 2 less than or equal > 2 greater than >= 2 greater than or equal - 3 subtract + 3 add (or concatenate if strings) * 4 multiply / 4 divide mod 4 modulo \ 4 integer divide | 5 bitwise or (16 bits) & 5 bitwise and (16 bits) ` 5 bitwise xor (16 bits) TsrBasic Reference Manual Page 3 ~ 6 bitwise negate (16 bits) - 6 arithmetic negate not 6 logical negate ^ 7 power The plus operator (+) performs addition if both operands are numeric or concatenation if either operand is a string. This means that you cannot use the plus operator to concatenate two numbers. Use the CAT function for this purpose. 6. Editor and Environment TsrBasic provides a simple interactive command mode that allows you to enter and execute statements and commands. Program statements are entered with line numbers, which must be in the range 1-32767. Commands and immediate mode statements are entered without line numbers. The backspace key can be used to delete the last character entered. The escape key can be used to delete the entire line. Note: Type control-c to terminate a runaway TsrBasic program. For more complex editing needs, the TsrBasic EDIT command can be used to invoke an editor of your choice. The syntax of the EDIT command is as follows: edit [line-number-spec] The EDIT command lets you use your favorite DOS editor to edit the current program. Here's how it works: TsrBasic writes the current file, or the part specified by line-number-spec to a temporary file. It then invokes the editor specified by the EDITOR environment variable on the temporary file. After you exit the editor, TsrBasic loads (if no line-number-spec was used) or merges (if a line-number-spec was used) the temporary file. See your DOS reference manual for more information on environment variables. Because DOS is not reentrant, the EDIT command will not work when you have recalled a suspended TsrBasic from the DOS shell. In this case it will return a "DOS is busy" error. You can, however, use the EDIT command when you have recalled TsrBasic from most other applications, provided there is sufficient memory. Note that no default editor is supplied with TsrBasic. Page 4 TsrBasic Reference Manual 7. Suspend Statement The SUSPEND statement provides access to TsrBasic's terminate and stay resident capabilities. Executing the SUSPEND statement will cause TsrBasic to return to the environment from which it was invoked. TsrBasic can be recalled by hotkey sequence, timer expiration, or a period of keyboard inactivity, depending on parameters specified in the SUSPEND statement. After recall, TsrBasic executes the statement following the SUSPEND statement, if one exists, or returns to command level. The syntax for SUSPEND is: suspend screen, key-code, key-flags, interval, inactivity, status All parameters are optional. Parameters to the right of the one you wish to specify may be omitted. The parameters have the following functions and defaults: screen - boolean, if true (1) save the contents of the screen when the hotkey sequence is entered or the timer interval expires so that the screen may be restored by the next SUSPEND statement. The default is true. key-code - keyboard scan code that, when combined with the key-flags parameter, will recall the interpreter. This key-code should be selected from the list of keyboard scan codes in Appendix D. The default is 0x30 (the b key). key-flags - keyboard flags for control, shift and alt keys that, when combined with the key-code parameter, will recall the interpreter. Possible values for the keyboard flags are: 0x80 = insert on 0x40 = caps lock on 0x20 = num lock on 0x10 = scroll lock on 0x08 = alt key down 0x04 = control key down 0x02 = left shift down 0x01 = right shift down These flags may be OR'd together, i.e. 0x02 | 0x04 represents shift+control, so that shift and control and the key-code specified above must be held down simultaneously to recall the interpreter. The default is 0x06 (shift+control). interval - amount of time, in clock ticks, to wait before recalling the interpreter. This is used for TsrBasic Reference Manual Page 5 background tasks. Since there are approximately 18 clock ticks per second, multiply the number of seconds you want to wait by 18 to get the interval. A value of 0 disables the interval timer and the interpreter is recalled using the hotkey sequence (or keyboard timer, if specified). The default is zero (disabled). inactivity - amount of time, in clock ticks, to wait after last keystroke is entered before recalling the interpreter. This is used for screen savers. The default is zero (disabled). status - a variable which is used to hold an integer value returned by SUSPEND. This variable is set to 0 if the program was recalled by the hotkey sequence, 1 if recalled by the interval timer and 2 if recalled by the keyboard inactivity timer. Note: the combined defaults for SUSPEND are: suspend 1, 0x30, 0x06, 0, 0 So, if you enter SUSPEND without options, the interpreter will suspend and you can return to it by entering ctrl-shift-b. Here is a simple terminate and stay resident program that executes in the background to print the time in the upper right hand corner of the screen every second. Note how the status argument is used to distinguish between timer and hotkey events: 100 print "Press ctrl-shift-b to terminate clock." 110 suspend 0, 0x30, 0x06, 18, 0, timer 120 if not timer then cls : end 130 display 0, 72, time() 140 goto 110 8. Lookup Function Sometimes it is useful to be able to specify things like colors by meaningful names, and other times it is useful to be able to specify them by numbers. TsrBasic avoids this conflict by providing a LOOKUP function to convert meaningful names to numbers. The LOOKUP function can be used in instances where names are more appropriate, such as: 100 foreground lookup ("red") 110 background lookup ("black") 120 print "The time is "; time() Page 6 TsrBasic Reference Manual and numbers can be used when they are more appropriate: 100 for i = 1 to 15 110 foreground i 120 print "This is color "; i 130 next i The following table summarizes the names that LOOKUP can map to numbers. black 0 hres2 6 fill 3 blue 1 text 7 or 0 green 2 herc 8 and 1 cyan 3 mres16 13 reset 2 red 4 hres16 14 set 3 magenta 5 eres2 15 xor 4 yellow 6 eres16 16 mda 1 white 7 vres2 17 cga 2 low 0 vres16 18 ega 4 high 8 mres256 19 vga 8 bw40 0 default -1 mga 16 co40 1 direct 0 hgc 32 bw80 2 bios 1 co80 3 dos 2 mres4 4 graphics 3 mres0 5 outline 2 The LOOKUP function provides name to number mapping for the following statements: background config mode box foreground put circle get type color intensity See the detailed description of the statement for more information on the LOOKUP mappings that can be used. 9. Text Windows The following TsrBasic statements and functions provide support for TsrBasic text windows: background foreground savescreen blank getscreen scroll border init type column intensity winbottom csroff locate winleft csron page winright csrbottom refresh wintop csrtop restorescreen display row TsrBasic Reference Manual Page 7 TsrBasic text windows are created using the WINBOTTOM, WINLEFT, WINRIGHT and WINTOP statements to define the edges of the window. Subsequent text input/output using the INPUT and PRINT statements is directed to the window. The DISPLAY statement is used as an alternative to PRINT to display text anywhere on the screen. The LOCATE statement positions the cursor relative to the top left corner of the current window. Absolute cursor positioning is accomplished using the COLUMN and ROW statements. The BORDER statement draws a border around the window. The FOREGROUND and BACKGROUND statements set the foreground and background colors for text output. Colors are represented by numbers in the range 0 to 7. The LOOKUP function can be used to convert the following color names into color numbers: 0 - black 4 - red 1 - blue 5 - magenta 2 - green 6 - yellow 3 - cyan 7 - white Note that the range of colors that can be displayed depends on the video adapter in your PC. The INTENSITY statement selects the brightness of text characters. Intensity is specified as either 0 or 1. The LOOKUP function can be used to convert the following intensity names into intensity numbers: 0 - low 8 - high The contents of the current text window are saved into a TsrBasic variable using the SAVESCREEN statement and restored using the RESTORESCREEN statement. The CSRBOTTOM and CSRTOP statements set the size and shape of the cursor. Each character position on the screen is composed of a number of video scan lines. The number of scan lines depends on the video adapter. The scan lines are numbered top down and range from 0 to 6 for cga adapters and from 0 to 13 for other adapters. If CSRTOP is set to 0 and CSRBOTTOM is set to the last scan line in the cell (say 13 for an ega adapter) then the cursor will occupy the whole cell. The CSROFF and CSRON statements can be used to turn the cursor off (i.e. hide it) or back on. The TYPE statement selects the output mode for text. It is normally set to direct mode (0) for fast output. Other options are 1 for BIOS access, 2 for BIOS/DOS access, and 3 for text in graphics mode. The default is 0. Use 1 if you have any video Page 8 TsrBasic Reference Manual problems with 0, use 2 if you want to redirect output using DOS redirection capability. Use 3 for mixed text and graphics in graphics modes (see MODE). The LOOKUP function can be used to map the following type names to numbers: 0 - direct 1 - bios 2 - dos 3 - graphics 10. Graphics TsrBasic provides graphics support for CGA, EGA, VGA and Hercules compatible video adapters. The following statements and functions provide support for TsrBasic graphics: box fill mode circle get moveto clip lineto pixel color mapload put config mapsave The MODE statement selects a graphics mode. The set of graphics modes you may use is dependent on the type of video adapter that is installed in your PC. The graphics mode is specified as an integer number in the range -1 to 19. The LOOKUP function can be used to convert a mode name into a mode number. The following modes are supported: Name Number Res Type Colors Adapter bw40 0 40x25 text 16 gray cga,ega,vga co40 1 40x25 text 16/8 color cga,ega,vga bw80 2 80x25 text 16 gray cga,ega,vga co80 3 80x25 text 16/8 color cga,ega,vga mres4 4 320x200 graph 4 color cga,ega,vga mres0 5 320x200 graph 4 gray cga,ega,vga hres2 6 640x200 graph 2 bw cga,ega,vga text 7 80x25 text 2 bw mda,hgc hgc 8 720x348 graph 2 bw hgc mres16 13 320x200 graph 16 color ega,vga hres16 14 640x200 graph 16 color ega,vga eres2 15 640x350 graph 2 bw ega, vga eres16 16 640x350 graph 16 color ega, vga vres2 17 640x480 graph 2 bw vga vres16 18 640x480 graph 16 color vga mres256 19 320x200 graph 256 color vga In addition, the following mode is defined to let you exit graphics mode and return to the default mode: default -1 n/a n/a n/a n/a all TsrBasic Reference Manual Page 9 You can determine the type of video adapter that is installed in your PC, along with the x and y resolution, the number of colors, and the current mode by using the CONFIG statement. The syntax is: config xpix, ypix, colors, adapter, mode where xpix, ypix, colors, adapter and mode are variables. Xpix, ypix and colors are the number of x pixels, y pixels and colors, respectively, for the current mode. Adapter is the type of video adapter and is one of the following: 1 mda (monochrome display adapter) 2 cga (color graphics adapter) 4 ega (enhanced graphics adapter) 8 vga (video gate array) 16 mga (multicolor graphics array) 32 hgc (hercules graphics card) The graphics coordinate system is layed out like the text coordinate system with the origin (0,0) at the top left corner of the screen. The bottom right corner varies, depending on the graphics mode. In mode 14, for example, the bottom right corner is 639, 199. If you want to display text and graphics on the same screen you must use the TYPE statement to select the text in graphics mode (type 3). After you exit graphics mode set the text type back to 0 for improved performance. The foreground and background colors for TsrBasic graphics modes are specified using the COLOR statement. Graphics colors are independent of text colors. Colors are represented by numbers in the range 0 to 15. The LOOKUP function can be used to convert a color name into a color number as described in the section on text windows. The BOX and CIRCLE statements draw boxes and circles using a "bounding" rectangle which describes the top left and bottom right corners of the image. These statements also take an argument that controls whether the image is to be filled or not. The LOOKUP function can be used to map these control names to numbers. The following control names are supported by the lookup function: 2 - outline 3 - fill Graphics images can be transferred from the screen to memory using the GET statement and from memory to the screen using the PUT statement. They can also be transferred from memory to a file Page 10 TsrBasic Reference Manual in bitmap form using the MAPSAVE statement and transferred from a file to memory using the MAPLOAD statement. The PUT statement uses a control parameter to describe the method for adding the image to the screen. The lookup function can be used to map the following control names to numbers: name number effect or 0 superimpose image and 1 intersection of images reset 2 negative of image set 3 normal image xor 4 invert image The xor control value can be used twice in succession to add and remove objects without modifying the background. This is useful for animation. TsrBasic conserves DOS memory by using a graphics dynamic link library (DLL) for graphics operations. This library is loaded automatically when necessary and is freed when you exit graphics mode using the mode -1 (default) statement. The graphics library requires about 40 kb of memory. If you do not have at least 40 kb of free memory you will not be able to load the graphics library or do graphics operations. The image transfer statements allocate memory for the bitmap directly from DOS. Note that multi-color high resolution images produce large bitmaps and require larges amounts of memory. A 320x200 16 color bitmap requires about 64 kb. A 640x486 16 color bitmap takes up more memory than you are likely to have in your PC and will therefore need to be transferred in pieces (to separate files), using multiple GET/MAPSAVE statements. The memory for image bitmaps is automatically freed when you exit graphics mode with the mode -1 (default) statement. It may also be explicitly freed by using PUT 0,0,0,0 to save a zero length bitmap. If you have a Hercules compatible video adapter you will need to execute MSHERC.EXE from DOS prior to entering graphics mode. TsrBasic Reference Manual Page 11 11. String Handling TsrBasic supports the usual set of BASIC string handling functions, as well as PARSE, STRINS and STROVR, which are specific to TsrBasic. The following list summarizes the string handling functions available with TsrBasic: asc left space cat len strins chr mid strovr copy parse instr right 11.1 Parse Function The PARSE function breaks a string into pieces called tokens. The syntax of the PARSE function is as follows: parse (buffer,literals,connectors,discards,delimiters,specials) buffer - string to parse literals - grouping characters to discard connectors - grouping characters to save discards - leading characters to discard delimiters - delimiters to discard specials - delimiters to save The buffer parameter is a variable containing the string to be parsed. The PARSE function splits a token off the front end of the buffer and returns it as the function value. The resulting string, less the first token, is returned via the buffer parameter. The returned buffer will be equal to the null string when all the tokens have been parsed from it. The buffer parameter should not be an array reference. The parameters represented by literals, connectors, discards, delimiters and specials control the way the parsing is performed. Each parameter is a character string or variable containing one or more characters. The default for literals is double and single quote. The default for discards is space and tab. The default for delimiters is comma. The default for all other parameters is the null string. These defaults give PARSE a default behavior equivalent to the processing done by the INPUT statement. All parameters except for buffer are optional. Parameters to the right of the one you wish to specify may be omitted. Here is an example: after executing the following: Page 12 TsrBasic Reference Manual a = "one, two, three" b = parse (a) c = parse (a) d = parse (a) a is equal to "one" b is equal to "two" c is equal to "three" Literals and connectors are used to quote sequences of characters so they are not affected by other parse actions. The difference between literals and connectors is that characters in the list of literals are not returned as part of the token whereas characters from the list of connectors are. Note the difference in the following example, where single quote is used first as a literal and then as a connector: after executing the following: a = "'hello world'" b = parse (a, "'") a = "'hello world'" c = parse (a, "", "'") b is equal to "hello world" c is equal to "'hello world'" Discards are a list of characters to strip from the beginning of the token. They are normally used to strip preceding spaces or tabs. Delimiters and Specials are characters that mark the end of a token. The difference between them is that delimiters are not returned as part of the token whereas specials are returned as the next token. Here is an example: after executing the following: a = "execute 3 + 4 * 5" b = parse (a, "", "", "", " ", "+*") c = parse (a, "", "", "", " ", "+*") d = parse (a, "", "", "", " ", "+*") e = parse (a, "", "", "", " ", "+*") f = parse (a, "", "", "", " ", "+*") g = parse (a, "", "", "", " ", "+*") TsrBasic Reference Manual Page 13 b is equal to execute c is equal to 3 d is equal to + e is equal to 4 f is equal to * g is equal to 5 The PARSE function is well suited to being used in a loop to initialize an array of tokens, as follows: 100 tokcnt = 0 110 dim token(30) 120 print "enter text: "; 130 line input text 140 if text = "" then goto 180 150 token(tokcnt) = parse (text) 160 tokcnt = tokcnt + 1 170 goto 140 180 print "done" 11.2 Strins Function The STRINS function inserts a string into the middle of another string. Here is its syntax: newstr = strins (oldstr, start, midstr) The string represented by midstr is inserted into oldstr starting at an offset of start into oldstr to produce newstr. For example: after executing the following: oldstr = "advance" midstr = "THANKS" newstr = strins (oldstr, 4, midstr) newstr is equal to "advTHANKSance" 11.3 Strovr Function The STROVR function overlays a string onto the middle of another string. Here is the syntax for STROVR: newstr = strovr (oldstr, start, midstr) The string represented by midstr is overlayed onto oldstr starting at an offset of start into oldstr to produce newstr, as follows: Page 14 TsrBasic Reference Manual after executing the following: oldstr = "The quick fox jumps over the lazy dog" midstr = "cat" newstr = strovr (oldstr, 11, midstr) newstr is equal to "The quick cat jumps over the lazy dog" This function is roughly equivalent to the MID statement in other versions of BASIC. 12. File Operations TsrBasic supports simple file operations on standard ASCII files. The following operations are supported: access input print close line input tab eof open The OPEN statement opens a file. The mode parameter describes the access mode for the file. Possible values of mode are: "r" open existing file for reading "w" truncate or create for writing "a" write to end of existing file "r+" open existing file for reading and writing "w+" truncate or create new file for reading and writing "a+" allow reading and writing at end of file Append "b" to any of the above modes to access the file in binary mode. This prevents carriage return/newline and control-z mapping. 13. Execute Statement The EXECUTE statement translates and executes its single string expression argument. This argument can be either a TsrBasic statement-list or a command. Here is an example of how it can be used to implement a simple calculator: 100 print "enter expression: "; 110 line input expression 120 if expression = "quit" then end 130 execute "print " + expression 140 goto 100 TsrBasic Reference Manual Page 15 14. If Statement The TsrBasic IF statement takes two forms. One is the conventional: if expression then statement-list [else statement-list] where statement-list is a list of colon separated statements. The other form of the TsrBasic IF statement is designed to simplify structured programming. It is coded as follows: if expression then statement-list ... [else statement-list ...] end if Any number of lines of statement-lists can appear in the THEN and ELSE clauses, and they may include nested IF statements. The only requirement for this form of the IF statement is that the THEN, ELSE and END IF keywords appear on separate lines. Note that the ELSE clause is optional. 15. Link Command The LINK command links the TsrBasic interpreter with the current program to create a DOS executable file. The TsrBasic program can then be invoked just like any other DOS program. It can even get access to command line arguments using the ARGC and ARGV functions. Here is an example of a simple program that will get the name of a file from the DOS command line and list it to the console. See the description of file operations in section 12 for more information. Page 16 TsrBasic Reference Manual 100 if argc() <> 1 110 then 120 print "usage: list <file>" 130 end 140 end if 150 open #1, "r", argv (1) 160 if not eof (1) 170 then 180 line input #1, buf 190 print buf 200 goto 160 210 end if 220 close #1 This program can be converted into an executable file using the LINK command. The resulting .exe file can then be executed from the DOS command line with a single argument specifying a file to list. Note: the LINK command writes the current settings of the command line options for data area, program and symbol table size to the .exe file. These sizes do not need to be specified again when the resulting .exe file is executed. 16. Command Line Options TsrBasic supports the following command line options. Note that they are case sensitive and must be specified using lower case. tsrbasic [-d<n>] [-p<n>] [-s<n>] [files] The -d<n> option defines the amount of storage allocated for the data defined in DATA statements. The <n> parameter specifies the number of data elements that can be defined in your program. The default is -d100, which provides storage for 100 elements. Increase this parameter if you see a "Too many data items" error message. The -p<n> option defines the amount of storage allocated for the intermediate code program. The <n> parameter is specified in units of intermediate code instructions. The default is -p750 which represents 750 intermediate code instructions and is roughly equivalent to 300 lines of TsrBasic source code. Increase this parameter if you see a "Program too long" error message. The -s<n> option defines the amount of storage allocated for the symbol table. The <n> parameter specifies the maximum number of symbols. A symbol table entry is required for each variable, array and literal, including those defined in immediate mode. The default is -s150. Increase this parameter if you see a "Too many symbols" error message. TsrBasic Reference Manual Page 17 One or more TsrBasic source files can be specified on the command line. These files are processed in the order they are specified. In order to be executed, a file must have a RUN command in it. The interactive command processor is entered after the last file is processed. 17. Error Handling TsrBasic errors fall into two categories: compilation errors and runtime errors. Compilation errors reflect errors in your source code that must be corrected before the program can be executed. The most common compilation error is "syntax error." If you get a syntax error, and the cause of the error is not immediately obvious, look very carefully at the statement and compare the syntax you specified to that which is listed in the summary of statements and functions. Be especially careful to check for invalid or missing operators. Runtime errors are errors that could not be detected at compilation time, like "Cannot open file." They may be trapped using an ON ERROR GOTO statement. The ERL, ERR and ERM functions can be used within an error handler to identify the line number on which the error occured as well as the error code and the error message text. An error handler can use the RESUME statement to retry the statement that caused the error, return control to the statement following the line that caused the error, or return control to some other location. See Appendix C for a complete list of error codes and messages. 18. Using Keyboard Scan Codes When you press a key on the keyboard, the keyboard sends a scan code to the CPU indicating the key that was pressed. These scan codes are usually translated into characters to be used by your program. Several TsrBasic statements deal directly with raw scan codes. The SUSPEND statement, for instance, uses a scan code value to specify the hotkey that is used to recall the interpreter. The scan code values are taken from the list in Appendix D. The GETKEY and INKEY functions both return combinations of scancodes and characters. The return value consists of two bytes. The high order byte is the scan code and the low order byte is the character value, or zero for keys that do not have character values, such as function keys. To get the high order byte, or Page 18 TsrBasic Reference Manual scan code, right shift the returned value by 8 bits. This is equivalent to integer division by 2^8 or 256: scan_code = inkey () \ 256 To get the low order byte, or character value, zero the high order byte by ANDing with 0xff or 255: char_code = inkey () & 255 The following TsrBasic program will tell you the scan code and character associated with any key: 100 print "Enter key, or q to stop"; 110 key = getkey () 120 scan_code = key \ 256 130 char_code = key & 0xff 140 print 150 print "scan code = "; scan_code 160 print "char code = "; char_code; 170 print " ("; chr (char_code); ")" 180 if char_code <> asc ("q") then goto 100 Note that control-c will not terminate a program that is using GETKEY to read a scancode. Instead, GETKEY will return the scancode for control-c. Appendix A. Summary of Statements and Functions A TsrBasic program is made up of statements and functions. When the RUN command is entered, the statements and functions are compiled into intermediate code and then executed. Commands differ from statements in that they are not compiled into intermediate code. Statements can be entered without a line number, in which case they are executed immediately, or with a line number, in which case they are stored as part of the current program. Multiple statements can be entered on a single line, separated by colons. Functions return values. They are passed an argument list consisting of zero or more expressions, separated by commas. Statements, functions and commands in TsrBasic are not case sensitive. They may be entered in any combination of lower and upper case. In the following summary, functions are indicated by an equal sign: n = abs (m) TsrBasic Reference Manual Page 19 and statements are indicated merely by the presence of the statement name: beep Some TsrBasic keywords can be referenced as both statements and functions to get and/or set values. Keywords that can be used as both statements and functions have syntax specifications for each form. The following summary uses the letter b to represent boolean values, the letters n and m to represent integers, the letters r, s and t to represent strings and the letters x and y to represent real numbers. Values are converted to the appropriate type when necessary. Note: The trigonometric functions expect arguments expressed in radians. To convert degrees to radians, multiply by pi/180. y = abs(x) Return absolute value of x. b = access(s) Return true if file s exists. n = argc() Return number of arguments on dos command line. s = argv(n) Return argument number n from dos command line. n = asc(s) Return ascii code of first character of s. y = atn(x) Return arctangent of x, where x is in radians. background n Set background color for subsequent text output to n. Use the lookup function to map color names to numbers. Use the refresh statement to make the color change occur immediately. s = background ([n]) Return current text background color, optionally set new background color to n. beep Generate tone through speaker. blank Clear entire screen, differs from cls in that cls clears just the current text window. Page 20 TsrBasic Reference Manual border Shrink the text area of the window by one row or column on each side and draw a border around it. box x1, y1, x2, y2, f Draw a box with top left corner at x1, y1 and bottom right corner at x2, y2. Outline the box if f is 2 and fill the box if f is 3. The lookup function may be used to map "outline" and "fill" to 2 and 3. Available in graphics mode only. s = cat(t[,u...]) Return the concatenation of strings t, u, etc, see also: +. chain s Load file specified by s and run it, see also: common. s = chr(n) Return the character equivalent for ascii code n. n = cint(x) Return x rounded up to next integer. circle x1, y1, x2, y2, f Draw a circle within the bounding rectangle specified by a top left corner at x1, y1 and a bottom right corner at x2, y2. Outline the circle if f is 2 and fill the circle if f is 3. The lookup function may be used to map "outline" and "fill" to 2 and 3. Available in graphics mode only. clip x1, y1, x2, y2 Define a graphics view port with a top left corner at x1, y1 and a bottom right corner at x2, y2. Subsequent graphics output beyond this rectangle will be clipped. Available in graphics mode only. close #n Close file opened with file number n, see also: open, input, print. cls Clear current text window, see also: blank. color n, m Set graphics foreground color to n and background color to m. The graphics color is maintained independently of the text color. The lookup function may be used to map color names to color numbers. Available in graphics mode only. column n Move cursor to absolute column n, where the leftmost column is 0 and the rightmost column is usually 79. See also TsrBasic Reference Manual Page 21 locate, which positions the cursor relative to the origin of the current text window. n = column ([m]) Return current cursor column, optionally moving cursor to column m. common variable [,variable]... Define common variables for chained programs, see also: chain. config xpix, ypix, colors, adapter, mode Get the current graphics configuration. cont Continue program execution after stop, see also: stop. s = copy(t,n) Return a string consisting of n copies of t. y = cos(x) Return the cosine of x, where x is in radians. csroff Turn the cursor off. csron Turn the cursor on and set it to a default size. csrbottom n Change the size of the cursor by setting the bottom of the cursor to scan line number n. Must be 0 to 6 for cga and 0 to 12 for ega. The bottom scan line should be numerically greater than the top scan line. n = csrbottom ([m]) Get the current bottom scan line of the cursor, and optionally set it to scan line m. csrtop n Change the size of the cursor by setting the top of the cursor to scan line number n. Must be 0 to 6 for cga and 0 to 12 for ega. The top scan line should be numerically less than the top scan line. n = csrtop ([m]) Get the current top scan line of the cursor, and optionally set it to scan line m. s = date() Return the current date in mm:dd:yy format. Page 22 TsrBasic Reference Manual data value [,value]... Define numeric and string values, see also: read. m = dec(n) Return the decimal equivalent of hex or octal n, see also: hex, oct. dim array(n[,n]...) [,array(n[,n]...)]... Define array with index zero to n, see also: erase, shift, sort. display n,m,s Display string s at absolute row n and column m, without moving the cursor. end Terminate program execution. s = environ(t) Return value of environment variable t. b = eof(n) Return true if end of file reached on file n. erase array [,array].. Free array, see also: dim. n = erl() Return line number on which error occurred. Valid in error handler only. See also: erm, err, on error. s = erm() Return error message associated with error. Valid in error handler only. See also erl, err, on error. n = err() Return error number associated with error. Valid in error handler only. See also erl, erm, on error. error n Simulate occurrence of error n, see also: on error, resume. execute s Execute string expression s as a TsrBasic statement. y = exp(x) Return natural log (e) to the power of x. fill x1, y1, n Fill the graphics image that has border color n and surrounds the point x1, y1. Use lookup to map color names to numbers. Available in graphics mode only. TsrBasic Reference Manual Page 23 n = fix(x) Return x truncated to an integer. n = fre() Return amount of free TsrBasic memory in bytes. for variable = expression to expression [step expression] For...next loop, see also: next. foreground c Set foreground color for subsequent text output to n. Use the lookup function to map color names to numbers. Use the refresh statement to make the color change occur immediately. d = foreground ([c]) Return current text foreground color, optionally set new foreground color to c. get x1, y1, x2, y2 Transfer a graphics image from the screen to memory. The image is bounded by a rectangle with a top left corner of x1, y1, and a bottom right corner of x2, y2. The image may then be transferred to a file using mapsave or back to the screen using put. Available in graphics mode only. n = getkey () Wait for a key to be entered and return the scan code. See Appendix D for more information on scan codes. n = getscreen () Return the attributes and ascii code of the character at the current cursor position. The attributes are returned in the high order byte and the ascii code is returned in the low order byte. goto n Goto line number n, also valid in immediate mode after run. gosub n Call subroutine at line number n, see also: return. m = hex(n) Return hexadecimal equivalent of decimal or octal n. See also: dec, oct. if expression then statement-list [else statement-list] If...then...else statement, see detailed description. init Set current text window and cursor to default size and color. In the normal text video mode there are 25 rows and Page 24 TsrBasic Reference Manual 80 columns. The top-left corner is 0, 0 and the bottom right corner is 24, 79. n = inkey() Return scan code if key entered else zero, see detailed description of scan codes. m = inp(n) Return byte read from hardware port n. input [#file-number] variable [,variable]... Input one or more items into variables, see also: line input, parse. s = instr([n,]r,t) Return first occurrence of s in r optionally starting at n. n = int(x) Return x truncated to an integer and rounded down if negative. intensity n Set text intensity (brightness) attribute to n. Use lookup function to map intensity names "low" and "high" to intensity numbers 0 and 8. s = left(t,n) Return leftmost n characters of s. n = len(s) Return number of characters in s. [let] variable = expression Assign expression to variable or array. line input [#file-number] variable Input an entire line of text into a variable or array. lineto x1, y1 Draw a line in the current graphics color to point x1, y1. Valid only in graphics mode. See also: mode, moveto. locate n, m Set cursor to row n and column m relative to the current text window (0,0 is top left). See also: screen. mapload n Load a graphics image bitmap, previously saved by mapsave, from file IMAGE.n where n is a number. The bitmap may then be transferred to the screen using put. TsrBasic Reference Manual Page 25 mapsave n Save a graphics image bitmap to file IMAGE.n where n is a number. The bitmap must have previously been transferred from the screen to memory using get. mode n Set video/graphics mode to n. See detailed description of graphics modes for more information. moveto x1, y1 Move to point x1, y1 for subsequent graphics output. Valid only in graphics mode. See also: mode, lineto. next variable For...next loop, see also: for y = log(x) Return natural logarithm of x. s = mid(t,n[,m]) Return m characters from t starting at n, return remainder of string t if m is omitted. m = oct(n) Return octal equivalent of decimal or hexadecimal n. See also: dec, hex. on error goto n Call error handler at line number n. Return from it with resume. See also: erl, erm, err. open #n, s, t Open file with access mode s and pathname t, and associate it with file number n. See detailed description for information on access modes. out port, expression Output integer byte value to port, see also: inp. page n Set current video text page for video adapters capable of supporting multiple text pages. n = page ([m]) Get the current video text page and optionally set it to page m. s = parse(t[,v...]) Return a token parsed from t, see detailed description. i = peek(j,k) Return byte located at segment j, offset k. Page 26 TsrBasic Reference Manual pixel x1, y1 Turn on graphics pixel at point x1, y1. Available only in graphics mode. poke segment, offset, expression Set byte at segment and offset to integer value, see also: peek. print [#n] expression [, or ; expression]... Print to file number n or console, semicolon causes print items to be adjacent, comma causes them to be separated by tabs. put x1, y1, n Transfer a graphics image from memory to the screen. The image must have previously been captured using get, or read from a disk file using mapload. The top left corner is put at x1, y1 and the control argument n describes how the image is transferred to the screen. See the detailed description of graphics for more information. randomize Seed random number generator. read variable [,variable]... Read values into variables or arrays, see also: data, restore. refresh Refresh the text screen. This can be used after the foreground and background statements to change the color of text that is already on the screen. rem Remark, i.e. this line is a comment, equivalent to single quote. restore Restore data list to beginning, see also: data, read. restorescreen s Restore screen contents to previous value, see savescreen. In addition to restoring the contents of the screen, this statement also restores the text window dimensions that were in effect when the corresponding savescreen was executed. resume Return from error handler and retry statement that caused error. See also: on error. TsrBasic Reference Manual Page 27 resume n Return from error handler to line-number n. See also: on error. resume next Return from error handler to statement following the one that caused the error. See also: on error. return Return from subroutine entered via gosub. row n Move cursor to absolute row n, where the top row is 0 and the bottom row is usually 24. See also locate, which positions the cursor relative to the origin of the current text window. n = row ([m]) Return current cursor row and optionally move cursor to row m. s = right(t,n) Return rightmost n characters of t. m = rnd([n]) Return random number, optionally based on seed n. savescreen s Save screen contents in variable s for a subsequent restorescreen. This function saves the text window defined using the wintop, winleft, winbottom and winright statements. To save the entire screen, use the init statement first to set the text window size back to the entire screen. screen "command", parameters Not supported in Version 2.0. See setailed description of text windows for alternate statements and functions. scroll n Scroll screen up n rows if n is positive or down n rows if rows is negative. m = sgn(x) Return -1 if x is negative, 0 if x is 0, +1 if x is positive. shell s Pass string expression s to DOS shell to execute as a command. Because DOS is not reentrant, this statement will not work when you have recalled a suspended TsrBasic session from the DOS shell. In this case it will return a "DOS is Page 28 TsrBasic Reference Manual busy" error. You can, however, use the SHELL statement when you have recalled TsrBasic from most other applications, provided there is sufficient memory. shift a, n Shift one dimensional array a by n elements. If n is negative elements are shifted down and extra elements are discarded from the low end. If n is positive then elements are shifted up and extra elements are discarded from the high end. y = sin(x) Return sine of x, where x is in radians. sort a, n Sort one dimensional array a into ascending order if n is positive and into descending order if n is negative. sound frequency, duration Generate tone, use a frequency of zero for a delay. s = space(n) Return string of n spaces, see also: copy y = sqr(x) Return square root of x. stop Stop execution. Useful for debugging. See also: cont. suspend screen, key-code, key-flags, interval, status Terminate and stay resident. See detailed description of suspend statement for more information. swap variable-a, variable-b Swap the contents of variable-a and variable-b. tab(n) Position cursor to column n (as print argument only). y = tan(x) Return tangent of x, where x is in radians. s = time() Return current time in hh:mm:ss format. troff Disable statement tracing. tron Enable statement tracing. TsrBasic Reference Manual Page 29 type n Set type of video access to n, where n is 0 for direct (fast) access, 1 for BIOS access, 2 for BIOS/DOS access, and 3 for text in graphics mode. The default is 0. Use 1 if you have any video problems with 0, use 2 if you want to redirect output using DOS redirection capability. Use 3 for mixed text and graphics in graphics modes (see mode). winbottom n Set the bottom row of the text window to n, where n is in the range of 0 (top) to 24 (bottom). See detailed description of text windows for more information. n = winbottom ([m]) Return the current bottom row of the text window and optionally set it to m. winleft n Set the left column of the text window to n, where n is in the range of 0 (left) to 79 (right). n = winleft ([m]) Return the current left column of the text window and optionally set it to m. winright n Set the right column of the text window to n, where n is in the range of 0 (left) to 79 (right). n = winright ([m]) Return the current right column of the text window and optionally set it to m. wintop n Set the top row of the text window to n, where n is in the range of 0 (top) to 24 (bottom). n = wintop ([m]) Return the current top row of the text window and optionally set it to m. Appendix B. Summary of Commands Commands are usually entered without a line number and are executed immediately. They may, however, be included in programs if they are passed as arguments to the EXECUTE statement. In this case, they are processed when the EXECUTE statement is executed. Page 30 TsrBasic Reference Manual In the following list of commands, the phrase line-number-spec refers to an optional specification of line numbers. The specification may take the following forms: - all lines n line n n- line n through end n-m line n through m -n beginning through n If the specification is omitted, all lines are processed. clear Free all variables. chdir pathname Make pathname the current directory. delete [line-number-spec] Delete lines from current program, use caution when entering this command without a line-number-spec, because it will delete the entire program. dis [line-number-spec] Disassemble intermediate code. edit [line-number-spec] Invoke editor specified by EDITOR environment variable on line-number-spec. kill pathname Delete file specified by pathname. link pathname Translate current program into an executable called pathname. list [line-number-spec] List current program load pathname Clear current program and load new program, default extension is ".bas". Append a period if the filename does not have an extension. merge pathname Merge new program with current program. mkdir pathname Create a directory specified by pathname. new Erase the current program. TsrBasic Reference Manual Page 31 quit Terminate TsrBasic and unload from memory if resident. renum new-first-line line-increment Renumber current program. rmdir pathname Remove directory specified by pathname. run [line-number] Execute current program, optionally starting at line-number. save pathname Save current program to file specified by pathname, default extension is ".bas". Append a period if you do not want the filename to have an extension. Appendix C. Error Codes and Messages The following list describes TsrBasic error codes and messages: Code Message 0 Internal error 1 Syntax error 2 Uninitialized variable 3 Missing left paren 4 Missing right paren 5 Missing comma or right paren 6 Missing factor 7 Expression too complex 8 Too many symbols 9 Program too long 10 Too many nested calls 11 Too many nested GOSUB's 12 RETURN without GOSUB 13 Duplicate definition 14 Invalid subscript 15 Too many data items 16 Out of data 17 FOR loops nested too deep 18 Missing NEXT 19 Missing FOR 20 Cannot open file 21 File not open 22 File in use 23 Undefined line number 24 Break 25 Cannot continue 26 File or dir not found Page 32 TsrBasic Reference Manual 27 Assignment to constant 28 Cannot locate tsrbasic 29 i/o error 30 DOS is busy 31 Missing END IF 32 Cannot load GRAPHICS.DLL 33 Floating point exception 34 Missing THEN 35 Use of keyword as variable 36 Graphics error 37 Cannot terminate TSR Appendix D. Keyboard Scan Codes The following table lists the key and the corresonding scan code, in decimal (and in parenthesis). Note that some keys, such as control and shift cannot be processed by getkey and inkey. Characters a (30) k (37) u (22) b (48) l (38) v (47) c (46) m (50) w (17) d (32) n (49) x (45) e (18) o (24) y (21) f (33) p (25) z (44) g (34) q (16) h (35) r (19) i (23) s (31) j (36) t (20) Digits 1 (2) 5 (6) 9 (10) 2 (3) 6 (7) 0 (11) 3 (4) 7 (8) 4 (5) 8 (9) Function Keys f1 (59) f5 (63) f9 (67) f2 (60) f6 (64) f10 (68) f3 (61) f7 (65) f4 (62) f8 (66) TsrBasic Reference Manual Page 33 Special Keys alt (56) equals (13) page down (81) arrow down (80) enter (28) page up (73) arrow left (75) escape (1) period (52) arrow right (77) home (71) prt sc / * (55) arrow up (72) insert (82) right bracket (27) back quote (41) keypad + (78) right shift (54) back space (14) keypad - (74) semicolon (39) back slash (43) keypad 5 (76) scroll lock (70) caps lock (58) keypad enter (78) single quote (40) comma (51) left bracket (26) slash (53) control (29) left shift (42) space (57) delete (83) minus (12) tab (15) end (79) num lock (69) Page 34 TsrBasic Reference Manual