ProfitPress Mega CDROM2 Shareware Freeware (MSDOS)(1992)(Eng)

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

/ ProfitPress Mega CDROM2 …eeware (MSDOS)(1992)(Eng) / ProfitPress-MegaCDROM2.B6I / PROG / BASIC / ASIC20.ZIP / ASIC.DOC next >

Wrap

Text File | 1990-10-13 | 186.4 KB | 7,036 lines

mCB +--------------------------------------------------------------------+ | | | A S I C 2.0 | | | | "Its Almost Basic" | | | | | | Copyright 1990 | | by | | David A. Visti | | | | All Rights Reserved | +--------------------------------------------------------------------+ | ASIC 2.0 is provided as shareware. Under the shareware concept, | | you can test a program before you buy it. If you find it suitable | | for your needs and make use of this program, you are expected to | | send a $10 registration fee. | | | | Feel free to distribute this software to others. However, you | | may not charge for the distribution of this software to others | | nor may you alter the software or this documentation. | | | | Registered users of any version of ASIC will receive a diskette | | containing the current version of ASIC, plus may purchase future | | updates at half of the normal registration price. A printed 2.0 | | manual is available to registered users for an additional $10.00. | +--------------------------------------------------------------------+ | | | Please send registration fees and suggestions to: | | | | David Visti | | P.O. Box 2952 | | Raleigh, NC 27602-2952 | | | | Please mention the version of ASIC in any correspondence | | (This is ASIC Version 2.0) | +--------------------------------------------------------------------+ | I can also be reached for questions/comments on GEnie and | | Compuserve via EMAIL: | | | | Compuserve 73065,1302 | | GEnie D.VISTI | | | +--------------------------------------------------------------------+ | | | DISCLAIMER: This software is provided "as is" without warranty | | of any kind. In no event shall I be held liable for any damages | | whatsoever arising from the use of or inability to use this | | product. | | | | Your registration fee entitles you to use this software on a | | single computer. Site licenses are available, write for details. | +--------------------------------------------------------------------+ A S I C Table of Contents Chapter Title 1. Getting Started Page 3 2. Tutorial Page 5 3. Integrated Editor/Compiler Environment Page 10 4 Using the Debugger Page 20 5. Stand-alone Compiler Options Page 28 6. Language Elements Page 31 7. Keyword Reference Page 35 ABS Page 35 ASC Page 35 BLOAD Page 36 BSAVE Page 37 CALL Page 38 CHDIR Page 40 CHR$ Page 41 CLOSE Page 42 CLS Page 42 CODE Page 43 COLOR Page 44 COMMAND$ Page 45 COMSTAT Page 46 CSRLIN Page 47 DATA Page 48 DATE$ Page 49 DEFSEG Page 49 DIM Page 50 END Page 50 FOR/NEXT Page 51 GOSUB Page 53 GOTO Page 53 IF/THEN/ELSE Page 54 INKEY$ Page 55 INP Page 56 INPUT Page 57 INPUT# Page 58 KILL Page 59 LEN Page 59 LOCATE Page 60 LPRINT Page 61 MID$ Page 62 MKDIR Page 63 NAME Page 64 OPEN Page 65 OPENCOM Page 66 OUT Page 67 PEEK Page 67 POINT Page 68 Page - 1 Table of Contents (Continued) Chapter Title 7. Keyword Reference (Continued) POKE Page 69 POS Page 69 PRESET Page 70 PRINT Page 71 PRINT# Page 72 PSET Page 74 RANDOMIZE Page 74 READ Page 75 RECEIVE Page 76 REM Page 77 RESTORE Page 77 RETURN Page 78 RMDIR Page 78 RND Page 79 RUN Page 80 SCREEN Page 81 SEND Page 82 SOUND Page 83 STR$ Page 83 TIME$ Page 84 TIMER Page 85 VAL Page 86 VARPTR Page 86 WIDTH Page 87 ZBIT Page 87 ZMODE Page 88 8. Compatibility with BASICA/GWBASIC Page 89 9. Technical Details/Tips Page 92 10. Error Messages Page 96 Page - 2 A S I C Chapter 1 Getting Started INTRODUCTION Welcome to ASIC! ASIC is a "BASIC" programming language compiler for IBM PC's and compatibles. It includes an integrated full screen editor, from which you can edit, compile, and debug your programs. Or at your option, you can use your own text editor, and compile your programs from the MS DOS command line. ASIC is a subset of BASICA and GWBASIC which supports over 60 BASIC statements, integer and string variables, and integer arrays. It will compile your programs at high speed, and the code it generates is fast and compact. The syntax of each ASIC statement is generally a valid subset of the syntax used by BASICA and GWBASIC (exceptions are noted in Chapter 8.) All you need to get started is: 1) ASIC 2) IBM PC or 100% Compatible 3) 300-400k Available Memory* 4) Two floppy disk drives <or> One hard disk drive and one floppy disk drive The first step is to install ASIC as described below. Then, proceed to Chapter 2 for a brief ASIC tutorial. Following that you can read the remainder of the documentation straight through, or refer to it as you need it. Have Fun! * The ASIC Compiler will run in 300k of memory. The ASIC Editor will run in less than 200k of memory, however, to compile and debug within the editor, 400k of available memory is required. If ASIC does not find sufficient memory to call the compiler from within the editor, it will ignore the compile request and return to the editor. Page - 3 INSTALLATION To install ASIC execute the following commands as appropriate for your machine. The procedure to do so is provided below for both floppy systems and hard disk based systems. Also refer to the README file on your ASIC Diskette for additional information. TWO-FLOPPY DISK SYSTEM INSTALLATION 1) Make sure that the following files are all on the same diskette (the diskette that contains these files will be referred to in this manual as the "Compiler" diskette): ASIC.EXE ASICC.EXE 2) Format one or more blank diskettes to hold your programs (these diskettes will be referred to in this manual as your "Program" diskettes): Note: Whenever you see the symbol <enter> in this document, this refers to the <enter> or <return> key on your keyboard. HARD DISK SYSTEM INSTALLATION 1) Type: C: <enter> 2) Type: MD C:\ASIC <enter> 3) The next step is to copy the ASIC software to the ASIC directory. If your ASIC software is on a floppy, insert the floppy in Drive A: then type the command: COPY A:*.* C:\ASIC <enter> If your ASIC software is already on a hard disk directory, copy it to the ASIC directory with the command: COPY C:\directoryname\*.* C:\ASIC <enter> Note that ASIC will run from any subdirectory, however, the tutorial assumes ASIC is under C:\ASIC Note: Whenever you see the symbol <enter> in this document, this refers to the <enter> or <return> key on your keyboard. Page - 4 A S I C Chapter 2 Tutorial ASIC programs look very much like regular "BASIC" programs which you are probably already familiar with. The one very noticeable difference is that ASIC programs have no line numbers. Let's take a look at a very simple program written both in GWBASIC/BASICA and in ASIC: GWBASIC/BASICA ASIC --------------------------+---------------------------------- | 10 I=I+1 | ADDONE: I=I+1 20 PRINT I | PRINT I 30 IF I<100 THEN 10 | IF I<100 THEN ADDONE: --------------------------+---------------------------------- Both of these programs do the same thing. They display the numbers from 1 to 100. However, notice that ASIC allows you to use descriptive labels (ADDONE) instead of a line number (10). These labels can be up to 80 characters long! Also note that the ASIC "PRINT" and "IF" statements were indented only for increased program readability. The ASIC program could just as well have been written as: ASIC ------------------------------ ADDONE:I=I+1 PRINT I IF I<100 THEN ADDONE: ------------------------------ We could have made our variable names longer. Instead of "I" we could have chosen "SECONDS" or "VELOCITY", or some other name up to 80 characters in total. In ASIC, variable names, labels, and string constants can all be up to 80 characters in length. Well, now that we've seen a basic ASIC program, let's try to enter and run a slightly larger program. The program we will be working with will print the message "HELLO yourname" in 256 color combinations. If you have a monochrome display card, don't worry, the program will work, but instead of seeing different colors you'll see characters with different attributes, such as blinking, underlined, etc. Page - 5 Let's get started. If you haven't done so already, install ASIC as described in Chapter 1. Now then, writing an ASIC program involves these three steps. 1. Write your program. 2. Compile your program. 3. Run/Test your Program. These three steps can all be performed from within the ASIC Integrated Environment. Before we proceed with our "Hello yourname" Program, let's go over some conventions. In the following section: FLOPPY TYPE--> Means that only 2-floppy disk system users should type this line. HARD TYPE--> Means that only hard disk system users should type this line. TYPE--> Means that both floppy and hard disk users should type this line. X> This is a representation of the prompt from PC-DOS or MS-DOS. Floppy Disk Users will actually see "A>" for a prompt. Hard Disk Users will see "C>" for a prompt. <enter> Means that you should press the <enter> or <return> key on your keyboard. <?> Text enclosed between the "<" and the ">" symbols indicate a key to type. Don't type the "<" or ">" symbols. For example, if the tutorial lists "<F1>", your should press the "F1" key on your keyboard. NOTE: Floppy Disk users need to insert their ASIC Compiler diskette in Drive A: at this point, and a Program diskette in Drive B: (See the Installation section for more information) Let's begin: FLOPPY TYPE--> A: <enter> HARD TYPE--> CD C:\ASIC <enter> The computer should respond: X> Now enter the command to invoke ASIC Page - 6 TYPE--> ASIC <enter> You are now in ASIC. The top line is the Menu Bar. The bottom line is the Status Line. Chapter 3 describes these features in more detail. For now, we'll just describe a couple of features on these lines. The status line indicates that the current mode is "INSERT". This means that any characters you type on a line will be inserted between the existing characters. If you press the <INS> key on the keypad, ASIC will toggle to it's other mode, OVERSTRIKE. In this mode, when you type a character, it overlays the character that was there before. Each time you press the <INS> key, ASIC will toggle between the INSERT and OVERSTRIKE modes. You can open the menus listed on the "Menu Bar" by holding down the ALT key while typing the Capitalized letter of the menu you wish to open. For example, to open the File menu, press <ALT><F>. The "File" menu will pop open. You can select a menu option from that menu by typing the capitalized letter of the option, or by using the arrow keys on your keypad to highlight the option you want and then pressing <enter>. Let's leave this menu for now. To do so, press the <ESC> key. The <ESC> key will always let you escape from any menu in ASIC, without taking any action. If you need help, press the <F1> key for a quick summary of some of ASIC's features. Chapter 3 gives a full description of the ASIC Editor Commands which are available. Entering a program in ASIC is simplicity itself. We'll simply type in each line, pressing <enter> at the end of each line. If you make a typing mistake, just use the arrow keys to move to the error, and type in the correction. Use the <DEL> or <Backspace> keys to delete any unwanted characters from the screen. Make sure the status line says "Mode: Insert". This is the default mode in ASIC. If it doesn't, press the <INS> key until it does. Now let's enter our program (the program below intentionally contains an invalid ASIC statement. We'll correct the line later in the tutorial, for now, type in the program exactly as it's listed below): TYPE--> CLS <enter> TYPE--> PRINT "Please enter your name"; <enter> TYPE--> INPUT YOURNAME$ <enter> TYPE--> FOR I=1 TO 16 <enter> TYPE--> FOR J=1 TO 16 <enter> TYPE--> COLOR I,J <enter> TYPE--> PRINT "HELLO "; <enter> TYPE--> PRINT YOURNAME$; <enter> TYPE--> NEXT J <enter> TYPE--> NEXT I <enter> TYPE--> CLS <enter> TYPE--> THE END <enter> Page - 7 There, that was easy. Now, let's compile our program. To do it, we'll open the "Compile" menu, and select the "Compile program" option: TYPE--> <ALT><C> The "Compile" menu will pop open. The first option, "Compile program" can be selected by typing the option letter which is capitalized "C", or by moving the highlight bar to this option and pressing the <enter> key. Since the highlight bar is already on this option, let's just press <enter>: TYPE--> <enter> Since we didn't specify a file name when we invoked ASIC, ASIC will now ask for a file name (so it can save your program before calling the compiler): FLOPPY TYPE--> B:TUTOR.ASI <enter> HARD TYPE--> TUTOR.ASI <enter> Note that ASIC requires that your programs be stored in files ending with the extension ".ASI". Had we entered "TUTOR" for our program name, ASIC would have appended the letters ".ASI" for us. If we tried to provide a different extension, such as "TUTOR.SRC", ASIC would display an error message. Also, whenever you are presented a dialog box where you are asked to enter text (such as file name, or Y/N responses to questions), you must press the <enter> key before ASIC will accept the input. Once you select the "Compile program" option, you'll see the ASIC compiler screen appear. It will display a count of the lines compiled, and when it is done, it will return to the ASIC editor. If it detected any errors, it will display the first error message at the bottom of the editor screen. It will also highlight the line in your program which is in error. In this case the line "THE END" was flagged with the error message "Syntax Error". Of course, that line should have been entered simply as "END". That should be easy enough to fix. Let's exit the error menu by pressing the <ESC> key: TYPE--> <ESC> The error menu has disappeared, and our cursor is now on the erroneous line. To fix the line: TYPE--> <DEL><DEL><DEL><DEL> Page - 8 That should do it. The last line of our program should now read "END". Let's recompile the program: TYPE--> <ALT><C> TYPE--> <enter> This time you should see the message "No Compiler Errors". If you didn't, check your spelling and recompile the program until you receive this message. Press <ESC> to remove the "No Compiler Errors" Window. Now let's run the program. To do so, we'll open the "Run" menu, and select the "Run your program" option. TYPE--> <ALT><R> TYPE--> <r> This time, we just entered the capitalized letter from the menu option "Run your program". Your computer screen should now prompt you to "Please enter your name?". Go ahead and enter your name now: TYPE--> yourname <enter> You should see "HELLO yourname" printed in various color combinations, and then the ASIC editor screen will reappear. Well, that's all there is to writing, compiling, and running an ASIC program. Now, to exit ASIC, open the "File" menu and select the "eXit" option. TYPE--> <ALT><F> TYPE--> <X> You should see your MS DOS prompt once again. By the way, now that you've successfully compiled the program, you can execute it directly from MS DOS. Let's try it: HARD TYPE--> TUTOR <enter> FLOPPY TYPE--> B:TUTOR <enter> Well, that's a brief introduction to ASIC! Next, you might want to read Chapter 3, "Integrated Editor/Compiler Environment" to learn about the many other features available in the ASIC editor. Following this you should read Chapter 4 which explains how to use the new ASIC Debugger. Chapter 4 includes another short tutorial in which you debug a program. The remaining chapters provide reference material which you can either read, or just refer to as needed. Chapter 5 explains how to compile programs directly from the command line of DOS. Chapters 6-8 describe the BASIC statements which are supported by ASIC. Chapter 10 provides more descriptive information for ASIC error messages. Hope you enjoy programming in ASIC! Page - 9 A S I C Chapter 3 Integrated Editor/Compiler Environment INTRODUCTION The ASIC integrated environment lets you edit, save, compile, and debug your ASIC programs without ever leaving ASIC! This chapter will explain the usage of the integrated environment. ASIC SCREEN CONTENTS ASIC divides the screen into three parts. The top line is called the "Menu Bar". All of the menu's available to you are listed on this line. The bottom Line is called the "Status Line". It continuously displays some important program information. The middle 23 lines are the "Edit Window". This is the section of the screen where you can make changes or additions to your program. MENU BAR PROCESSING Currently, there are four menus available. The "File" menu allows you to load/save your existing program files to/from disk. It is also used to exit ASIC. The "Edit" menu contains various editing commands which are available. The "Compile" menu is used to compile your program, set compiler options, and to view compiler errors. The "Run" menu allows you to run your programs, and test them using the new ASIC debugger. To open a menu, hold down the <ALT> key and type the first letter of the menu. The menu will pop down and display the options available on that menu. If you want to close the menu without taking any action, press the <ESC> key. If you wish to open a different menu without first closing the current menu, press the left or right arrow keys. Otherwise, to select an option, type the capitalized letter of the menu option. For example, on the "File" menu, to select the "eXit" option, type an "X" or an "x". Another way to select an option is to move the "Highlighted Bar" down to the option you wish to select, and press the <enter> key. Some functions may be accessed outside of the menus with function keys. These are listed on the menus (eg. "search Again <F3>" on the Edit Menu), however, these function keys do not operate when a menu is open. (A list of these Function keys is presented later in this chapter in the Keyboard Usage Section). Page - 10 Now let's describe the options available on each menu. FILE MENU "Open" Option This option allows you to open an existing ASIC file and load it into the ASIC edit buffer where you can modify it. If you select this option another window will open to ask you the file name. If you don't wish to open a file, you can press <ESC> to close the menu without taking any action. Otherwise, enter an ASIC file name, and press the <enter> key. "Save" Option This option allows you to write the changes you've made to your program back to the file. Changes you enter in the ASIC editor are made to memory only. You must select this option before your changes will become permanent. Note: Your file is saved to disk automatically whenever you compile it, or run it, if the file modified indicator is set. "save As" Option This option will allow you to write the changes you've made to the program in the edit buffer to a new file. You will be prompted to provide ASIC with a new file name. "eXit" Option This option will allow you to exit from ASIC back to MS DOS. ASIC will ask you if you wish to save your file before you exit. EDIT MENU "Begin block" Option This option will allow you to mark the beginning of a block of text for use with the block delete, copy, and move commands described below. To mark a block of text, move the cursor to the first line of the block, and then select this option. The beginning line of the block will be highlighted on the screen. Next, move the cursor to the ending line of the block, and select the "End block" option from this menu. All of the lines in the block will be highlighted. This block of lines can now be "moved", "copied", or "deleted" using the block commands described below. "End block" Option This option will allow you to mark the end of a block of text. Refer to the "Begin block" Option above for more information. Page - 11 "Search" Option This option allows you to locate a string of characters in the edit buffer. When you select this option, ASIC will ask you for a search string which can be up to 30 characters in length. ASIC will then search forward from the current line until it finds the string or reaches the end of the edit buffer. If it finds the string, the cursor will be placed on the line containing the string. "Replace" Option This option will allow you to replace one or more occurrences of a string of characters with another set of characters. When you select this option, ASIC will ask you for a search string which can be up to 30 characters in length. ASIC will then ask you for the string of characters which is to replace the search string. Finally, ASIC will ask you to specify how many occurrences of this search string are to be replaced (from 1-9999). ASIC will search forward from the current line, and briefly display each line as it modifies it. If it reaches the end of the edit buffer before it has replaced the number of occurrences you've specified, ASIC will display an "End of Buffer" message, and stop. "Delete block" Option This option will delete a block of lines. Refer to the "Begin block" option above for information on marking a block of lines. If you haven't marked a block of lines, selecting this option will have no effect. "Move block" Option This option will move a block of lines to a new location in the edit buffer. Refer to the "Begin block" option above for information on marking a block of lines. If you don't mark a block of lines, selecting this option will have no effect. Once you have marked a block of lines, move the cursor to the location in the edit buffer where you want the lines moved. Selecting the "Move block" option will result in the block of lines being deleted from their current location, and moved to the buffer at the line following the cursor. ASIC will not overlay lines, it will insert enough blank space to hold the relocated text. "Copy block" Option This option is the same as the "Move block" option, with one exception. After moving the block, ASIC does NOT delete the original block of lines. Use this option to clone a block of text. Page - 12 "search Again <F3>" Option This option will allow you to search for the next occurence of the last string you searched for with the "Search" Option, without retyping the previous search string. This option may also be selected outside of the Edit Menu by pressing function key <F3>. COMPILE MENU "Compile program <F10>" Option Use this option to have ASIC compile the program which is currently loaded in the edit buffer. If the compile is successful, ASIC will display the message "No Compiler Errors". Otherwise, it will display the first error message (see "View compile errors" option below). ASIC will automatically save your program before calling the compiler. This option may also be selected outside of the menu by pressing function key <F10>. "Full program listing" Option This menu option, and the next two options are used to toggle various compiler options on or off. When the option is on, you will see a "check mark" symbol next to the option. This compiler option will cause ASIC to display each source line as it compiles it. This option will slow down the compile, but since ASIC also writes these lines to a listing file, this option can be used to create a compile listing. The compile listing will be contained in a file called "progname.LST", where "progname" is the name of your program. "Printer output" Option This menu option will toggle the "Printer output" compiler option on or off. When the option is on, you will see a "check mark" symbol next to the option name. This compiler option will cause compiler messages to be printed on your printer. "Symbol table" Option This menu option will toggle the "Symbol table" compiler option on or off. When the option is on, you will see a "check mark" symbol next to the option name. This compiler option will cause ASIC to create a symbol table file called "progname.SYM", where "progname" is the name of your program. The symbol table is a list of all variables, labels, and internally created compiler addresses. Page - 13 "Debugging code" Option This menu option will toggle the "Debugging code" compiler option on or off. When the option is on, you will see a "check mark" symbol next to the option name. This compiler option will cause ASIC to generate code required by the ASIC debugger to allow you to set breakpoints, single step through your program, and view/modify program variables. This option is "on" by default in the integrated environment. You should leave this option on while you are debugging your program. When you have everything working properly, you should turn it "off" and recompile your program. This will reduce the size of your program slightly, and will make it run faster (of course, you can't use the debugger with it, since there is no debugging information available to ASIC any more. If you need to debug your program again, just recompile with the this option turned "on" again). "View compile errors" Option When you wish to examine the errors from a previous compile of your program, select this option. If no errors exist, ASIC will so inform you. Otherwise, ASIC will display the first error message at the bottom of the screen, and it will highlight the line of your program which corresponds to that error. If you wish to correct the program line, press the <ESC> key. The cursor will be positioned at the beginning of that program line. You may also view subsequent compiler errors by pressing the <F10> key instead of the <ESC> key. RUN MENU The "Using the ASIC Debugger" Chapter has additional information on the debugger and it's options. You may wish to refer to it, should you need more information than is provided below. "Run your program <F5>" Option After you have successfully compiled your program, you can select this option to cause ASIC to load and execute your program. After your program ENDs, ASIC will return you to the editor. ASIC will save the edit buffer before loading and executing your program. If you are running a program containing debugging code, this option will cause ASIC to run your program up to the first breakpoint it encounters, or through the end of your program if you haven't set any breakpoints. If you are already "paused" at a breakpoint, selecting this option will cause your program to resume execution at the statement following the breakpoint, and run up to the next breakpoint or to the end of your program, if no further breakpoints are encountered. This option may also be selected outside of the "Run menu" by pressing function key <F5>. Page - 14 "Breakpoint toggle <F9>" Option If you have compiled your program with the "Debugging code" option turned on, you may use this option to set breakpoints. You can have up to 20 breakpoints active at a time. When you run your program with breakpoints set, ASIC will pause your program when it tries to execute a line on which you have set a breakpoint. At this time, you can view or modify variables, or view the screen output produced by your program. You can then resume program execution by selecting the "Run your program" option from the run menu. If you select this option and the current statement in the edit buffer already has a breakpoint set, then the breakpoint for that source statement will be removed (toggled off). Lines at which you have set a breakpoint will be displayed in reverse video. Also, when you run your program and ASIC stops at a breakpoint, ASIC will display the next line to execute in reverse video on the second line of the screen with a red background (underlined if you have a monochrome system). This option may also be selected outside of the "Run" Menu by pressing function key <F9>. "Trace <F8>" Option If you have compiled your program with the "Debugging code" option turned on, you may use this option to execute your program one statement at a time. After you select this option, ASIC will execute the next program statement in your program, and pause, displaying the next line which will be executed in reverse video with a red background (underlined if you have a monochrome system). At this time, you can view or modify variables, or view the screen output produced by your program. You can then resume program execution by selecting the "Run your program" option from the run menu, or by selecting the "Trace" option again. This option may also be selected outside of the "Run" Menu by pressing function key <F8>. "Modify variable" Option If you have compiled your program with the "Debugging code" option turned on, you may use this option to modify the contents of variables in your program while your program is paused at a breakpoint or following a "Trace" command. When you select this option, ASIC will ask you for the variable name. After you enter the variable name, ASIC will ask you for the new value to be stored in the variable. If the variable is an array, ASIC will ask you which element of the array to modify. Page - 15 "Watch variable <F6>" Option If you have compiled your program with the "Debugging code" option turned on, you may use this option to view the contents of variables in your program, while your program is paused at a breakpoint or following a "Trace" command. After you enter the variable name, ASIC will open a "Watch" window at the bottom of the screen showing you the variable name and the current value. As you continue execution of your program and reach a new breakpoint, the values of variables will be updated to reflect their new values. In this way you can watch the changing values of variables in your program without inserting "PRINT variablename" statements in your program. Up to 10 variables may be watched at a time. If you enter a variable name which is an array, ASIC will ask you which element of the array you wish to watch. This option may also be selected outside of the "Run" Menu by pressing function key <F6>. "Unwatch variable <F7>" Option If you have compiled your program with the "Debugging code" option turned on, you may use this option to remove variables from the "Watch" window (see previous option). When you select this option, you will be asked for a variable name to remove from the window. If the variable is an array, you will also be asked which element of the array. ASIC will then remove the variable from the watch window, and resize the window accordingly. Since only 10 variables may be watched concurrently, you may need to remove variables which are no longer needed from the "Watch" Window using this command. This option may also be selected outside of the "Run" Menu by pressing function key <F7>. "Abort execution" Option If you are running your program, and it is paused at a breakpoint, you may select this option to abort the execution of your program. Your program will be terminated immediately. "Clear all break/watch" Option If you have set breakpoints or watch variables (using the above) options, you may use this option to remove all of them at once, instead of removing them one at a time using the "Toggle breakpoint" or "Unwatch variable" options. Page - 16 "Program arguments" Option This option allows you to pass command line arguments to your programs, which may be retrieved by your program using the COMMAND$ statement. If you are testing outside the integrated environment, you would normally specify the command line arguments by typing "progname arguments". However, in the integrated environment, since ASIC is executing your program for you, this option is a means to pass the "arguments" to your program as if they had been typed on the command line following your program name. "Swap to user screen <F4>" Option Whenever ASIC pauses your program at a breakpoint, it saves the screen created by your program in a memory buffer. You may select this option to view your program screen output. When you are done viewing your program's output, press a key to return to viewing the ASIC editor. This function may also be selected outside the "Run" Menu by pressing the <F4> function key. STATUS LINE The bottom line of the ASIC screen is called the "Status Line". As it's name implies, it is used to display various types of status information. At the left of the status line "FILE: xxxxxxxx.xxx" will display the name of the file which is currently loaded in the edit buffer. If you haven't opened a file yet, the file name will be blank. After the file name is the "File Modified Indicator". If you have entered any changes in the edit buffer, and have not saved them to disk, an "*" will appear to indicate this. If the edit buffer has not been modified since the last save to disk, no "*" will be present. The next piece of information is "Mode:". Mode will always display one of two values: "Insert" or "Ovrstr". In "Insert" mode, any characters you type in the edit buffer will be inserted at the cursor position, and the characters to the right of the cursor will be shifted to the right by one. In "Ovrstr" mode, any characters you type in the edit buffer will overlay (and thus destroy) the character at the cursor position. You can change back and forth between these two modes by pressing the <INS> key on your keypad. To the right of "Mode:" ASIC displays the number of bytes which it allocated to the edit buffer. Divide this number by 81 to get a rough idea of how many lines will fit in the edit buffer. Page - 17 The "Line: nnnn" status indicator, will identify which line of the file is being displayed. For example, if the display reads "Line: 100", the line containing the cursor is the 100th line in the file. When ASIC is reading or writing your program to/from disk, it will display a running total of the number of records read/written in this field. The "Row:" and "Col:" numbers identify the relative position of the cursor within the "Edit Window". EDIT WINDOW The edit window is the area of the screen where your program is displayed. It displays up to 23 lines of your program at a time. You can use the keys described below to manipulate the text in this window. KEYBOARD USAGE Most keys on the keyboard behave in ASIC just as you'd expect. The key usages which might not be obvious are described here. <ESC> Exit from any menu without taking any action. <TAB> Move the cursor to the next "tab stop". Tab stops in ASIC are fixed at every fourth column (4,8,12,etc). <HOME> Move the cursor to the beginning of the current line. <END> Move the cursor to the last non-blank character on the current line. <DEL> Delete the character at the cursor position. <INS> Toggle between Insert and Overstrike Modes. <PGUP> Display the previous "page" of the edit buffer. <PGDN> Display the next "page" of the edit buffer. <Ctl-PGUP> Display the first "page" of the edit buffer. <Ctl-PGDN> Display the last "page" in the edit buffer. <Backspace> Delete the character at the cursor position, and move the cursor one column to the left. <Up Arrow> Moves cursor up one line. <Down Arrow> Moves cursor down one line. Page - 18 <Left Arrow> Moves cursor left one column. <Right Arrow> Moves cursor right one column. <Alt-D> Delete the line containing the cursor. <Alt-A> Add a line following the line containing the cursor. <F1> Displays a help screen. <F3> Repeats the last "Search" command. See Edit Menu Section of this chapter for more information. <F4> Swaps the display to the output from your program temporarily. See Run Menu Section of this chapter for more information. <F5> Runs your program. See Run Menu Section of this chapter for more information. <F6> Add a variable to the "Watch" Window. See Run Menu Section of this chapter for more information. <F7> Remove a variable from the "Watch" Window. See Run Menu Section of this chapter for more information. <F8> Execute a single statement of your program. See Run Menu Section of this chapter for more information. <F9> Toggle breakpoint on/off at the current edit buffer line. See Run Menu Section of this chapter for more information. <F10> Compile your program. See Compile Menu Section of this chapter for more information. <enter> In Insert mode, pressing <enter> is identical to pressing <Alt-A>. In OvrStr mode, pressing <enter> is identical to pressing the <Down Arrow> key. Page - 19 A S I C Chapter 4 Using the Debugger INTRODUCTION The source level debugger in ASIC's integrated programming environment helps you debug your programs by allowing you to "peek" inside them as they're running. You can single step through your programs, or select places in the program where you wish execution to pause by setting breakpoints. Then, while the program is paused, you can view or modify any of your program's variables, and also examine the screen output created by your program. All of the debugger's commands can be selected from the run menu, and they are described in the "RUN MENU" Section of Chapter 3, "Integrated Editor/Compiler Environment". Many of the debugger commands may be selected outside the "Run" menu, by pressing a function key (eg, <F5>,<F6>,etc). A complete list of the function keys available is contained in Chapter 3, in the "KEYBOARD USAGE" Section. This chapter explains how to use the debugger with a short tutorial which guides you through a sample debugging session. The tutorial is followed by a reference section which you should read after completing the tutorial. DEBUGGER TUTORIAL The debugger tutorial follows the same format as the general tutorial in chapter 2. You should complete (or at least review) the general tutorial before taking the debugger tutorial. This tutorial will use a program file provided with your ASIC compiler package called "DBGTUTOR.ASI". If you are running from a hard disk, make sure it is in the ASIC directory. If you are running from a two-floppy system, make sure it is on the diskette in drive b:, with the compiler in drive a:. NOTE: Floppy disk users should verify that the ASIC compiler diskette is in drive A: and the "DBGTUTOR.ASI" disk is in drive b: before proceeding. Page - 20 Let's get started: FLOPPY TYPE--> A: <enter> ASIC B:DBGTUTOR <enter> HARD TYPE--> C: <enter> CD C:\ASIC <enter> ASIC DBGTUTOR <enter> You should be in ASIC now, and you should see a source program. The first few lines should contain: dim scores(10) data 55,33,877,99,44,101,21,88,105,1 rem DBGTUTOR.ASI . . (etc) . This sample program will sort an array of 10 scores into ascending sequence. It uses a simple "bubble" sort algorithm. The "bubble" sort algorithm simply steps through each element of the array and compares it to its next higher neighbor. If it's neighbor's value is less than its own, the two values are swapped. It is necessary to execute this process N-1 times where N= number of items to sort. Here's why. Let's say the lowest value to be sorted was "1" and it is in array element "10" (assume 10 numbers will be sorted). The first swapping pass will result in the "1" being swapped from element 10 to element 9 of the array. An additional 8 passes through the array are necessary to move the "1" to array element number 1. This algorithm gets it's name, because the process of moving the elements has been compared to that of bubbles slowly rising to the surface. This program has a list of ten scores to be sorted. Line 5 of the program will read the ten scores to an array called "Scores", and also print the original values (before the sort) to the screen. Then two loops will execute at statements 8 and 9 in the program to perform the bubble sort as described above. Finally, after the sort is complete, the sorted values will be displayed. First, let's compile the program. When we plan to use the debugger, we must set the "Debugging code" option on. This is done on the Compile Menu. However, the default in the integrated environment is "Debugging code" on. Let's take a look to be sure: TYPE--> <Alt><c> The compile menu should pop open, and you should see a check mark next to the "Debugging code" option. If you don't, press the letter "D", and a check mark should appear. Once you've verified that the option is on, we can compile the program. Notice that there is an <F10> next to the option. Instead of opening this menu and selecting the Page - 21 "Compile" option, we could have pressed <F10>. Let's try it. First, let's close the menu (Function keys don't work inside a menu): TYPE--> <ESC> The menu should have closed. Now let's compile using the function key: TYPE--> <F10> You should see the compiler screen pop up, and compile the program. No errors should be detected. Now we're ready to test the program. First, let's set a breakpoint so we can easily view the screen output, Use the down arrow key to position the cursor on line 20 (the line number is displayed on the ASIC status line). Line 20 should contain an "END" statement. Let's open the run menu and set a breakpoint: TYPE--> <Alt><r> <b> The "END" statement should now be displayed in reverse video. That tells us that a breakpoint has been set there. Did you notice that the breakpoint option on the menu also had a function key listed. We could set a breakpoint without opening a menu, by pressing <F9> instead. Now that we've set a breakpoint, let's run the program and see how it works: TYPE--> <Alt><r> <r> Note that we could have pressed the short cut key of <F5> to run the program instead of selecting the option from the menu. At this point our program is running, but is paused at the breakpoint we set on line 20. When you reach a breakpoint, ASIC will position the breakpointed line on the second line of the edit window, highlighted in red (or underlined, if you have a monochrome system). ASIC has interrupted the program before it executed the line with the breakpoint, in this case "END". Let's take a look at the screen output of the program to see if it worked: TYPE--> <Alt><r> <s> Note we could also select the "Swap" function by pressing <F4> without opening a menu. You should now see the output from the program on the screen. It should look something like: Original Scores: 55 33 877 99 44 101 21 88 105 1 Sorting... Here are the sorted scores: 33 55 99 44 101 21 88 105 1 877 Page - 22 Well, that doesn't look quite right. Maybe we can use the debugger to figure out what went wrong. First, let's allow the program to run to completion (remember, we're paused at a breakpoint on the "END" statement). Swap back to the ASIC screen from the user screen by pressing any key: TYPE--> <enter> You should see the editor screen again. Now let's tell ASIC to resume program execution: TYPE--> <Alt><r> <r> ASIC has executed the END statement, and our program has terminated. You should see the message "Program Terminated Normally (0)". (The "0" is the return code set by the program. You can set return codes in your programs using the new END statement. Refer to Chapter 7 for details.). Now we'll set another breakpoint in the program. Move the cursor to line 7 (the status line should now say LINE: 7) using the arrow keys. The cursor should now be positioned on the statement which says: PRINT "Sorting...". Set a breakpoint here: TYPE--> <F9> The source statement should now appear in reverse video. We used the shortcut key <F9> to set the breakpoint this time, but you could have opened the Run Menu, and selected the Breakpoint option and done the same thing. Let's remove the breakpoint: TYPE--> <F9> Line 7 should no longer be highlighted. The same command is used to turn breakpoints on or off for a source line. ASIC just checks to see if a breakpoint is already set at that source line when you select the breakpoint command. If one is set, it "toggles" it off (ie removes it), otherwise, it "toggles" it on (ie sets a breakpoint). This exercise was just to show you how to remove a breakpoint, let's go ahead and set it again: TYPE--> <F9> Line 7 should be highlighted again (the breakpoint is set). If might be nice to see what's in some of our program's variables, so let's "watch" some variables. Open the Run Menu, select the Watch command, and tell ASIC you want to watch variable "I". TYPE--> <Alt><r> <w> i<enter> Page - 23 ASIC should have opened a "Watch" window at the bottom of the screen. You should see the variable name "I" at the left, followed by a ":". Following the ":" is the current value of that variable. The number there now doesn't really mean anything, since our program is not running. But once the we start the program, this number should represent the actual value of the variable "I". Let's watch a few more variables: j, j1, and scores(1). This time, we'll use the shortcut key for the watch command: TYPE--> <F6> j<enter> Variable "J" should now be in the watch window. TYPE--> <F6> j1<enter> Variable "J1" should now be in the watch window. When we watch "scores", we'll also have to tell ASIC which element we want to watch by entering a subscript, since "scores" is an array. First ASIC will prompt you for the variable name. Type it, without the subscript. ASIC will prompt you for the numeric subscript. TYPE--> <F6> scores<enter> <1><enter> Scores(1) should now be in the watch window. Now we're ready to run the program again: TYPE--> <F5> Again we selected the short cut key, you could have selected the "Run your program" option from the "Run" Menu. The second line of the edit screen should show the PRINT "Sorting..." statement (highlighted in red, or underlined if you have a monochrome monitor). The variables in the watch window should have the following values: I: 11 J: 0 J1: 0 SCORES(1): 55 Let's execute the next statement by using the Trace command: TYPE--> <Alt><r> <t> ASIC has executed the PRINT "Sorting..." statement and has paused execution on the "FOR I" statement on line 8 of the program. Since the PRINT statement did not modify any variables, the numbers in the Page - 24 watch window should remain unchanged. Let's Trace one more statement, this time, we'll use the short cut key: TYPE--> <F8> ASIC has executed the "FOR I" statement on line 8, and is now paused on statement "FOR J" on line 9 of the program. Something looks wrong though. Even though we executed the first "FOR I" statement, the variable "I" still contains "11". It should contain "1". If you look at line 8, you'll see that the FOR statement was mistyped, it reads: "FOR I = I to 9", instead of "FOR I=1 to 9". Since the program also used variable "I" to READ the data into the array, "I" still contains the value "11". Since "11" is greater than the "TO" value of the "FOR" loop, the FOR loop on line 8 is executed only 1 time instead of 9 times. That's why the data is not being fully sorted. With the ASIC debugger, we can continue testing without recompiling, by modifying the value of "I" to "1", so we can see if the rest of our logic is correct. If changing "I" to "1" works, then we can go back and modify the "FOR" statement and recompile the program to correct the program permanently. Modify the value of "I" to "1": TYPE--> <Alt><r> <m> i<enter> <1><enter> The watch window should now show the value of "I" as 1. We can resume program execution at this point by selecting the "Run your program" option. We'll use the short cut key again: TYPE--> <F5> ASIC should pause the program at the next breakpoint, which is on line 20. This statement contains the "END" command. Now let's see if the program worked, by swapping to the user screen: TYPE--> <F4> Again, we used the short cut key. You should see the following on your screen: Original Scores: 55 33 877 99 44 101 21 88 105 1 Sorting... Here are the sorted scores: 1 21 33 44 55 88 99 101 105 877 It looks like the program worked. Let's return to the editor screen. TYPE--> <enter> Now we could press <F5> to resume execution and in this case terminate, since the END statement is the next one to execute. But let's look at another way to terminate a program. While at a Page - 25 breakpoint, you can select the "Abort your program" option, which instructs ASIC to terminate your program immediately, without executing any more of your program. Let's try it: TYPE--> <Alt><r> <a> ASIC should display the message "Program Terminated Normally (0)". At this point, we'll just exit from ASIC, but normally, you would fix the FOR statement using the editor, save the file, recompile the program, and retest it to make sure the "bug" is really fixed. TYPE--> <Alt><f> <x> You should be back at the DOS prompt now. That concludes the brief introduction to the ASIC debugger. The rest of this chapter provides some additional reference material for the debugger. Chapter 3 provides additional information about each of the debugging commands. DEBUGGER TIPS 1) WHEN YOU ARE DONE DEBUGGING YOUR PROGRAM, YOU SHOULD RECOMPILE WITH THE "DEBUGGING CODE" OPTION TURNED OFF. Although your program can run from the DOS command line with debugging code present, it will increase the program size and execution times. Recompiling with the "Debugging code" option off will insure your programs will be smaller and faster. 2) Remember that the default option on the command line compiler is "Debugging code" off. The default option in the integrated environment is "Debugging code" on. 3) Breakpoints/Watches are automatically cleared when you OPEN or COMPILE a file. 4) If you change source lines in a program while a program is running, without recompiling, source statements will not match executable code. Abort the running program and recompile after making code changes. 5) Breakpoints are set in the edit buffer relative to the beginning of the buffer. If you insert/delete lines in the buffer, the breakpoints will still be set at the same relative line number from the beginning of the buffer. 6) ASIC takes over the INT 3 Interrupt vector for debugging purposes. It re-installs the default vector when you exit ASIC. 7) You must compile with the "Debugging code" option to use source level debugging. Page - 26 8) If you wish to run a program from the beginning again while its already running, select the "Abort your program" option from the Run menu. Then, select the "Run your program" option. 9) If you select the Abort option from the Run menu, your program's files will NOT be closed gracefully. That is, data in the buffers will not be flushed to disk. 10) You may still run a program in the integrated environment that has been compiled without the Debugging code option. You just won't be able to use the debugging commands (eg, Breakpoints/Watches). 11) Toggling a breakpoint on/off will clear any block of text you had previously marked for editing (eg, MOVE, COPY). 12) When modifying array variables, make sure that the subscript you specify is valid. For example, if you "DIM A(10)", make sure the subscript you specify is in the range of 0 to 10. ASIC does not check the range of a subscript. If you specify a subscript that exceeds the valid range for that variable, your program may crash. 13) You can pass arguments to programs using the "Arguments" option on the Run Menu. You may retrieve these options in your program with the COMMAND$ statement. Using the "Arguments" option is equivalent to specifying arguments following the program name, when you run your program from the DOS command line. 14) The compiler allows variable names up to 80 characters in length. The debugger only uses the first 30 characters of a variable name. When the debugger finds two variables whose names are not unique within 30 characters, it will always select the first one it finds (this applies to the Watch/Unwatch/Modify Variables commands). 15) ASIC will allow you to set a breakpoint on a "FOR" statement. However, you should be aware that the source statement containing the "FOR" is executed only once (to initialize the loop). When the "NEXT" statement executes, control transfers back to the line following the "FOR", instead of the "FOR". For example, in the following code fragment: FOR I = 1 TO 3 <---Executes 1 time to initialize loop PRINT I <---Executes 3 times A=A+1 <---Executes 3 times NEXT I <---Executes 3 times, loops back to "PRINT I", not to "FOR I= 1 TO 3" Page - 27 A S I C Chapter 5 Compiler Options COMMAND LINE SYNTAX Invoke the command line version of the compiler as follows: ASICC filename option1 option2 option3 option4 option5 option6 Where: filename is the name of the source program to be compiled. This file must have the file extension ".ASI", although the extension may be omitted from the command line. optionN specifies any options desired. No options are required, but as many as six may be specified. COMPILER OPTIONS A total of six compiler switches are currently available for ASIC. Each is described in detail below: Switch Description C CONTINUE--ASIC will not pause after messages are issued, but will continue compiling. Default: ASIC will pause after each error message. Compilation will resume after you press a key. Page - 28 Switch Description L LIST ALL--ASIC will list each source line as it compiles it. Default: ASIC will list only source lines with compile errors. Comment: Use of this switch will slow compile speeds slightly due to the additional screen I/O. P PRINTLIST--ASIC will echo all messages which appear on the screen to the printer. Output to the printer will be paged with header lines identifying the program name, and the date/time compiled. Default: ASIC will not send any messages to the printer. Comments: Even though output to the printer is buffered, this option will slow compile speeds considerably. The compiler typically compiles only as fast as your printer can print the messages. An alternative to this switch is the DISKLIST option described below. D DISKLIST--ASIC will echo all screen messages to a disk file named "progname.LST". The format is the same produced by PRINTLIST. This allows you to compile at higher speed, and print the source listing later from the disk file via the DOS print spooler. Default: ASIC does not produce a ".LST" file. S SYMTAB----ASIC will produce a formatted Symbol Table in a file named "progname.SYM". The symbol table contains a list of all variables, labels, and internally created compiler addresses. Default: ASIC does not produce a ".SYM" file. Page - 29 X DEBUG-----ASIC will generate debugging code in the ".COM" file and a ".DBG" file for use by the integrated environment debugger. Default: ASIC does not generate debugging information. Comment: If you are running from the integrated environment, ASIC sets this option on by default. You may turn it off in the Compile menu, should you so desire. COMPILE EXAMPLES Example 1: Compile "MYFILE.ASI" with default compiler options: ASICC MYFILE Example 2: Compile "MYPROG.ASI", Listing all source lines, writing a compile listing to a disk file for printing later. The listing file will be called "MYPROG.LST": ASICC MYPROG L D Example 3: Compile "FILEX.ASI", don't pause for any errors, and print the errors on the printer: ASICC FILEX C P Page - 30 A S I C Chapter 6 Language Elements CHARACTER SET Symbol Description * Multiplication Example: A=B*C (multiply B by C, store result in A) / Division Example: A=B/C (divide B by C, store result in A) + Addition Example: A=B+C (add C to B, store result in A) + String Concatenation Example: A$="AB"+"C" (A$ will contain "ABC") = Assignment Example: A=1 (A will be assigned the value 1) = Equality testing Example: IF A=1 THEN QUIT: (If the value stored in (A equals 1 goto label QUIT) - Subtraction Example: A=B-C (Subtract C from B, store result in A) " String Delimiter Example: A$="the string is inside quote marks" () Parenthesis -- Ignored by ASIC Page - 31 Symbol Description ; Suppress Carriage Return/Line Feed with PRINT/LPRINT # Used to identify file usage with PRINT#/INPUT# , Comma, Ignored by ASIC $ Distinguishes a String Variable from an Integer. Example: ABC$ <---- string variable Example: ABC <---- integer variable : Distinguishes a Label from a variable name. Example: START: <---Label name Page - 32 CONSTANTS, VARIABLES, AND LABELS ASIC supports the following data types: Integer Constants, Integer Variables, single dimension Integer Arrays, String Constants, and String Variables. The following describes the restrictions for each data type. INTEGER CONSTANTS Range +32767 to -32767 Example: -26 INTEGER VARIABLE Described by a variable name beginning with a letter, followed by up to 79 additional letters or numbers. It may contain a number in the range +32767 to -32767. Example: VELOCITY1 INTEGER ARRAY Described by a variable name beginning with a letter, followed by up to 79 additional letters or numbers. This name is followed by an integer variable or constant for the dimension of the array. Arrays must be dimensioned at the beginning of the program. See the DIM statement. Example: GROWTH (YEAR) STRING CONSTANT A group of 0-80 characters enclosed by quotation marks. Example: "This is a String Constant" STRING VARIABLE Described by a variable name which begins with a letter, followed by up to 78 additional letters or numbers, terminated with a "$". Can contain 0-80 characters. Example: ADDRESS$ LABEL A Label is a location in your program you wish to transfer to. It must begin with a letter, and it may contain up to 78 additional letters or numbers. It must be terminated with a ":". Example: START: Page - 33 VARIABLES VS. CONSTANTS In general, ASIC will allow the use of either variables, arrays, or constants as operands to any program statement. For example: PRINT CASH PRINT 20 PRINT A(10) All three of the above examples are valid. The only case where a constant cannot be used, is where the value is being modified. For example: A = A + B <----VALID 17 = A + C <----INVALID Of course you must specify the correct data type for the ASIC keyword. For example: A = ABS("HELLO") <----INVALID This statement is invalid because you cannot take the absolute value of a string! There are a few ASIC statements which will accept only integer constants for some operands (DIM, OPEN, PRINT#, INPUT#). Refer to the individual statement for more information. Finally, there is a restriction on the use of subscripts for Arrays. A subscript for an array cannot be another array. For example: A(I(1)) <----INVALID A(I) <----VALID Page - 34 A S I C Chapter 7 Keyword Reference ABS Format: integer1 = ABS (integer2) Description: This function returns the absolute value of integer2 which is then stored in integer1. Example: A = ABS (-7) After execution of this statement, "A" will contain 7. ASC Format: integer1 = ASC (string1) Description: This function returns the ASCII value of the first character of string1, storing the result in integer1. Example: A = ASC("123") After execution of this statement "A" would contain 49, which the is ASCII value of "1". Page - 35 BLOAD Format: BLOAD string1, integer1, integer2 Description: This function loads data previously saved by BSAVE from a file to memory. String1 should be the name of the file previously created by BSAVE. Integer1 should be the memory offset to load the data to. Integer2 should be the number of bytes to read from the file. If DEFSEG has been set, it will be used as the data segment, otherwise, the default ASIC data segment will be used. Example: DEFSEG -18432 BLOAD "SAVED.DAT" 0 100 After execution of these statements 100 bytes will be read from the file "SAVED.DAT" and stored in memory start at 0 bytes from the start of the override data segment (which in this case happens to point to the beginning of video memory for a CGA card). Assuming a CGA card was present, the first 50 characters on the screen would contain data read from the file (don't forget that each screen character is represented by two bytes data and attribute, that's why only 50 characters will be displayed, assuming you are not in graphics mode). Comments: THIS FUNCTION IS RECOMMENDED ONLY FOR ADVANCED PROGRAMMERS. THIS STATEMENT WILL ALLOW YOU TO OVERLAY ANY AREA OF MEMORY, AND IT IS VERY EASY TO ACCIDENTALLY OVERLAY YOUR PROGRAM OR THE MEMORY USED BY DOS. If ASIC detects an error executing this command, it will set the system ERROR variable. These error codes are listed in the Error Messages Chapter. This statement is slightly different from GWBASIC/BASICA in that you must specify how many bytes to read from the file. Also, the memory offset is not stored in the file by BSAVE, so you must specify the offset as integer1 in ASIC. Offset is optional in GWBASIC/BASICA. See also: DEFSEG,BSAVE Page - 36 BSAVE Format: BSAVE string1, integer1, integer2 Description: This statement writes the block of memory beginning at offset integer1 from the start of the data segment for a length of integer2 bytes to the file specified by string1. This data may be later loaded by BLOAD. If DEFSEG has been set, it will be used as the data segment, otherwise, the default ASIC data segment will be used. Example: DEFSEG -18432 BSAVE "SAVED.DAT" 0 4000 After execution of these statements 4000 bytes at offset 0 bytes from the start of the override data segment (which in this case happens to point to the beginning of video memory for a CGA card) will be written to the file "SAVED.DAT". Assuming a CGA card was present, the current screen would be saved to disk, assuming you are not in graphics mode. Comments: If ASIC detects an error executing this command, it will set the system ERROR variable. These error codes are listed in the Error Messages Chapter. See also: DEFSEG,BLOAD Page - 37 CALL Format: CALL (string1,string2) Description: This function can be used to load and execute other programs compiled with ASIC or another compiler. String1 represents the name of the program to execute. String2 contains any arguments to be passed to the program (it may be NULL, ie ""). If an error occurs when ASIC attempts to call the program, it will set the system ERROR variable to 255. Otherwise, the ERROR variable will be set to the value of the return code of the called program (which is 0 unless the called program specifies otherwise). Example: CALL ("MYPROG.COM","") REM other code follows This statement would cause ASIC to load and execute the program "MYPROG.COM". No arguments will be passed to the program. When MYPROG terminates, the calling program will regain control on the line following the call, in this case the "REM" statement. Example 2: CALL ("COMMAND.COM"," /C WP.BAT") In this example, a ".BAT" type file is executed called "WP.BAT". To run ".BAT" files, it is necessary to load a copy of COMMAND.COM as shown above (COMMAND.COM contains the DOS code required to load and execute ".BAT" files). Using this format, you can also run some "built in" DOS commands such as DIR or SORT. Using CALL with this format, is similar to using the GWBASIC/BASICA SHELL command. Page - 38 CALL (Continued) Comments: String1 must contain the FULL pathname of the program (ie,"\directory\progname.COM") only if the program is NOT in the current directory. You must include the file extension on the file name (for example, use "MYPROG.COM" instead of just "MYPROG", or use "MYPROG.EXE" instead of "MYPROG"). If you wish to pass arguments to the program build it as follows: YOURPARM$ = "arguments" N = LEN(YOURPARM$) A$ = CHR$(N) A$ = A$ + YOURPARM$ B$ = CHR$(13) A$ = A$ + B$ CALL "progname" a$ The above creates an argument list according to the strict DOS calling rules, but so far, I have found that you can just create the arguments in a string, and precede them with a leading space. You might want to try this short cut first, and only resort to the full formal approach if you have problems with it: CALL "progname" " arguments" CAUTION: You may use the debugger with programs which contain "CALL" or "RUN" statements. However, the programs you call should not themselves contain debugging code. For example, if A.ASI calls B.ASI, then make sure you compile B.ASI with the "Debugging Code" option OFF before you try to debug program A.ASI. Failure to do so will cause the debugger to behave erratically. This also applies to programs you write using other compilers, since they also use the same interrupt that ASIC uses (INT 3) for debugging purposes. See also: RUN,COMMAND$ Page - 39 CHDIR Format: CHDIR string1 Description: This statement will change the current directory to that specified in string1. If an error occurs when ASIC executes this command, it will set the System ERROR variable. A list of possible error codes is listed in the Error Messages Chapter of this manual. Example: CHDIR "\DOS" IF ERROR = 0 THEN NOERROR: If Drive "C" was the current drive, then this statement would change the current directory to "C:\DOS". CHDIR "C:\DOS" This statement would change the current directory on drive C to "C:\DOS" whether or not drive C is the current drive. It would NOT change the default drive to "C". Note that DOS retains a current directory for each disk drive on your computer. See also: MKDIR, RMDIR Page - 40 CHR$ Format: string1 = CHR$(integer1) Description: This function converts an integer in the range of 0-255 to an ASCII character, and stores in string1. Example: A$ = CHR$(49) After execution of this statement, "A$" will contain "1", since "1" is represented by ASCII 49. Comments: If integer1 is outside the range 0-255, then the least significant byte of integer 1 is converted to string1. Page - 41 CLOSE Format: CLOSE integer1 Description: This function closes the file number identified by integer1. If an error is returned by DOS, the system variable "ERROR" will be > 0. Example: CLOSE 1 IF ERROR > 0 THEN CHECKERROR: After successful execution of the CLOSE statement, the file previously opened as file 1 will be closed. If an error is returned by DOS, the ERROR variable will be set by ASIC to a non-zero value. Comments: IF YOU FAIL TO CLOSE AN OPEN FILE (WHICH WAS OPENED FOR WRITING), YOU MAY LOSE DATA, SINCE FILE I/O IS BUFFERED, AND THE LAST BUFFER MAY NOT HAVE BEEN FLUSHED. Also, integer1 may only be a constant with the value of 1-3. See Also: OPEN,PRINT#,INPUT# CLS Format: CLS Description: This function clears the screen. Page - 42 CODE Format: CODE (integer1) Description: This function may be used to insert machine language code directly into your program. Integer1 should be in the range of 0-255. Example: CODE 205 CODE 5 These statements represent the machine code generated from the assembly language statement "INT 5". INT 5 is the BIOS routine which will print the screen to the printer. After execution of these statements in your program, the current screen contents would be printed on your printer. Comments: THIS STATEMENT IS INTENDED FOR ADVANCED PROGRAMMERS. THIS STATEMENT IS VERY POWERFUL, AND IF YOU DON'T UNDERSTAND MACHINE LANGUAGE YOU COULD EASILY CRASH YOUR PROGRAM. When you use this statement, be sure to save the contents of the following 8088 registers if you plan to modify them, and restore them before returning to ASIC. Otherwise the results may be unpredictable. Registers: DS/CS/ES/SS. Also, make sure you clean up the stack before you return (ie, if you push a value to the stack, make sure you pop it before you return to ASIC) Failure to do so, will almost certainly cause your program to crash. Page - 43 COLOR Format: COLOR integer1,integer2 Description: This function is used to set the foreground and background screen colors. The foreground color is specified in integer1, the background color in integer2. Valid Colors: Foreground Background ---------- ---------- Black 0 0 Blue 1 1 Green 2 2 Cyan 3 3 Red 4 4 Magenta 5 5 Brown 6 6 White 7 7 Dark Gray 8 Light Blue 9 Light Green 10 Light Cyan 11 Light Red 12 Light Magenta 13 Yellow 14 Bright White 15 Note: Colors 8-15 when specified for background color result in blinking text. Example: COLOR 4,8 After execution of this statement, future characters written to the screen will be Blinking Red on a Black Background. Page - 44 COMMAND$ Format: string1 = COMMAND$ Description: This statements retrieves any command line arguments that were entered and stores them in string1. Example: If your program was invoked with: MYPROG XXX And if your program MYPROG.ASI contained the following: A$=COMMAND$ PRINT A$ After execution of these statements, the screen would display " XXX". Comments: In the integrated environment, you can specify command line arguments on the "Run" Menu. This statement is an extension over BASICA/GWBASIC. Page - 45 COMSTAT Format: integer1 = COMSTAT (integer2) Description: This statement returns the status of a com port. Integer2 should contain "0" for COM1, or "1" for COM2. The status of that COM port is returned in integer1. Each bit in integer1 represents a different piece of information. These are described in the table below. Note that you may test if a bit is on/off using the ZBIT command. Example: PORTSTAT = COMSTAT (0) DATAREADY = ZBIT(8,PORTSTAT) IF DATAREADY = 1 THEN GORECEIVE: These statements do the following. The first retrieves the status of COM1 to the variable PORTSTAT. The second checks to see if bit 8 is on, DATAREADY will contain 1 if so, otherwise it will contain 0. Since Bit 8 is used to determine if data is waiting to be received from the port, if DATAREADY = 1 then the program will transfer to the label GORECEIVE: which would contain code to RECEIVE data from the port. Comments: Status Codes Returned by COMSTAT (Meaning when set to 1) Bit 0 Delta clear-to-send 1 Delta data-set-ready 2 Trailing-edge ring detector 3 Delta receive line signal detect 4 Clear-to-send 5 Data-set-ready 6 Ring Indicator 7 Received line signal detect 8 Data Ready 9 Overrun error 10 Parity error 11 Framing error 12 Break-detect error 13 Transfer holding register empty 14 Transfer shift-register empty 15 Time-out error See also: OPENCOM,SEND,RECEIVE Page - 46 CSRLIN Format: integer1 = CSRLIN Description: This function returns row of the cursor. Example: LOCATE 10,20 A = CSRLIN The locate command will have positioned the cursor in row 10, column 20. After execution of the CSRLIN statement, "A" will contain the value of 10. See also: POS Page - 47 DATA Format: DATA constant1[,constant2,...,constantn] Description: This statement is used store integer and string constants in memory for later retrieval by READ statements. At least one integer or string constant must be specified, although multiples of each type are permitted. Example: DATA 1,"APPLE",2,"ORANGES" READ A READ A$ READ B READ B$ The above statements are equivalent of entering the following code: A=1 A$="APPLE" B=2 B$="ORANGES" Comments: All DATA Statements must be placed at the beginning of the program, before all other statement types, except DIM statements. DIM statements, if specified, must precede all other statements including DATA statements. As long as you follow these rules, you may specify an unlimited number of DATA statements. GWBASIC/BASICA does not require quotes around string constants in some instances. ASIC always requires quotes around string constants. See also: READ,RESTORE Page - 48 DATE$ Format: string1 = DATE$ Description: This function returns the value of the system date in the format of "MM-DD-YYYY". Example: A$=DATE$ PRINT A$ After executing these statements, the date stored in the PC's System Clock will be displayed on the screen. Comments: Note: if the date printed is wrong, you have probably not set the system clock. Most older XT's and PC's do not have a battery to preserve the DATE and TIME in the system clock, so you have to set them each time you power up the PC. Most AT's and newer PC's have a battery backup, so that the date is preserved for you. Unlike GWBASIC/BASICA, you cannot set the system date with DATE$, however, you can set the system date from DOS by typing DATE. See also: TIME$, TIMER DEFSEG Format: DEFSEG = integer1 This function is used the alter the default data segment used when peeking and poking data with PEEK and POKE statements. DEFSEG, PEEK, and especially POKE are not recommended for beginners. If integer1 =-1, then the data segment address is set back to the ASIC default data segment address. See also: PEEK, POKE, BLOAD, BSAVE Page - 49 DIM Format: DIM variable(integer1) Description: This statement will create one dimensional arrays. An integer variable name must be specified in variable. Integer 1 contains the number of elements in the array. Example: DIM A(10) In this example an array of 10 integer variables is defined. Comments: On the DIM statement, integer1 may only be a constant. Also, DIM statements must appear before all other statement types in the program. END Format: END [(integer1)] Description: This statement causes your program to terminate and return to DOS, optionally setting a return code. Integer1 may be optionally specified to set the return code. If omitted, ASIC uses a return code of zero by default. Example: END In this example, the program will terminate and return to DOS with a return code of zero. END (20) In this example, the program will terminate and return to DOS with a return code of "20". Comments: The optional return code is an extension over GWBASIC/BASICA. Page - 50 FOR/NEXT Format: FOR integer1 = integer2 to integer3 NEXT integer1 Description: These two statements are used to create a loop, so that you can execute a portion of your program a certain number of times. All of the code between the FOR and the NEXT statement will be executed a certain number of times, but at least once. The actual number of times the loop executes is dependent on integer1/integer2/integer3. When the FOR statement is encountered in your program, integer1 is assigned the value of integer2. Then the statements up to the matching NEXT statement is executed one time. Then, 1 is added to integer1, and integer1 is compared to integer3. If integer1 is greater than integer3 then the control passes to the statement following NEXT. Otherwise, the program loops back up to the statement following the FOR statement. Example: FOR I = 1 TO 2 FOR J = 3 TO 5 PRINT I; PRINT J NEXT J NEXT I PRINT "AFTER THE LOOP"; PRINT I; PRINT J; Execution of this section of code would result in the following printout: 1 3 1 4 1 5 2 3 2 4 2 5 AFTER THE LOOP 3 6 Comments: Unlike BASICA/GWBASIC, ASIC FOR/NEXT loops execute at least 1 time. For example, the value "HELLO" will be printed in the following example. It wouldn't have been in BASICA/GWBASIC. FOR I = 1 TO 0 PRINT "HELLO" NEXT I Page - 51 FOR/NEXT (Continued) Unlike GWBASIC/BASICA, arrays may be used for integer1 and integer2. However, if integer3 is an array, element zero will be used, regardless of the subscript you specify. ASIC will allow you to modify the value of integer3, while GWBASIC/BASICA ignores changes. J=1 FOR I=1 TO J J=2 NEXT I The above loop will execute one time in GWBASIC/BASICA, but it will execute two times in ASIC. Page - 52 GOSUB Format: GOSUB label1 Description: This statement "calls" a subroutine called "label1". This subroutine must contain a "RETURN". After the subroutine is executed, control is returned to the next statement following the GOSUB. Example: GOSUB PRINTIT: PRINT "All Done!" END PRINTIT: PRINT "It" RETURN After execution of this code the screen would contain: It All Done! GOTO Format: GOTO label1 Description: This statement transfer program execution to the statement identified by label1. Example: GOTO SKIPIT: PRINT "YOU'LL NEVER GET HERE" SKIPIT: PRINT "ALL DONE!" After execution of this code, the screen will appear as follows: ALL DONE! Note that the first print statement never executes because of the GOTO. Page - 53 IF/THEN/ELSE Format: IF condition THEN label1 <--Format 1 IF condition THEN label1 ELSE label2 <--Format 2 Description: This statement is used to conditionally transfer to a different location in the program. If "condition" is true, control is transferred to label1. If "condition" is false, if label2 is specified, control transfers to label2, otherwise a false condition will cause the program to continue executing the statement following the IF statement. The operand "condition" is one of the following: integer1 > integer2 string1 > string2 integer1 = integer2 string1 = string2 integer1 < integer2 string1 < string2 Example: IF A > 0 THEN APLUS: In this example, if A is greater than zero, the program jumps to the label called "APLUS:". Example: IF A$="YES" THEN TRUE: ELSE FALSE: In this example, if A$ contains the string "YES", the program jumps to the label called "TRUE:", otherwise the program transfers to label "FALSE:" Page - 54 INKEY$ Format: string1 = INKEY$ Description: Used to retrieve keystrokes from the keyboard buffer. If a character is waiting in the buffer, string1 will be set to the value of that character, and that character will be removed from the keyboard buffer. If the buffer is empty, string1 will be set to a value of "" (that is, a null string with a length of 0). If an extended key is pressed (for example the function keys F1 through F10), the system variable EXTENDED will be set to 1 otherwise it will contain 0. Example: LOOP: X$=INKEY$ IF X$="" THEN LOOP: The above code will cause the program to loop until a key is pressed. Comment: ASIC provides an extension here over BASICA/GWBASIC. the EXTENDED system variable will allow you to detect special keys as mentioned above. To do so requires an understanding of keyboard scan codes, which is beyond the scope of this manual. For more information I would suggest Peter Norton's Programmer's Guide to the IBM PC (Microsoft Press). Page - 55 INP Format: integer1 = INP (integer2) Description: This statement reads a byte from port integer2 and stores the result in integer1. Example: A=INP(513) A=ZBIT(4,A) IF A=1 THEN TRIGGERPRESSED: The above code will test the joystick port to see if the trigger is being pressed on joystick 1. You need a game card and joystick for this to work. See also: OUT Page - 56 INPUT Format: INPUT variable1 Description: This statement will retrieve a line of text terminated from the input buffer and stores it in variable1. ASIC will first issue the prompt "?". It will then wait until the user enters a string or integer and presses the <return> or <enter> key. The type of data ASIC will expect is dependent on the type of variable1 (integer or string). If an integer is being entered, ASIC will edit the input for validity as an integer, and if the edit fails will issue another "?" to the user, and will wait for the number to be retyped. Only when a valid integer has been entered will variable1 be updated, and only then will control return to your ASIC program. Example: PRINT "Enter a String"; INPUT A$ ASIC will issue the prompt: Enter a String? It will then wait until you enter a string or press enter. If you pressed enter with no characters A$ would contain "" (ie its length would equal 0), otherwise A$ would contain the string entered. Example: INPUT I In this example ASIC will issue the prompt: ? ASIC will then wait for you to enter a valid number. If you enter an invalid number, say "x", ASIC will reissue the "?" prompt and wait for you to retype your input. Once the input has been edited by ASIC, "I" would contain the number entered. See Also: INKEY$ Page - 57 INPUT# Format: INPUT# integer1, variable1 [NONULL] Description: This statement will read a variable from a file identified by file number integer1. It will be stored in variable1. When reading ASCII strings from a file not created by ASIC, specify the NONULL option. This tells ASIC to not expect NULLs at then end of strings. (however, if ASIC finds a NULL, it will still consider this the end of that string). If an error occurs during a read, the system variable ERROR will be set to a non-zero value. The possible errors are listed in the error messages section of this manual. If you read a file past it's end, the contents of variable1 are undefined. Example: INPUT#1, A$ IF ERROR=99 THEN ENDOFFILE: In this example, a string will be read from file #1, and it will be stored in A$. The system ERROR variable is then checked to see if End of file was reached. Note, other ERRORS could also be returned by INPUT#, besides error code 99. Refer to the error messages section for more information. Comments: Note that integer1 must be a constant in the range of 1-3. It identifies a file by file number which must have previously been opened by an OPEN command. ASIC assumes that integers will be stored in files in 2-byte binary format, which is the format ASIC writes integers. Consequently, If a file contained a string "123", but you told ASIC to read integer "X", then ASIC would read two bytes from the file and interpret "12" as two binary bytes that it would then combine and store as "X". "X" would contain the integer value 12849. Thus to read an integer correctly, you will have had to previously written it with an ASIC program. See Also: OPEN, CLOSE, PRINT# Page - 58 KILL Format: KILL string1 Description: This statement is used to delete a file from disk. It is similar to the DOS ERASE Statement. Specify the file to delete in string1. You can specify the full path to the file, or just the file name if it is in the current directory. If an error occurs (eg, File not found), then ASIC will set the System ERROR variable. A list of codes returned by KILL is listed in the ERROR Messages Chapter of this manual. Example: KILL "TEMP.DAT" IF ERROR = 0 THEN NOERROR: REM CHECK ERROR CODES HERE After this statement is executed, the file "TEMP.DAT" will have been erased from the current directory of the current drive, and will no longer be accessible from DOS or your programs. LEN Format: integer1 = LEN (string1) Description: This statement returns the length (number of characters) of a string, and stores the length in integer1. Example: A$="abc" LENGTH1 = LEN(A$) After execution of these statements, LENGTH1 would contain 3. Page - 59 LOCATE Format: LOCATE row,column Description: This statement is used to position the cursor to a row and column. Row and Column should be integers. Row has the range 0-24, Column has the range 0-79. This function does not perform edits on the ranges of row and column. Consequently using this function with values outside these ranges will have unpredictable results. Example: LOCATE 10,20 PRINT "HELLO" After execution of these statements, the message "HELLO" will appear beginning at row 10, column 20. Page - 60 LPRINT Format: LPRINT printobject [;] Description: This statement is used to send the contents of printobject to an attached printer. "printobject" can be any valid ASIC datatype: integer constant, integer number, string constant, string variable, and also array elements. Optionally, a ";" can be included with this statement to suppress a carriage return/line feed which ASIC normally also sends to the printer following each LPRINT. This can be used to string several printobjects together on a single print line. Example: A=12345 LPRINT "The value of A is: "; LPRINT A After execution of these statements the printer would print: The value of A is: 12345 Comments: Note that if the printer is not "online" that DOS will issue a message to "Abort, Retry, or Ignore". This could overwrite a portion of the program display, unless not planned for. Note also, that some printers do not begin printing until they receive a carriage return/line feed sequence. Page - 61 MID$ Format: string1 = MID$(string2,integer1,integer2) Description: This statement is used to extract a substring from string2 beginning at position integer1 within string2 and continuing for integer2 bytes. This value is then stored in string1. Example: A$="THE QUICK BROWN FOX" B$=MID$(A$,1,4) C$=MID$(A$,11,9) D$=B$ + C$ After execution of these statements, the contents of A$ will be unchanged. The contents of B$ will be "THE ". The contents of C$ will be "BROWN FOX", and the contents of D$ will be "THE BROWN FOX". Page - 62 MKDIR Format: MKDIR string1 Description: This statement is used to create a new DOS directory. Specify the directory to create in string1. If ASIC is unable to create the directory, it will set the System ERROR variable. A list of ERROR codes may be found is the Error Messages Chapter of this manual. Example: MKDIR "WORK" IF ERROR = 0 THEN NOERROR: This code would create a directory called "WORK" under the current directory of the current drive. Example 2: MKDIR "C:\WORK" This code would create a directory called "WORK" under the root directory of drive "C". See also: CHDIR,RMDIR Page - 63 NAME Format: NAME string1 AS string2 Description: This statement will allow you to rename a file. String1 should contain the current file name, and string2 should contain the new name for the file. If ASIC is unable to rename the file, it will set the System ERROR variable. A list of ERROR codes is contained in the Error Messages Chapter of this Manual. Example: NAME "olddata.txt" AS "newdata.txt" IF ERROR = 0 THEN SUCCESS: After execution of these statements, file "olddata.txt" will have been renamed to "newdata.txt" Comments: You cannot rename a file to a new disk drive. Page - 64 OPEN Format: OPEN string1, integer1, string2 Description: This statement is used to open a file for input or output. Up to three files may be open concurrently, these are known as file 1, 2, or 3. You must specify with integer1 which file number you wish to open this file as. Integer1 may only be a constant. The file mode is specified in string1. The valid values are "I" for INPUT and "O" for OUTPUT. The file name is specified with string2. Any errors returned from DOS on the OPEN call will be returned in the system variable "ERROR". Example: A$="INFILE" OPEN "I",3,A$ IF ERROR > 0 THEN PROCESSERROR: OPEN "O",1,"A:\NEWFILE.DAT" IF ERROR > 0 THEN PROCESSERROR: In this example, two files are opened. File "INFILE" from the current disk drive and directory will be opened as file number 3 for input. The file "A:\NEWFILE.DAT" will be opened for output as file number 1. Note that if "A:\NEWFILE.DAT" previously existed, it contents will be destroyed in preparation for writing. Page - 65 OPENCOM Format: OPENCOM(integer1,integer2,integer3,integer4,integer5) Description: This statement is used to initialize the serial port. Integer1 is used to specify the baud rate. Integer2 specifies parity. Integer3 specifies stop bits. Integer4 specifies bytesize, and Integer5 identifies which port to open (see the tables below). OPENCOM does not check the validity of the values you give it. Example: OPENCOM(2,0,0,3,0) This statement would open COM1 at 300 baud, No parity, 1 Stop bit, 8 bit bytesize. Comments: The following tables provide appropriate values for each parameter required by OPENCOM. (integer1) (integer2) BAUD RATE PARITY ------+----------- ------+------------ VALUE | DESCRIPTION VALUE | DESCRIPTION 0 | 110 baud 0 | No Parity 1 | 150 baud 1 | Odd Parity 2 | 300 baud 3 | Even Parity 3 | 600 baud 4 | 1200 baud (integer3) 5 | 2400 baud STOP BITS 6 | 4800 baud ------+------------ 7 | 9600 baud VALUE | DESCRIPTION 0 | One Stop Bit 1 | Two Stop Bits (integer4) (integer5) BYTE SIZE COM PORT ------+------------ ------+------------ VALUE | DESCRIPTION VALUE | DESCRIPTION 2 | 7 Bits 0 | Com1 3 | 8 Bits 1 | Com2 See also: COMSTAT,RECEIVE,SEND Page - 66 OUT Format: OUT (integer1,integer2) Description: This statement writes a byte to a port. Integer1 should contain the port to write to. Integer2 should contain an integer value in the range of 0-255 to be written to the port. See also: INP PEEK Format: integer1 = PEEK (integer2) Description: This statement is used to examine actual memory location values directly. By default, the ASIC DS address is assumed. However, this may be overridden with the use of the DEFSEG command. The value of the byte at address integer2 is stored in integer1. See also: DEFSEG, POKE Page - 67 POINT Format: integer1 = POINT (integer2,integer3) Description: This statement is used to determine the color of a given pixel in medium and high resolution graphics modes. The row to test is specified with integer2, the column with integer3. The color of the pixel is stored in integer1. Example: PCOLOR = POINT (10,20) After execution of this statement, PCOLOR will contain the color of the pixel in row 10 column 20. Comments: No range checking is performed on row and column. If the specified row or column is outside the valid range for the given graphics mode, the results are unpredictable. See also: PSET, PRESET, SCREEN Page - 68 POKE Format: POKE integer1, integer2 Description: This instruction is used store the byte value integer2 at the memory address specified by integer1. By default, ASIC uses it's default data segment address, however, this may be overridden with the DEFSEG statement. Comments: This statement is NOT RECOMMENDED FOR BEGINNERS. Directly overwriting memory locations can be disastrous, unless you know what is stored at that address. This can cause program "hangs", system crashes, etc. See also: DEFSEG, PEEK POS Format: integer1 = POS (integer2) Description: This statement finds the column number of the cursor and stores it in integer1. integer2 is a dummy argument included only because a dummy argument is required in BASICA/GWBASIC. Example: A = POS(0) After this statement executes, A will contain the column number of the cursor. See also: CSRLIN Page - 69 PRESET Format: PRESET (integer1,integer2) Description: This statement is used to set the color of a pixel to the background color. The row of the pixel is specified in integer1, and the column is specified in integer2. This statement only works in medium and high resolution graphics modes. Example: PRESET (10,20) The pixel at row 10 column 20 would be set to the background color. See also: PSET, SCREEN, POINT Page - 70 PRINT Format: PRINT printobject1 [;] Description: This statement is used to print to the screen. Printing begins at the current cursor location. Printobject1 is defined as any valid ASIC data type: integer constant, integer variable, string constant, string variable, and arrays. The semicolon is optional and is used to tell ASIC if you want a carriage return/line feed issued. A semicolon at the end of a PRINT statement will suppress the carriage return/line feed ASIC normally issues. Example: A=1000 PRINT "A="; PRINT A PRINT "DONE!" After execution of these statements your screen would display: A= 1000 DONE! See also: COLOR, SCREEN, LOCATE Page - 71 PRINT# Format: PRINT# constant1, printobject1 [NONULL] Description: This statement is used to write integers and strings to disk. Constant1 identifies the file number that the file was opened as. This must be a constant with a value of 1, 2 or 3. The file must have been previously opened with the OPEN command. If printobject1 is a string, you can also add the optional argument "NONULL", which will cause ASIC to suppress the trailing NULL character it would normally write to disk. DOS errors are returned in the system variable "ERROR". A list of these error codes may be found in the error messages section of this manual. Also, refer to the technical details section of this manual for more information on the format in which ASIC writes the data to disk. Example: PRINT# 1, "HELLO" IF ERROR = 255 THEN DISKFULL: PRINT# 1, "WORLD" IF ERROR = 255 THEN DISKFULL: After successful execution of the print statements the file identified by file number 1 would contain "HELLO0WORLD0" . Note that the "0" following HELLO and WORLD in our example represents the ASCII null character. Strings in ASIC are always internally terminated with ASCII null characters. By default, these nulls are also written to disk. PRINT# 2, "HELLO" NONULL In this example, the string "HELLO" would be written to file #2, and no trailing NULL will be written to disk. PRINT #3, 1234 In this example, the number "1234" would be written to file #3 as two bytes in Intel binary format (the file would contain the two hexadecimal bytes: D2 04). Page - 72 PRINT# (Continued) Comments: Note that while ASIC doesn't generate carriage returns and line feeds for you as it does with the PRINT command, you can write these characters to disk as follows: A$=CHR$(13) B$=CHR$(11) A$ = A$ + B$ PRINT #1, A$ You might be wondering what the purpose of the new NONULL option is. ASIC 1.0 always wrote trailing NULL's with strings. This was necessary, since when ASIC read a string from a file, it assumed that it would be terminated by a NULL. In general, if you are writing a file to be read by an ASIC program, you should not specify the NONULL option. In this way, ASIC will be able to correctly read the string. However, sometimes you may want to write a string for use by another program. In this case, the NULL character sometimes confuses the other program. Specifying the NONULL option will cause ASIC to suppress the offending NULL character. What happens if you read a string that is terminated by a Carriage Return/Line Feed Sequence (such as GWBASIC/BASICA produces)? In this instance, specify the NONULL option on the INPUT# statement. Then ASIC will read the string until it finds a NULL or until it reads 80 characters, whichever comes first. You can find the true end of the string after you INPUT# it, by using the MID$ command to find the Carriage Return character (ASCII value 13). See also: OPEN, CLOSE, INPUT# Page - 73 PSET Format: PSET (integer1,integer2),integer3 Description: This statement is used to set a pixel to a specified color in medium and high resolution graphics modes. The row is specified in integer1, the column in integer2, and the color in integer3. Note that no range checking is performed on integer1 or integer2. A row or column specified outside the range allowed by the graphics mode in use can result in unpredictable results. Example: PSET (10,20),1 In this example the pixel defined at row 10 and column 20 will be set to color 1. See also: PRESET, SCREEN, POINT RANDOMIZE Format: RANDOMIZE Description: This statement will cause the seed for the random number generator to be reseeded using the system timer. This statement should always precede the first RND statement in your program, unless you want the same sequence of random numbers generated. See also: RND Page - 74 READ Format: READ variable1 Description: This statement reads a constant from DATA statements into a variable. Variable1 is either a string or integer type variable. Example: DATA 7,"CARGO" READ A READ B$ After execution of these statements, "A" will contain 7, and B$ will contain "CARGO". Comments: ASIC does not check to see that the data type on the READ statement matches the data type on the DATA statement. It is up to the programmer to insure that the types match. The above example is correct. The DATA statement contains an integer, then a string. This is the same sequence in which the DATA is READ (ie, integer, then string). In the above example, if the read statements were reversed, the contents of A and B$ are undefined. Also note that ASIC does not check to see that you don't read past the end of the DATA you specified. In the above example, if you had a third READ statement that contained "READ C$", then C$ would contain random garbage, since you read three values, but only provided data for two. See also: DATA,RESTORE Page - 75 RECEIVE Format: variable1 = RECEIVE(integer2) Description: This statement will read a byte from the specified serial port. Integer2 identifies which port to read (0=COM1, and 1=COM2). The byte read is stored in variable1 (which may be an integer or string type variable). Before executing this statement you should first check to see if there is data waiting to be read. Executing this statement when data is not waiting can cause your PC to "hang" until data is received at the hardware serial port. The example below illustrates how to determine if data is waiting to be received. Example: OPENCOM(2,0,0,3,0) PORTSTAT = COMSTAT(0) DATAREADY = ZBIT(8,PORTSTAT) IF DATAREADY = 0 THEN NODATAWAITING: A$=RECEIVE(0) These statements do the following. The first retrieves the status of COM1 to the variable PORTSTAT. The second checks to see if bit 8 is on, DATAREADY will contain 1 if so, otherwise it will contain 0. Since Bit 8 is used to determine if data is waiting to be received from the port, if DATAREADY NOT = 0 then the program will RECEIVE data from the port to variable "A$". Comments: Variable1 can be either a string or integer type variable. However, if variable1 is a string, bear in mind that you cannot directly receive a NULL (ASCII Code 0), since NULL is used to delimit the end of a string in ASIC. However, if in the above example data was waiting at the port but A$ contained "" after the receive, you would know that the character received was a NULL. This is not a problem if variable1 is an integer variable. See also: OPENCOM,SEND,COMSTAT Page - 76 REM Format: REM free form comments Description: This statement is used to insert comments into your program. Everything following REM is treated by ASIC as a comment. RESTORE Format: RESTORE Description: This statement allows you to READ data from DATA statements after you have already READ it once. Example: DATA 0 READ A RESTORE READ B In this example, "READ A" causes variable "A" to be set to 0. Now, the DATA statement is "used up". There is no more data left on it to be read. The RESTORE resets the DATA so that the next statement "READ B" will result in "B" being set to 0. If the RESTORE was not done, the contents of B would be undefined. See also: READ, DATA Page - 77 RETURN Format: RETURN Description: Used to return from a GOSUB call. Comments: Executing a RETURN statement without having first executed a GOSUB statement could cause unpredictable results. See also: GOSUB RMDIR Format: RMDIR string1 Description: This statement will delete an empty directory from disk. String1 should contain the name of the directory to delete. If ASIC is unable to delete the directory, it will set the System ERROR variable. A list of ERROR codes is listed in the Error Messages Chapter. Example: RMDIR "C:\WORK\TEST" IF ERROR = 0 THEN SUCCESS: After execution of this code, the directory TEST under directory WORK will be deleted (if it had no files or subdirectories in it, and if it is not the current directory for drive "C"). See also: MKDIR,CHDIR Page - 78 RND Format: integer1 = RND (integer2) Description: This statement will return an integer number in the range of 0 through 32767 and store it in integer1. Integer2 is a dummy argument and can be any valid integer value. Example: A = RND(0) After execution of this statement "A" will contain a number between 0 and 32767 inclusive. Comments: In BASICA/GWBASIC, RND always returns a value between 1 and 0, however, since ASIC only operates with integer values, having the random number function only return two values seemed ridiculous. Page - 79 RUN Format: RUN string1 Description: This function can be used to load and execute other programs compiled with ASIC or another compiler. String1 represents the name of the program to execute. If an error occurs when ASIC attempts to RUN the program, it will set the system ERROR variable to 255. Otherwise, the ERROR variable will be set to the value of the return code of the called program (which is 0 unless the called program specifies otherwise). Example: RUN "OTHER.COM" Comments: String1 must contain the FULL pathname of the program (ie,"\directory\progname.COM") only if the program is NOT in the current directory. You must include the file extension on the file name (for example, use "MYPROG.COM" instead of just "MYPROG", or use "MYPROG.EXE" instead of "MYPROG"). At this time, RUN and CALL are functionally equivalent, with one exception. RUN does not accept program arguments, but CALL does. CAUTION: You may use the debugger with programs which contain "CALL" or "RUN" statements. However, the programs you call should not themselves contain debugging code. For example, if A.ASI calls B.ASI, then make sure you compile B.ASI with the "Debugging Code" option OFF before you try to debug program A.ASI. Failure to do so will cause the debugger to behave erratically. This also applies to programs you write using other compilers, since they also use the same interrupt that ASIC uses (INT 3) for debugging purposes. See also: CALL Page - 80 SCREEN Format: SCREEN integer1 Description: This statement will transfer the computer from text mode to medium and high resolution graphics modes. integer1 must be an integer constant with a value of 0,1 or 2. Screen mode 0 is 25 lines by 80 columns text with 16 colors. Screen mode 1 is medium resolution graphics mode with 25 lines by 40 columns text, or 200 rows by 320 columns of pixels with four colors. Screen mode 2 is high resolution graphics mode with 25 lines by 80 columns of text, or 200 rows by 640 columns of pixels with two colors (black and white). Example: SCREEN 1 After execution of this statement, the screen will be in medium resolution graphics mode. Comments: Any program which uses the two graphics modes (1 and 2) should issue a "SCREEN 0" command before terminating. Otherwise, the screen will be left in 25x40 character graphics mode which is very irritating under DOS. See also: PSET, PRESET, POINT Page - 81 SEND Format: SEND (data1,integer2) Description: This statement is used to send one character to a serial port. The port should initialized with OPENCOM prior to using this statement. Data1 may be any valid data type (integer or string, variable or constant) and it should contain the character to be sent to the port. Integer2 identifies which COM port to send to (0=COM1, 1=COM2). Example: OPENCOM(2,0,0,3,0) SEND ("X",0) The above code will open COM1 at 300baud, 1 stop bit, 8bit character size, with no parity. It will then send the character "X" to COM1. See also: RECEIVE,COMSTAT,OPENCOM Page - 82 SOUND Format: SOUND integer1,integer2 Description: This statement will generate a sound on your computer speaker with a frequency of integer1, and a duration of integer2. Frequency should be in the range of 0 to 32767. ASIC, however, only checks to see that it is non-negative. Example: SOUND 400,20 Execution of the above statement will produce a short beep. Comments: ASIC "frequencies" values go from high to low. That is, a frequency of 0 is the highest, and 32767 is the lowest. STR$ Format: string1 = STR$ (integer1) Description: This statement will convert integer1 to a string format and store the string format in string1. Example: A=1234 A$ = STR$(A) After execution of these statements, A$ would contain the string "1234". See also: VAL Page - 83 TIME$ Format: string1 = TIME$ Description: This statement will retrieve the current time from the PC's system clock. The time will be retrieved and stored in String1, in the format: "HH.MM.SS". Example: CURTIME$=TIME$ PRINT CURTIME$ After execution of the above statements the current time (as per the PC's internal clock) will be displayed on the screen. Comments: Note: if the time printed is wrong, you have probably not set the system clock. Most older XT's and PC's do not have a battery to preserve the DATE and TIME in the system clock, so you have to set them each time you power up the PC. Most AT's and newer PC's have a battery backup, so that the date is preserved for you. Unlike GWBASIC/BASICA, you cannot set the system time with TIME$, however, you can set the system time from DOS by typing TIME. See also: DATE$, TIMER Page - 84 TIMER Format: integer1 = TIMER Description: This statement will retrieve a timer count from the PC's hardware circuitry. The timer count will be placed in integer1. The timer count is in "clock ticks". A "clock tick" occurs in the PC approximately 18.2 times per second. The PC is continually incrementing this clock counter. This statement can be used to time the duration of events up to a few minutes long. Example: CLS PRINT "PRESS A KEY" STARTCNT=TIMER LOOP:X$=INKEY$ IF X$="" THEN LOOP: ENDCNT=TIMER ELAPSED=ENDCNT-STARTCNT ELAPSED=ABS(ELAPSED) ELAPSED=ELAPSED/18 PRINT "IT TOOK YOU APPROXIMATELY"; PRINT ELAPSED PRINT " SECONDS TO PRESS A KEY" The above code fragment will time how long you wait to press a key in seconds. You could modify it easily to display in clock ticks, which would provide much more accuracy, if you deleted the statement which divides the ELAPSED count by 18. Comments: Note that it is necessary to use the absolute value of ELAPSED since the clock counts in the following sequence 0-32767, -32768 to -1, and then back to 0. This is because internally the PC is treating the clock count as an unsigned 16 bit field, but ASIC integers are 2's complement signed 16 bit integers. See also: DATE$,TIME$ Page - 85 VAL Format: integer1 = VAL (string1) Description: This statement will attempt to convert string1 into an integer value, and it will store the result in integer1. Example: A$ = "12345" A = VAL (A$) After execution of these statements, variable "A" would contain the value 12345. See also: STR$ VARPTR Format: integer1 = VARPTR (variable1) Description: This statement will return the address of a variable variable1 and store it in integer1. This may be used to peek and poke values directly into a variable. Example: A$ = "XYZ" B = VARPTR(A$) C = PEEK (B) PRINT C After execution of these statements the screen would display the number 88 which is the number for the ASCII character "X". See also: PEEK, POKE Page - 86 WIDTH Format: WIDTH integer1 Description: This statement will set the screen to 40 column text or 80 column text mode only. The only two valid values for integer1 are thus 40 and 80. In ASIC, WIDTH 80 is equivalent to executing SCREEN 0. Also, WIDTH 40 is equivalent to executing SCREEN 1. If you use WIDTH 40, you should always reset the screen back to WIDTH 80 before terminating your program with END. Otherwise, your PC will be left in 40 column mode. ZBIT Format: integer1 = ZBIT(integer2,integer3) Description: This statement is used to determine if a single "bit" in an integer variable is set to "1". Integer2 represents the bit to be tested. It should be in the range 0 to 15. Integer3 represents the integer variable or constant to be tested. The result of the test is returned to integer1. If the bit was set, integer1 will be set to "1", otherwise, integer1 will be set to "0". Example: GAMEPORT = INP(513) TRIGGER = ZBIT(4,GAMEPORT) IF TRIGGER = 1 THEN TRIGGERPRESSED: In this example, the joystick port is read, and it's status is placed in the variable "GAMEPORT". The bit which represents the trigger for joystick 1 is then tested using ZBIT. If the trigger bit is set, then the program would transfer to the label "TRIGGERPRESSED:". Note that the above code assumes that a game card is present in the computer. Comments: This statement is an extension over GWBASIC/BASICA, although it is possible to perform similar tests in GWBASIC/BASICA with the boolean AND statement. Page - 87 ZMODE Format: integer = ZMODE Description: This command returns a code which indicates whether a color or monochrome card is active in the system. ZMODE returns a value of 1 when a color card is detected, and a value of 0 for monochrome. Example: A = ZMODE IF A = 1 THEN CONTINUE: PRINT "This program requires a Color Card to Run" END CONTINUE: REM rest of code follows here The above code fragment will check for a color card, if not found the program will terminate with an appropriate message. Otherwise the program will continue. Comments: This statement is an extension over BASICA/GWBASIC. Page - 88 A S I C Chapter 8 Compatibility with GWBASIC/BASICA In general, although ASIC does not support all options on every BASIC statement, those it does support work like they do in BASICA/GWBASIC. The known exceptions are listed in this chapter. INKEY$ This statement is compatible, however ASIC does provide an extension over GWBASIC/BASICA. If an extended key is pressed (e.g. F1-F10), ASIC returns the scan code for the extended key, and sets a special system variable "EXTENDED" to a value of 1. For non-extended keys, the "EXTENDED" variable will contain 0. FILE HANDLING ASIC provides no EOF statement or ON ERROR statements. Instead, ASIC sets a special system variable when an error occurs during file I/O. This special variable is called "ERROR" and it is set after every file I/O statement (OPEN/INPUT#/PRINT#/CLOSE, etc) to either 0 to indicate no errors, or a non-zero value. If a non-zero value is present, an error has occurred. The specific errors are identified in chapter 10. FILE FORMAT ASIC Files are written with 2 bytes per integer in binary format, instead of string format as in BASICA/GWBASIC. Strings are written as a sequence of ASCII characters terminated by an ASCII null, or optionally with no NULL terminator. Page - 89 PUNCTUATION ASIC permits use of punctuation that it does not require to allow you to enter statements in their familiar GWBASIC/BASICA Formats. For example: A = ABS (B(1)) This statement is valid in both ASIC and in GWBASIC/BASICA. However, ASIC ignores the parenthesis and comma. Thus ASIC will actually accept the following formats as alternatives to the above: A = ABS B 1 A = ABS B 1,,,,,,))))) FOR/NEXT FOR/NEXT loops always fall through the body of the FOR at least one time in ASIC. This does not happen in BASICA/GWBASIC. For more information on this, refer to Chapter 7. RND RND (N) returns a value from 0-32767 inclusive instead of 0 to 1 as in BASICA/GWBASIC. LOCATE/CSRLIN/POS Coordinates are specified in range 0-24 and 0-79 instead of 1-25 and 1-80. PSET/PRESET/POINT Coordinates are specified in row/column order instead of column/row order. ZMODE ZMODE is an extension over BASICA/GWBASIC. It returns a code which the program can check to determine if the PC contains a color or monochrome display adapter card. COMMAND$ COMMAND$ is an extension over BASICA/GWBASIC. It returns the command line arguments. Page - 90 BLOAD/BSAVE File formats are not compatible with GWBASIC/BASICA. BLOAD requires offset and the number of bytes to read. OPENCOM/COMSTAT/SEND/RECEIVE These statements provide serial port support in ASIC. In GWBASIC/BASICA this is provided by OPEN/INPUT#/PRINT#. DATE$/TIME$ ASIC allows you to retrieve the system date and time, but will not allow you to set new system date/time values. CALL/RUN These statements perform functions similar to their GWBASIC/BASICA counterparts, but function differently. Refer to the keyword reference for the appropriate keyword for details on their operation. TIMER Since ASIC only supports integer variables, only the lowest 16 bits of the system clock timer is returned. This is in clock ticks. There are approximately 18.2 clock ticks per second. ZBIT This is an extension over BASICA/GWBASIC. It has similarities to the logical AND in GWBASIC/BASICA. Page - 91 A S I C Chapter 9 Technical Details/Tips This chapter contains technical information and tips regarding ASIC. COMPILER LIMITS Maximum Source Program Size: Unlimited - Command Line 809 Lines - Integrated Environment Maximum Object Program Size: 64k bytes (.COM Format restriction) Maximum Source Line Length 128 bytes - Command Line 80 bytes - Integrated Environment Compiler Symbol Table Size: 750+ Symbols Maximum Number of Arrays: 25 FOR/NEXT Nesting Depth 25 Compiler Memory Requirements 300k - Command Line 400k - Integrated Environment COMPILER OPERATION ASIC is a single pass compiler written entirely in C (Borland Turbo C Version 2.0). Each source statement is translated directly into machine code. ASIC compiles 100% in memory for maximum speed. The compiler does not require any disk work space. ASIC generates a minimum of error checking code. This is because the ASIC philosophy stresses execution speed. This does place greater responsibility on the programmer to check for out of bounds conditions, etc.. Page - 92 DEBUGGER LIMITS Maximum Concurrent Breakpoints 20 Maximum Concurrent Watches 10 Maximum Symbol Length 30 Characters Maximum Symbols Same as Compiler Maximum Source Statements 809 Lines DEBUGGER OPERATION When you select the "Debugging code" compiler option, the ASIC compiler inserts additional machine language instructions into your program. It inserts a single statement at the beginning of your program (specifically, INT 3) which allows it to gain control. When the ASIC editor is loaded, it saves the existing INT 3 vector, and installs the ASIC Debugger as INT 3. In this way, when your program begins executing, the INT 3 statement that ASIC inserted in your program causes a transfer of control to the debugger. Once the debugger gains control, it can set or remove additional breakpoints as needed in your program, plus provide access to the video memory and variable memory locations with the Swap, Watch, Unwatch, and Modify Commands. When you exit the ASIC editor, ASIC deinstalls the debugger from INT 3, and restores the original interrupt 3 vector. The compiler also creates a file with a ".DBG" extension which contains the symbolic information needed by the debugger (ie, variable names and offsets, and source statement offsets). DEBUGGER OVERHEAD Running a program in debugging mode adds a small amount of overhead to your program (both compiled code size, and execution speed). Specifically, the size of the debugging code will be (approximately): CodeSizeIncrease = 1 + LinesOfSourceCode Note that the actual increase will usually be less than the above, since DIM, DATA, REM, and blank source lines do not require debugging code. The reduction in execution speed is very slight in most cases (for you assembly language programmers out there, a single NOP instruction is executed for each source line). Page - 93 STORAGE FORMATS Integers are stored in ASIC as two bytes, with the low order byte appearing first (as per Intel conventions). String variables are stored as FIXED 80 character strings terminated by an ASCII null character for a total length of 81 characters. String constants are stored with 1 byte per character in the string followed by a terminating ASCII null character. Each element in an array requires two bytes. (Don't forget arrays have an element zero (ie DIM A(2) is comprised of A(0), A(1), and A(2)). Examples: Item Data Type Storage Requirements A Integer Variable 2 bytes 17 Integer Constant 2 bytes A$ String Variable 81 bytes "ABC" String Constant 4 bytes "A" String Constant 2 bytes DIM A(10) Integer Array 22 bytes DIM A(1) Integer Array 4 bytes As you can see, string variables are expensive in terms of storage space. Since string constants are stored at actual length +1, It is MUCH more efficient to store short strings as constants in ASIC in terms of storage space. There is no performance advantage to constants over variables, however. In disk files, strings and integers are written out in the above formats. Note that unlike GWBASIC/BASICA, integers are NOT expanded into strings when written, and conversely, not converted from strings to integers when read. String variables and constants are written out as ASCII strings terminated by a null character (however, the null can be suppressed). Thus, string variables when written to disk, take the same space byte for byte as string constants. The reason behind fixed length string variables was avoidance of string "garbage collection". In addition to slight performance advantages, there is the added benefit of providing a string memory address which never changes. Thus once VARPTR retrieves the address of a variable, you never have to worry about it changing. Page - 94 MEMORY MAP The following describes the structure of the ".COM" file created by ASIC. All addresses are in Hexadecimal. Description Address Range ------------------------------ ------------- Program Segment Prefix (PSP) 0000 - 00FF (Created/Required by DOS) Transfer to Program Code 0100 - 0102 String Conversion Buffer 0103 - 0109 Input Buffer 010A - 015B Screen Width 015C Color/Attribute Byte 015D Screen Graphics Mode 015E Cursor Position 015F - 0160 File Control Table 0161 - 0169 ERROR System Variable 016A - 016B System Subroutine Vectors 016C - 017F EXTENDED System Variable 0180 - 0181 RND Seed 0182 - 0185 Math Work Area 0186 - 018D DEFSEG System Variable 018E - 018F Start DATA Block Pointer 0190 - 0191 Current DATA Block Pointer 0192 - 0193 Reserved for future use 0194 - 0195 System Subroutines 0196+ | | v Data Segment Address Varies | | | v Code Segment Address Varies | | | v ^ | | Program Stack (builds downward) FFFF Page - 95 A S I C Chapter 10 Error Messages This chapter contains compiler messages, run-time error messages, and File I/O Error Codes. COMPILER ERRORS These messages indicate errors in your source program. Those which begin with "** E" indicate "fatal" errors, which prevent ASIC from successfully compiling your program. Warnings begin with "* W" and indicate possible errors and informative messages which will not prevent ASIC from generating an executable ".COM" file. ** E001 ** File Extensions must be either ".ASI" or omitted ASIC requires source programs to have the extension ".ASI". Rename your source file with the DOS "RENAME" command to the name "file.ASI", where "file" is your source program name. Then resubmit the compile. ** E002 ** File Name specified is too long The source file may be identified by a file name up to 124 characters long including disk drive specifiers and sub directory names. Move the source program to a directory which may be specified within this length. Page - 96 ** E003 ** Error Opening File: xxxxxxxx.xxx The file indicated by "xxxxxxxx.xxx" could not be opened by ASIC. This error can be issued when ASIC attempts to read your source file, or when it writes any one of the possible output files (".COM", ".LST", or ".SYM"). If indicated file is your source program name, verify the spelling, and either make sure it is in the same directory as ASIC, or specify the full path name for the file. If the indicated file is an output file, the error is usually a result of a write protect tab on the diskette or insufficient disk space. ** E004 ** DIM Statements must precede all others In ASIC, DIM statements must appear before all other statement types, including REMarks. Move all of your DIM statements to the very beginning of your source file. ** E005 ** Too many characters in source line Source program lines in ASIC are limited to 120 characters. Change the indicated source line, so that it fits within this limit. ** E006 ** Unmatched Quote ('"') in source line A string constant was found with either no opening or closing quote mark. Quotation marks must be matched in pairs within source lines. ** E007 ** Token in source line > 82 characters long Individual tokens in ASIC are limited to 82 characters in length, regardless of type. A token is a group of letters and/or numbers delimited on either side by a space or math symbol. Example, even though string constants are limited to 80 characters, ASIC considers the "token" to include the quotation marks. In this case, however, ASIC detected a token longer than the longest possible token, the string constant. Check for "tokens" or "words" more than 82 characters long in the indicated source line. Page - 97 ** E008 ** More than 30 tokens in source line Since all ASIC statements require less than 30 tokens, ASIC will flag any statement which contains more than this number. A token is a group of letters and/or numbers delimited on either side by a space or math symbol. ** E009 ** Keyword Unknown: xxxxxxxxx ASIC detected the symbol indicated by "xxxxxxxx" in your source line, but it was not a valid variable name, constant, label, or ASIC Function Name. ** E010 ** Symbol Table Space Exhausted The symbol table is used by ASIC to keep track of your variables, constants and labels. It is also used to hold information used in FOR/NEXT processing, and internal system subroutine generation. Reduce the number of LABELS, VARIABLE NAMES, or CONSTANTS in your program, and recompile. ** E011 ** Symbol Incomplete Reference Space Exhausted This table is a sister table to the Symbol Table, it contains references to LABEL type symbols which have been defined in the symbol table. Try to reduce the number of references made to LABEL symbols within the program and recompile. ** E012 ** No keywords in source line Every ASIC source program line must contain an ASIC keyword (eg. "PRINT", "=", "GOSUB", etc). ** E013 ** Syntax Error The "catch-all" error for ASIC. This error is usually issued when ASIC has identified an error in the parameters for an ASIC keyword. The best way to find this error is to refer to the entry in the Keyword Reference (chapter 7) for that particular keyword. Page - 98 ** E014 ** Undefined Symbol: xxxxxx ASIC detected a LABEL "xxxxxx" which was referenced, but never defined in the program. A label is considered to be defined when it is the first token on the source line. A reference to a label occurs when a label name appears elsewhere in the source statement Example: PRINTIT: PRINT "hello" <---Defined GOTO PRINTIT: <--Referenced ** E015 ** Compiled Code Exceeds 64k-Can't fit in .COM file Your source program is too large to fit in the .COM file format. Eliminate extraneous variables and program statements. Note: REM statements do NOT generate any output code, so elimination of REM statements will not alleviate this problem. ** E016 ** Integer Constant Not in range +32767 to -32767 The above range of numbers is the maximum which can be contained in integer format in ASIC. Reduce the constant so that it falls within the specified range. ** E017 ** Duplicate Label: xxxxxx The indicated label "xxxxxx" was defined more than once in the program. Reduce the multiple definitions to a single definition and then recompile. ** E018 ** Second FOR defined for variable with no intervening NEXT FOR/NEXT Statements cannot be nested with the same variable name. VALID INVALID FOR I=1 TO 10 FOR I=1 TO 10 FOR J=1 TO 20 FOR I=1 TO 20 NEXT J NEXT I NEXT I NEXT I Page - 99 ** E019 ** For/Next Table Space Exhausted An unlimited of FOR/NEXT statements can exist, however, they can be "nested" to a maximum depth of 25. ** E020 ** NEXT without FOR A NEXT statement was found, however it was not preceded in the source program with a matching FOR statement. ** E021 ** FOR without NEXT at Source Line NNNNN The indicated source line NNNNN contains a FOR statement, for which no NEXT statement was ever found. ** E022 ** Invalid Option: x An invalid compile option was specified. Review Chapter 5 for a list of valid compile options. ** E023 ** More than 63000 bytes in Data Segment An ASIC program can be up to 64k bytes in size. Of this total, 63000 bytes can contain program variables and constants, leaving at least 1k for program code. Reduce the number of variables and constants in your program. ** E024 ** Too many arrays defined A single ASIC source program can contain up to 25 arrays. ** E025 ** Re-DIMension of previously DIMensioned variable Only one DIM statement can be specified per array name. Page - 100 ** E026 ** Invalid subscript on Array A subscript was found which is not valid. Either ASIC expected more or less subscripts than were present, or ASIC detected a subscript which was itself an array. Subscripts on arrays may only be non-array variables and/or integer constants. ** E027 ** String Arrays Are Not Supported A DIM statement specified a string variable type. Only integer arrays are supported. ** E028 ** Comfile Buffer - Memory Allocation Failed ASIC attempted to allocate memory for an internal buffer . This memory allocation failed. More memory is required. If you have any TSR's loaded in memory, remove them and try again. ** E029 ** Codeseg Buffer - Memory Allocation Failed. ASIC attempted to allocate memory for an internal buffer. This memory allocation failed. More memory is required. If you have any TSR's are loaded in memory, remove them and try again. ** E030 ** Code Segment Memory Exhausted ASIC will attempt to allocate 64k of memory to use a work space to hold the code generated by your program statements. This message indicates that the amount of memory it was able to allocate was not sufficient to hold the code generated by the program you are trying to compile. ** E031 ** Data Segment Memory Exhausted ASIC will attempt to allocate 64k of memory to use a work space to hold the data segment for your program. This message indicates that the amount of memory it was able to allocate was not sufficient to hold the data generated by the program you are trying to compile. Page - 101 ** E032 ** Insufficient Memory to Run ASIC You don't have enough memory to run ASIC. If you have any TSR's loaded, try removing them and re-compiling. ** E033 ** Edit Buffer Memory Allocation Failed ASIC attempted to allocate memory for the edit buffer in the integrated environment, but was unable to. If you have any TSR's loaded, remove them from memory, and try again. ** E034 ** DATA Statements Must Precede All Except DIM's If you wish to use the DATA statement in ASIC, you must place them all at the beginning of your program following any DIM statements. If you are not using any DIM statements, then the DATA statements should be the at the very beginning of the program. * W001 * Last Statement Not END -- END supplied Warning only. Asic expects the last statement of a program to be an END statement. If it does not find one, it generates one for you. * W002 * Printer Not Ready - 'P' Option Ignored You selected the "Printer" option, but ASIC was not able to access the printer. Make sure the printer is online before compiling with the 'P' option. * W004 * Edit Buffer Full--File Truncated While loading a file, the edit buffer filled before ASIC reached end-of-file. The file is truncated in memory. IF YOU SAVE THE FILE AFTER RECEIVING THIS MESSAGE, PART OF THE FILE WILL BE LOST ON DISK. IT IS RECOMMENDED THAT YOU EITHER EXIT ASIC IMMEDIATELY, OR THAT YOU SAVE THE TRUNCATED FILE UNDER A NEW NAME SO THAT THE ORIGINAL FILE IS NOT DAMAGED. Page - 102 * W005 * Edit Buffer Full ASIC issues this message when the edit buffer is full and you attempt to insert a line. Delete some unnecessary source lines to create space in the edit buffer. * W006 * Source/Dest of Block Copy/Move May Not Overlap You attempted to move or copy a block of lines to a destination line which was within the source block of lines. Execution of this block move/copy would result in an endless series of copies or moves. Move the cursor outside of the highlighted block of lines, and try again. * W007 * Source Program Modified. Recompile? (Y/N) You selected the RUN or TRACE option of ASIC. ASIC has noticed that you have modified the source. You should answer "Y" here to cause ASIC to recompile your program before running it. If you instead answer "N", ASIC will execute the existing copy of the compiled program, which will not contain your latest changes. * W009 * File has been modified. Save File Now? (Y/N) You have told ASIC to exit back to DOS, but the edit buffer has been modified. You should answer "Y" so that ASIC will save your changes back to disk. If you answer "N" here, any changes you have made to your program since the last SAVE command will be lost. * W010 * Too Much Debugging Info-Truncating ASIC could not handle all of the debugging information it found. This error should not occur. Page - 103 * W011 * Variable Not Found During the processing of a Watch, Unwatch, or Modify Command, you specified a variable name which ASIC could not find in the debugging information. Checking your spelling for possible errors. Also, verify that you have compiled your program with the Debugging compiler option turned ON. * W012 * Maximum Number of Variables Are Being Watched You are already "watching" the maximum number of variables that this version of ASIC supports. "Unwatch" one of the variables in the watch window. This will allow you to "Watch" a new one. * W013 * There Are No Variables Being Watched You selected the "Unwatch" command. However, there are no variables in the watch window to "Unwatch". Before this command may be used, you must first have added a variable to the Watch window using the "Watch variable" command. * W014 * Unable to Load/Run Program When ASIC attempted to load and run either the compiler or your program it detected an error. This is due to one of two reasons. First, ASIC could not find the program on disk. If compiling, make sure that the ASICC.EXE file is in the same directory as the ASIC.EXE file, and make that directory current. The second reason that you might get this error is that there may be insufficient memory available on your PC. In this case, you either need to free up more memory (by removing TSR's, etc), or you could execute your program or the compiler from the DOS command line. For more information on compiling from the command line, see Chapter 5--Stand-alone Compiler Options. * W015 * Can't Set Breakpoint There--No Code Generated For That Source Line You attempted to set a breakpoint and either 1) You haven't compiled with the Debugging Compiler Option turned on, or 2) You have tried to set a breakpoint on a line which did not generate any object code. Thus, breakpoints cannot be set on REM or DATA statements, for example. If you are sure that you have compiled with the above option turned on, then try setting the breakpoint on another nearby statement. Page - 104 * W018 * Your Program Must Be Running To Use This Function You selected a function which is only operable when you are running a program (which was compiled with the debugging compiler option turned on). After your program terminates, this function is not available. * W019 * Function Unavailable Until You Terminate Your Program You selected a function while your program was running in debugging mode. Before you can execute this function you must either Abort your program, or allow it to Run until normal termination. Both the Run and the Abort Options are available on the "Run" Menu. * W020 * Invalid Debug (.DBG) File Format ASIC attempted to access the symbolic debugging information file created by the compiler for your program. It was able to locate the file, but detected an error in the format while reading it. Make sure that the version number of both the ASIC Integrated Editor and the ASIC Compiler are the same. The version number is displayed on the top line of the editor screen, following the word "ASIC". It is also displayed on the compiler status screen while a compile is executing. * W021 * Maximum Number of Breakpoints Already Set You have attempted to set another breakpoint, but the maximum number that this version of ASIC can support are already in use. Remove one of the existing breakpoints you have set. This will free one up for your use elsewhere. Page - 105 RUN TIME ERRORS Divide Overflow This message indicates that your program attempted to divide by zero. Page - 106 SYSTEM ERROR CODE VALUES After most commands which access the disk, ASIC sets a special "ERROR" variable to indicate success or failure of that command. After you execute one of these commands, you can reference this variable as a regular variable in your program, to determine the outcome of the command(eg. "IF ERROR = 000 THEN OKAY:"). ERROR Codes Set by BLOAD 000 No Error 002 File Not Found 003 Path Not Found or File Doesn't Exist 004 File Not Found 005 File Access Denied 006-255 Read Past End of File ERROR Codes Set by BSAVE 000 No Error 002 File Not Found 004 File Not Found 005 File Access Denied 006-255 Disk Full ERROR Codes Set by CALL 000-254 Return Code from Program (Zero If Not Set by User Program) 255 Error Loading/Running Program ERROR Codes Set by CHDIR 000 No Error 003 Path Not Found ERROR Codes Set by CLOSE 000 No Error 006 Invalid Handle 095 Cannot Close File -- File is not Open ERROR Codes Set by INPUT# 000 No Error 005 Read Access Denied 006 Invalid File Handle 096 Input String Truncated at 80 characters (this error code is not set when you specify NONULL) 098 File Not Open for Input 099 End of File Page - 107 SYSTEM ERROR CODE VALUES (Continued) ERROR Codes Set by KILL 000 No Error 002 File Not Found 005 Access Denied ERROR Codes Set by MKDIR 000 No Error 003 Path Not Found 005 Access Denied ERROR Codes Set by NAME 000 No Error 002 File Not Found 003 Path Not Found or File Doesn't Exist 005 Access Denied 017 Not Same Disk Drive ERROR Codes Set by OPEN --- Mode Input 000 No Error 002 File Not Found 004 File Not Found 005 File Access Denied 254 File Number Already in Use ERROR Codes Set by OPEN --- Mode Output 000 No Error 003 Path Not Found 004 No File Handle Available 005 File Access Denied 254 File Number Already in Use ERROR Codes Set by PRINT# 000 No Error 005 File Access Denied 006 Invalid File Handle 097 File Not Open for Output 255 Disk Full ERROR Codes Set by RMDIR 000 No Error 003 Path Not Found 005 Access Denied 006 Can't Delete Current Directory 016 Can't Delete Current Directory Page - 108 SYSTEM ERROR CODE VALUES (Continued) ERROR Codes Set by RUN 000-254 Return Code from Program (Zero If Not Set by User Program) 255 Error Loading/Running Program Page - 109