home *** CD-ROM | disk | FTP | other *** search
/ Turbo Toolbox / Turbo_Toolbox.iso / sharew / asic400 / asic.doc next >
Encoding:
Text File  |  1994-03-01  |  304.9 KB  |  9,638 lines

  1.  
  2.  
  3.  
  4.  
  5.  
  6.        +--------------------------------------------------------------------+
  7.        |                                                                    |
  8.        |                            A S I C (tm) 4.00                       |
  9.        |                           "Its Almost Basic"                       |
  10.        |                                                                    |
  11.        |                                                                    |
  12.        |                                                                    |
  13.        |                             Copyright 1993                         |
  14.        |                                   by                               |
  15.        |                             80/20 Software                         |
  16.        |                                                                    |
  17.        |                          All Rights Reserved                       |
  18.        +--------------------------------------------------------------------+
  19.        |  ASIC 4.00 is provided as shareware.  Under the shareware          |
  20.        |  concept,  you can test a program before you buy it. If you find   |
  21.        |  it suitable for your needs and make use of this program, you are  |
  22.        |  expected to send a $20 registration fee.                          |
  23.        |                                                                    |
  24.        |  Feel free to distribute this software to others.  However, you    |
  25.        |  may not charge for the distribution of this software to others    |
  26.        |  nor may you alter the software or this documentation.             |
  27.        |                                                                    |
  28.        |  Registered users of any version of ASIC will receive a diskette   |
  29.        |  containing the current version of ASIC, plus may purchase future  |
  30.        |  updates at half of the normal registration price.  A printed      |
  31.        |  manual is available to registered users for an additional $10.00. |
  32.        |                                                                    |
  33.        |  For further ordering information, please see the file ORDER.FRM,  |
  34.        |  included with ASIC.                                               |
  35.        +--------------------------------------------------------------------+
  36.        |                                                                    |
  37.        |     Please send registration fees and suggestions to:              |
  38.        |                                                                    |
  39.        |                             80/20 Software                         |
  40.        |                             P.O. Box 2952                          |
  41.        |                             Raleigh, NC  27602-2952                |
  42.        |                                                                    |
  43.        |                                                                    |
  44.        |     Please mention the version of ASIC in any correspondence       |
  45.        |                       (This is ASIC Version 4.00)                  |
  46.        +--------------------------------------------------------------------+
  47.        |    You can also send questions/comments on GEnie and Compuserve    |
  48.        |     via EMAIL:                                                     |
  49.        |                                                                    |
  50.        |                     Compuserve      73065,1302                     |
  51.        |                     GEnie           D.VISTI                        |
  52.        |                                                                    |
  53.        +--------------------------------------------------------------------+
  54.        |                                                                    |
  55.        |  DISCLAIMER:  This software is provided "as is" without warranty   |
  56.        |  of any kind, either expressed or implied.                         |
  57.        |                                                                    |
  58.        |  Your registration fee entitles you to use this software on a      |
  59.        |  single computer.  Site licenses are available, write for details. |
  60.        |                                                                    |
  61.        |  ASIC is a trademark of 80/20 Software                             |
  62.        +--------------------------------------------------------------------+
  63.  
  64.  
  65.  
  66.  
  67.  
  68.  
  69.                                         A S I C
  70.                                    Table of Contents
  71.  
  72.          Chapter Title
  73.  
  74.             1.   Getting Started                         Page 5
  75.                       Introduction                       Page 5
  76.                       Installation                       Page 6
  77.             2.   Tutorial                                Page 7
  78.             3.   Integrated Editor/Compiler Environment  Page 13
  79.                       Introduction                       Page 13
  80.                       ASIC Screen Contents               Page 13
  81.                       Menu Bar Processing                Page 13
  82.                       Mouse Usage                        Page 14
  83.                       Getting Help                       Page 15
  84.                            Menu Help                     Page 15
  85.                            Keyword Help                  Page 15
  86.                       File Menu                          Page 16
  87.                            Open                          Page 16
  88.                            DOS Shell                     Page 16
  89.                            Save                          Page 16
  90.                            Save As                       Page 16
  91.                            Exit                          Page 16
  92.                       Edit Menu                          Page 17
  93.                            Begin Block                   Page 17
  94.                            End Block                     Page 17
  95.                            Search                        Page 17
  96.                            Replace                       Page 17
  97.                            Delete Block                  Page 17
  98.                            Move Block                    Page 18
  99.                            Copy Block                    Page 18
  100.                            Search Again                  Page 18
  101.                       Compile Menu                       Page 18
  102.                            Compile Program               Page 18
  103.                            Full Program Listing          Page 19
  104.                            Printer Output                Page 19
  105.                            Symbol Table                  Page 19
  106.                            Extended Math                 Page 19
  107.                            Decimal Math                  Page 20
  108.                            Debugging Code                Page 20
  109.                            View Compile Errors           Page 20
  110.                            Write Options To Disk         Page 21
  111.                       Advanced Options Sub-Menu          Page 21
  112.                            COM Output File               Page 21
  113.                            EXE Output File               Page 21
  114.                            OBJ Output File               Page 22
  115.                            Stack Size                    Page 22
  116.                            Object Names                  Page 23
  117.                            Library Names                 Page 23
  118.                            LINK.EXE Path                 Page 23
  119.  
  120.  
  121.  
  122.  
  123.  
  124.  
  125.  
  126.                                        Page - 1
  127.  
  128.  
  129.  
  130.  
  131.  
  132.                              Table of Contents (Continued)
  133.  
  134.          Chapter Title
  135.  
  136.             3.   Integrated Editor/Compiler Environment (Continued)
  137.  
  138.                       Run Menu                           Page 24
  139.                            Run Your Program              Page 24
  140.                            Breakpoint Toggle             Page 24
  141.                            Trace                         Page 24
  142.                            Modify Variable               Page 25
  143.                            Watch Variable                Page 25
  144.                            Unwatch Variable              Page 25
  145.                            Abort Execution               Page 25
  146.                            Clear All Break/Watch         Page 25
  147.                            Program Arguments             Page 26
  148.                            Swap To User Screen           Page 26
  149.                       Status Line                        Page 26
  150.                       Edit Window                        Page 28
  151.                       Keyboard Usage                     Page 28
  152.             4    Using the Debugger                      Page 29
  153.                       Introduction                       Page 29
  154.                       Debugger Tutorial                  Page 29
  155.                       Debugger Tips                      Page 35
  156.             5.   Command-Line Compiler Options           Page 37
  157.                       Command Line Syntax                Page 37
  158.                       Compiler Options                   Page 38
  159.                       Compiler Examples                  Page 42
  160.                       Program Project File               Page 43
  161.             6.   Language Elements                       Page 44
  162.                       Character Set                      Page 44
  163.                       Constants, Variables, and Labels   Page 46
  164.                       Variables vs. Constants            Page 49
  165.                       Conversion Between Numeric Formats Page 50
  166.             7.   Keyword Reference                       Page 52
  167.                       ABS                                Page 52
  168.                       ASC                                Page 52
  169.                       BEEP                               Page 53
  170.                       BLOAD                              Page 54
  171.                       BSAVE                              Page 55
  172.                       CALL                               Page 56
  173.                       CHDIR                              Page 59
  174.                       CHR$                               Page 60
  175.                       CLOSE                              Page 60
  176.                       CLS                                Page 61
  177.                       CODE                               Page 61
  178.                       COLOR                              Page 62
  179.                       COMMAND$                           Page 63
  180.                       COMSTAT                            Page 64
  181.                       CSRLIN                             Page 65
  182.                       DATA                               Page 66
  183.                       DATE$                              Page 67
  184.                       DEFSEG                             Page 67
  185.                       DIM                                Page 68
  186.                       END                                Page 68
  187.                       ENVIRON$                           Page 69
  188.                       FILEPOS                            Page 70
  189.  
  190.                                        Page - 2
  191.  
  192.  
  193.  
  194.  
  195.  
  196.                              Table of Contents (Continued)
  197.  
  198.          Chapter Title
  199.  
  200.             7.   Keyword Reference (Continued)
  201.  
  202.                       FIND                               Page 72
  203.                       FOR/NEXT                           Page 74
  204.                       GETDIR                             Page 75
  205.                       GOSUB                              Page 76
  206.                       GOTO                               Page 76
  207.                       IF/THEN/ELSE/ENDIF                 Page 77
  208.                       INKEY$                             Page 79
  209.                       INP                                Page 79
  210.                       INPUT                              Page 80
  211.                       INPUT#                             Page 82
  212.                       INSTR                              Page 84
  213.                       INT86                              Page 85
  214.                       KILL                               Page 87
  215.                       LCASE$                             Page 87
  216.                       LEFT$                              Page 88
  217.                       LEN                                Page 88
  218.                       LOCATE                             Page 89
  219.                       LPRINT                             Page 90
  220.                       LTRIM$                             Page 91
  221.                       MID$                               Page 91
  222.                       MKDIR                              Page 92
  223.                       MOD                                Page 92
  224.                       NAME                               Page 93
  225.                       OPEN                               Page 93
  226.                       OPENCOM                            Page 94
  227.                       OUT                                Page 95
  228.                       PEEK                               Page 95
  229.                       POINT                              Page 96
  230.                       POKE                               Page 97
  231.                       POS                                Page 97
  232.                       PRESET                             Page 98
  233.                       PRINT                              Page 99
  234.                       PRINT#                             Page 100
  235.                       PSET                               Page 102
  236.                       RANDOMIZE                          Page 102
  237.                       READ                               Page 103
  238.                       RECEIVE                            Page 104
  239.                       REM                                Page 105
  240.                       RESTORE                            Page 105
  241.                       RETURN                             Page 106
  242.                       RIGHT$                             Page 106
  243.                       RMDIR                              Page 107
  244.                       RND                                Page 108
  245.                       RTRIM$                             Page 109
  246.                       RUN                                Page 110
  247.                       SCREEN                             Page 111
  248.                       SEND                               Page 112
  249.                       SOUND                              Page 112
  250.                       SPACE$                             Page 113
  251.                       STR$                               Page 113
  252.                       STRING$                            Page 114
  253.  
  254.                                        Page - 3
  255.  
  256.  
  257.  
  258.  
  259.  
  260.                              Table of Contents (Continued)
  261.  
  262.          Chapter Title
  263.  
  264.             7.   Keyword Reference (Continued)
  265.  
  266.                       TIME$                              Page 115
  267.                       TIMER                              Page 116
  268.                       UCASE$                             Page 117
  269.                       VAL                                Page 117
  270.                       VARPTR                             Page 118
  271.                       WHILE/WEND                         Page 118
  272.                       WIDTH                              Page 119
  273.                       ZBIT                               Page 119
  274.                       ZMODE                              Page 120
  275.             8.   Compatibility with BASICA/GWBASIC       Page 121
  276.             9.   Technical Details/Tips                  Page 124
  277.                       Compiler Limits                    Page 124
  278.                       Compiler Operation                 Page 125
  279.                       Memory Optimization                Page 125
  280.                       Performance Optimization           Page 126
  281.                       Debugger Limits                    Page 127
  282.                       Debugger Operation                 Page 127
  283.                       Debugger Overhead                  Page 127
  284.                       Storage Formats                    Page 128
  285.                       Memory Map - COM File              Page 130
  286.                       Memory Map - EXE File              Page 131
  287.             10.  Mixed Language Programming              Page 133
  288.                       Overview                           Page 133
  289.                       Developing Assembler Routines      Page 133
  290.                       Assembling Your Subroutine         Page 134
  291.                       Developing the Calling ASIC Progrm Page 134
  292.                       Building the Executable Program    Page 134
  293.                       Other Link Options                 Page 136
  294.                       Debugging                          Page 136
  295.             11.  Error Messages                          Page 137
  296.                       Compiler Errors                    Page 137
  297.                       Fatal Errors                       Page 137
  298.                       Non-Fatal Warnings                 Page 144
  299.                       Run Time Errors                    Page 149
  300.                       System ERROR Code Values           Page 150
  301.  
  302.  
  303.  
  304.  
  305.  
  306.  
  307.  
  308.  
  309.  
  310.  
  311.  
  312.  
  313.  
  314.  
  315.  
  316.  
  317.  
  318.                                        Page - 4
  319.  
  320.  
  321.  
  322.  
  323.  
  324.  
  325.  
  326.  
  327.                                         A S I C
  328.  
  329.                                        Chapter 1
  330.  
  331.                                     Getting Started
  332.  
  333.  
  334.  
  335.                                      INTRODUCTION
  336.  
  337.             Welcome to ASIC!
  338.  
  339.             ASIC is a "BASIC" programming language compiler for IBM PCs and
  340.        compatibles.  It includes an integrated full screen editor, from which
  341.        you can edit, compile, and debug your programs.  Or, at your option, you
  342.        can use your own text editor, and compile your programs from the MS DOS
  343.        command line.
  344.  
  345.             ASIC supports a large subset of BASICA and GWBASIC.  It supports
  346.        over 80 BASIC statements, decimal, integer and string variables and
  347.        arrays.  It will compile your programs at high speed, and the code it
  348.        generates is fast and compact.  The syntax of each ASIC statement is
  349.        generally a valid subset of the syntax used by BASICA and GWBASIC
  350.        (exceptions are noted in Chapter 8.)
  351.  
  352.             All you need to get started is:
  353.  
  354.                  1)  ASIC
  355.                  2)  IBM PC or 100% Compatible
  356.                  3)  405k Available Memory
  357.                  4)  Two floppy disk drives
  358.                           <or>
  359.                      One hard disk drive and one floppy disk drive
  360.  
  361.             Optional:
  362.  
  363.                  1) Microsoft Compatible Mouse
  364.  
  365.  
  366.             The first step is to install ASIC as described below.  Then,
  367.        proceed to Chapter 2 for a brief ASIC tutorial.  Following that you can
  368.        read the remainder of the documentation straight through, or refer to it
  369.        as you need it.  Have Fun!
  370.  
  371.  
  372.  
  373.  
  374.  
  375.  
  376.  
  377.  
  378.  
  379.  
  380.  
  381.  
  382.                                        Page - 5
  383.  
  384.  
  385.  
  386.  
  387.  
  388.                                      INSTALLATION
  389.  
  390.        To conserve disk space, ASIC files are shipped in compressed format.
  391.        So, before you can run ASIC, you must first install it using the ASIC
  392.        INSTALL.EXE program.  To do so, follow the instructions below.  Commands
  393.        you type are listed in ALL CAPS .  Where you see <ENTER>, you should
  394.        press the <ENTER> key on your keyboard.
  395.  
  396.        If you are installing to a 3 1/2" diskette or a 1.2 megabyte 5 1/4"
  397.        diskette, you will need 1 blank formatted diskette.  If you are
  398.        installing to a 360k diskette, you will need 2 formatted diskettes for a
  399.        full install (or 1 formatted diskette if you opt to not install the
  400.        documentation).  If you are installing to a hard disk, about 500k bytes
  401.        are required for a full install (about 150k is required for a minimal
  402.        install).  To install:
  403.  
  404.        1)   Insert your ASIC diskette into your floppy drive.
  405.  
  406.        2)   If the ASIC diskette is in drive A, type:         A:  <ENTER>
  407.             If the ASIC diskette is in drive B, type:         B:  <ENTER>
  408.  
  409.        3)   Change the default directory by typing:      CD \  <ENTER>
  410.  
  411.        4)   Run the ASIC INSTALL.EXE program by typing:  INSTALL <ENTER>
  412.  
  413.  
  414.        The ASIC install program will prompt you for the information it needs.
  415.        You will be asked for the following information:
  416.  
  417.        1)  The drive and directory containing the ASIC installation files.
  418.        2)  The drive and directory you want ASIC installed to.
  419.  
  420.        You will be offered the option of installing (or not installing) the
  421.        ASIC documentation files and sample programs.  It is recommended that
  422.        you install all options.  Note:  If you do not install the documentation
  423.        files, the online help function will not be available.  If you are
  424.        installing to a 360k 5-1/4" floppy diskette, the online help function
  425.        will not be available inside the integrated editor.
  426.  
  427.        You may rerun the INSTALL program later to install options that you
  428.        skipped the first time.
  429.  
  430.  
  431.  
  432.  
  433.  
  434.  
  435.  
  436.  
  437.  
  438.  
  439.  
  440.  
  441.  
  442.  
  443.  
  444.  
  445.  
  446.                                        Page - 6
  447.  
  448.  
  449.  
  450.  
  451.  
  452.  
  453.  
  454.  
  455.                                         A S I C
  456.  
  457.                                        Chapter 2
  458.  
  459.                                        Tutorial
  460.  
  461.  
  462.        ASIC programs look very much like regular "BASIC" programs which you are
  463.        probably already familiar with.  The one very noticeable difference is
  464.        that ASIC programs have no line numbers.  Let's take a look at a very
  465.        simple program written both in GWBASIC/BASICA and in ASIC:
  466.  
  467.             GWBASIC/BASICA                          ASIC
  468.             -------------------------+----------------------------------
  469.                                      |
  470.             10  I=I+1                |  ADDONE:  I=I+1
  471.             20  PRINT I              |         PRINT I
  472.             30  IF I<100 THEN 10     |         IF I<100 THEN ADDONE:
  473.             -------------------------+----------------------------------
  474.  
  475.             Both of these programs do the same thing.  They display the numbers
  476.        from 1 to 100.  However, notice that ASIC allows you to use descriptive
  477.        labels (ADDONE) instead of a line number (10).  These labels can be up
  478.        to 80 characters long!  Also note that the ASIC  "PRINT" and "IF"
  479.        statements were indented only for increased program readability.  The
  480.        ASIC program could just as well have been written as:
  481.  
  482.                                          ASIC
  483.                             ------------------------------
  484.                                  ADDONE:I=I+1
  485.                                  PRINT I
  486.                                  IF I<100 THEN ADDONE:
  487.                             ------------------------------
  488.  
  489.             We could have made our variable names longer.  Instead of "I" we
  490.        could have chosen "SECONDS" or "VELOCITY", or some other name up to 80
  491.        characters in total.  In ASIC, variable names, labels, and string
  492.        constants can all be up to 80 characters in length.
  493.  
  494.             Well, now that we've seen a basic ASIC program, let's try to enter
  495.        and run a slightly larger program.  The program we will be working with
  496.        will print the message "HELLO yourname" in 256 color combinations.  If
  497.        you have a monochrome display card, don't worry, the program will work,
  498.        but instead of seeing different colors you'll see characters with
  499.        different attributes, such as blinking, underlined, etc.
  500.  
  501.             Let's get started.  If you haven't done so already, install ASIC as
  502.        described in Chapter 1.  Now then, writing an ASIC program involves
  503.        these three steps.
  504.  
  505.             1.  Write your program.
  506.             2.  Compile your program.
  507.             3.  Run/Test your Program.
  508.  
  509.  
  510.                                        Page - 7
  511.  
  512.  
  513.  
  514.  
  515.  
  516.             These three steps can all be performed from within the ASIC
  517.        Integrated Environment.  Before we proceed with our "Hello yourname"
  518.        Program, let's go over some conventions.
  519.  
  520.  
  521.             In the following section:
  522.  
  523.             FLOPPY TYPE-->      Means that only 2-floppy disk system users
  524.                                 should type this line.
  525.  
  526.             HARD TYPE-->        Means that only hard disk system users
  527.                                 should type this line.
  528.  
  529.             TYPE-->             Means that both floppy and hard disk users
  530.                                 should type this line.
  531.  
  532.             X>                  This is a representation of the prompt from
  533.                                 PC-DOS or MS-DOS.  Floppy Disk Users will
  534.                                 actually see "A>" for a prompt.  Hard Disk
  535.                                 Users will see "C>" for a prompt.
  536.  
  537.             <enter>             Means that you should press the <enter>
  538.                                 or <return> key on your keyboard.
  539.  
  540.             <?>                 Text enclosed between the "<" and the ">"
  541.                                 symbols indicate a key to type.  Don't type
  542.                                 the "<" or ">" symbols.  For example, if the
  543.                                 tutorial lists "<F1>", your should press the
  544.                                 "F1" key on your keyboard.
  545.  
  546.        NOTE:  Floppy Disk users need to insert their ASIC Compiler diskette in
  547.        Drive A: at this point, and a blank diskette in Drive B:  (See the
  548.        Installation section for more information)
  549.  
  550.        The tutorial uses the keyboard for all commands, but includes a few
  551.        notes on mouse usage.  For more information on using the mouse with ASIC
  552.        see the "MOUSE USAGE" section in Chapter 3.
  553.  
  554.        Let's begin:
  555.  
  556.  
  557.             FLOPPY TYPE-->      A: <enter>
  558.             HARD TYPE-->        CD C:\ASIC <enter>
  559.  
  560.        The computer should respond:
  561.  
  562.                                 X>
  563.  
  564.        Now enter the command to invoke ASIC:
  565.  
  566.             TYPE-->             ASIC <enter>
  567.  
  568.        You are now in ASIC.  The top line is the Menu Bar.  The bottom line is
  569.        the Status Line.  Chapter 3 describes this in more detail.  For now,
  570.        we'll just describe a couple of features on these lines.
  571.  
  572.  
  573.  
  574.                                        Page - 8
  575.  
  576.  
  577.  
  578.  
  579.  
  580.        The status line indicates that the current mode is "INSERT".  This means
  581.        that any characters you type on a line will be inserted between the
  582.        existing characters.  If you press the <INS> key on the keypad, ASIC
  583.        will toggle to its other mode, OVERSTRIKE.  In this mode, when you type
  584.        a character, it overlays the character that was there before.  Each time
  585.        you press the <INS> key, ASIC will toggle between the INSERT and
  586.        OVERSTRIKE modes.
  587.  
  588.        You can open the menus listed on the "Menu Bar" by holding down the ALT
  589.        key while typing the Red Capitalized letter of the menu you wish to
  590.        open.  For example, to open the File menu, press <ALT><F>.  Try it now:
  591.  
  592.             TYPE-->    <Alt><F>
  593.  
  594.        The "File" menu will pop open.  You can select a menu option from that
  595.        menu by typing the capitalized letter of the option, or by using the
  596.        arrow keys on your keypad to highlight the option you want and then
  597.        pressing <enter>.
  598.  
  599.                  MOUSE USERS:  If you have a mouse, you can open a
  600.                  menu by clicking the left mouse button on the menu
  601.                  name.  For example, to open the "File" menu,
  602.                  position the mouse pointer anywhere on the word
  603.                  "File", and click the left button.
  604.  
  605.        If you are not sure what the menu option will do, you can press <F1> and
  606.        ASIC will display some help information for the highlighted menu option.
  607.        When you opened the File menu, the first option on that menu, "Open" was
  608.        highlighted.  Let's get some help on "Open":
  609.  
  610.             TYPE-->    <F1>
  611.  
  612.        ASIC will display some help information on "Open".  Let's close the help
  613.        window now:
  614.  
  615.             TYPE-->    <ESC>
  616.  
  617.        The help window will close.  The <ESC> key will always let you escape
  618.        from any menu or help screen in ASIC, without taking any action.
  619.  
  620.                  MOUSE USERS:  To close a menu you can click the
  621.                  right mouse button.  In fact, you can always use the
  622.                  right mouse button to cancel an option, instead of
  623.                  pressing the <ESC> key, if you prefer.
  624.  
  625.         Let's also close the file menu for now:
  626.  
  627.             TYPE-->    <ESC>
  628.  
  629.        The "File" menu should have closed.  By the way, in addition to the menu
  630.        help, ASIC provides additional online help.  If you need general ASIC
  631.        help, press the <F1> key for a quick summary of some of ASIC's features:
  632.  
  633.             TYPE-->    <F1>
  634.  
  635.  
  636.  
  637.  
  638.                                        Page - 9
  639.  
  640.  
  641.  
  642.  
  643.  
  644.        ASIC will display some general help.  From this screen, we can also
  645.        retrieve additional information about BASIC statements such as PRINT or
  646.        GOSUB.  Let's bring up an index of these statements.
  647.  
  648.             TYPE-->    <F1>
  649.  
  650.        ASIC has opened a help index screen.  From this screen we can use the
  651.        arrow keys to highlight any ASIC keyword and obtain more information for
  652.        that keyword by then pressing enter.  We won't do that now, but don't
  653.        forget that this screen is available. Chapter 3 of the ASIC Reference
  654.        Manual describes all of the online "HELP" features available in ASIC and
  655.        provides a full description of the ASIC Editor Commands which are
  656.        available.  Exit the help menu:
  657.  
  658.             TYPE-->    <ESC>
  659.  
  660.        Entering a program in ASIC is simplicity itself.  We'll simply type in
  661.        each line, pressing <enter> at the end of each line.  If you make a
  662.        typing mistake, just use the arrow keys to move to the error, and type
  663.        in the correction.  Use the <DEL> or <Backspace> keys to delete any
  664.        unwanted characters from the screen.
  665.  
  666.        Make sure the status line says "Mode: Insert".  This is the default mode
  667.        in ASIC.  If it doesn't, press the <INS> key until it does.  Now let's
  668.        enter our program (the program below intentionally contains an invalid
  669.        ASIC statement.  We'll correct the line later in the tutorial, for now,
  670.        type in the program exactly as it's listed below):
  671.  
  672.             TYPE-->        CLS  <enter>
  673.             TYPE-->        PRINT "Please enter your name"; <enter>
  674.             TYPE-->        INPUT YOURNAME$  <enter>
  675.             TYPE-->        FOR I=1 TO 16  <enter>
  676.             TYPE-->            FOR J=1 TO 16  <enter>
  677.             TYPE-->                COLOR I,J <enter>
  678.             TYPE-->                PRINT "HELLO "; <enter>
  679.             TYPE-->                PRINT YOURNAME$; <enter>
  680.             TYPE-->            NEXT J <enter>
  681.             TYPE-->        NEXT I <enter>
  682.             TYPE-->        CLS <enter>
  683.             TYPE-->        THE END <enter>
  684.  
  685.        There, that was easy.  Now, let's compile our program.  To do it, we'll
  686.        open the "Compile" menu, and select the "Compile program" option:
  687.  
  688.             TYPE-->       <ALT><C>
  689.  
  690.        The "Compile" menu will pop open.  The first option, "Compile program"
  691.        can be selected by typing the option letter which is capitalized "C", or
  692.        by moving the highlight bar to this option and pressing the <enter> key.
  693.        Since the highlight bar is already on this option, let's just press
  694.        <enter>:
  695.  
  696.                  MOUSE USERS: To select an option with the mouse,
  697.                  position the mouse pointer on the option name and
  698.                  click the left mouse button.
  699.  
  700.             TYPE-->       <enter>
  701.  
  702.                                        Page - 10
  703.  
  704.  
  705.  
  706.  
  707.  
  708.        Since we didn't specify a file name when we invoked ASIC, ASIC will now
  709.        ask for a file name (so it can save your program before calling the
  710.        compiler):
  711.  
  712.             FLOPPY TYPE-->      B:TUTOR.ASI  <enter>
  713.             HARD TYPE-->        TUTOR.ASI <enter>
  714.  
  715.        Note that ASIC requires that your programs be stored in files ending
  716.        with the extension ".ASI".  Had we entered "TUTOR" for our program name,
  717.        ASIC would have appended the letters ".ASI" for us.  If we tried to
  718.        provide a different extension, such as "TUTOR.SRC", ASIC would display
  719.        an error message.
  720.  
  721.        Once you select the "Compile program" option, you'll see the ASIC
  722.        compiler screen appear.  It will display a count of the lines compiled,
  723.        and when it is done, it will return to the ASIC editor.
  724.  
  725.        If ASIC detected any errors, it will display the first error message at
  726.        the bottom of the editor screen.  It will also highlight the line in
  727.        your program which is in error.  In this case the line "THE END" was
  728.        flagged with the error message "Syntax Error".  Of course, that line
  729.        should have been entered simply as "END".
  730.  
  731.        That should be easy enough to fix.  Let's exit the error menu by
  732.        pressing the <ESC> key:
  733.  
  734.             TYPE-->      <ESC>
  735.  
  736.        The error menu has disappeared, and our cursor is now on the erroneous
  737.        line.  To fix the line:
  738.  
  739.             TYPE-->      <DEL><DEL><DEL><DEL>
  740.  
  741.        That should do it.  The last line of our program should now read "END".
  742.        Before we continue, let's assume we knew the name of the END command,
  743.        but could not remember the proper syntax for it.  ASIC provides an
  744.        online lookup for each ASIC statement.  With the cursor positioned
  745.        somewhere on the word "END":
  746.  
  747.             TYPE-->      <Ctl><F1>
  748.  
  749.        ASIC should have opened a help window describing the "END" statement.
  750.        To return to your program press the <ESC> key.
  751.  
  752.             TYPE-->      <ESC>
  753.  
  754.        The help window should have disappeared and you should see your program
  755.        displayed again.  Let's recompile the program:
  756.  
  757.             TYPE-->      <ALT><C>
  758.             TYPE-->      <enter>
  759.  
  760.  
  761.  
  762.  
  763.  
  764.  
  765.  
  766.                                        Page - 11
  767.  
  768.  
  769.  
  770.  
  771.  
  772.  
  773.        This time you should see the message "No Compiler Errors". If you
  774.        didn't, check your spelling and recompile the program until you receive
  775.        this message.  Press <ESC> to remove the "No Compiler Errors" Window.
  776.  
  777.        Now let's run the program.  To do so, we'll open the "Run" menu, and
  778.        select the "Run your program" option.
  779.  
  780.             TYPE-->      <ALT><R>
  781.             TYPE-->      <r>
  782.  
  783.        This time, we just entered the capitalized letter from the menu option
  784.        "Run your program".  Your computer screen should now prompt you to
  785.        "Please enter your name?".  Go ahead and enter your name now:
  786.  
  787.             TYPE-->      yourname  <enter>
  788.  
  789.        You should see "HELLO yourname" printed in various color combinations,
  790.        and then the ASIC editor screen will reappear.  Well, that's all there
  791.        is to writing, compiling, and running an ASIC program.  Now, to exit
  792.        ASIC, open the "File" menu and select the "eXit" option.
  793.  
  794.             TYPE-->      <ALT><F>
  795.             TYPE-->      <X>
  796.  
  797.        You should see your MS DOS prompt once again.  By the way, now that
  798.        you've successfully compiled the program, you can execute it directly
  799.        from MS DOS.  Let's try it:
  800.  
  801.             HARD TYPE-->     TUTOR <enter>
  802.             FLOPPY TYPE-->   B:TUTOR <enter>
  803.  
  804.        Well, that's a brief introduction to ASIC!  Next, you might want to read
  805.        Chapter 3, "Integrated Editor/Compiler Environment" to learn about the
  806.        many other features available in the ASIC editor.  Following this you
  807.        should read Chapter 4 which explains how to use the ASIC Debugger.
  808.        Chapter 4 includes another short tutorial in which you debug a program.
  809.  
  810.             The remaining chapters provide reference material which you can
  811.        either read, or just refer to as needed.  Chapter 5 explains how to
  812.        compile programs directly from the command line of DOS.  Chapters 6-8
  813.        describe the BASIC statements which are supported by ASIC.  Chapter 9
  814.        provides some technical information about ASIC.  Chapter 10 explains how
  815.        to call assembly language object modules from an ASIC program.  Chapter
  816.        11 provides more descriptive information for ASIC error messages.
  817.  
  818.        Hope you enjoy programming in ASIC!
  819.  
  820.  
  821.  
  822.  
  823.  
  824.  
  825.  
  826.  
  827.  
  828.  
  829.  
  830.                                        Page - 12
  831.  
  832.  
  833.  
  834.  
  835.  
  836.  
  837.  
  838.  
  839.                                         A S I C
  840.  
  841.                                        Chapter 3
  842.  
  843.                               Integrated Editor/Compiler
  844.                                       Environment
  845.  
  846.  
  847.                                      INTRODUCTION
  848.  
  849.             The ASIC integrated environment lets you edit, save, compile, and
  850.        debug your ASIC programs without ever leaving ASIC!  This chapter will
  851.        explain the usage of the integrated environment.
  852.  
  853.  
  854.                                  ASIC SCREEN CONTENTS
  855.  
  856.             ASIC divides the screen into three parts.  The top line is called
  857.        the "Menu Bar".  All of the menus available to you are listed on this
  858.        line.  The bottom line is called the "Status Line".  It continuously
  859.        displays some important program information.  The middle 23 lines are
  860.        the "Edit Window".  This is the section of the screen where you can make
  861.        changes or additions to your program.
  862.  
  863.                                   MENU BAR PROCESSING
  864.  
  865.        Currently, there are four menus available.  The "File" menu allows you
  866.        to load/save your existing program files to/from disk.  It is also used
  867.        to exit ASIC.  The "Edit" menu contains various editing commands which
  868.        are available.  The "Compile" menu is used to compile your program, set
  869.        compiler options, and to view compiler errors.  The "Run" menu allows
  870.        you to run your programs, and test them using the ASIC debugger.
  871.  
  872.             To open a menu, hold down the <ALT> key and type the first letter
  873.        of the menu.  The menu will pop down and display the options available
  874.        on that menu.  If you want to close the menu without taking any action,
  875.        press the <ESC> key.  If you wish to open a different menu without first
  876.        closing the current menu, press the left or right arrow keys.
  877.  
  878.             Otherwise, to select an option, type the capitalized letter of the
  879.        menu option.  For example, on the "File" menu, to select the "eXit"
  880.        option, type an "X" or an "x".  Another way to select an option is to
  881.        move the "Highlighted Bar" down to the option you wish to select, and
  882.        press the <enter> key.
  883.  
  884.             Some functions may be accessed outside of the menus with short cut
  885.        keys.  For example, the "eXit    <ALT-X>" function in the file menu can
  886.        be selected by holding down the ALT key and tapping the "x" key.  The
  887.        short cut keys are listed on the menus following the option name (they
  888.        are enclosed in brackets as in <F2> or <ALT-X>).  Not all menu options
  889.        have short cut keys.  Note that these short cut keys do not operate when
  890.        a menu is open.  (A list of these short cut keys is presented later in
  891.        this chapter in the Keyboard Usage Section).
  892.  
  893.  
  894.                                        Page - 13
  895.  
  896.  
  897.  
  898.  
  899.  
  900.  
  901.                                       MOUSE USAGE
  902.  
  903.             If you are familiar with other Mouse Programs, such as Microsoft
  904.        Windows, you will find that you will use the mouse in much the same way
  905.        in ASIC.
  906.  
  907.             Menus can be opened by moving the mouse pointer to a menu name on
  908.        the menu bar, and clicking the left mouse button.  Once the menu is open
  909.        you can select an option by positioning the mouse pointer on the desired
  910.        option, and clicking the left mouse button.  To close a menu without
  911.        selecting an option, click the right button.
  912.  
  913.             A new feature added to several screens, is the "scroll bar".
  914.        Scroll bars let you scroll through lists of items in screen window. A
  915.        vertical scroll bar appears on the right side of the main editor window
  916.        (and on the file open, save, and some help screens).  At the top of the
  917.        scroll bar is a small arrow that points upwards.  At the bottom of the
  918.        scroll bar is a small arrow that points downwards.  Between the two
  919.        arrows is a small square, called a slider.
  920.  
  921.             At the bottom of the main edit window there is also a horizontal
  922.        scroll bar, that lets you scroll the edit buffer left and right.
  923.  
  924.             To use the scroll bar, click the left mouse button on one of the
  925.        arrows to scroll the contents of a window by one line.   Click on the
  926.        shaded area between the arrows to scroll a page at a time.  You can also
  927.        "drag" the slider to any position on the scroll bar to scroll the window
  928.        to the same relative position.  To drag the slider, position the mouse
  929.        pointer on the slider, hold down the left mouse button, and move the
  930.        mouse pointer to the desired position on the scroll bar.  Once at the
  931.        desired position, release the mouse button.
  932.  
  933.             To select a block of text in the editor, position the mouse pointer
  934.        on the first line in the block you wish to select.  Press and HOLD the
  935.        left mouse button until the first line is highlighted.  Continue holding
  936.        the left mouse button down, and drag the mouse pointer to the ending
  937.        line of the block.  When you reach the last line you want to include in
  938.        the block, release the left mouse button.
  939.  
  940.             When responding to dialog box messages, the left mouse button is
  941.        the same as pressing  <ENTER>, and the right mouse button is the same as
  942.        press the <ESC> key.
  943.  
  944.             To get context sensitive help for menu options or ASIC keywords,
  945.        press and briefly HOLD the right mouse button.
  946.  
  947.             To position the keyboard cursor, move the mouse pointer to the
  948.        desired location in the edit window, and click the left mouse button.
  949.        The cursor will move to the mouse pointer location.
  950.  
  951.  
  952.  
  953.  
  954.  
  955.  
  956.  
  957.  
  958.                                        Page - 14
  959.  
  960.  
  961.  
  962.  
  963.  
  964.                                      GETTING HELP
  965.  
  966.  
  967.        ASIC provides "online" help within the integrated environment to assist
  968.        you with keyboard usage, menu options, and ASIC keywords.  This section
  969.        tells you how to access this online help.
  970.  
  971.        General Help
  972.  
  973.        General describes the usage of the keyboard in ASIC.  Keyboard keys
  974.        which perform ASIC functions are described in this section.  Access
  975.        general help by pressing Function key <F1>.  Pressing <F1> a second time
  976.        will display an ASIC keyword index.  You can get additional help on
  977.        individual ASIC keywords from this screen.  This information includes a
  978.        description of what the keyword does, and the keyword syntax.
  979.  
  980.                  MOUSE USERS:  You can select help by positioning the
  981.                  mouse pointer on  the "F1=Help"  option on the menu
  982.                  bar, and clicking the left mouse button.
  983.  
  984.        Menu Help
  985.  
  986.        If you open a menu, but you are not sure what a certain menu option
  987.        does, you may display a description of the highlighted menu option by
  988.        pressing the <F1> key.  Doing so will open a help window which describes
  989.        the menu option.  Press <ESC> to exit the help screen and return to the
  990.        menu.
  991.  
  992.                  MOUSE USERS:  You can get help for a menu option with the
  993.                  mouse as follows.  Position the mouse pointer on the menu
  994.                  option, and press and briefly HOLD the right mouse button.
  995.  
  996.  
  997.        Keyword Help
  998.  
  999.        Can't remember the syntax for a particular ASIC keyword?  Well, help is
  1000.        just a keystroke away.  Position the cursor on the keyword in the edit
  1001.        buffer.  Then, hold down the <Ctl> key and press the <F1> key.
  1002.        ASIC will display a description of the keyword, and describe proper
  1003.        syntax for that keyword.  For example, if you tried to compile a
  1004.        program, but received a syntax error on the keyword "PRINT" in your
  1005.        program, you could obtain help on the "PRINT" statement by using the
  1006.        arrow keys to position the cursor anywhere on the word "PRINT" and then
  1007.        pressing <Ctl-F1>.  If ASIC cannot find the keyword (eg, say the cursor
  1008.        was positioned on a variable called "APPLES", which is not an ASIC
  1009.        keyword), then ASIC will display a list of valid keywords.  Use the
  1010.        cursor keys to highlight one of these keywords and press <enter> to
  1011.        retrieve help for the highlighted keyword.  You may also access this
  1012.        keyword help list by pressing the <F1> key twice from within the editor.
  1013.  
  1014.                  MOUSE USERS:  You can also get keyword help using the mouse.
  1015.                  Position the mouse pointer on the keyword, and press and
  1016.                  briefly HOLD the right mouse button.
  1017.  
  1018.             Now let's describe the options available on each menu.
  1019.  
  1020.  
  1021.  
  1022.                                        Page - 15
  1023.  
  1024.  
  1025.  
  1026.  
  1027.  
  1028.  
  1029.  
  1030.                                        FILE MENU
  1031.  
  1032.        "Open...   <F3>" Option
  1033.  
  1034.             This option allows you to open an existing ASIC file and load it
  1035.        into the ASIC edit buffer where you can modify it.  If you select this
  1036.        option another window will open to ask you the file name.  If you don't
  1037.        wish to open a file, you can press <ESC> to close the menu without
  1038.        taking any action.  Otherwise, enter an ASIC file name, and press the
  1039.        <enter> key.  There is a second way to select a file to open, if the
  1040.        file already exists. You can select the file name from the list
  1041.        displayed, by using the arrow keys or mouse to scroll through the list
  1042.        of file names.  To select a file from the list, press <ENTER>, or
  1043.        position the mouse pointer on the file name, and click the left mouse
  1044.        button.  This option may also be selected outside of the menu by
  1045.        pressing the <F3> key.
  1046.  
  1047.        "Dos shell" Option
  1048.  
  1049.             This option allows you to temporarily exit to MS DOS to execute one
  1050.        or more DOS commands or other programs.  When you are ready to return to
  1051.        ASIC, type EXIT <enter>.
  1052.  
  1053.        "Save   <F2>" Option
  1054.  
  1055.             This option allows you to write the changes you've made to your
  1056.        program back to the file.  Changes you enter in the ASIC editor are made
  1057.        to memory only.  You must select this option before your changes will
  1058.        become permanent.  Note:  Your file is saved to disk automatically
  1059.        whenever you compile it or run it, if the file has been modified.  This
  1060.        option may also be selected outside the menu by pressing the <F2> key.
  1061.  
  1062.        "save As..." Option
  1063.  
  1064.             This option will allow you to write the changes you've made to the
  1065.        program in the edit buffer to a new file.  You will be prompted to
  1066.        provide ASIC with a new file name.  If  you want to overlay an existing
  1067.        file, you can select the file name from the list displayed by using the
  1068.        arrow keys or mouse to scroll through the list of file names.  To select
  1069.        a file from the list, press <ENTER>, or position the mouse pointer on
  1070.        the file name, and click the left mouse button.  BE CAREFUL--WHEN YOU
  1071.        SELECT A FILE FROM THE LIST, YOU ARE TELLING ASIC TO OVERLAY AN EXISTING
  1072.        FILE.
  1073.  
  1074.        "eXit   <Alt-X>" Option
  1075.  
  1076.             This option will allow you to exit from ASIC back to MS DOS.  ASIC
  1077.        will ask you if you wish to save your file before you exit.  This option
  1078.        may be selected outside this menu by pressing <ALT-X>.
  1079.  
  1080.  
  1081.  
  1082.  
  1083.  
  1084.  
  1085.  
  1086.                                        Page - 16
  1087.  
  1088.  
  1089.  
  1090.  
  1091.  
  1092.  
  1093.  
  1094.                                        EDIT MENU
  1095.  
  1096.        "Begin block" Option
  1097.  
  1098.             This option will allow you to mark the beginning of a block of text
  1099.        for use with the block delete, copy, and move commands.  To mark a block
  1100.        of text, move the cursor to the first line of the block, and then select
  1101.        this option.  The beginning line of the block will be highlighted on the
  1102.        screen.  Next, move the cursor to the ending line of the block, and
  1103.        select the "End block" option from this menu.  All of the lines in the
  1104.        block will be highlighted.  This block of lines can now be "moved",
  1105.        "copied", or "deleted" using the block commands.  If you have a mouse,
  1106.        you can select text without using the "Begin Block" and "End Block"
  1107.        options.  To select a block of text with the mouse, position the mouse
  1108.        pointer on the first line in the block, press and HOLD the left mouse
  1109.        button until the line is highlighted, and (while continuing to hold down
  1110.        the left mouse button) drag the mouse pointer to the ending line of the
  1111.        block.  Once you reach the ending line of the block, you may release the
  1112.        left mouse button.  The block should be highlighted on the screen.
  1113.  
  1114.        "End block" Option
  1115.  
  1116.             This option will allow you to mark the end of a block of text.
  1117.        Refer to the "Begin block" Option for more information.
  1118.  
  1119.        "Search..." Option
  1120.  
  1121.             This option allows you to locate a string of characters in the edit
  1122.        buffer.  When you select this option, ASIC will ask you for a search
  1123.        string which can be up to 30 characters in length.  ASIC will then
  1124.        search forward from the current line until it finds the string or
  1125.        reaches the end of the edit buffer.  If it finds the string, the cursor
  1126.        will be placed on the line containing the string.
  1127.  
  1128.        "Replace..." Option
  1129.  
  1130.             This option will allow you to replace one or more occurrences of a
  1131.        string of characters with another set of characters.  When you select
  1132.        this option, ASIC will ask you for a search string which can be up to 30
  1133.        characters in length.  ASIC will then ask you for the string of
  1134.        characters which is to replace the search string.  Finally, ASIC will
  1135.        ask you to specify how many occurrences of this search string are to be
  1136.        replaced (from 1-9999).  ASIC will search forward from the current line,
  1137.        and briefly display each line as it modifies it.  If it reaches the end
  1138.        of the edit buffer before it has replaced the number of occurrences
  1139.        you've specified, ASIC will display an "End of Buffer" message, and
  1140.        stop.
  1141.  
  1142.        "Delete block" Option
  1143.  
  1144.             This option will delete a block of lines.  Refer to the "Begin
  1145.        block" option for information on marking a block of lines.  If you
  1146.        haven't marked a block of lines, selecting this option will have no
  1147.        effect.
  1148.  
  1149.  
  1150.                                        Page - 17
  1151.  
  1152.  
  1153.  
  1154.  
  1155.  
  1156.  
  1157.  
  1158.                                  EDIT MENU (Continued)
  1159.  
  1160.        "Move block" Option
  1161.  
  1162.             This option will move a block of lines to a new location in the
  1163.        edit buffer.  Refer to the "Begin block" option for information on
  1164.        marking a block of lines.  If you don't mark a block of lines, selecting
  1165.        this option will have no effect.  Once you have marked a block of lines,
  1166.        move the cursor to the location in the edit buffer where you want the
  1167.        lines moved. Selecting the "Move block" option will result in the block
  1168.        of lines being deleted from their current location, and moved to the
  1169.        buffer at the line following the cursor.  ASIC will not overlay lines,
  1170.        it will insert enough blank space to hold the relocated text.
  1171.  
  1172.        "Copy block" Option
  1173.  
  1174.             This option is the same as the "Move block" option, with one
  1175.        exception.  After moving the block, ASIC does NOT delete the original
  1176.        block of lines.  Use this option to clone a block of text.  Refer to the
  1177.        "Begin block" option for information on marking a block of text.
  1178.  
  1179.        "search Again <CTL-L>" Option
  1180.  
  1181.             This option will allow you to search for the next occurrence of the
  1182.        last string you searched for with the "Search" Option, without retyping
  1183.        the previous search string.  This option may also be selected outside of
  1184.        the Edit Menu by pressing <CTL-L>.
  1185.  
  1186.  
  1187.                                      COMPILE MENU
  1188.  
  1189.        "Compile program <F10>" Option
  1190.  
  1191.             Use this option to have ASIC compile the program which is currently
  1192.        loaded in the edit buffer.  If the compile is successful, ASIC will
  1193.        display the message "No Compiler Errors".  Otherwise, it will display
  1194.        the first error message (see "View compile errors" option).  ASIC will
  1195.        automatically save your program before calling the compiler.  This
  1196.        option may also be selected outside of the menu by pressing function key
  1197.        <F10>.
  1198.  
  1199.        "Advanced options" Option
  1200.  
  1201.             Select this option to bring up a menu of compiler options for the
  1202.        advanced ASIC user.
  1203.  
  1204.  
  1205.  
  1206.  
  1207.  
  1208.  
  1209.  
  1210.  
  1211.  
  1212.  
  1213.  
  1214.                                        Page - 18
  1215.  
  1216.  
  1217.  
  1218.  
  1219.  
  1220.  
  1221.  
  1222.                                COMPILE MENU (Continued)
  1223.  
  1224.        "Full program listing" Option
  1225.  
  1226.             This menu option, and the next six options are used to toggle
  1227.        various compiler options on or off.  When the option is on, you will see
  1228.        a "check mark" symbol next to the option.  This compiler option will
  1229.        cause ASIC to display each source line as it compiles it.  This option
  1230.        will slow down the compile, but since ASIC also writes these lines to a
  1231.        listing file, this option can be used to create a compile listing.  The
  1232.        compile listing will be contained in a file called "progname.LST", where
  1233.        "progname" is the name of your program.
  1234.  
  1235.        "Printer output" Option
  1236.  
  1237.             This menu option will toggle the "Printer output" compiler option
  1238.        on or off.  When the option is on, you will see a "check mark" symbol
  1239.        next to the option name.  This compiler option will cause compiler
  1240.        messages to be printed on your printer.
  1241.  
  1242.        "Symbol table" Option
  1243.  
  1244.             This menu option will toggle the "Symbol table" compiler option on
  1245.        or off.  When the option is on, you will see a "check mark" symbol next
  1246.        to the option name.  This compiler option will cause ASIC to create a
  1247.        symbol table file called "progname.SYM", where "progname" is the name of
  1248.        your program.  The symbol table is a list of all variables, labels, and
  1249.        internally created compiler addresses.
  1250.  
  1251.        "Extended math" Option
  1252.  
  1253.             By default, ASIC will permit regular integer variables. These
  1254.        variables are very efficient and only require two bytes (or characters)
  1255.        of memory storage.  However, these integers can only hold numbers in the
  1256.        range of -32767 to +32767.  For many programs this is sufficient.
  1257.        However, there may be cases when you want to represent larger integer
  1258.        values.  Because of this, ASIC provides a "long" integer data type.  The
  1259.        long integer requires four bytes of memory storage.  However, it can
  1260.        hold a much larger range of numbers.  A long integer can store numbers
  1261.        in the range of -2,147,483,647 to +2,147,483,647.  When you need to use
  1262.        long integers in your program, you need to turn on this option, so that
  1263.        ASIC can generate the proper code.  When the option is on, you will see
  1264.        a "check mark" symbol next to the option name.  If this option is not
  1265.        turned on and your program contains long integers, ASIC will generate a
  1266.        compiler error.  If this happens, just turn this option on, and re-
  1267.        compile your program.  To "create" a long integer variable or constant,
  1268.        simply append the "&" character to the variable name or constant
  1269.        value(eg, SAMPLEVAR& or 123456&).  For further information on using long
  1270.        integers, refer to Chapter 6, "Language Elements", of the ASIC Manual.
  1271.  
  1272.  
  1273.  
  1274.  
  1275.  
  1276.  
  1277.  
  1278.                                        Page - 19
  1279.  
  1280.  
  1281.  
  1282.  
  1283.  
  1284.  
  1285.  
  1286.                                COMPILE MENU (Continued)
  1287.  
  1288.        "decimal Math" Option
  1289.  
  1290.             Select this option if your program needs to perform decimal math.
  1291.        When the option is on, you will see a "check mark" symbol next to the
  1292.        option name.  When you select this option, ASIC generates supporting
  1293.        code for your program which supports the "Decimal" variable type.
  1294.        Decimal variables may be identified by adding a "@" symbol following the
  1295.        variable name. (eg, BALANCE@).  "Decimal" type variables can contain
  1296.        numbers in the range of +999,999,999,999.99999 to
  1297.        -999,999,999,999.99999.  Unlike floating point numbers in GWBASIC or
  1298.        BASICA, ASIC "Decimal" variables do not exhibit rounding errors.  Full
  1299.        precision is maintained through all 5 decimal places (digits following
  1300.        the fifth decimal place are truncated).  For further information on
  1301.        using decimal variables, refer to Chapter 6, "Language Elements", of the
  1302.        ASIC Manual.  If this option is not turned on and your program contains
  1303.        decimal variables or constants, ASIC will generate a compiler error.  If
  1304.        this happens, just turn this option on, and re-compile your program.
  1305.  
  1306.        "Debugging code" Option
  1307.  
  1308.             This menu option will toggle the "Debugging code" compiler option
  1309.        on or off.  When the option is on, you will see a "check mark" symbol
  1310.        next to the option name.  This compiler option will cause ASIC to
  1311.        generate code required by the ASIC debugger to allow you to set
  1312.        breakpoints, single step through your program, and view/modify program
  1313.        variables.  This option is "on" by default in the integrated
  1314.        environment.  You should leave this option on while you are debugging
  1315.        your program.  When you have everything working properly, you should
  1316.        turn it "off" and recompile your program.  This will reduce the size of
  1317.        your program slightly, and will make it run faster (of course, you can't
  1318.        use the debugger with it, since there is no debugging information
  1319.        available to ASIC any more.  If you need to debug your program again,
  1320.        just recompile with the this option turned "on" again).
  1321.  
  1322.        "View compile errors" Option
  1323.  
  1324.             When you wish to examine the errors from a previous compile of your
  1325.        program, select this option.  If no errors exist, ASIC will so inform
  1326.        you.  Otherwise, ASIC will display the first error message at the bottom
  1327.        of the screen, and it will highlight the line of your program which
  1328.        corresponds to that error.  If you wish to correct the program line,
  1329.        press the <ESC> key.  The cursor will be positioned at the beginning of
  1330.        that program line.  You may also view subsequent compiler errors by
  1331.        pressing the <ENTER> key instead of the <ESC> key.
  1332.  
  1333.  
  1334.  
  1335.  
  1336.  
  1337.  
  1338.  
  1339.  
  1340.  
  1341.  
  1342.                                        Page - 20
  1343.  
  1344.  
  1345.  
  1346.  
  1347.  
  1348.  
  1349.  
  1350.                                COMPILE MENU (Continued)
  1351.  
  1352.        "Write options to disk" Option
  1353.  
  1354.             Writes current compiler options to a file called ASIC.CFG.  When
  1355.        you enter ASIC, ASIC always reads options from this file.  Note that
  1356.        when you open a program, ASIC first checks for a "progname.PRJ" file.
  1357.        The ".PRJ" file ,if found, will override ASIC.CFG.  Since ASIC
  1358.        automatically creates/updates the ".PRJ" file whenever you save a
  1359.        program, normally the only time that the ASIC.CFG options will be used
  1360.        is when you enter the editor with a new file.  Once you save a program
  1361.        the first time, ASIC creates the custom ".PRJ" file for the program.
  1362.        Think of the ASIC.CFG file, then, as the default options for new
  1363.        programs.
  1364.  
  1365.  
  1366.                                    ADVANCED OPTIONS
  1367.                               (SUBMENU OF "COMPILE" MENU)
  1368.  
  1369.             When you select the "Advanced options" option from the "Compile"
  1370.        menu, this sub-menu will be displayed.  These give the advanced
  1371.        programmer the ability to tell ASIC how to produce the compiler output
  1372.        files.
  1373.  
  1374.        "Com output file" Option
  1375.  
  1376.             This option, the "Exe output file", and the "Obj output file"
  1377.        options allow you to tell ASIC what type of output file to produce when
  1378.        compiling.  Only one of these three options may be selected at the same
  1379.        time.  The option that is currently selected will be preceded with a
  1380.        small dot.  This option is the default option.  When you select this
  1381.        option, ASIC will produce a ".COM" output file.  This file can contain a
  1382.        maximum of 64k bytes of program code and data.
  1383.  
  1384.        "Exe output file" Option
  1385.  
  1386.             This option, the "Com output file", and the "Obj output file"
  1387.        options allow you to tell ASIC what type of output file to produce when
  1388.        compiling.  Only one of these three options may be selected at the same
  1389.        time.  The option that is currently selected will be preceded with a
  1390.        small dot.  When you select this option, ASIC will produce a ".EXE"
  1391.        output file.  This output file can contain up to 64k program code, 64k
  1392.        program data, and 64k stack.  ASIC does not produce an intermediate OBJ
  1393.        file, and ASIC uses its internal linker.  Unlike the "Obj output file"
  1394.        option, ASIC does not use the DOS LINK command to produce the EXE file,
  1395.        and no OBJ file is created when using this option.  Turn this option on
  1396.        when:  1) you want to compile large programs, 2) you want to minimize
  1397.        the amount of memory required when your program runs, or 3) you want  to
  1398.        adjust the program stack size.  The only drawback to this option, is
  1399.        that the EXE file is slightly larger on disk than the COM file, and that
  1400.        ASIC only asks DOS for the amount of memory your program needs.  With
  1401.        COM files, DOS gives your program all available memory.  Note:  If you
  1402.        compile a program with this option turned off, and then turn this option
  1403.        on, be sure to recompile your program.
  1404.  
  1405.  
  1406.                                        Page - 21
  1407.  
  1408.  
  1409.  
  1410.  
  1411.  
  1412.  
  1413.  
  1414.                              ADVANCED OPTIONS (Continued)
  1415.  
  1416.        "Obj output file" Option
  1417.  
  1418.             This option, the "Exe output file" option, and the "Com output
  1419.        file" option allow you to tell ASIC what type of output file to produce
  1420.        when compiling.  Only one of these three options may be selected at the
  1421.        same time.  The option that is currently selected will be preceded with
  1422.        a small dot.  When you select this option, ASIC will produce a ".OBJ"
  1423.        output file that is in the standard MS DOS LINK format.  This file is
  1424.        not directly executable.  First, it must be "LINK"ed into a ".EXE" file.
  1425.        ASIC will attempt to call the MS DOS LINK program for you. To do so, it
  1426.        must be able to locate the "LINK.EXE" program (provided with MS DOS).
  1427.        It will search for this file in the current directory, and the "C:\DOS"
  1428.        subdirectory.  If it can't find the file there, it will not be able to
  1429.        link your program.  ASIC does provide a new option, to let you specify
  1430.        the location of the LINK.EXE program (see "Link.EXE path" option).  You
  1431.        may be wondering why you'd want to go through all of the bother of using
  1432.        this option, when you could create an EXE file directly using the "EXE
  1433.        output file" option.  Well, normally you will want to use the "EXE
  1434.        output file" option.  But, the "OBJ output file option provides one
  1435.        important advantage.  Using this option, you can use the CALL SUB
  1436.        statement in your programs, and you can tell ASIC to link in other OBJ
  1437.        files (created with an assembler) with your ASIC program.  See chapter
  1438.        10, "Mixed Language Programming", of the ASIC manual for more
  1439.        information.  Also, refer to the "obJect names..." option, the "liBrary
  1440.        name..." option, and the "Link.exe path..." option on this same menu.
  1441.  
  1442.        "Stack size..." Option
  1443.  
  1444.             This option will allow you to adjust the size of the stack that
  1445.        ASIC generates for your program.  When you select this option, you will
  1446.        be prompted for the number of bytes to allocate to the stack in your
  1447.        program.  If you select a number that is too small for your program's
  1448.        needs, the results when you attempt to run your program will be
  1449.        unpredictable.  The ASIC defaults are 2000 bytes (4000 bytes in
  1450.        debugging mode).  Note that if you compile with debugging mode on and
  1451.        specify a stack size of less than 4000 bytes, ASIC will ignore your
  1452.        stack size and continue to use 4000 bytes.  This option has no effect
  1453.        when you are using the "Com output file" option.
  1454.  
  1455.  
  1456.  
  1457.  
  1458.  
  1459.  
  1460.  
  1461.  
  1462.  
  1463.  
  1464.  
  1465.  
  1466.  
  1467.  
  1468.  
  1469.  
  1470.                                        Page - 22
  1471.  
  1472.  
  1473.  
  1474.  
  1475.  
  1476.  
  1477.  
  1478.                              ADVANCED OPTIONS (Continued)
  1479.  
  1480.        "obJect names..." Option
  1481.  
  1482.             This option allows you to identify other object file names that
  1483.        ASIC should pass to the DOS LINK.EXE program.  This option is ignored by
  1484.        the compiler unless you are compiling with the "Obj output file" Option.
  1485.        When you select this option, ASIC will prompt you for a list of object
  1486.        names.  Each object file name should be separated from each other by a
  1487.        "+" sign.  For example, to identify OBJECT1.OBJ and OBJECT2.OBJ you
  1488.        would enter:  OBJECT1.OBJ+OBJECT2.OBJ for the object names.  Since the
  1489.        LINKer expects the file extensions to be ".OBJ", you can omit the
  1490.        extension as long as it is ".OBJ".  For example, we could have entered:
  1491.        OBJECT1+OBJECT2.  By default, the linker will assume that the object
  1492.        files will be in the current directory, so if they're somewhere else, be
  1493.        sure to include the full path, as in:
  1494.        C:\OBJECT\OBJECT1+C:\OBJECT\OBJECT2.  Refer to the "Mixed Language
  1495.        Programming" chapter of the ASIC Manual for more information.
  1496.  
  1497.        "liBrary names..." Option
  1498.  
  1499.             This option allows you to identify object program libraries (such
  1500.        as those built with the Microsoft LIB command) that ASIC should pass to
  1501.        the DOS LINK.EXE program.  This option is ignored by the compiler unless
  1502.        you are compiling with the "Obj output file" Option.  When you select
  1503.        this option, ASIC will prompt you for a list of library file names.
  1504.        Each library file name should be separated from each other by a "+"
  1505.        sign.  For example, to identify LIB1.LIB and LIB2.LIB you would enter:
  1506.        LIB1.LIB+LIB2.LIB for the library names.  Since the LINKer expects the
  1507.        file extensions to be ".LIB", you can omit the extension as long as it
  1508.        is ".LIB".  For example, we could have entered:  LIB1+LIB2.  By default,
  1509.        the linker will assume that the library file will be in the current
  1510.        directory, so if the libraries are elsewhere, be sure to include the
  1511.        full path, as in:  C:\LIB\LIB1+C:\LIB\LIB2 for example.  Refer to the
  1512.        "Mixed Language Programming" Chapter of the ASIC Manual for more
  1513.        information.
  1514.  
  1515.        "Link.exe path..." Option
  1516.  
  1517.             This option is used to tell ASIC where to find the MS DOS LINK.EXE
  1518.        program.  This option is ignored by the compiler, unless you are using
  1519.        the "Obj output file" Option.  When you use the "Obj output file"
  1520.        Option, ASIC utilizes the LINK.EXE program, which is provided with MS
  1521.        DOS, to link your ASIC program and additional object files into an MS
  1522.        DOS EXE file.  If you do not provide a path, ASIC will attempt to find
  1523.        LINK.EXE under the current directory, and under the "C:\DOS" directory
  1524.        (if applicable).  If it can't find the program in either place, the EXE
  1525.        file will not be built.  When you select this option, you will be
  1526.        prompted to enter the directory in which ASIC may find the LINK.EXE
  1527.        program.  For example, if you determined that the LINK.EXE program is
  1528.        stored under "C:\UTIL" on your hard disk, you would enter:  C:\UTIL for
  1529.        this option.  On future compiles, ASIC will look for the LINK.EXE file
  1530.        in the "C:\UTIL" directory.  Instead of using this option, you may also
  1531.        copy the LINK.EXE file to your ASIC directory.
  1532.  
  1533.  
  1534.                                        Page - 23
  1535.  
  1536.  
  1537.  
  1538.  
  1539.  
  1540.                                        RUN MENU
  1541.  
  1542.             The "Using the ASIC Debugger" Chapter has additional information on
  1543.        the debugger and it's options.  You may wish to refer to it, should you
  1544.        need more information than is provided below.
  1545.  
  1546.        "Run your program <F5>" Option
  1547.  
  1548.             After you have successfully compiled your program, you can select
  1549.        this option to cause ASIC to load and execute your program.  After your
  1550.        program ENDs, ASIC will return you to the editor.  ASIC will save the
  1551.        edit buffer before loading and executing your program.  If you are
  1552.        running a program containing debugging code, this option will cause ASIC
  1553.        to run your program up to the first breakpoint it encounters, or through
  1554.        the end of your program if you haven't set any breakpoints.  If you are
  1555.        already "paused" at a breakpoint, selecting this option will cause your
  1556.        program to resume execution at the statement following the breakpoint,
  1557.        and run up to the next breakpoint or to the end of your program, if no
  1558.        further breakpoints are encountered.  This option may also be selected
  1559.        outside of the "Run menu" by pressing function key <F5>.
  1560.  
  1561.        "Breakpoint toggle <F9>" Option
  1562.  
  1563.             If you have compiled your program with the "Debugging code" option
  1564.        turned on, you may use this option to set breakpoints.  You can have up
  1565.        to 20 breakpoints active at a time.  When you run your program with
  1566.        breakpoints set, ASIC will pause your program when it tries to execute a
  1567.        line on which you have set a breakpoint.  At this time, you can view or
  1568.        modify variables, or view the screen output produced by your program.
  1569.        You can then resume program execution by selecting the "Run your
  1570.        program" option from the run menu.  If you select this option and the
  1571.        current statement in the edit buffer already has a breakpoint set, then
  1572.        the breakpoint for that source statement will be removed (toggled off).
  1573.        Lines at which you have set a breakpoint will be displayed in reverse
  1574.        video.  Also, when you run your program and ASIC stops at a breakpoint,
  1575.        ASIC will display the next line to execute in reverse video on the
  1576.        second line of the screen with a red background (underlined if you have
  1577.        a monochrome system).  This option may also be selected outside of the
  1578.        "Run" Menu by pressing function key <F9>.
  1579.  
  1580.        "Trace <F8>" Option
  1581.  
  1582.             If you have compiled your program with the "Debugging code" option
  1583.        turned on, you may use this option to execute your program one statement
  1584.        at a time.  After you select this option, ASIC will execute the next
  1585.        program statement in your program, and pause, displaying the next line
  1586.        which will be executed in reverse video with a red background
  1587.        (underlined if you have a monochrome system).  At this time, you can
  1588.        view or modify variables, or view the screen output produced by your
  1589.        program.  You can then resume program execution by selecting the "Run
  1590.        your program" option from the run menu, or by selecting the "Trace"
  1591.        option again.  This option may also be selected outside of the "Run"
  1592.        Menu by pressing function key <F8>.
  1593.  
  1594.  
  1595.  
  1596.  
  1597.  
  1598.                                        Page - 24
  1599.  
  1600.  
  1601.  
  1602.  
  1603.  
  1604.                                  RUN MENU (Continued)
  1605.  
  1606.        "Modify variable..." Option
  1607.  
  1608.             If you have compiled your program with the "Debugging code" option
  1609.        turned on, you may use this option to modify the contents of variables
  1610.        in your program while your program is paused at a breakpoint or
  1611.        following a "Trace" command.  When you select this option, ASIC will ask
  1612.        you for the variable name.  After you enter the variable name, ASIC will
  1613.        ask you for the new value to be stored in the variable.  If the variable
  1614.        is an array, ASIC will ask you which element of the array to modify.
  1615.  
  1616.        "Watch variable... <F6>" Option
  1617.  
  1618.             If you have compiled your program with the "Debugging code" option
  1619.        turned on, you may use this option to view the contents of variables in
  1620.        your program, while your program is paused at a breakpoint or following
  1621.        a "Trace" command.  After you enter the variable name, ASIC will open a
  1622.        "Watch" window at the bottom of the screen showing you the variable name
  1623.        and the current value.  As you continue execution of your program and
  1624.        reach a new breakpoint, the values of variables will be updated to
  1625.        reflect their new values.  In this way you can watch the changing values
  1626.        of variables in your program without inserting "PRINT variablename"
  1627.        statements in your program.  Up to 10 variables may be watched at a
  1628.        time.  If you enter a variable name which is an array, ASIC will ask you
  1629.        which element of the array you wish to watch.  This option may also be
  1630.        selected outside of the "Run" Menu by pressing function key <F6>.
  1631.  
  1632.        "Unwatch variable... <F7>" Option
  1633.  
  1634.             If you have compiled your program with the "Debugging code" option
  1635.        turned on, you may use this option to remove variables from the "Watch"
  1636.        window (see previous option).  When you select this option, you will be
  1637.        asked for a variable name to remove from the window.  If the variable is
  1638.        an array, you will also be asked which element of the array.  ASIC will
  1639.        then remove the variable from the watch window, and resize the window
  1640.        accordingly.  Since only 10 variables may be watched concurrently, you
  1641.        may need to remove variables which are no longer needed from the "Watch"
  1642.        Window using this command.  This option may also be selected outside of
  1643.        the "Run" Menu by pressing function key <F7>.
  1644.  
  1645.        "Abort execution" Option
  1646.  
  1647.             If you are running your program, and it is paused at a breakpoint,
  1648.        you may select this option to abort the execution of your program.  Your
  1649.        program will be terminated immediately.
  1650.  
  1651.        "Clear all break/watch" Option
  1652.  
  1653.             If you have set breakpoints or watch variable options, you may use
  1654.        this option to remove all of them at once, instead of removing them one
  1655.        at a time using the "Toggle breakpoint" or "Unwatch variable" options.
  1656.  
  1657.  
  1658.  
  1659.  
  1660.  
  1661.  
  1662.                                        Page - 25
  1663.  
  1664.  
  1665.  
  1666.  
  1667.  
  1668.                                  RUN MENU (Continued)
  1669.  
  1670.        "Program arguments..." Option
  1671.  
  1672.             This option allows you to pass command line arguments to your
  1673.        programs, which may be retrieved by your program using the COMMAND$
  1674.        statement.  If you are testing outside the integrated environment, you
  1675.        would normally specify the command line arguments by typing
  1676.        "progname arguments".  However, in the integrated environment, since
  1677.        ASIC is executing your program for you, this option is a means to pass
  1678.        the "arguments" to your program as if they had been typed on the command
  1679.        line following your program name.
  1680.  
  1681.        "Swap to user screen <F4>" Option
  1682.  
  1683.             Whenever ASIC pauses your program at a breakpoint, it saves the
  1684.        screen created by your program in a memory buffer.  You may select this
  1685.        option to view your program screen output.  When you are done viewing
  1686.        your program's output, press a key to return to viewing the ASIC editor.
  1687.        This function may also be selected outside the "Run" Menu by pressing
  1688.        the <F4> function key.
  1689.  
  1690.  
  1691.                                       STATUS LINE
  1692.  
  1693.             The bottom line of the ASIC screen is called the "Status Line".  As
  1694.        it's name implies, it is used to display various types of status
  1695.        information.  At the left of the status line "FILE: xxxxxxxx.xxx" will
  1696.        display the name of the file which is currently loaded in the edit
  1697.        buffer.  If you haven't opened a file yet, the file name will be blank.
  1698.  
  1699.  
  1700.             After the file name is the "File Modified Indicator".  If you have
  1701.        entered any changes in the edit buffer, and have not saved them to disk,
  1702.        an "*" will appear to indicate this.  If the edit buffer has not been
  1703.        modified since the last save to disk, no "*" will be present.
  1704.  
  1705.             The next piece of information is "Mode:".  Mode will always display
  1706.        one of two values:  "Insert" or "Ovrstr".  In "Insert" mode, any
  1707.        characters you type in the edit buffer will be inserted at the cursor
  1708.        position, and the characters to the right of the cursor will be shifted
  1709.        to the right by one.  In "Ovrstr" mode, any characters you type in the
  1710.        edit buffer will overlay (and thus destroy) the character at the cursor
  1711.        position.  You can change back and forth between these two modes by
  1712.        pressing the <INS> key on your keypad.
  1713.  
  1714.             To the right of "Mode:" ASIC displays how many thousands of bytes
  1715.        are still available for use by ASIC.   You will see this number decrease
  1716.        as you add more lines to your programs.
  1717.  
  1718.             The "Line: nnnn" status indicator, will identify which line of the
  1719.        file is being displayed.  For example, if the display reads "Line: 100",
  1720.        the line containing the cursor is the 100th line in the file. When ASIC
  1721.        is reading or writing your program to/from disk, it will display a
  1722.        running total of the number of records read/written in this field.
  1723.  
  1724.  
  1725.  
  1726.                                        Page - 26
  1727.  
  1728.  
  1729.  
  1730.  
  1731.  
  1732.                                 STATUS LINE (Continued)
  1733.  
  1734.  
  1735.             The "Row:" and "Col:" numbers identify the relative position of the
  1736.        cursor within the "Edit Window".
  1737.  
  1738.  
  1739.                                       EDIT WINDOW
  1740.  
  1741.             The edit window is the area of the screen where your program is
  1742.        displayed.  It displays up to 21 lines of your program at a time.  You
  1743.        can use the keys described below to manipulate the text in this window.
  1744.  
  1745.  
  1746.                                     KEYBOARD USAGE
  1747.  
  1748.             Most keys on the keyboard behave in ASIC just as you'd expect.  The
  1749.        key usages which might not be obvious are described here.
  1750.  
  1751.        <ESC>          Exit from any menu without taking any action.
  1752.  
  1753.        <TAB>          Move the cursor to the next "tab stop".  Tab stops in
  1754.                       ASIC are fixed at every fourth column (4,8,12,etc).
  1755.  
  1756.        <HOME>         Move the cursor to the beginning of the current line.
  1757.  
  1758.        <END>          Move the cursor to the first blank character following
  1759.                       the last non-blank character on the current line.
  1760.  
  1761.        <DEL>          Delete the character at the cursor position.
  1762.  
  1763.        <INS>          Toggle between Insert and Overstrike Modes.
  1764.  
  1765.        <PGUP>         Display the previous "page" of the edit buffer.
  1766.  
  1767.        <PGDN>         Display the next "page" of the edit buffer.
  1768.  
  1769.        <Ctl-PGUP>     Display the first "page" of the edit buffer.
  1770.  
  1771.        <Ctl-PGDN>     Display the last "page" in the edit buffer.
  1772.  
  1773.        <Backspace>    Delete the character to the left of the cursor
  1774.                       position, and move the cursor one column to the left.
  1775.        <Up Arrow>     Moves cursor up one line.
  1776.  
  1777.        <Down Arrow>   Moves cursor down one line.
  1778.  
  1779.  
  1780.  
  1781.  
  1782.  
  1783.  
  1784.  
  1785.  
  1786.  
  1787.  
  1788.  
  1789.  
  1790.                                        Page - 27
  1791.  
  1792.  
  1793.  
  1794.  
  1795.  
  1796.                               KEYBOARD USAGE (Continued)
  1797.  
  1798.  
  1799.        <Left Arrow>   Moves cursor left one column.
  1800.  
  1801.        <Right Arrow>  Moves cursor right one column.
  1802.  
  1803.        <Ctl-LfArrow>  Moves cursor left one word.
  1804.  
  1805.        <Ctl-RtArrow>  Moves cursor right one word.
  1806.  
  1807.        <Ctl-L>        Repeats the last "Search" command.  See Edit Menu
  1808.                       Section of this chapter for more information.
  1809.  
  1810.        <Alt-A>        Add a line following the line containing the cursor.
  1811.  
  1812.        <Alt-D>        Delete the line containing the cursor.
  1813.  
  1814.        <Alt-I>        Insert a line before the line containing the cursor.
  1815.  
  1816.        <Alt-X>        Exit ASIC.
  1817.  
  1818.        <F1>           Displays a help screen.
  1819.  
  1820.        <CTL-F1>       Displays help information for the keyword located at
  1821.                       the cursor position.
  1822.  
  1823.        <F2>           Saves the edit buffer to disk.
  1824.  
  1825.        <F3>           Load a new file into the edit buffer.
  1826.  
  1827.        <F4>           Swaps the display to the output from your program
  1828.                       temporarily.  See Run Menu Section of this chapter for
  1829.                       more information.
  1830.  
  1831.        <F5>           Runs your program.  See Run Menu Section of this
  1832.                       chapter for more information.
  1833.  
  1834.        <F6>           Add a variable to the "Watch" Window.  See Run Menu
  1835.                       Section of this chapter for more information.
  1836.  
  1837.        <F7>           Remove a variable from the "Watch" Window.  See Run
  1838.                       Menu Section of this chapter for more information.
  1839.  
  1840.        <F8>           Execute a single statement of your program.  See Run
  1841.                       Menu Section of this chapter for more information.
  1842.  
  1843.        <F9>           Toggle breakpoint on/off at the current edit buffer
  1844.                       line.  See Run Menu Section of this chapter for more
  1845.                       information.
  1846.  
  1847.        <F10>          Compile your program.  See Compile Menu Section of
  1848.                       this chapter for more information.
  1849.  
  1850.        <enter>        In Insert mode, pressing <enter> is identical to
  1851.                       pressing <Alt-A>.  In OvrStr mode, pressing <enter>
  1852.                       is identical to pressing the <Down Arrow> key.
  1853.  
  1854.                                        Page - 28
  1855.  
  1856.  
  1857.  
  1858.  
  1859.  
  1860.  
  1861.  
  1862.  
  1863.                                         A S I C
  1864.  
  1865.                                        Chapter 4
  1866.  
  1867.                                   Using the Debugger
  1868.  
  1869.  
  1870.  
  1871.                                      INTRODUCTION
  1872.  
  1873.             The source level debugger in ASIC's integrated programming
  1874.        environment helps you debug your programs by allowing you to "peek"
  1875.        inside them as they're running.  You can single step through your
  1876.        programs, or select places in the program where you wish execution to
  1877.        pause by setting breakpoints.  Then, while the program is paused, you
  1878.        can view or modify any of your program's variables, and also examine the
  1879.        screen output created by your program.
  1880.  
  1881.             All of the debugger's commands can be selected from the run menu,
  1882.        and they are described in the "RUN MENU" Section of Chapter 3,
  1883.        "Integrated Editor/Compiler Environment".  Many of the debugger commands
  1884.        may be selected outside the "Run" menu, by pressing a function key (eg,
  1885.        <F5>,<F6>,etc).  A complete list of the function keys available is
  1886.        contained in Chapter 3, in the "KEYBOARD USAGE" Section.
  1887.  
  1888.             This chapter explains how to use the debugger with a short tutorial
  1889.        which guides you through a sample debugging session.  The tutorial is
  1890.        followed by a reference section which you should read after completing
  1891.        the tutorial.
  1892.  
  1893.                                    DEBUGGER TUTORIAL
  1894.  
  1895.             The debugger tutorial follows the same format as the general
  1896.        tutorial in chapter 2.  You should complete (or at least review) the
  1897.        general tutorial before taking the debugger tutorial.
  1898.  
  1899.             This tutorial will use a program file provided with your ASIC
  1900.        compiler package called "DBGTUTOR.ASI".  If you are running from a hard
  1901.        disk, make sure it is in the ASIC directory.  If you are running from a
  1902.        two-floppy system, make sure it is on the diskette in drive b:, with the
  1903.        compiler in drive a:.
  1904.  
  1905.        NOTE:  Floppy disk users should verify that the ASIC compiler diskette
  1906.        is in drive A: and the "DBGTUTOR.ASI" disk is in drive b: before
  1907.        proceeding.
  1908.  
  1909.        Let's get started:
  1910.  
  1911.             FLOPPY TYPE-->      A: <enter>
  1912.                                 ASIC B:DBGTUTOR <enter>
  1913.  
  1914.             HARD TYPE-->        C: <enter>
  1915.                                 CD C:\ASIC <enter>
  1916.                                 ASIC DBGTUTOR <enter>
  1917.  
  1918.                                        Page - 29
  1919.  
  1920.  
  1921.  
  1922.  
  1923.  
  1924.        You should be in ASIC now, and you should see a source program.  The
  1925.        first few lines should contain:
  1926.  
  1927.                            dim scores(10)
  1928.                            data 55,33,877,99,44,101,21,88,105,1
  1929.                            rem DBGTUTOR.ASI
  1930.                                 .
  1931.                                 . (etc)
  1932.                                 .
  1933.  
  1934.        This sample program will sort an array of 10 scores into ascending
  1935.        sequence.  It uses a simple "bubble" sort algorithm.  The "bubble" sort
  1936.        algorithm simply steps through each element of the array and compares it
  1937.        to its next higher neighbor.  If its neighbor's value is less than its
  1938.        own, the two values are swapped.  It is necessary to execute this
  1939.        process N-1 times where N= number of items to sort.  Here's why.  Let's
  1940.        say the lowest value to be sorted was "1" and it is in array element
  1941.        "10" (assume 10 numbers will be sorted).  The first swapping pass will
  1942.        result in the "1" being swapped from element 10 to element 9 of the
  1943.        array.  An additional 8 passes through the array are necessary to move
  1944.        the "1" to array element number 1.  This algorithm gets its name,
  1945.        because the process of moving the elements has been compared to that of
  1946.        bubbles slowly rising to the surface.
  1947.  
  1948.        This program has a list of ten scores to be sorted.  Line 5 of the
  1949.        program will read the ten scores to an array called "Scores", and also
  1950.        print the original values (before the sort) to the screen.  Then two
  1951.        loops will execute at statements 8 and 9 in the program to perform the
  1952.        bubble sort as described above.  Finally, after the sort is complete,
  1953.        the sorted values will be displayed.
  1954.  
  1955.        First, let's compile the program.  When we plan to use the debugger, we
  1956.        must set the "Debugging code" option on.  This is done on the Compile
  1957.        Menu.  However, the default in the integrated environment is "Debugging
  1958.        code" on.  Let's take a look to be sure:
  1959.  
  1960.  
  1961.             TYPE-->        <Alt><c>
  1962.  
  1963.        The compile menu should pop open, and you should see a check mark next
  1964.        to the "Debugging code" option.  If you don't, press the letter "D", and
  1965.        a check mark should appear.  Once you've verified that the option is on,
  1966.        we can compile the program.  Notice that there is an <F10> next to the
  1967.        option.  Instead of opening this menu and selecting the "Compile"
  1968.        option, we could have pressed <F10>.  Let's try it.  First, let's close
  1969.        the menu (Function keys don't work inside a menu):
  1970.  
  1971.             TYPE-->        <ESC>
  1972.  
  1973.        The menu should have closed.  Now let's compile using the function key:
  1974.  
  1975.             TYPE-->        <F10>
  1976.  
  1977.        You should see the compiler screen pop up, and compile the program.  No
  1978.        errors should be detected.  Now we're ready to test the program.  First,
  1979.        let's set a breakpoint so we can easily view the screen output, Use the
  1980.  
  1981.  
  1982.                                        Page - 30
  1983.  
  1984.  
  1985.  
  1986.  
  1987.  
  1988.        down arrow key to position the cursor on line 20 (the line number is
  1989.        displayed on the ASIC status line).  Line 20 should contain an "END"
  1990.        statement.  Let's open the run menu and set a breakpoint:
  1991.  
  1992.  
  1993.             TYPE-->        <Alt><r>
  1994.                            <b>
  1995.  
  1996.        The "END" statement should now be displayed in reverse video.  That
  1997.        tells us that a breakpoint has been set there.  Did you notice that the
  1998.        breakpoint option on the menu also had a function key listed.  We could
  1999.        set a breakpoint without opening a menu, by pressing <F9> instead.  Now
  2000.        that we've set a breakpoint, let's run the program and see how it works:
  2001.  
  2002.             TYPE-->        <Alt><r>
  2003.                            <r>
  2004.  
  2005.        Note that we could have pressed the short cut key of <F5> to run the
  2006.        program instead of selecting the option from the menu.  At this point
  2007.        our program is running, but is paused at the breakpoint we set on line
  2008.        20.  When you reach a breakpoint, ASIC will position the breakpointed
  2009.        line on the second line of the edit window, highlighted in red (or
  2010.        underlined, if you have a monochrome system). ASIC has interrupted the
  2011.        program before it executed the line with the breakpoint, in this case
  2012.        "END".  Let's take a look at the screen output of the program to see if
  2013.        it worked:
  2014.  
  2015.             TYPE-->        <Alt><r>
  2016.                            <s>
  2017.  
  2018.        Note we could also select the "Swap" function by pressing <F4> without
  2019.        opening a menu.  You should now see the output from the program on the
  2020.        screen.  It should look something like:
  2021.  
  2022.        Original Scores:
  2023.            55    33   877    99    44   101    21    88   105     1
  2024.        Sorting...
  2025.        Here are the sorted scores:
  2026.            33    55    99    44   101    21    88   105     1   877
  2027.  
  2028.        Well, that doesn't look quite right.  Maybe we can use the debugger to
  2029.        figure out what went wrong.  First, let's allow the program to run to
  2030.        completion (remember, we're paused at a breakpoint on the "END"
  2031.        statement).  Swap back to the ASIC screen from the user screen by
  2032.        pressing any key:
  2033.  
  2034.             TYPE-->        <enter>
  2035.  
  2036.        You should see the editor screen again.  Now let's tell ASIC to resume
  2037.        program execution:
  2038.  
  2039.             TYPE-->        <Alt><r>
  2040.                            <r>
  2041.  
  2042.        ASIC has executed the END statement, and our program has terminated.
  2043.        You should see the message "Program Terminated Normally (0)".  (The "0"
  2044.        is the return code set by the program.  You can set return codes in your
  2045.  
  2046.                                        Page - 31
  2047.  
  2048.  
  2049.  
  2050.  
  2051.  
  2052.        programs using the END statement.  Refer to Chapter 7 for details.).
  2053.        Now we'll set another breakpoint in the program.  Move the cursor to
  2054.        line 7 (the status line should now say LINE: 7) using the arrow keys.
  2055.        The cursor should now be positioned on the statement which says:  PRINT
  2056.        "Sorting...".  Set a breakpoint here:
  2057.  
  2058.             TYPE-->        <F9>
  2059.  
  2060.        The source statement should now appear in reverse video.  We used the
  2061.        shortcut key <F9> to set the breakpoint this time, but you could have
  2062.        opened the Run Menu, and selected the Breakpoint option and done the
  2063.        same thing.  Let's remove the breakpoint:
  2064.  
  2065.             TYPE-->        <F9>
  2066.  
  2067.        Line 7 should no longer be highlighted.  The same command is used to
  2068.        turn breakpoints on or off for a source line.  ASIC just checks to see
  2069.        if a breakpoint is already set at that source line when you select the
  2070.        breakpoint command.  If one is set, it "toggles" it off (ie removes it),
  2071.        otherwise, it "toggles" it on (ie sets a breakpoint).  This exercise was
  2072.        just to show you how to remove a breakpoint, let's go ahead and set it
  2073.        again:
  2074.  
  2075.             TYPE-->        <F9>
  2076.  
  2077.        Line 7 should be highlighted again (the breakpoint is set).
  2078.        It might be nice to see what's in some of our program's variables, so
  2079.        let's "watch" some variables.  Open the Run Menu, select the Watch
  2080.        command, and tell ASIC you want to watch variable "I".
  2081.  
  2082.             TYPE-->        <Alt><r>
  2083.                            <w>
  2084.                            i<enter>
  2085.  
  2086.        ASIC should have opened a "Watch" window at the bottom of the screen.
  2087.        You should see the variable name "I" at the left, followed by a ":".
  2088.        Following the ":" is the current value of that variable.  The number
  2089.        there now doesn't really mean anything, since our program is not
  2090.        running.  But once the we start the program, this number should
  2091.        represent the actual value of the variable "I".
  2092.  
  2093.        Let's watch a few more variables: j, j1, and scores(1).  This time,
  2094.        we'll use the shortcut key for the watch command:
  2095.  
  2096.             TYPE-->        <F6>
  2097.                            j<enter>
  2098.  
  2099.        Variable "J" should now be in the watch window.
  2100.  
  2101.             TYPE-->        <F6>
  2102.                            j1<enter>
  2103.  
  2104.        Variable "J1" should now be in the watch window.  When we watch
  2105.        "scores", we'll also have to tell ASIC which element we want to watch by
  2106.        entering a subscript, since "scores" is an array.  First ASIC will
  2107.        prompt you for the variable name.  Type it, without the subscript.  ASIC
  2108.        will prompt you for the numeric subscript.
  2109.  
  2110.                                        Page - 32
  2111.  
  2112.  
  2113.  
  2114.  
  2115.  
  2116.  
  2117.  
  2118.             TYPE-->        <F6>
  2119.                            scores<enter>
  2120.                            <1><enter>
  2121.  
  2122.        Scores(1) should now be in the watch window.  Now we're ready to run the
  2123.        program again:
  2124.  
  2125.             TYPE-->        <F5>
  2126.  
  2127.        Again we selected the short cut key, you could have selected the "Run
  2128.        your program" option from the "Run" Menu.  The second line of the edit
  2129.        screen should show the PRINT "Sorting..." statement (highlighted in red,
  2130.        or underlined if you have a monochrome monitor).  The variables in the
  2131.        watch window should have the following values:
  2132.  
  2133.             I:    11
  2134.             J:     0
  2135.             J1:     0
  2136.             SCORES(1):    55
  2137.  
  2138.        Let's execute the next statement by using the Trace command:
  2139.  
  2140.             TYPE-->        <Alt><r>
  2141.                            <t>
  2142.  
  2143.        ASIC has executed the PRINT "Sorting..." statement and has paused
  2144.        execution on the "FOR I" statement on line 8 of the program.  Since the
  2145.        PRINT statement did not modify any variables, the numbers in the watch
  2146.        window should remain unchanged.  Let's Trace one more statement, this
  2147.        time, we'll use the short cut key:
  2148.  
  2149.             TYPE-->        <F8>
  2150.  
  2151.        ASIC has executed the "FOR I" statement on line 8, and is now paused on
  2152.        statement "FOR J" on line 9 of the program.  Something looks wrong
  2153.        though.  Even though we executed the first "FOR I" statement, the
  2154.        variable "I" still contains "11".  It should contain "1".  If you look
  2155.        at line 8, you'll see that the FOR statement was mistyped, it reads:
  2156.        "FOR I = I to 9", instead of "FOR I=1 to 9".  Since the program also
  2157.        used variable "I" to READ the data into the array, "I" still contains
  2158.        the value "11".  Since "11" is greater than the "TO" value of the "FOR"
  2159.        loop, the FOR loop on line 8 is executed only 1 time instead of 9 times.
  2160.        That's why the data is not being fully sorted.  With the ASIC debugger,
  2161.        we can continue testing without recompiling, by modifying the value of
  2162.        "I" to "1", so we can see if the rest of our logic is correct.  If
  2163.        changing "I" to "1" works, then we can go back and modify the "FOR"
  2164.        statement and recompile the program to correct the program permanently.
  2165.        Modify the value of "I" to "1":
  2166.  
  2167.             TYPE-->        <Alt><r>
  2168.                            <m>
  2169.                            i<enter>
  2170.                            <1><enter>
  2171.  
  2172.  
  2173.  
  2174.                                        Page - 33
  2175.  
  2176.  
  2177.  
  2178.  
  2179.  
  2180.  
  2181.        The watch window should now show the value of "I" as 1.  We can resume
  2182.        program execution at this point by selecting the "Run your program"
  2183.        option.  We'll use the short cut key again:
  2184.  
  2185.             TYPE-->        <F5>
  2186.  
  2187.        ASIC should pause the program at the next breakpoint, which is on line
  2188.        20.  This statement contains the "END" command.  Now let's see if the
  2189.        program worked, by swapping to the user screen:
  2190.  
  2191.             TYPE-->        <F4>
  2192.  
  2193.        Again, we used the short cut key.  You should see the following on your
  2194.        screen:
  2195.  
  2196.        Original Scores:
  2197.            55    33   877    99    44   101    21    88   105     1
  2198.        Sorting...
  2199.        Here are the sorted scores:
  2200.             1    21    33    44    55    88    99   101   105   877
  2201.  
  2202.        It looks like the program worked.  Let's return to the editor screen.
  2203.  
  2204.             TYPE-->        <enter>
  2205.  
  2206.        Now we could press <F5> to resume execution and in this case terminate,
  2207.        since the END statement is the next one to execute.  But let's look at
  2208.        another way to terminate a program.  While at a breakpoint, you can
  2209.        select the "Abort your program" option, which instructs ASIC to
  2210.        terminate your program immediately, without executing any more of your
  2211.        program.  Let's try it:
  2212.  
  2213.             TYPE-->        <Alt><r>
  2214.                            <a>
  2215.  
  2216.        ASIC should display the message "Program Terminated Normally (0)".  At
  2217.        this point, we'll just exit from ASIC, but normally, you would fix the
  2218.        FOR statement using the editor, save the file, recompile the program,
  2219.        and retest it to make sure the "bug" is really fixed.
  2220.  
  2221.             TYPE-->        <Alt><f>
  2222.                            <x>
  2223.  
  2224.        You should be back at the DOS prompt now.  That concludes the brief
  2225.        introduction to the ASIC debugger.  The rest of this chapter provides
  2226.        some additional reference material for the debugger.  Chapter 3 provides
  2227.        additional information about each of the debugging commands.
  2228.  
  2229.  
  2230.  
  2231.  
  2232.  
  2233.  
  2234.  
  2235.  
  2236.  
  2237.  
  2238.                                        Page - 34
  2239.  
  2240.  
  2241.  
  2242.  
  2243.  
  2244.  
  2245.                                      DEBUGGER TIPS
  2246.  
  2247.        1)  WHEN YOU ARE DONE DEBUGGING YOUR PROGRAM, YOU SHOULD RECOMPILE
  2248.            WITH THE "DEBUGGING CODE" OPTION TURNED OFF. Although your program
  2249.            can run from the DOS command line with debugging code present, it
  2250.            will increase the program size and execution times.  Recompiling
  2251.            with the "Debugging code" option off will insure your programs
  2252.            will be smaller and faster.
  2253.  
  2254.        2)  Remember that the default option on the command line compiler is
  2255.            "Debugging code" off.  The default option in the integrated
  2256.            environment is "Debugging code" on.
  2257.  
  2258.        3)  Breakpoints/Watches are automatically cleared when you
  2259.            OPEN or COMPILE a file.
  2260.  
  2261.        4)  If you change source lines in a program while a program
  2262.            is running, without recompiling, source statements will
  2263.            not match executable code.  Abort the running program
  2264.            and recompile after making code changes.
  2265.  
  2266.        5)  Breakpoints are set in the edit buffer relative to the
  2267.            beginning of the buffer.  If you insert/delete lines in
  2268.            the buffer, the breakpoints will still be set at the
  2269.            same relative line number from the beginning of the
  2270.            buffer.
  2271.  
  2272.        6)  ASIC takes over the INT 3 Interrupt vector for debugging
  2273.            purposes. It re-installs the default vector when you
  2274.            exit ASIC.
  2275.  
  2276.        7)  You must compile with the "Debugging code" option to use
  2277.            source level debugging.
  2278.  
  2279.        8)  If you wish to run a program from the beginning again
  2280.            while its already running,  select the "Abort your
  2281.            program" option from the Run menu.  Then, select the
  2282.            "Run your program" option.
  2283.  
  2284.        9)  If you select the Abort option from the Run menu, your
  2285.            program's files will NOT be closed gracefully.  That
  2286.            is, data in the buffers will not be flushed to disk.
  2287.  
  2288.        10) You may still run a program in the integrated environment that
  2289.            has been compiled without the Debugging code option.  You just
  2290.            won't be able to use the debugging commands (eg,
  2291.            Breakpoints/Watches).
  2292.  
  2293.        11) Toggling a breakpoint on/off will clear any block of
  2294.            text you had previously marked for editing (eg, MOVE,
  2295.            COPY).
  2296.  
  2297.  
  2298.  
  2299.  
  2300.  
  2301.  
  2302.                                        Page - 35
  2303.  
  2304.  
  2305.  
  2306.  
  2307.  
  2308.                                DEBUGGER TIPS (Continued)
  2309.  
  2310.        12) When modifying array variables, make sure that the
  2311.            subscript you specify is valid.  For example, if you
  2312.            "DIM A(10)", make sure the subscript you specify is in
  2313.            the range of 0 to 10.  ASIC does not check the range of
  2314.            a subscript.  If you specify a subscript that exceeds
  2315.            the valid range for that variable, your program may
  2316.            crash.
  2317.  
  2318.        13) You can pass arguments to programs using the "Arguments"
  2319.            option on the Run Menu.  You may retrieve these options
  2320.            in your program with the COMMAND$ statement.  Using the
  2321.            "Arguments" option is equivalent to specifying arguments
  2322.            following the program name, when you run your program
  2323.            from the DOS command line.
  2324.  
  2325.        14) The compiler allows variable names up to 80 characters in
  2326.            length.  The debugger only uses the first 30 characters of a
  2327.            variable name.  When the debugger finds two variables whose names
  2328.            are not unique within 30 characters, it will always select the
  2329.            first one it finds (this applies to the Watch/Unwatch/Modify
  2330.            Variables commands).
  2331.  
  2332.        15) ASIC will allow you to set a breakpoint on a "FOR" statement.
  2333.            However, you should be aware that the source statement containing
  2334.            the "FOR" is executed only once (to initialize the loop).  When
  2335.            the "NEXT" statement executes, control transfers back to the line
  2336.            following the "FOR", instead of the "FOR".  For example, in the
  2337.            following code fragment:
  2338.  
  2339.             FOR I = 1 TO 3           <---Executes 1 time to initialize loop
  2340.                  PRINT I             <---Executes 3 times
  2341.                  A=A+1               <---Executes 3 times
  2342.             NEXT I                   <---Executes 3 times, loops back to
  2343.                                          "PRINT I", not to "FOR I= 1 TO 3"
  2344.  
  2345.        16)  Because a single machine language instruction could span multiple
  2346.             CODE statements, ASIC does not allow breakpoints on CODE
  2347.             statements.
  2348.  
  2349.  
  2350.  
  2351.  
  2352.  
  2353.  
  2354.  
  2355.  
  2356.  
  2357.  
  2358.  
  2359.  
  2360.  
  2361.  
  2362.  
  2363.  
  2364.  
  2365.  
  2366.                                        Page - 36
  2367.  
  2368.  
  2369.  
  2370.  
  2371.  
  2372.  
  2373.  
  2374.  
  2375.                                         A S I C
  2376.  
  2377.                                        Chapter 5
  2378.  
  2379.                              Command Line Compiler Options
  2380.  
  2381.  
  2382.                                   COMMAND LINE SYNTAX
  2383.  
  2384.  
  2385.        Invoke the command line version of the compiler as follows:
  2386.  
  2387.  
  2388.             ASICC filename option1 option2 option3[...optionN]
  2389.  
  2390.                       or
  2391.  
  2392.             ASICC filename.PRJ option1 option2 option3[...optionN]
  2393.  
  2394.  
  2395.             Where:  filename    is the name of the source program or project
  2396.                                 file to be compiled.  Source files must have
  2397.                                 the file extension ".ASI", although the
  2398.                                 extension may be omitted from the command line.
  2399.  
  2400.             filename.PRJ        Project files may be specified instead of a
  2401.                                 source file name.  These have a ".PRJ"
  2402.                                 extension, and the ".PRJ" extension must be
  2403.                                 typed if you want ASIC to use the project file
  2404.                                 for the compile. Specifying a project file
  2405.                                 tells ASIC to look for a project file (created
  2406.                                 by the integrated environment), and use the
  2407.                                 options from this file during the compile.
  2408.                                 ASIC will then strip off the ".PRJ" extension
  2409.                                 and try to compile a file with the same
  2410.                                 filename as the ".PRJ" file, but with a ".ASI"
  2411.                                 extension.
  2412.  
  2413.             optionN             specifies any options desired.  No options are
  2414.                                 required, but more than one can be specified as
  2415.                                 long as you insert a space between each one.
  2416.  
  2417.  
  2418.  
  2419.  
  2420.  
  2421.  
  2422.  
  2423.  
  2424.  
  2425.  
  2426.  
  2427.  
  2428.  
  2429.  
  2430.                                        Page - 37
  2431.  
  2432.  
  2433.  
  2434.  
  2435.  
  2436.  
  2437.  
  2438.                                    COMPILER OPTIONS
  2439.  
  2440.  
  2441.  
  2442.        The following compiler switches are currently available for ASIC:
  2443.  
  2444.        Switch    Description
  2445.  
  2446.        B/xxx          BUILD--Use this option to specify the type of output file
  2447.                       ASIC is to produce.  The "xxx" on this option should be
  2448.                       one of the following:
  2449.  
  2450.                       xxx= COM       <--produce .COM file
  2451.                            EXE       <--produce .EXE file
  2452.                            OBJ       <--produce .EXE file via OBJ file
  2453.                                           using DOS LINK command
  2454.                                           optionally linking with
  2455.                                           other OBJ or LIB files.
  2456.  
  2457.                       Default:  ASIC will generate a ".COM" output file.
  2458.  
  2459.  
  2460.        C              CONTINUE--ASIC will not pause after messages are issued,
  2461.                       but will continue compiling.
  2462.  
  2463.                       Default:  ASIC will pause after each error message.
  2464.                       Compilation will resume after you press a key.
  2465.  
  2466.        D              DISKLIST--ASIC will echo all screen messages to a disk
  2467.                       file named "progname.LST".  The format is the same
  2468.                       produced by    PRINTLIST.  This allows you to compile at
  2469.                       higher speed, and print the source listing later from the
  2470.                       disk file via the DOS print spooler.
  2471.  
  2472.                       Default:  ASIC does not produce a ".LST" file.
  2473.  
  2474.  
  2475.        DEC            DECIMAL MATH--ASIC will enable the Decimal Math Option.
  2476.                       When this option is selected, you may specify decimal
  2477.                       numbers (eg, BALANCE@, 123.456789, etc) which can hold
  2478.                       numbers in the range +/-999,999,999,999.99999.  This
  2479.                       option does increase the size of your ".COM" or ".EXE"
  2480.                       file.
  2481.  
  2482.                       Default:  ASIC does not enable the Decimal Math Option.
  2483.  
  2484.  
  2485.        E              EMATH--ASIC will enable the Extended Math Option.  When
  2486.                       this option is selected, you may specify long integers
  2487.                       (eg, VELOCITY&, 123456789&, etc) which can hold a larger
  2488.                       range of values (+2,147,483,647 to -2,147,483,647).  This
  2489.                       option does increase the size of your ".COM" or ".EXE"
  2490.                       file by a couple of hundred bytes.
  2491.  
  2492.                       Default:  ASIC does not enable the Extended Math Option.
  2493.  
  2494.                                        Page - 38
  2495.  
  2496.  
  2497.  
  2498.  
  2499.  
  2500.                              COMPILER OPTIONS (Continued)
  2501.  
  2502.  
  2503.        Switch    Description
  2504.  
  2505.        L              LIST ALL--ASIC will list each source line as it compiles
  2506.                       it.
  2507.  
  2508.                       Default:  ASIC will list only source lines with compile
  2509.                       errors.
  2510.  
  2511.                       Comment:  Use of this switch will slow compile speeds
  2512.                       slightly due to the additional screen I/O.
  2513.  
  2514.  
  2515.        LIB=xxx        LINK LIBRARY--Specifies libraries that ASIC should pass
  2516.                       to the DOS LINKer.  This option is ONLY used by ASIC when
  2517.                       you compile with the "B/OBJ" option.  It is ignored when
  2518.                       you compile with the "B/COM" or "B/EXE" options.  A link
  2519.                       library is usually used to store commonly used
  2520.                       subroutines in OBJECT format.  You can create assembly
  2521.                       language subroutines for ASIC, and store them in a
  2522.                       library using the Borland TLIB Program or the Microsoft
  2523.                       LIB Program.  The "xxx" should specify one or more
  2524.                       library file specs with each library spec separated with
  2525.                       a "+" character.  See the "Mixed Language Programming"
  2526.                       chapter of the ASIC manual for more information.
  2527.  
  2528.                       Examples:
  2529.  
  2530.                            LIB=C:\ASIC\MATH.LIB
  2531.  
  2532.                            LIB=C:\DOS\MISC.LIB+C:\LIB\COMMON
  2533.  
  2534.                       The first example shows a single library spec for
  2535.                       MATH.LIB library.  The second example shows how to
  2536.                       include more than one library--MISC.LIB and COMMON.LIB
  2537.                       libraries.
  2538.  
  2539.                       Comments:  When specifying libraries, you may omit the
  2540.                       file extension, if it is ".LIB".
  2541.  
  2542.  
  2543.  
  2544.  
  2545.  
  2546.  
  2547.  
  2548.  
  2549.  
  2550.  
  2551.  
  2552.  
  2553.  
  2554.  
  2555.  
  2556.  
  2557.  
  2558.                                        Page - 39
  2559.  
  2560.  
  2561.  
  2562.  
  2563.  
  2564.                              COMPILER OPTIONS (Continued)
  2565.  
  2566.  
  2567.        Switch    Description
  2568.  
  2569.  
  2570.        LNK=xxx        LINKer LOCATION--Specifies the location of the DOS
  2571.                       LINK.EXE program to ASIC.  This option is ONLY used when
  2572.                       compiling with the "B/OBJ" option. Unless the LINK.EXE
  2573.                       which is provided with MS DOS is located in the default
  2574.                       ASIC directory, ASIC may not be able to locate the
  2575.                       program, and will thus be unable to LINK your program to
  2576.                       create a ".EXE" file.  The LINK.EXE should be included on
  2577.                       your MS DOS distribution disks (if it is not already in
  2578.                       your DOS directory). "xxx" should specify a file path.
  2579.                       For more information on this option see the "Mixed
  2580.                       Languages Programming" Chapter of the ASIC Manual.
  2581.  
  2582.                       Example:
  2583.  
  2584.                            LNK=C:\DOS3
  2585.  
  2586.                       Default:  By default, ASIC will attempt to locate the
  2587.                       linker in the default directory.  If it can't find the
  2588.                       LINK.EXE file there, it tries to find it under the
  2589.                       "C:\DOS" directory.  If it can't find it there, it gives
  2590.                       up and issues an error message.
  2591.  
  2592.  
  2593.        OBJ=xxx        ADDITIONAL OBJECT FILES--Specifies a list of additional
  2594.                       object files that ASIC should link with the main object
  2595.                       file.  This option is ONLY used by ASIC when you are
  2596.                       compiling with the "B/OBJ" option.  You do not need to
  2597.                       include the name of your ASIC program here, that is done
  2598.                       automatically by ASIC.  When you compile with this
  2599.                       option, ASIC creates an OBJ file which can be linked
  2600.                       using the DOS LINKer.  Optionally, you can included "CALL
  2601.                       SUB" statements in your program which reference
  2602.                       separately compiled OBJ files.  This option allows you to
  2603.                       pass other object file names to the DOS LINKer to resolve
  2604.                       these external references.  The "xxx" parameter should
  2605.                       include file specs for one or more object files with a
  2606.                       "+" character separating each object file.  See the
  2607.                       "Mixed Language Programming" Chapter of the ASIC Manual
  2608.                       for more details.
  2609.  
  2610.                       Examples:
  2611.  
  2612.                            OBJ=C:\ASIC\MYSUB.OBJ
  2613.                            OBJ=C:\LIB\SUB1.OBJ+C:\OBJ\SUB2
  2614.  
  2615.                       The first example specifies a single object to be passed
  2616.                       to the linker.  The second example illustrates two object
  2617.                       files: SUB1.OBJ and SUB2.OBJ.
  2618.  
  2619.                       Comments:  The file extension may be omitted if it is
  2620.                       ".OBJ".
  2621.  
  2622.                                        Page - 40
  2623.  
  2624.  
  2625.  
  2626.  
  2627.  
  2628.                              COMPILER OPTIONS (Continued)
  2629.  
  2630.  
  2631.        Switch    Description
  2632.  
  2633.  
  2634.        P              PRINTLIST--ASIC will echo all messages which appear on
  2635.                       the screen to the printer. Output to the printer will be
  2636.                       paged with header lines identifying the program name, and
  2637.                       the date/time compiled.
  2638.  
  2639.                       Default:  ASIC will not send any messages to the printer
  2640.  
  2641.                       Comments: Even though output to the printer is buffered,
  2642.                       this option will slow compile speeds considerably.  The
  2643.                       compiler typically compiles only as fast as your printer
  2644.                       can print the messages.  An alternative to this switch is
  2645.                       the DISKLIST option.
  2646.  
  2647.  
  2648.        S              SYMTAB--ASIC will produce a formatted Symbol Table in a
  2649.                       file named "progname.SYM".  The symbol table contains a
  2650.                       list of all variables, labels, and internally created
  2651.                       compiler addresses.
  2652.  
  2653.                       Default:  ASIC does not produce a ".SYM" file.
  2654.  
  2655.  
  2656.        STK=n          STACK SIZE--Specifies the size of the stack that you wish
  2657.                       ASIC to create.  This option is ignored when you are
  2658.                       using the "B/COM" option.  "n" equals the size of the
  2659.                       stack you want in bytes.
  2660.  
  2661.                       Default:  By default, ASIC sets the stack size to 2000
  2662.                       bytes (4000 bytes if you are compiling with debugging
  2663.                       mode).
  2664.  
  2665.                       Examples:
  2666.  
  2667.                            STK=512
  2668.  
  2669.                       In the above example, the stack size would be set to 512
  2670.                       bytes.
  2671.  
  2672.                       Comments:  The default stack sizes that ASIC provides are
  2673.                       normally adequate, however, they may be larger than your
  2674.                       program may need.  If you are interested in minimizing
  2675.                       your program's memory usage, you may experiment with the
  2676.                       STK option, however, setting the size too small can cause
  2677.                       unpredictable results.  This option is recommended only
  2678.                       for experienced ASIC users.  The stack size must be in
  2679.                       the range 16 to 32767.  ASIC will not allow you to create
  2680.                       a stack size smaller than 4000 bytes when compiling with
  2681.                       debugging mode on.  If you specify a smaller value in
  2682.                       this instance, ASIC will override it with a size of 4000.
  2683.  
  2684.  
  2685.  
  2686.                                        Page - 41
  2687.  
  2688.  
  2689.  
  2690.  
  2691.  
  2692.                              COMPILER OPTIONS (Continued)
  2693.  
  2694.  
  2695.        Switch    Description
  2696.  
  2697.        X              DEBUG--ASIC will generate debugging code in the ".COM" or
  2698.                       ".EXE" file and a ".DBG" file for use by the integrated
  2699.                       environment debugger.
  2700.  
  2701.                       Default:  ASIC does not generate debugging information.
  2702.  
  2703.                       Comment:  If you are running from the integrated
  2704.                       environment, ASIC sets this option on by default.  You
  2705.                       may turn it off in the Compile menu, should you so
  2706.                       desire.
  2707.  
  2708.  
  2709.                                    COMPILE EXAMPLES
  2710.  
  2711.  
  2712.        Example 1:     Compile "MYFILE.ASI" with default compiler options:
  2713.  
  2714.  
  2715.                       ASICC MYFILE
  2716.  
  2717.  
  2718.        Example 2:     Compile "MYPROG.ASI", Listing all source lines, writing a
  2719.                       compile listing to a disk file for printing later.  The
  2720.                       listing file will be called "MYPROG.LST":
  2721.  
  2722.                       ASICC MYPROG L D
  2723.  
  2724.  
  2725.        Example 3:     Compile "FILEX.ASI", don't pause for any errors, and
  2726.                       print the errors on the printer:
  2727.  
  2728.                       ASICC FILEX C P
  2729.  
  2730.  
  2731.        Example 4:     Compile "CRUNCH.ASI" and allow long (32 bit) integer
  2732.                       numbers:
  2733.  
  2734.                       ASICC CRUNCH E
  2735.  
  2736.  
  2737.        Example 5:     Compile "BIGPROG.ASI" and create a ".EXE" format output
  2738.                       file:
  2739.  
  2740.                       ASICC BIGPROG B/EXE
  2741.  
  2742.        Example 6:     Compile "SAMPLE.ASI" and create a ".EXE" format output
  2743.                       file, with a stack size of 2500 bytes.
  2744.  
  2745.                       ASICC SAMPLE B/EXE STK=2500
  2746.  
  2747.  
  2748.  
  2749.  
  2750.                                        Page - 42
  2751.  
  2752.  
  2753.  
  2754.  
  2755.  
  2756.  
  2757.  
  2758.                              COMPILE EXAMPLES (Continued)
  2759.  
  2760.        Example 7:     Here's a more complex example, which demonstrates the
  2761.                       use of the B/OBJ build options.  Assume we have a program
  2762.                       called "MAIN.ASI" which calls three assembly language
  2763.                       subroutines, called "A", "B", and "C".  Subroutine "A" is
  2764.                       stored in file "A.OBJ".  Subroutines "B" and "C" are
  2765.                       stored in a library called "ASMSUB.LIB".  The DOS
  2766.                       LINK.EXE file is contained in the subdirectory "C:\UTIL".
  2767.                       Here is the ASICC command to compile MAIN.ASI and link in
  2768.                       the subroutines called using "CALL SUB" in the MAIN.ASI
  2769.                       program:
  2770.  
  2771.                       ASICC MAIN B/OBJ OBJ=A LIB=ASMSUB LNK=C:\UTIL
  2772.  
  2773.  
  2774.                                  PROGRAM PROJECT FILE
  2775.  
  2776.             The ASIC integrated environment automatically stores compile
  2777.        options for each program in a file called "progname.PRJ".  Whenever you
  2778.        compile from the integrated editor, ASIC will always check for this
  2779.        file, and set compile options based on the file.
  2780.  
  2781.             Since MS DOS has a restriction of 128 characters for a command
  2782.        line, you may find it useful to use the integrated environment to set
  2783.        your compile options for a program, even if you are not using the
  2784.        environment for editing.  This is especially true when you are using the
  2785.        "B/OBJ" option, where you frequently may be passing many parameters.
  2786.        Then, you may type the program project file name instead of the program
  2787.        source file name when compiling from the command line and ASIC will use
  2788.        the options from the ".PRJ" file for that compile.
  2789.  
  2790.             You may still specify additional compile line options when
  2791.        compiling using the ".PRJ" file option.  In this case, the option from
  2792.        the command line will override any corresponding option from the ".PRJ"
  2793.        file.
  2794.  
  2795.             Although the ".PRJ" file is a standard DOS text file, it is
  2796.        recommended that you not edit this file using a text editor--if
  2797.        incorrectly modified, compiler results may be unpredictable.
  2798.  
  2799.             Example:
  2800.  
  2801.                  ASICC myfile.prj LIB=NEWLIB
  2802.  
  2803.             In this example, all options set in the "MYFILE.PRJ" file will be
  2804.        read and used by the ASIC command line compiler, except for the "LIB"
  2805.        option which was specified on the command line.  For this compile, ASIC
  2806.        will set the LIB option to "NEWLIB" irregardless of what the LIB option
  2807.        was set to in the project file.  ASIC will then try to compile a source
  2808.        file called "MYFILE.ASI".
  2809.  
  2810.  
  2811.  
  2812.  
  2813.  
  2814.                                        Page - 43
  2815.  
  2816.  
  2817.  
  2818.  
  2819.  
  2820.  
  2821.  
  2822.  
  2823.                                         A S I C
  2824.  
  2825.                                        Chapter 6
  2826.  
  2827.                                    Language Elements
  2828.  
  2829.  
  2830.  
  2831.                                      CHARACTER SET
  2832.  
  2833.  
  2834.        Symbol         Description
  2835.  
  2836.          *            Multiplication
  2837.                       Example: A=B*C  (multiply B by C, store result in A)
  2838.  
  2839.          /            Division
  2840.                       Example: A=B/C  (divide B by C, store result in A)
  2841.  
  2842.          +            Addition
  2843.                       Example: A=B+C  (add C to B, store result in A)
  2844.  
  2845.          +            String Concatenation
  2846.                       Example: A$="AB"+"C"   (A$ will contain "ABC")
  2847.  
  2848.          =            Assignment
  2849.                       Example: A=1    (A will be assigned the value 1)
  2850.  
  2851.          =            Equality testing
  2852.                       Example: IF A=1 THEN QUIT:  (If the value stored in
  2853.                            A equals 1 goto label QUIT)
  2854.  
  2855.          <            Less than testing
  2856.                       Example:  IF A<1 THEN QUIT:  (If the value stored in
  2857.                            A is less than 1 goto label QUIT)
  2858.  
  2859.          >            Greater than testing
  2860.                       Example:  IF A<1 THEN QUIT:  (If the value stored in
  2861.                            A is greater than 1 goto label QUIT)
  2862.  
  2863.          -            Subtraction
  2864.                       Example: A=B-C   (Subtract C from B, store result in A)
  2865.  
  2866.          "            String Delimiter
  2867.                       Example: A$="the string is inside quote marks"
  2868.  
  2869.          ()           Parenthesis -- Ignored by ASIC
  2870.  
  2871.          ;            Suppress Carriage Return/Line Feed with PRINT/LPRINT
  2872.  
  2873.          #            Used to identify file usage with PRINT#/INPUT#
  2874.  
  2875.  
  2876.  
  2877.  
  2878.                                        Page - 44
  2879.  
  2880.  
  2881.  
  2882.  
  2883.  
  2884.                                CHARACTER SET (Continued)
  2885.  
  2886.        Symbol         Description
  2887.  
  2888.          ,            Comma,  Ignored by ASIC
  2889.  
  2890.          $            Distinguishes a String Variable from an Integer.
  2891.                       Example:    ABC$   <---- String Variable
  2892.                       Example:    ABC    <---- Integer Variable
  2893.  
  2894.          :            Distinguishes a Label from a variable name.
  2895.                       Example:    START:    <---Label name
  2896.  
  2897.          &            Distinguishes a "long" (32 bit) integer from a normal
  2898.                       integer (16 bit) variable or constant.  Normal integers
  2899.                       can hold numbers in the range +32,767 to -32,767.  Long
  2900.                       integers can hold numbers in the range +2,147,483,647
  2901.                       to -2,147,483,647.  Note:  You must compile with the
  2902.                       "Extended Math" Option enabled to use long integers.
  2903.                       Example:    APPLES&   <--Long Integer Variable
  2904.                       Example:    ORANGES   <--Normal Integer Variable
  2905.                       Example:    123457&   <--Long Integer Constant
  2906.                       Example:    1234      <--Short Integer Constant
  2907.  
  2908.          @            Distinguishes a "decimal" (64 bit) variable or constant
  2909.                       from a normal integer (16 bit) variable or constant.
  2910.                       Decimal numbers can be in the range
  2911.                       +999,999,999,999.99999 to -999,999,999,999.99999.  Note:
  2912.                       You must compile with the "Decimal Math" option enabled
  2913.                       to use decimal numbers.
  2914.                       Example:  APPLES@   <--Decimal Variable
  2915.                       Example:  1234.567  <--Decimal Constant
  2916.                       Example:  123@      <--Decimal Constant
  2917.                       Example:  1.2@      <--Decimal Constant
  2918.  
  2919.  
  2920.  
  2921.  
  2922.  
  2923.  
  2924.  
  2925.  
  2926.  
  2927.  
  2928.  
  2929.  
  2930.  
  2931.  
  2932.  
  2933.  
  2934.  
  2935.  
  2936.  
  2937.  
  2938.  
  2939.  
  2940.  
  2941.  
  2942.                                        Page - 45
  2943.  
  2944.  
  2945.  
  2946.  
  2947.  
  2948.                            CONSTANTS, VARIABLES, AND LABELS
  2949.  
  2950.  
  2951.        ASIC supports the following data types:
  2952.  
  2953.             Decimal Constants        Integer Constants
  2954.             Decimal Variables        Integer Variables
  2955.             Decimal Arrays           Integer Arrays
  2956.  
  2957.             String Constants         Long Integer Constants
  2958.             String Variables         Long Integer Variables
  2959.             String Arrays            Long Integer Arrays
  2960.  
  2961.  
  2962.        Integer constants may be specified in decimal (base 10), hexidecimal
  2963.        (base 16), or binary (base 2).  The following describes the restrictions
  2964.        for each data type.
  2965.  
  2966.        DECIMAL CONSTANTS   Range     +999,999,999,999.99999 to
  2967.                                      -999,999,999,999.99999
  2968.  
  2969.                            Example:        105.1
  2970.  
  2971.        DECIMAL VARIABLE    Described by a variable name beginning with a
  2972.                            letter, followed by up to 78 additional letters
  2973.                            or numbers, terminated with an "@" symbol.  It
  2974.                            may contain a number in the range of
  2975.                            +/-999,999,999,999.99999
  2976.  
  2977.                            Example:       INTEREST@
  2978.  
  2979.        DECIMAL ARRAY       Described by a variable name beginning with a
  2980.                            letter, followed by up to 78 additional letters
  2981.                            or numbers, terminated by an "@" symbol.  This
  2982.                            is followed by an integer variable or constant
  2983.                            for the dimension of the array.  Arrays must be
  2984.                            dimensioned at the beginning of the program.  See
  2985.                            the DIM statement.
  2986.  
  2987.                            Example:       SALES@(YEAR)
  2988.  
  2989.        INTEGER CONSTANTS   Range  +32767 to -32767
  2990.  
  2991.                            Example:       -26
  2992.  
  2993.        INTEGER VARIABLE    Described by a variable name beginning with a
  2994.                            letter, followed by up to 79 additional letters
  2995.                            or numbers.  It may contain a number in the range
  2996.                            +32767 to -32767.
  2997.  
  2998.                            Example:       VELOCITY1
  2999.  
  3000.  
  3001.  
  3002.  
  3003.  
  3004.  
  3005.  
  3006.                                        Page - 46
  3007.  
  3008.  
  3009.  
  3010.  
  3011.  
  3012.  
  3013.  
  3014.                      CONSTANTS, VARIABLES, AND LABELS (Continued)
  3015.  
  3016.        INTEGER ARRAY       Described by a variable name beginning with a
  3017.                            letter, followed by up to 79 additional letters
  3018.                            or numbers.  This name is followed by an
  3019.                            integer variable or constant for the dimension
  3020.                            of the array.  Arrays must be dimensioned at the
  3021.                            beginning of the program.  See the DIM statement.
  3022.  
  3023.                            Example:       GROWTH (YEAR)
  3024.  
  3025.        LONG INTEGER        Range  +2,147,483,647 to -2,147,483,647
  3026.        CONSTANTS
  3027.                            Example:       3234457&
  3028.  
  3029.        LONG INTEGER        Described by a variable name beginning with a
  3030.        VARIABLE            letter, followed by up to 78 additional letters or
  3031.                            numbers terminated with a "&".  Can contain
  3032.                            numbers in the range +2,147,483,647 to
  3033.                            -2,147,483,647.
  3034.  
  3035.                            Example:       VELOCITY1&
  3036.  
  3037.        LONG INTEGER        Described by a variable name beginning with a
  3038.        ARRAY               letter, followed by up to 78 additional letters or
  3039.                            numbers, terminated with a "&".  This name is
  3040.                            followed by an integer variable or constant for
  3041.                            the dimension of the array.  Arrays must be
  3042.                            dimensioned at the beginning of the program.
  3043.                            See the DIM statement.
  3044.  
  3045.                            Example:       GALAXY& (BILLIONSOF)
  3046.  
  3047.        HEXIDECIMAL         Hexidecimal constants are constants which are
  3048.        CONSTANT            stated in base 16 instead of base 10 like normal
  3049.                            constants.  These may be specified wherever you
  3050.                            can specify a integer constant.  Hexidecimal
  3051.                            constants in ASIC must be prefixed by "&hex". This
  3052.                            prefix should be immediately followed by a valid
  3053.                            normal or long integer constant.  Hex constants
  3054.                            may contain up to 8 hexidecimal digits for long
  3055.                            constants, and 4 hexidecimal digits for normal
  3056.                            constants.
  3057.  
  3058.                            Example:  &hexB000   <--equivalent to -20400
  3059.  
  3060.                            Example:  &hexB&     <--equivalent to 11&
  3061.  
  3062.                            Example:  &hexFFFFFFFF&  <--equivalent to -1&
  3063.  
  3064.                            Example:  &hexB000&  <--equivalent to 45056&
  3065.  
  3066.  
  3067.  
  3068.  
  3069.  
  3070.                                        Page - 47
  3071.  
  3072.  
  3073.  
  3074.  
  3075.  
  3076.  
  3077.  
  3078.                      CONSTANTS, VARIABLES, AND LABELS (Continued)
  3079.  
  3080.        BINARY CONSTANT     Binary constants are constants which are stated in
  3081.                            base 2 instead of base 10 like normal constants.
  3082.                            These may be specified wherever you can specify a
  3083.                            integer constant.  Binary constants in ASIC must
  3084.                            be prefixed by "&bin".  This prefix should be
  3085.                            immediately followed by a valid normal or long
  3086.                            integer constant.  Binary constants may contain
  3087.                            up to 32 binary digits for long constants or 16
  3088.                            binary digits for normal constants.
  3089.  
  3090.                            Example:  &bin10         <--equivalent to 2
  3091.  
  3092.                            Example:  &bin10101011&  <--equivalent to 171&
  3093.  
  3094.        STRING CONSTANT     A group of 0-80 characters enclosed by quotation
  3095.                            marks.
  3096.  
  3097.                            Example:       "This is a String Constant"
  3098.  
  3099.        STRING VARIABLE     Described by a variable name which begins with a
  3100.                            letter, followed by up to 78 additional
  3101.                            letters or numbers, terminated with a "$".
  3102.                            Can contain 0-80 characters.
  3103.  
  3104.                            Example:       ADDRESS$
  3105.  
  3106.        STRING ARRAY        Described by a variable name which begins with a
  3107.                            letter, followed by up to 78 additional letters or
  3108.                            numbers, followed by a $, followed by an integer
  3109.                            variable or constant enclosed in parenthesis
  3110.                            representing the subscript.  Arrays must be
  3111.                            dimensioned at the beginning of the program.
  3112.                            See the DIM statement.
  3113.  
  3114.  
  3115.                            Example:       STATE$(50)
  3116.  
  3117.        LABEL               A Label is a location in your program you wish
  3118.                            to transfer to.  It must begin with a letter,
  3119.                            and it may contain up to 78 additional letters
  3120.                            or numbers.  It must be terminated with a ":".
  3121.  
  3122.                            Example:       START:
  3123.  
  3124.  
  3125.  
  3126.  
  3127.  
  3128.  
  3129.  
  3130.  
  3131.  
  3132.  
  3133.  
  3134.                                        Page - 48
  3135.  
  3136.  
  3137.  
  3138.  
  3139.  
  3140.                                 VARIABLES VS. CONSTANTS
  3141.  
  3142.  
  3143.        In general, ASIC will allow the use of either variables, arrays, or
  3144.        constants as operands to any program statement.  For example:
  3145.  
  3146.  
  3147.                       PRINT CASH
  3148.                       PRINT 20
  3149.                       PRINT A(10)
  3150.  
  3151.        All three of the above examples are valid.  The only case where a
  3152.        constant cannot be used, is where the value is being modified.  For
  3153.        example:
  3154.  
  3155.                  A = A + B           <----VALID
  3156.                  17 = A + C          <----INVALID
  3157.  
  3158.        Of course you must specify the correct data type for the ASIC keyword.
  3159.        For example:
  3160.  
  3161.                  A = ABS("HELLO")    <----INVALID
  3162.  
  3163.  
  3164.        This statement is invalid because you cannot take the absolute value of
  3165.        a string!
  3166.  
  3167.        There are a few ASIC statements which will accept only integer constants
  3168.        for some operands (DIM, OPEN, PRINT#, INPUT#).  Refer to the individual
  3169.        statement for more information.
  3170.  
  3171.        There is a restriction on the use of subscripts for Arrays.  A subscript
  3172.        for an array cannot be another array,.  For example:
  3173.  
  3174.  
  3175.                  A(I(1))             <----INVALID
  3176.                  A(I)                <----VALID
  3177.  
  3178.        Finally, decimal variables or constants cannot be used as subscripts:
  3179.  
  3180.                  A@(1.1)             <----INVALID
  3181.                  A@(B@)              <----INVALID
  3182.                  A@(1)               <----VALID
  3183.                  A@(A)               <----VALID
  3184.                  A@(A&)              <----VALID
  3185.  
  3186.  
  3187.  
  3188.  
  3189.  
  3190.  
  3191.  
  3192.  
  3193.  
  3194.  
  3195.  
  3196.  
  3197.  
  3198.                                        Page - 49
  3199.  
  3200.  
  3201.  
  3202.  
  3203.  
  3204.  
  3205.  
  3206.  
  3207.         CONVERSION BETWEEN NUMERIC FORMATS (INTEGER, LONG INTEGER AND DECIMAL)
  3208.  
  3209.  
  3210.        Decimal numbers, long integers, or normal integers may be used on any
  3211.        ASIC statement in any combination.  Consequently, in the "Keyword
  3212.        Reference" Chapter of this is manual, operands are identified only as
  3213.        "number".  "Number" in this context should be interpreted as meaning
  3214.        that the operand for that statement can be any of the following: integer
  3215.        constant, integer variable, integer array, long integer constant, long
  3216.        integer variable, long integer array, decimal constant, decimal
  3217.        variable, or decimal array.  Exceptions, if any, are noted in the
  3218.        documentation for the statement.
  3219.  
  3220.        If you do mix decimal number, long integers, or regular integers in a
  3221.        statement, you should be aware of how ASIC converts between the formats.
  3222.        The following rules apply:
  3223.  
  3224.             1)  If a long integer variable or constant is being stored in a
  3225.                 normal integer variable, the long integer (32 bit) number 
  3226.                 will ALWAYS convert correctly to a normal integer (16 bit) 
  3227.                 value provided the long integer variable contains a number
  3228.                 which will fit in a normal integer (ie, within the range of
  3229.                 +32767 to -32767).  If, however, the number is outside of
  3230.                 this range, ASIC will truncate it to make it fit in a normal
  3231.                 integer.  This truncation will cause some surprising (but
  3232.                 predictable) answers.  For example if "A&" contained the
  3233.                 value "50000&", and the following ASIC statement was executed
  3234.                 "A=A&", then the value of "A" would be "-15536".  The reason
  3235.                 that the overflow results in such a strange number is due to
  3236.                 the way the IBM PC stores numbers in binary format and is too
  3237.                 complicated to describe here.  The important thing
  3238.                 to remember is, for ASIC to convert from long integers to
  3239.                 normal integers correctly, the value in the long integer
  3240.                 should be in the range of +32767 to -32767.
  3241.  
  3242.             2)  If a normal integer variable or constant is being stored in
  3243.                 a long integer variable, ASIC will always convert the number
  3244.                 correctly.
  3245.  
  3246.             3)  If a decimal number is stored in a normal or long integer, the
  3247.                 fractional component of the number will be discarded, and the
  3248.                 remaining integer value will be stored in the normal or long
  3249.                 integer.  The result will be truncated if necessary to fit.
  3250.                 For example, after the statement "A=12345.67890" is executed,
  3251.                 variable "A" would contain the value "12345".  As another
  3252.                 example, after the statement, "A=50000.12345" is executed,
  3253.                 variable "A" would contain the value "-15536".  The reason
  3254.                 that the overflow results in such a strange number is due to
  3255.                 the way the IBM PC stores numbers in binary format and is too
  3256.                 complicated to describe here.  The important thing
  3257.                 to remember is, for ASIC to convert from decimal numbers to
  3258.                 integers correctly, the value of the decimal number should be
  3259.                 within the range for the target variable type.
  3260.  
  3261.  
  3262.                                        Page - 50
  3263.  
  3264.  
  3265.  
  3266.  
  3267.  
  3268.  
  3269.             4)  If a long or normal integer is stored in a decimal variable,
  3270.                 ASIC will always convert the number correctly.
  3271.  
  3272.             5)  IMPORTANT NOTE:  When performing math with a mixture of decimal
  3273.                 and integer variables, ASIC automatically converts the operands
  3274.                 to the storage type of the result BEFORE computing the result,
  3275.                 and the math function called will be based on the variable type
  3276.                 of the result.  GWBASIC/BASICA floating point, on the other
  3277.                 hand, converts the operands to the most precise format of the
  3278.                 operand types to the RIGHT of the equal sign and compute the
  3279.                 results based on the longest type to the right of the equal
  3280.                 sign, before scaling the result.  This can be illustrated with
  3281.                 the following examples:
  3282.  
  3283.                  ASIC                     GWBASIC/BASICA
  3284.  
  3285.                  A@=2*2.6 = 5.2           A#=2%*2.6 = 5.2
  3286.                  B=2*2.6= 4               B%=2%*2.6 = 5
  3287.                  B&=500 * 500=250000      B&=500% * 500%= OVERFLOW
  3288.                  B&=500& * 500&=250000    B&=500& * 500&=250000
  3289.  
  3290.  
  3291.  
  3292.  
  3293.  
  3294.  
  3295.  
  3296.  
  3297.  
  3298.  
  3299.  
  3300.  
  3301.  
  3302.  
  3303.  
  3304.  
  3305.  
  3306.  
  3307.  
  3308.  
  3309.  
  3310.  
  3311.  
  3312.  
  3313.  
  3314.  
  3315.  
  3316.  
  3317.  
  3318.  
  3319.  
  3320.  
  3321.  
  3322.  
  3323.  
  3324.  
  3325.  
  3326.                                        Page - 51
  3327.  
  3328.  
  3329.  
  3330.  
  3331.  
  3332.  
  3333.  
  3334.                                         A S I C
  3335.  
  3336.                                        Chapter 7
  3337.  
  3338.                                    Keyword Reference
  3339.  
  3340.  
  3341.  
  3342.  
  3343.                                           ABS
  3344.  
  3345.        Format:        number1 = ABS (number2)
  3346.  
  3347.        Description:
  3348.  
  3349.             This function returns the absolute value of number2 which is then
  3350.        stored in number1.
  3351.  
  3352.        Example:
  3353.  
  3354.                  A = ABS (-7)
  3355.  
  3356.        After execution of this statement, "A" will contain 7.
  3357.  
  3358.  
  3359.  
  3360.                                           ASC
  3361.  
  3362.        Format:        number1 = ASC (string1)
  3363.  
  3364.        Description:
  3365.  
  3366.             This function returns the ASCII value of the first character of
  3367.        string1, storing the result in number1.
  3368.  
  3369.        Example:
  3370.  
  3371.                  A = ASC("123")
  3372.  
  3373.        After execution of this statement "A" would contain 49, which the is
  3374.        ASCII value of "1".
  3375.  
  3376.  
  3377.  
  3378.  
  3379.  
  3380.  
  3381.  
  3382.  
  3383.  
  3384.  
  3385.  
  3386.  
  3387.  
  3388.  
  3389.  
  3390.                                        Page - 52
  3391.  
  3392.  
  3393.  
  3394.  
  3395.  
  3396.                                          BEEP
  3397.  
  3398.        Format:        BEEP
  3399.  
  3400.        Description:
  3401.  
  3402.             This statement will cause a short "beep" to be produced on the PC
  3403.        speaker.
  3404.  
  3405.        Example:
  3406.  
  3407.                  IF A>99 THEN
  3408.                       BEEP
  3409.                       PRINT "Number is too big!"
  3410.                       A=99
  3411.                  ENDIF
  3412.  
  3413.        The preceding program fragment will check to see if variable "A"
  3414.        contains a value less than 100.  If it does not, it will produce a short
  3415.        "beep", display a message, and set the value of "A" to 99.
  3416.  
  3417.  
  3418.  
  3419.  
  3420.  
  3421.  
  3422.  
  3423.  
  3424.  
  3425.  
  3426.  
  3427.  
  3428.  
  3429.  
  3430.  
  3431.  
  3432.  
  3433.  
  3434.  
  3435.  
  3436.  
  3437.  
  3438.  
  3439.  
  3440.  
  3441.  
  3442.  
  3443.  
  3444.  
  3445.  
  3446.  
  3447.  
  3448.  
  3449.  
  3450.  
  3451.  
  3452.  
  3453.  
  3454.                                        Page - 53
  3455.  
  3456.  
  3457.  
  3458.  
  3459.  
  3460.                                          BLOAD
  3461.  
  3462.        Format:        BLOAD string1, number1, number2
  3463.  
  3464.        Description:
  3465.  
  3466.             This function loads data previously saved by BSAVE from a file to
  3467.        memory.  String1 should be the name of the file previously created by
  3468.        BSAVE.  Number1 should be the memory offset to load the data to.
  3469.        Number2 should be the number of bytes to read from the file (in the
  3470.        range of 1 to 32767).  If DEFSEG has been set, it will be used as the
  3471.        data segment, otherwise, the default ASIC data segment will be used.
  3472.  
  3473.        Example:
  3474.  
  3475.                  DEFSEG = &hexB800
  3476.                  BLOAD "SAVED.DAT" 0 100
  3477.  
  3478.        After execution of these statements 100 bytes will be read from the file
  3479.        "SAVED.DAT" and stored in memory start at 0 bytes from the start of the
  3480.        override data segment (which in this case happens to point to the
  3481.        beginning of video memory for a CGA card).  Assuming a CGA card was
  3482.        present, the first 50 characters on the screen would contain data read
  3483.        from the file (don't forget that each screen character is represented by
  3484.        two bytes data and attribute, that's why only 50 characters will be
  3485.        displayed, assuming you are not in graphics mode).
  3486.  
  3487.        Comments:
  3488.  
  3489.             THIS FUNCTION IS RECOMMENDED ONLY FOR ADVANCED PROGRAMMERS.  THIS
  3490.        STATEMENT WILL ALLOW YOU TO OVERLAY ANY AREA OF MEMORY, AND IT IS VERY
  3491.        EASY TO ACCIDENTALLY OVERLAY YOUR PROGRAM OR THE MEMORY USED BY DOS.
  3492.  
  3493.             If ASIC detects an error executing this command, it will set the
  3494.        system ERROR variable.  These error codes are listed in the Error
  3495.        Messages Chapter of the ASIC Manual
  3496.  
  3497.             This statement is slightly different from GWBASIC/BASICA in that
  3498.        you must specify how many bytes to read from the file.  Also, the memory
  3499.        offset is not stored in the file by BSAVE, so you must specify the
  3500.        offset as number1 in ASIC.  Offset is optional in GWBASIC/BASICA.
  3501.  
  3502.             ASIC uses a slightly different file format than GWBASIC/BASICA,
  3503.        however, it is relatively easy to convert the GWBASIC/BASICA to ASIC
  3504.        format.  GWBASIC/BASICA files have a seven byte header that ASIC does
  3505.        not have.  If you strip off these 7 bytes and rewrite the file, ASIC
  3506.        should be able to process the file.
  3507.  
  3508.        See also:
  3509.  
  3510.             DEFSEG,BSAVE
  3511.  
  3512.  
  3513.  
  3514.  
  3515.  
  3516.  
  3517.  
  3518.                                        Page - 54
  3519.  
  3520.  
  3521.  
  3522.  
  3523.  
  3524.                                          BSAVE
  3525.  
  3526.        Format:        BSAVE string1, number1, number2
  3527.  
  3528.        Description:
  3529.  
  3530.             This statement writes the block of memory beginning at offset
  3531.        number1 from the start of the data segment for a length of number2 bytes
  3532.        to the file specified by string1.  This data may be later loaded by
  3533.        BLOAD.  If DEFSEG has been set, it will be used as the data segment,
  3534.        otherwise, the default ASIC data segment will be used.
  3535.        Number2 should be in the range of 1 to 32767.
  3536.  
  3537.        Example:
  3538.  
  3539.                  DEFSEG = &hexB800
  3540.                  BSAVE "SAVED.DAT" 0 4000
  3541.  
  3542.        After execution of these statements 4000 bytes at offset 0 bytes from
  3543.        the start of the override data segment (which in this case happens to
  3544.        point to the beginning of video memory for a CGA card) will be written
  3545.        to the file "SAVED.DAT".  Assuming a CGA card was present, the current
  3546.        screen would be saved to disk, assuming you are not in graphics mode.
  3547.  
  3548.        Comments:
  3549.  
  3550.             If ASIC detects an error executing this command, it will set the
  3551.        system ERROR variable.  These error codes are listed in the Error
  3552.        Messages Chapter of the ASIC Manual.
  3553.  
  3554.        See also:
  3555.  
  3556.             DEFSEG,BLOAD
  3557.  
  3558.  
  3559.  
  3560.  
  3561.  
  3562.  
  3563.  
  3564.  
  3565.  
  3566.  
  3567.  
  3568.  
  3569.  
  3570.  
  3571.  
  3572.  
  3573.  
  3574.  
  3575.  
  3576.  
  3577.  
  3578.  
  3579.  
  3580.  
  3581.  
  3582.                                        Page - 55
  3583.  
  3584.  
  3585.  
  3586.  
  3587.  
  3588.                                          CALL
  3589.  
  3590.        Format:        CALL (string1,string2)                       <-Format 1
  3591.                       CALL SUB (stringconstant1,[arg1,...,argN])   <-Format 2
  3592.  
  3593.        Description:
  3594.  
  3595.             Depending on the format that you select, this statement can be used
  3596.        to perform two different functions.  Format 1 is used to load and
  3597.        execute another program (in .EXE, .COM format).  Format 2 is used when
  3598.        you have compiled a subroutine in a .OBJ file, and wish to incorporate
  3599.        this routine in an ASIC program, and CALL it as a subroutine.  Notice
  3600.        the difference between these two approaches.  In format 1, execution of
  3601.        your ASIC program is suspended, and a new .EXE or .COM file is loaded
  3602.        from disk and executed.  When the .EXE or .COM program terminates, your
  3603.        ASIC program resumes execution.  With format 2, however, the subroutine
  3604.        itself is bound into your ASIC program with the DOS linker, so that when
  3605.        you call it, no disk access is required, and the overhead of the call is
  3606.        much lower.
  3607.  
  3608.             When using format 1, this statement can be used to load and execute
  3609.        other programs compiled with ASIC or another compiler.  String1
  3610.        represents the name of the program to execute.  String2 contains any
  3611.        arguments to be passed to the program (it may be NULL, ie "").  If an
  3612.        error occurs when ASIC attempts to call the program, it will set the
  3613.        system ERROR variable to 255.  Otherwise, the ERROR variable will be set
  3614.        to the value of the return code of the called program (which is 0 unless
  3615.        the called program specifies otherwise).
  3616.  
  3617.             Format 2 is used to call a separately compiled subroutine, that
  3618.        uses the BASIC (or PASCAL) parameter passing conventions.  You could use
  3619.        this to call a subroutine that you had written in assembler.  When using
  3620.        this format,  you must compile using the OBJ output option.  ASIC will
  3621.        produce an OBJ format output file, that can be linked with the standard
  3622.        DOS linker.  When you compile within the integrated environment, ASIC
  3623.        automatically calls the DOS linker for you, when the OBJ option is
  3624.        selected.  With this format, stringconstant1 must be a string constant
  3625.        that contains the name of the subroutine to be called.  The remaining
  3626.        fields (arg1 through argN) are optional, but if specified, they must be
  3627.        variables or constants.  These arguments will be passed to the called
  3628.        subroutine using the stack.  These arguments will be passed "by
  3629.        reference", which means that a pointer to the variable will be passed,
  3630.        instead of the value contained in the variable.  This means that the
  3631.        subroutine you call can modify the values of the ASIC variables passed.
  3632.  
  3633.        (See Chapter 10, Mixed Language Programming, of the ASIC manual, for
  3634.        more information on using format 2).
  3635.  
  3636.  
  3637.  
  3638.  
  3639.  
  3640.  
  3641.  
  3642.  
  3643.  
  3644.  
  3645.  
  3646.                                        Page - 56
  3647.  
  3648.  
  3649.  
  3650.  
  3651.  
  3652.                                    CALL (Continued)
  3653.  
  3654.        Example 1: (format 1)
  3655.  
  3656.                  CALL ("MYPROG.COM","")
  3657.                  REM other code follows
  3658.  
  3659.        This statement would cause ASIC to load and execute the program
  3660.        "MYPROG.COM".  No arguments will be passed to the program.  When MYPROG
  3661.        terminates, the calling program will regain control on the line
  3662.        following the call, in this case the "REM" statement.
  3663.  
  3664.        Example 2: (format 1)
  3665.  
  3666.                  CALL ("COMMAND.COM"," /C WP.BAT")
  3667.  
  3668.        In this example, a ".BAT" type file is executed called "WP.BAT".  To run
  3669.        ".BAT" files, it is necessary to load a copy of COMMAND.COM as shown
  3670.        above (COMMAND.COM contains the DOS code required to load and execute
  3671.        ".BAT" files).  Using this format, you can also run some "built in" DOS
  3672.        commands such as DIR or SORT.  Using CALL with this format, is similar
  3673.        to using the GWBASIC/BASICA SHELL command.
  3674.  
  3675.        Example 3: (format 2)
  3676.  
  3677.                  CALL SUB ("mysub",A,A$,1)
  3678.  
  3679.        In this example, a subroutine "mysub" is being called.  Three arguments
  3680.        are being passed to the subroutine, "A", "A$" and "1".  You must set the
  3681.        compiler output option to OBJ, and specify "MYSUB.OBJ" in the LINK
  3682.        options subroutine list.  The arguments will be passed to the subprogram
  3683.        on the stack in the order:   A,A$,1.
  3684.  
  3685.  
  3686.        Comments:
  3687.  
  3688.             Format 1:
  3689.  
  3690.             When using format 1, string1 must contain the FULL pathname of the
  3691.        program (ie,"\directory\progname.COM") only if the program is NOT in the
  3692.        current directory.  You must include the file extension on the file name
  3693.        (for example, use "MYPROG.COM" instead of just "MYPROG", or use
  3694.        "MYPROG.EXE" instead of "MYPROG").
  3695.  
  3696.             If you wish to pass arguments to the program build it as follows:
  3697.  
  3698.                  YOURPARM$ = "arguments"
  3699.                  N = LEN(YOURPARM$)
  3700.                  A$ = CHR$(N)
  3701.                  A$ = A$ + YOURPARM$
  3702.                  B$ = CHR$(13)
  3703.                  A$ = A$ + B$
  3704.                  CALL "progname" a$
  3705.  
  3706.  
  3707.  
  3708.  
  3709.  
  3710.                                        Page - 57
  3711.  
  3712.  
  3713.  
  3714.  
  3715.  
  3716.                                    CALL (Continued)
  3717.  
  3718.             The above creates an argument list according to the strict DOS
  3719.        calling rules, however, you can just create the arguments in a string,
  3720.        and precede them with a leading space.  This will work for arguments up
  3721.        to 32 characters in length (space character is ASCII 32).  You might
  3722.        want to try this short cut first, and only resort to the full formal
  3723.        approach if you have problems with it, or need to specify longer
  3724.        arguments:
  3725.  
  3726.                  CALL "progname" " arguments"
  3727.  
  3728.             It is recommended (but not required) that you compile your program
  3729.        using the EXE format (instead of the COM format) when your program uses
  3730.        format 1, since an EXE program will release more memory when calling the
  3731.        program.  This will allow you to call a slightly larger program than is
  3732.        possible with the COM format.
  3733.  
  3734.             Format 2:
  3735.  
  3736.             When using format 2 , the following considerations apply.  First,
  3737.        remember that the arguments you pass to the subroutine must match the
  3738.        arguments the subroutine expects to receive.  For example, if you pass a
  3739.        single integer to the subroutine, the subroutine had better expect to
  3740.        receive a single integer, or the results will be unpredictable.  Second,
  3741.        since all arguments are passed by reference, all arguments can be
  3742.        modified by the called routine.  Be aware that if you pass a constant
  3743.        such as "1" to the routine and it modifies the value to "2", that ASIC
  3744.        will now use the value "2" for the constant value of "1" wherever "1" is
  3745.        referenced your program.  For example, suppose you wrote a subroutine
  3746.        called ADD that added the value of argument 2 to the value of argument 1
  3747.        and stored the result in argument 1:
  3748.  
  3749.                  CALL SUB ("ADD", 1,33)
  3750.                  PRINT "1=";
  3751.                  PRINT 1
  3752.                  END
  3753.  
  3754.                       Program output is:
  3755.  
  3756.                            1=34
  3757.  
  3758.        Instead, you would want to code the program as follows:
  3759.  
  3760.  
  3761.                  A=1
  3762.                  CALL SUB ("ADD",A,1)
  3763.                  PRINT "A=";
  3764.                  PRINT A
  3765.                  PRINT "1=";
  3766.                  PRINT 1
  3767.                  END
  3768.  
  3769.                       Program output is:
  3770.  
  3771.                            A=34
  3772.                            1=1
  3773.  
  3774.                                        Page - 58
  3775.  
  3776.  
  3777.  
  3778.  
  3779.  
  3780.                                    CALL (Continued)
  3781.  
  3782.        CAUTION:
  3783.  
  3784.             IF YOU CALL A ".BAT" FILE AND DO NOT LOAD A COPY OF COMMAND.COM,
  3785.        THE RESULTS ARE UNPREDICTABLE (SEE ABOVE FOR AN EXAMPLE OF HOW TO CALL
  3786.        BAT FILE).
  3787.  
  3788.             You may use the debugger with programs which contain "CALL"
  3789.        statements.  However, the programs you call should not themselves
  3790.        contain debugging code.  For example, if A.ASI calls B.ASI, then make
  3791.        sure you compile B.ASI with the "Debugging Code" option OFF before you
  3792.        try to debug program A.ASI.  Failure to do so will cause the debugger to
  3793.        behave erratically.  This also applies to programs you write using other
  3794.        compilers, since they also use the same interrupt as ASIC (INT 3).
  3795.  
  3796.        See also:
  3797.  
  3798.             RUN,COMMAND$
  3799.  
  3800.  
  3801.  
  3802.                                          CHDIR
  3803.  
  3804.        Format:        CHDIR string1
  3805.  
  3806.        Description:
  3807.  
  3808.             This statement will change the current directory to that specified
  3809.        in string1.  If an error occurs when ASIC executes this command, it will
  3810.        set the System ERROR variable.  A list of possible error codes is listed
  3811.        in the Error Messages Chapter of the ASIC Manual.
  3812.  
  3813.        Example:
  3814.  
  3815.             CHDIR "\DOS"
  3816.             IF ERROR = 0 THEN NOERROR:
  3817.  
  3818.        If Drive "C" was the current drive, then this statement would change the
  3819.        current directory to "C:\DOS".
  3820.  
  3821.             CHDIR "C:\DOS"
  3822.  
  3823.        This statement would change the current directory on drive C to "C:\DOS"
  3824.        whether or not drive C is the current drive. It would NOT change the
  3825.        default drive to "C".  Note that DOS retains a current directory for
  3826.        each disk drive on your computer.
  3827.  
  3828.        See also:
  3829.  
  3830.             MKDIR, RMDIR
  3831.  
  3832.  
  3833.  
  3834.  
  3835.  
  3836.  
  3837.  
  3838.                                        Page - 59
  3839.  
  3840.  
  3841.  
  3842.  
  3843.  
  3844.                                          CHR$
  3845.  
  3846.        Format:        string1 = CHR$(number1)
  3847.  
  3848.        Description:
  3849.  
  3850.             This function converts an integer in the range of 0-255 to an
  3851.        ASCII character, and stores in string1.
  3852.  
  3853.        Example:
  3854.  
  3855.                  A$ = CHR$(49)
  3856.  
  3857.        After execution of this statement, "A$" will contain "1", since "1" is
  3858.        represented by ASCII 49.
  3859.  
  3860.        Comments:
  3861.  
  3862.                  If number1 is outside the range 0-255, then the least
  3863.        significant byte of the integer is converted to string1.
  3864.  
  3865.  
  3866.  
  3867.                                          CLOSE
  3868.  
  3869.        Format:        CLOSE number1
  3870.  
  3871.        Description:
  3872.  
  3873.             This function closes the file number identified by number1.  If an
  3874.        error is returned by DOS, the system variable "ERROR" will be > 0.
  3875.  
  3876.        Example:
  3877.  
  3878.                  CLOSE 1
  3879.                  IF ERROR > 0 THEN CHECKERROR:
  3880.  
  3881.        After successful execution of the CLOSE statement, the file previously
  3882.        opened as file 1 will be closed.  If an error is returned by DOS, the
  3883.        ERROR variable will be set by ASIC to a non-zero value.
  3884.  
  3885.        Comments:
  3886.  
  3887.             IF YOU FAIL TO CLOSE AN OPEN FILE (WHICH WAS OPENED FOR WRITING),
  3888.        YOU MAY LOSE DATA, SINCE FILE I/O IS BUFFERED, AND THE LAST BUFFER MAY
  3889.        NOT HAVE BEEN FLUSHED.
  3890.  
  3891.             Also, number1 may only be a constant with the value of 1-3.
  3892.  
  3893.        See Also:
  3894.  
  3895.             OPEN,PRINT#,INPUT#
  3896.  
  3897.  
  3898.  
  3899.  
  3900.  
  3901.  
  3902.                                        Page - 60
  3903.  
  3904.  
  3905.  
  3906.  
  3907.  
  3908.                                           CLS
  3909.  
  3910.        Format:        CLS
  3911.  
  3912.        Description:
  3913.  
  3914.             This function clears the screen.
  3915.  
  3916.        Example:
  3917.  
  3918.             CLS
  3919.  
  3920.        After execution of the above statement, the screen will be cleared.
  3921.  
  3922.  
  3923.  
  3924.                                          CODE
  3925.  
  3926.        Format:        CODE number1[,number2...numberN]
  3927.  
  3928.        Description:
  3929.  
  3930.             This function may be used to insert machine language code directly
  3931.        into your program.  Number1 through numberN should be integer constants
  3932.        in the range of 0-255.  At least one number must be specified, however,
  3933.        ASIC will allow up to 30 per CODE statement.
  3934.  
  3935.        Example:
  3936.                  CODE 205,5
  3937.  
  3938.        This statement represent the machine code generated from the assembly
  3939.        language statement "INT 5".  INT 5 is the BIOS routine which will print
  3940.        the screen to the printer.  After execution of these statements in your
  3941.        program, the current screen contents would be printed on your printer.
  3942.  
  3943.        Comments:
  3944.  
  3945.             THIS STATEMENT IS INTENDED FOR ADVANCED PROGRAMMERS.  THIS
  3946.        STATEMENT IS VERY POWERFUL, AND IF YOU DON'T UNDERSTAND MACHINE LANGUAGE
  3947.        YOU COULD EASILY CRASH YOUR PROGRAM.
  3948.  
  3949.             When you use this statement, be sure to save the contents of the
  3950.        following 8088 registers if you plan to modify them, and restore them
  3951.        before returning to ASIC.  Otherwise the results may be unpredictable.
  3952.        Registers:  DS/CS/ES/SS.  Also, make sure you clean up the stack before
  3953.        you return (ie, if you push a value to the stack, make sure you pop it
  3954.        before you return to ASIC)  Failure to do so, will almost certainly
  3955.        cause your program to crash.
  3956.  
  3957.  
  3958.  
  3959.  
  3960.  
  3961.  
  3962.  
  3963.  
  3964.  
  3965.  
  3966.                                        Page - 61
  3967.  
  3968.  
  3969.  
  3970.  
  3971.  
  3972.                                          COLOR
  3973.  
  3974.        Format:        COLOR number1,number2
  3975.  
  3976.        Description:
  3977.  
  3978.             This function is used to set the foreground and background screen
  3979.        colors.  The foreground color is specified in number1, the background
  3980.        color in number2.
  3981.  
  3982.                       Valid Colors:       Foreground     Background
  3983.                                           ----------     ----------
  3984.                       Black                    0              0
  3985.                       Blue                     1              1
  3986.                       Green                    2              2
  3987.                       Cyan                     3              3
  3988.                       Red                      4              4
  3989.                       Magenta                  5              5
  3990.                       Brown                    6              6
  3991.                       White                    7              7
  3992.                       Dark Gray                8
  3993.                       Light Blue               9
  3994.                       Light Green              10
  3995.                       Light Cyan               11
  3996.                       Light Red                12
  3997.                       Light Magenta            13
  3998.                       Yellow                   14
  3999.                       Bright White             15
  4000.  
  4001.                  Note:   Colors 8-15 when specified for background color
  4002.                            result in blinking text.
  4003.  
  4004.        Example:
  4005.  
  4006.                  COLOR 4,8
  4007.  
  4008.        After execution of this statement, future characters written to the
  4009.        screen will be Blinking Red on a Black Background.
  4010.  
  4011.  
  4012.  
  4013.  
  4014.  
  4015.  
  4016.  
  4017.  
  4018.  
  4019.  
  4020.  
  4021.  
  4022.  
  4023.  
  4024.  
  4025.  
  4026.  
  4027.  
  4028.  
  4029.  
  4030.                                        Page - 62
  4031.  
  4032.  
  4033.  
  4034.  
  4035.  
  4036.                                        COMMAND$
  4037.  
  4038.        Format:        string1 = COMMAND$
  4039.  
  4040.        Description:
  4041.  
  4042.             This statements retrieves any command line arguments that were
  4043.        entered and stores them in string1.
  4044.  
  4045.        Example:
  4046.                  If your program was invoked with:       MYPROG XXX
  4047.  
  4048.                  And if your program MYPROG.ASI contained the following:
  4049.  
  4050.                       A$=COMMAND$
  4051.                       A$=LTRIM$(A$)
  4052.                       IF A$="" THEN
  4053.                            PRINT "Enter File Name ";
  4054.                            INPUT A$
  4055.                       ENDIF
  4056.                       OPEN "I", 1, A$
  4057.  
  4058.  
  4059.             The above example would open file "XXXX" for input.  If the user
  4060.        had invoked the program by typing "MYPROG" with no parameters, then the
  4061.        program would prompt for the file name to open.
  4062.  
  4063.        Comments:
  4064.  
  4065.             In the integrated environment, you can specify command line
  4066.        arguments on the "Run" Menu.
  4067.  
  4068.             This statement is an extension over BASICA/GWBASIC.
  4069.  
  4070.  
  4071.  
  4072.  
  4073.  
  4074.  
  4075.  
  4076.  
  4077.  
  4078.  
  4079.  
  4080.  
  4081.  
  4082.  
  4083.  
  4084.  
  4085.  
  4086.  
  4087.  
  4088.  
  4089.  
  4090.  
  4091.  
  4092.  
  4093.  
  4094.                                        Page - 63
  4095.  
  4096.  
  4097.  
  4098.  
  4099.  
  4100.                                         COMSTAT
  4101.  
  4102.        Format:        number1 = COMSTAT (number2)
  4103.  
  4104.        Description:
  4105.  
  4106.             This statement returns the status of a com port.  Number2 should
  4107.        contain "0" for COM1, or "1" for COM2.  The status of that COM port is
  4108.        returned in number1.  Each bit in number1 represents a different piece
  4109.        of information.  These are described in the table below.  Note that you
  4110.        may test if a bit is on/off using the ZBIT command.
  4111.  
  4112.        Example:
  4113.  
  4114.             PORTSTAT = COMSTAT (0)
  4115.             DATAREADY = ZBIT(8,PORTSTAT)
  4116.             IF DATAREADY = 1 THEN GORECEIVE:
  4117.  
  4118.        These statements do the following.  The first retrieves the status of
  4119.        COM1 to the variable PORTSTAT.  The second checks to see if bit 8 is on,
  4120.        DATAREADY will contain 1 if so, otherwise it will contain 0.  Since Bit
  4121.        8 is used to determine if data is waiting to be received from the port,
  4122.        if DATAREADY = 1 then the program will transfer to the label GORECEIVE:
  4123.        which would contain code to RECEIVE data from the port.
  4124.  
  4125.        Comments:
  4126.  
  4127.             Status Codes Returned by COMSTAT (Meaning when set to 1)
  4128.  
  4129.             Bit 0     Delta clear-to-send
  4130.                 1     Delta data-set-ready
  4131.                 2     Trailing-edge ring detector
  4132.                 3     Delta receive line signal detect
  4133.                 4     Clear-to-send
  4134.                 5     Data-set-ready
  4135.                 6     Ring Indicator
  4136.                 7     Received line signal detect
  4137.                 8     Data Ready
  4138.                 9     Overrun error
  4139.                10     Parity error
  4140.                11     Framing error
  4141.                12     Break-detect error
  4142.                13     Transfer holding register empty
  4143.                14     Transfer shift-register empty
  4144.                15     Time-out error
  4145.  
  4146.  
  4147.        See also:
  4148.  
  4149.             OPENCOM,SEND,RECEIVE
  4150.  
  4151.  
  4152.  
  4153.  
  4154.  
  4155.  
  4156.  
  4157.  
  4158.                                        Page - 64
  4159.  
  4160.  
  4161.  
  4162.  
  4163.  
  4164.                                         CSRLIN
  4165.  
  4166.        Format:        number1 = CSRLIN
  4167.  
  4168.        Description:
  4169.  
  4170.             This function returns row of the cursor.
  4171.  
  4172.        Example:
  4173.  
  4174.                       LOCATE 10,20
  4175.                       A = CSRLIN
  4176.  
  4177.        The locate command will have positioned the cursor in row 10, column 20.
  4178.        After execution of the CSRLIN statement, "A" will contain the value of
  4179.        10.
  4180.  
  4181.        See also:
  4182.  
  4183.             POS
  4184.  
  4185.  
  4186.  
  4187.  
  4188.  
  4189.  
  4190.  
  4191.  
  4192.  
  4193.  
  4194.  
  4195.  
  4196.  
  4197.  
  4198.  
  4199.  
  4200.  
  4201.  
  4202.  
  4203.  
  4204.  
  4205.  
  4206.  
  4207.  
  4208.  
  4209.  
  4210.  
  4211.  
  4212.  
  4213.  
  4214.  
  4215.  
  4216.  
  4217.  
  4218.  
  4219.  
  4220.  
  4221.  
  4222.                                        Page - 65
  4223.  
  4224.  
  4225.  
  4226.  
  4227.  
  4228.                                          DATA
  4229.  
  4230.        Format:        DATA constant1[,constant2,...,constantn]
  4231.  
  4232.        Description:
  4233.  
  4234.             This statement is used store integer, decimal and string constants
  4235.        in memory for later retrieval by READ statements.  At least one constant
  4236.        must be specified, although multiples of each type are permitted.
  4237.  
  4238.        Example:
  4239.  
  4240.             DATA 1,"APPLE",2&,"ORANGES",1.2345
  4241.  
  4242.  
  4243.             READ A
  4244.             READ A$
  4245.             READ B&
  4246.             READ B$
  4247.             READ C@
  4248.  
  4249.        The above statements are equivalent of entering the following code:
  4250.  
  4251.             A=1
  4252.             A$="APPLE"
  4253.             B&=2&
  4254.             B$="ORANGES"
  4255.             C@=1.2345
  4256.  
  4257.        Comments:
  4258.  
  4259.             All DATA Statements must be placed at the beginning of the program,
  4260.        before all other statement types, except DIM or REM statements (or blank
  4261.        lines).  DIM statements, if specified, must precede all other statements
  4262.        including DATA statements except REM statements (or blank lines).  As
  4263.        long as you follow these rules, you may specify an unlimited number of
  4264.        DATA statements.
  4265.  
  4266.             GWBASIC/BASICA does not require quotes around string constants in
  4267.        some instances.  ASIC always requires quotes around string constants.
  4268.  
  4269.        See also:
  4270.  
  4271.             READ,RESTORE
  4272.  
  4273.  
  4274.  
  4275.  
  4276.  
  4277.  
  4278.  
  4279.  
  4280.  
  4281.  
  4282.  
  4283.  
  4284.  
  4285.  
  4286.                                        Page - 66
  4287.  
  4288.  
  4289.  
  4290.  
  4291.  
  4292.                                          DATE$
  4293.  
  4294.        Format:        string1 = DATE$
  4295.  
  4296.        Description:
  4297.  
  4298.             This function returns the value of the system date in the format of
  4299.        "MM-DD-YYYY".
  4300.  
  4301.        Example:
  4302.  
  4303.             A$=DATE$
  4304.             PRINT A$
  4305.  
  4306.        After executing these statements, the date stored in the PC
  4307.         System Clock will be displayed on the screen.
  4308.  
  4309.  
  4310.        Comments:
  4311.  
  4312.  
  4313.             Note:  if the date printed is wrong, you have probably not set the
  4314.        system clock.  Most older XTs and PCs do not have a battery to preserve
  4315.        the DATE and TIME in the system clock, so you have to set them each time
  4316.        you power up the PC.  Most ATs and newer PCs have a battery backup, so
  4317.        that the date is preserved for you.
  4318.  
  4319.             Unlike GWBASIC/BASICA, you cannot set the system date with DATE$,
  4320.        however, you can set the system date from DOS by typing DATE.
  4321.  
  4322.        See also:
  4323.  
  4324.             TIME$, TIMER
  4325.  
  4326.  
  4327.  
  4328.                                         DEFSEG
  4329.  
  4330.        Format:        DEFSEG = number1
  4331.  
  4332.             This function is used to alter the default data segment used when
  4333.        peeking and poking data with PEEK and POKE statements.  DEFSEG, PEEK,
  4334.        and especially POKE are not recommended for beginners.  If number1 =-1,
  4335.        then the data segment address is set back to the ASIC default data
  4336.        segment address.
  4337.  
  4338.        Example:
  4339.  
  4340.             DEFSEG = -1
  4341.  
  4342.        Execution of the above statement would reset the default data segment to
  4343.        the default ASIC data segment.
  4344.  
  4345.        See also:
  4346.  
  4347.             PEEK, POKE, BLOAD, BSAVE
  4348.  
  4349.  
  4350.                                        Page - 67
  4351.  
  4352.  
  4353.  
  4354.  
  4355.  
  4356.                                           DIM
  4357.  
  4358.        Format:        DIM variable(integer1)
  4359.  
  4360.  
  4361.        Description:
  4362.  
  4363.             This statement will create one dimensional arrays.  An integer,
  4364.        decimal or string variable name must be specified in variable.  Integer1
  4365.        contains the number of elements in the array.
  4366.  
  4367.        Example:
  4368.  
  4369.                  DIM A(10)
  4370.                  DIM A&(20)
  4371.                  DIM A$(5)
  4372.                  DIM A@(3)
  4373.  
  4374.        In this example an array of 10 normal integer variables is defined, an
  4375.        array of 20 long integer variables is defined, an array of 5 string
  4376.        variables is defined and an array of 3 decimal variables is defined.
  4377.  
  4378.        Comments:
  4379.  
  4380.             On the DIM statement, number1 may only be a constant.  Also, DIM
  4381.        statements must appear before all other statement types in the program
  4382.        except REM statements (or blank lines).
  4383.  
  4384.  
  4385.  
  4386.                                           END
  4387.  
  4388.        Format:        END [(number1)]
  4389.  
  4390.        Description:
  4391.  
  4392.             This statement causes your program to terminate and return to DOS,
  4393.        optionally setting a return code.  Number1 may be optionally specified
  4394.        to set the return code.  If omitted, ASIC uses a return code of zero by
  4395.        default.
  4396.  
  4397.        Example:
  4398.  
  4399.                  END
  4400.  
  4401.        In this example, the program will terminate and return to DOS with a
  4402.        return code of zero.
  4403.  
  4404.                  END (20)
  4405.  
  4406.        In this example, the program will terminate and return to DOS with a
  4407.        return code of "20".
  4408.  
  4409.        Comments:
  4410.  
  4411.             The optional return code is an extension over GWBASIC/BASICA.
  4412.  
  4413.  
  4414.                                        Page - 68
  4415.  
  4416.  
  4417.  
  4418.  
  4419.  
  4420.                                        ENVIRON$
  4421.  
  4422.        Format:        string1 = ENVIRON$(number1)
  4423.  
  4424.        Description:
  4425.  
  4426.             This statement will retrieve DOS environment strings.  Number1
  4427.        identifies which string to retrieve.  If found, the string is placed in
  4428.        string1.  If not found, a NULL string (length=0) is stored in string1.
  4429.  
  4430.        Example:
  4431.  
  4432.             FOR I=1 TO 5
  4433.                  A$=ENVIRON$(I)
  4434.                  PRINT A$
  4435.             NEXT I
  4436.  
  4437.        The above example will retrieve the first five DOS environment strings
  4438.        and display them.
  4439.  
  4440.        Comments:
  4441.  
  4442.             If the requested DOS environment string entry is greater than 80
  4443.        characters in length, ASIC will truncate it at 80 characters.
  4444.        Environment strings may be set in DOS using the SET command.
  4445.        Environment strings are one way of passing information to your program.
  4446.        Refer to your MS DOS Manual for more information.  Common uses of this
  4447.        command are to retrieve the user's PATH statement, or the COMSPEC
  4448.        variable.
  4449.  
  4450.  
  4451.  
  4452.  
  4453.  
  4454.  
  4455.  
  4456.  
  4457.  
  4458.  
  4459.  
  4460.  
  4461.  
  4462.  
  4463.  
  4464.  
  4465.  
  4466.  
  4467.  
  4468.  
  4469.  
  4470.  
  4471.  
  4472.  
  4473.  
  4474.  
  4475.  
  4476.  
  4477.  
  4478.                                        Page - 69
  4479.  
  4480.  
  4481.  
  4482.  
  4483.  
  4484.                                         FILEPOS
  4485.  
  4486.        Format:        number1 = FILEPOS (number2,number3)    <--Format 1
  4487.                       number1 = FILEPOS (number2,EOF)        <--Format 2
  4488.                       number1 = FILEPOS (number2,CURRENT)    <--Format 3
  4489.  
  4490.        Description:
  4491.  
  4492.             This statement is used to set or retrieve the read/write position
  4493.        for files opened in Random mode.  In all three formats, number2 is the
  4494.        file number of the file.  This file number must have been previously
  4495.        opened for Random mode by the OPEN statement.  Format 1 is used to set
  4496.        the current read/write position of the file specified by number2.
  4497.        Number3 should be the offset (in bytes) from the start of the file.
  4498.        Format 2 is used to set a read/write position of a random file to the
  4499.        end of the file.  Format 3 is used to retrieve the current read/write
  4500.        position (as a byte offset from the beginning of the file) of the file.
  4501.        In all cases, if an error occurs, the system ERROR variable will be set.
  4502.        A list of these codes is contained in the Error Codes Chapter of the
  4503.        ASIC Manual.  If no error occurs, then number1 will be set to the
  4504.        current read/write position of the file.
  4505.  
  4506.        Example 1:
  4507.  
  4508.             A&=FILEPOS(1, 100)
  4509.  
  4510.        This example assumes that file 1 was previously opened for RANDOM I/O
  4511.        using the OPEN statement.  After execution of this statement, the
  4512.        read/write position of file number 1 will be set to 100.  Subsequent
  4513.        PRINT # statements would write to the file starting at position 101.
  4514.  
  4515.        Example 2:
  4516.  
  4517.             A&=FILEPOS(1,EOF)
  4518.  
  4519.        This example assumes that file 1 was previously opened for RANDOM I/O
  4520.        using the OPEN statement.  After execution of this statement, the
  4521.        read/write position of file number 1 will be set to the end of the file.
  4522.        Subsequent PRINT # operations to this file will result in data being
  4523.        appended to this file.
  4524.  
  4525.        Example 3:
  4526.  
  4527.             A&=FILEPOS(1,CURRENT)
  4528.  
  4529.        This example assumes that file 1 was previously opened for RANDOM I/O
  4530.        using the OPEN statement.  After execution of this statement, the
  4531.        current read/write position of file number 1 will retrieved and stored
  4532.        in A&.  The read/write position of file number 1 will NOT be altered
  4533.        after execution of this statement.
  4534.  
  4535.  
  4536.  
  4537.  
  4538.  
  4539.  
  4540.  
  4541.  
  4542.                                        Page - 70
  4543.  
  4544.  
  4545.  
  4546.  
  4547.  
  4548.                                   FILEPOS (Continued)
  4549.  
  4550.        Comments:
  4551.  
  4552.             If you wish to use this command with files larger than 32767 bytes,
  4553.        you should use long integer or decimal numbers with this statement.  If
  4554.        you set the read/write position past the physical end of file and
  4555.        attempt to read from the file, you will receive an error on the INPUT#
  4556.        command.  If you set the read/write position past the end of file and
  4557.        issue a PRINT# command, the data will be correctly written at the
  4558.        position you specified.
  4559.  
  4560.        See also:
  4561.  
  4562.             OPEN, INPUT#, PRINT#, CLOSE
  4563.  
  4564.  
  4565.  
  4566.  
  4567.  
  4568.  
  4569.  
  4570.  
  4571.  
  4572.  
  4573.  
  4574.  
  4575.  
  4576.  
  4577.  
  4578.  
  4579.  
  4580.  
  4581.  
  4582.  
  4583.  
  4584.  
  4585.  
  4586.  
  4587.  
  4588.  
  4589.  
  4590.  
  4591.  
  4592.  
  4593.  
  4594.  
  4595.  
  4596.  
  4597.  
  4598.  
  4599.  
  4600.  
  4601.  
  4602.  
  4603.  
  4604.  
  4605.  
  4606.                                        Page - 71
  4607.  
  4608.  
  4609.  
  4610.  
  4611.  
  4612.                                          FIND
  4613.  
  4614.        Format:        string1=FIND FIRST (string2,number1)
  4615.                       string1=FIND CONTINUE
  4616.  
  4617.        Description:
  4618.  
  4619.             The FIND command is used to search the current file directory for
  4620.        file(s) which match a search string.  This command has two versions.
  4621.        FIND FIRST must be used to establish a new search and retrieve the first
  4622.        matching file name.  Thereafter, the FIND CONTINUE will retrieve
  4623.        additional file names which match the search string.  When performing
  4624.        the FIND FIRST, string2 should contain the full or partial file name to
  4625.        be searched for.  This string can be up to 8 alphanumeric characters
  4626.        optionally followed by a period and up to 3 alphanumeric characters for
  4627.        the file extension.  Standard DOS wild cards "*" and "?" may be included
  4628.        in the search string.  Number1 is used to specify a file attribute.  If
  4629.        number1 is "0", then all normal files in the directory will be searched.
  4630.        (A normal file is one in which the hidden, system, volume label, or
  4631.        directory attribute bit is NOT set).  Setting various bits (see table
  4632.        below) of number1 ON will expand the search to include normal files,
  4633.        plus those whose attributes have been specified in number1.  If a
  4634.        matching file name is found, then it will be stored in string1.  If an
  4635.        error occurs, then the system ERROR variable will be set.  A list of
  4636.        ERROR codes is contained in the ERROR code chapter of the ASIC Manual.
  4637.        After the initial FIND FIRST has been performed, you may search for
  4638.        additional files which match the search string and attribute by issuing
  4639.        a FIND CONTINUE statement.
  4640.  
  4641.        Search Attributes bits (number1)
  4642.        --------------------------------
  4643.  
  4644.        BIT
  4645.  
  4646.        0    Not Used
  4647.        1    Hidden
  4648.        2    System
  4649.        3    Volume Label
  4650.        4    Subdirectory
  4651.        5-7  Not Used
  4652.  
  4653.        Note that these attributes can all be specified simultaneously.  For
  4654.        example, to specify both hidden and system, use an attribute value of
  4655.        &bin00000110 (in binary) or 6 (in decimal).
  4656.  
  4657.  
  4658.  
  4659.  
  4660.  
  4661.  
  4662.  
  4663.  
  4664.  
  4665.  
  4666.  
  4667.  
  4668.  
  4669.  
  4670.                                        Page - 72
  4671.  
  4672.  
  4673.  
  4674.  
  4675.  
  4676.                                    FIND (Continued)
  4677.  
  4678.        Example:
  4679.  
  4680.                  SEARCH$="*.ASI"
  4681.                  ATTRIB=0
  4682.                  FILENAME$=FIND FIRST (SEARCH$,ATTRIB)
  4683.                  IF ERROR>0 THEN DONE:
  4684.                  PRINT A$
  4685.             LOOP:FILENAME$=FIND CONTINUE
  4686.                  IF ERROR>0 THEN DONE:
  4687.                  PRINT A$
  4688.                  GOTO LOOP
  4689.             DONE: PRINT "ALL MATCHING FILES DISPLAYED"
  4690.             END
  4691.  
  4692.        After execution of the above statements, all of the files with a file
  4693.        extension of ".ASI" in the current directory will be displayed on the
  4694.        screen.
  4695.  
  4696.        Comments:
  4697.  
  4698.             If you execute a FIND CONTINUE without executing a FIND FIRST, then
  4699.        the results are unpredictable.  Additional information is retrieved by
  4700.        the FIND command besides the file name.  Advanced programmers can also
  4701.        find additional information using the PEEK command starting at offset
  4702.        149 (from the default ASIC data segment).  Do not modify this data.  If
  4703.        you do so, the results are unpredictable.
  4704.  
  4705.  
  4706.        Additional File Information
  4707.        ---------------------------
  4708.  
  4709.        Address   Size (bytes)   Description
  4710.  
  4711.  
  4712.        149       1              File Attribute
  4713.        150       2              File Time Stamp
  4714.        152       2              File Date Stamp
  4715.        154       4              File Size (bytes)
  4716.  
  4717.  
  4718.        See also:
  4719.  
  4720.             NAME, KILL, GETDIR, CHDIR, MKDIR, RMDIR
  4721.  
  4722.  
  4723.  
  4724.  
  4725.  
  4726.  
  4727.  
  4728.  
  4729.  
  4730.  
  4731.  
  4732.  
  4733.  
  4734.                                        Page - 73
  4735.  
  4736.  
  4737.  
  4738.  
  4739.  
  4740.                                        FOR/NEXT
  4741.  
  4742.        Format:        FOR number1 = number2 to number3
  4743.                       NEXT number1
  4744.  
  4745.        Description:
  4746.  
  4747.             These two statements are used to create a loop, so that you can
  4748.        execute a portion of your program a certain number of times.  All of the
  4749.        code between the FOR and the NEXT statement will be executed a certain
  4750.        number of times, but at least once.  The actual number of times the loop
  4751.        executes is dependent on number1/number2/number3. When the FOR statement
  4752.        is encountered in your program, number1 is assigned the value of
  4753.        number2.  Then the statements up to the matching NEXT statement is
  4754.        executed one time.  Then, 1 is added to number1, and number1 is compared
  4755.        to number3.  If number1 is greater than number3 then the control passes
  4756.        to the statement following NEXT.  Otherwise, the program loops back up
  4757.        to the statement following the FOR statement.
  4758.  
  4759.        Example:
  4760.  
  4761.                  FOR I = 1 TO 2
  4762.                       FOR J = 3 TO 5
  4763.                            PRINT I;
  4764.                            PRINT J
  4765.                       NEXT J
  4766.                  NEXT I
  4767.                  PRINT "AFTER THE LOOP";
  4768.                  PRINT I;
  4769.                  PRINT J;
  4770.  
  4771.        Execution of this section of code would result in the following
  4772.        printout:
  4773.  
  4774.                  1    3
  4775.                  1    4
  4776.                  1    5
  4777.                  2    3
  4778.                  2    4
  4779.                  2    5
  4780.                  AFTER THE LOOP    3    6
  4781.  
  4782.        Comments:
  4783.  
  4784.             Unlike BASICA/GWBASIC, ASIC FOR/NEXT loops execute at least 1 time.
  4785.        For example, the value "HELLO" will be printed in the following example.
  4786.        It wouldn't have been in BASICA/GWBASIC.
  4787.  
  4788.                  FOR I = 1 TO 0
  4789.                       PRINT "HELLO"
  4790.                  NEXT I
  4791.  
  4792.  
  4793.  
  4794.  
  4795.  
  4796.  
  4797.  
  4798.                                        Page - 74
  4799.  
  4800.  
  4801.  
  4802.  
  4803.  
  4804.                                  FOR/NEXT (Continued)
  4805.  
  4806.             Unlike GWBASIC/BASICA, arrays may be used for number1 and number2.
  4807.        However, if number3 is an array, element zero will be used, regardless
  4808.        of the subscript you specify.
  4809.  
  4810.             Loops which range from a negative to positive number are not
  4811.        supported (for performance reasons).  Such loops will terminate after 1
  4812.        iteration.  For example, "FOR I =-10 to 10" will loop once.
  4813.  
  4814.             ASIC will allow you to modify the value of number3, while
  4815.        GWBASIC/BASICA ignores changes.
  4816.  
  4817.                  J=1
  4818.                  FOR I=1 TO J
  4819.                       J=2
  4820.                  NEXT I
  4821.  
  4822.             The above loop will execute one time in GWBASIC/BASICA, but it will
  4823.        execute two times in ASIC.
  4824.  
  4825.             Also note:  The storage type of number3 must be the same as
  4826.        number1.  For example, if "number1" is a decimal variable, then
  4827.        "number3" must be a decimal variable--it may not be an integer variable.
  4828.  
  4829.  
  4830.  
  4831.                                         GETDIR
  4832.  
  4833.        Format:        string1=GETDIR (number1)
  4834.  
  4835.        Description:
  4836.  
  4837.             This statement is used to retrieve the current DOS directory.
  4838.        Number1 should be set to "0" to obtain the directory for the current
  4839.        drive, "1" for the "A" drive, "2" for the "B" drive, etc.  If the
  4840.        statement is unsuccessful, the system ERROR variable will be set.  A
  4841.        complete list of ERROR codes is contained in the Error Code Chapter of
  4842.        the ASIC Manual.  The directory string will be stored in string1.  The
  4843.        directory string will not contain the drive letter, or the first "\".
  4844.        Thus, if the current directory on the specified drive was "C:\ASIC",
  4845.        then GETDIR would return "ASIC".  If the current directory was the root
  4846.        (eg, "C:\"), then GETDIR would return a NULL string ("").
  4847.  
  4848.        Example:
  4849.  
  4850.             A$=GETDIR(0)
  4851.  
  4852.        After execution of this statement, the variable A$ will contain the name
  4853.        of current directory on the current disk drive.
  4854.  
  4855.        See also:
  4856.  
  4857.             FIND, MDKIR, RMDIR, CHDIR
  4858.  
  4859.  
  4860.  
  4861.  
  4862.                                        Page - 75
  4863.  
  4864.  
  4865.  
  4866.  
  4867.  
  4868.                                          GOSUB
  4869.  
  4870.        Format:        GOSUB label1
  4871.  
  4872.        Description:
  4873.  
  4874.             This statement "calls" a subroutine called "label1".  This
  4875.        subroutine must contain a "RETURN".  After the subroutine is executed,
  4876.        control is returned to the next statement following the GOSUB.
  4877.  
  4878.        Example:
  4879.  
  4880.                  GOSUB PRINTIT:
  4881.                  PRINT "All Done!"
  4882.                  END
  4883.                  PRINTIT:  PRINT "It"
  4884.                  RETURN
  4885.  
  4886.        After execution of this code the screen would contain:
  4887.  
  4888.                  It
  4889.                  All Done!
  4890.  
  4891.  
  4892.  
  4893.                                          GOTO
  4894.  
  4895.        Format:        GOTO label1
  4896.  
  4897.        Description:
  4898.  
  4899.             This statement transfers program execution to the statement
  4900.        identified by label1.
  4901.  
  4902.        Example:
  4903.  
  4904.                  GOTO SKIPIT:
  4905.                  PRINT "YOU'LL NEVER GET HERE"
  4906.                  SKIPIT: PRINT "ALL DONE!"
  4907.  
  4908.        After execution of this code, the screen will appear as follows:
  4909.  
  4910.                  ALL DONE!
  4911.  
  4912.        Note that the first print statement never executes because of the GOTO.
  4913.  
  4914.  
  4915.  
  4916.  
  4917.  
  4918.  
  4919.  
  4920.  
  4921.  
  4922.  
  4923.  
  4924.  
  4925.  
  4926.                                        Page - 76
  4927.  
  4928.  
  4929.  
  4930.  
  4931.  
  4932.                                   IF/THEN/ELSE/ENDIF
  4933.  
  4934.        Format:        IF condition THEN label1                  <--Format 1
  4935.                       IF condition THEN label1 ELSE label2      <--Format 2
  4936.  
  4937.                       IF condition THEN                         <--Format 3
  4938.                            <zero or more ASIC statements>
  4939.                       ENDIF
  4940.  
  4941.                       IF condition THEN                         <--Format 4
  4942.                            <zero or more ASIC statements>
  4943.                       ELSE
  4944.                            <zero or more ASIC statements>
  4945.                       ENDIF
  4946.  
  4947.        Description:
  4948.  
  4949.             This statement is used to conditionally transfer to a different
  4950.        location in the program.  The operand "condition" is one of the
  4951.        following:
  4952.  
  4953.                       number1 > number2
  4954.                       string1  > string2
  4955.                       number1 = number2
  4956.                       string1  = string2
  4957.                       number1 < number2
  4958.                       string1  < string2
  4959.  
  4960.  
  4961.        Format 1--If "condition" is true, control is transferred to label1.
  4962.        Otherwise the program continues at the next statement.
  4963.  
  4964.        Format 2--If "condition" is true, control is transferred to label1,
  4965.        otherwise the program branches to label2 and continues execution from
  4966.        there.
  4967.  
  4968.        Format 3--If "condition" is true, the program will continue execution at
  4969.        the next statement.  If the condition is false, the program will branch
  4970.        to the statement following the next ENDIF statement encountered.
  4971.  
  4972.        Format 4--If "condition" is true, program will continue execution at the
  4973.        next statement up to the next ELSE statement encountered, at which point
  4974.        it will branch to the statement following the next ENDIF statement
  4975.        encountered.  If "condition" is false, the program will branch to the
  4976.        next ELSE statement and resume execution at that statement.
  4977.  
  4978.        Example 1:
  4979.  
  4980.                  IF A > 0 THEN APLUS:
  4981.  
  4982.        In this example, if A is greater than zero, the program jumps to the
  4983.        label called "APLUS:".
  4984.  
  4985.  
  4986.  
  4987.  
  4988.  
  4989.  
  4990.                                        Page - 77
  4991.  
  4992.  
  4993.  
  4994.  
  4995.  
  4996.                             IF/THEN/ELSE/ENDIF (Continued)
  4997.  
  4998.        Example 2:
  4999.  
  5000.                  IF A$="YES" THEN TRUE: ELSE FALSE:
  5001.  
  5002.        In this example, if A$ contains the string "YES", the program jumps to
  5003.        the label called "TRUE:", otherwise the program transfers to label
  5004.        "FALSE:"
  5005.  
  5006.        Example 3:
  5007.  
  5008.                  OPEN "I",1,"TEST.DAT"
  5009.                  IF ERROR>0 THEN
  5010.                       PRINT "ERROR OPENING FILE";
  5011.                       PRINT ERROR
  5012.                       END
  5013.                  ENDIF
  5014.                  REM rest of program follows
  5015.                  .
  5016.                  .
  5017.  
  5018.  
  5019.        In this example, if there is an error opening file "TEST.DAT", the
  5020.        program will print an error message and terminate.  Otherwise control
  5021.        will fall through to the REM statement and the program will continue.
  5022.  
  5023.        Example 4:
  5024.  
  5025.                  PRINT "ENTER A NUMBER";
  5026.                  INPUT NUMBER
  5027.                  IF NUMBER > 100 THEN
  5028.                       PRINT "THAT'S A BIG NUMBER"
  5029.                  ELSE
  5030.                       PRINT "THAT'S A SMALL NUMBER"
  5031.                  ENDIF
  5032.  
  5033.        Comments:
  5034.  
  5035.             Formats 3 and 4 are BLOCK IF formats.  You can nest BLOCK IF
  5036.        statements up to 25 levels deep.  The example below is shown three
  5037.        levels deep.
  5038.  
  5039.             IF A=1 THEN                                  <-Level 1
  5040.                  IF B=2 THEN                             <-Level 2
  5041.                       IF C=3 THEN                        <-Level 3
  5042.                            PRINT "C=3, B=2, AND A=1"
  5043.                       ELSE
  5044.                            PRINT "C<>3, B=2, AND A=1"    <-ELSE  for Level 3
  5045.                       ENDIF                              <-ENDIF for Level 3
  5046.                  ENDIF                                   <-ENDIF for Level 2
  5047.             ENDIF                                        <-ENDIF for Level 1
  5048.  
  5049.             It's a good idea to indent your IFs, ELSEs and ENDIFs as shown
  5050.        above.  Otherwise matching IFs up with matching ENDIFs and ELSEs can
  5051.        become very confusing.
  5052.  
  5053.  
  5054.                                        Page - 78
  5055.  
  5056.  
  5057.  
  5058.  
  5059.  
  5060.                                         INKEY$
  5061.  
  5062.        Format:        string1 = INKEY$
  5063.  
  5064.        Description:
  5065.  
  5066.             Used to retrieve keystrokes from the keyboard buffer.  If a
  5067.        character is waiting in the buffer, string1 will be set to the value of
  5068.        that character, and that character will be removed from the keyboard
  5069.        buffer.  If the buffer is empty, string1 will be set to a value of ""
  5070.        (that is, a null string with a length of 0).  If an extended key is
  5071.        pressed (for example the function keys F1 through F10), the system
  5072.        variable EXTENDED will be set to 1, otherwise it will contain 0.
  5073.  
  5074.        Example:
  5075.  
  5076.                  LOOP: X$=INKEY$
  5077.                  IF X$="" THEN LOOP:
  5078.  
  5079.        The above code will cause the program to loop until a key is pressed.
  5080.  
  5081.        Comment:
  5082.  
  5083.             ASIC provides an extension here over BASICA/GWBASIC.  The EXTENDED
  5084.        system variable will allow you to detect special keys as mentioned
  5085.        above.  To do so requires an understanding of keyboard scan codes, which
  5086.        is beyond the scope of the ASIC Manual.  For more information I would
  5087.        suggest Peter Norton's Programmer Guide to the IBM PC (Microsoft Press).
  5088.  
  5089.  
  5090.  
  5091.                                           INP
  5092.  
  5093.        Format:        number1 = INP (number2)
  5094.  
  5095.        Description:
  5096.  
  5097.             This statement reads a byte from port number2 and stores the result
  5098.        in number1.
  5099.  
  5100.        Example:
  5101.  
  5102.             A=INP(513)
  5103.             A=ZBIT(4,A)
  5104.             IF A=1 THEN TRIGGERPRESSED:
  5105.  
  5106.        The above code will test the joystick port to see if the trigger is
  5107.        being pressed on joystick 1.  You need a game card and joystick for this
  5108.        to work.
  5109.  
  5110.        See also:
  5111.  
  5112.             OUT
  5113.  
  5114.  
  5115.  
  5116.  
  5117.  
  5118.                                        Page - 79
  5119.  
  5120.  
  5121.  
  5122.  
  5123.  
  5124.                                          INPUT
  5125.  
  5126.        Format :       INPUT variable1     <--Format 1
  5127.                       INPUT variable1;    <--Format 2
  5128.  
  5129.  
  5130.        Description:
  5131.  
  5132.             This statement will retrieve a line of text from the input buffer
  5133.        and store it in variable1.  There are two statement formats.
  5134.  
  5135.             When using Format 1, ASIC will first issue the prompt "?".  It will
  5136.        then wait until the user enters a string or number and presses the
  5137.        <return> or <enter> key.  The type of data ASIC will expect is dependent
  5138.        on the type of variable1 (integer, decimal, or string).  If an integer
  5139.        or decimal is being entered, ASIC will edit the input for validity. If
  5140.        the edit fails ASIC will issue another "?" to the user, and will wait
  5141.        for the number to be retyped.  Only when a valid integer has been
  5142.        entered will variable1 be updated, and only then will control return to
  5143.        your ASIC program.  Following a successful INPUT, ASIC will generate a
  5144.        carriage return/line feed sequence and advance the cursor to the next
  5145.        line.
  5146.  
  5147.             When using Format 2, ASIC will NOT issue a prompt.  It will still
  5148.        edit the user input based on the type of variable.  However, if the
  5149.        input is invalid it does not reprompt the user to re-enter the data.
  5150.        Instead, it will set the system ERROR variable to "1" and return control
  5151.        to your ASIC program.  The value stored in variable1 will be undefined
  5152.        if the ERROR variable is set!  ASIC will issue a carriage return, but it
  5153.        will NOT issue a line feed.  Format 2 is useful when you want to use the
  5154.        INPUT statement with it's data edit capabilities in conjunction with a
  5155.        data entry form.  In this case, you don't want ASIC to write any prompts
  5156.        to the screen, and you don't want ASIC to scroll the screen.
  5157.  
  5158.        Example 1:
  5159.  
  5160.                  PRINT "Enter a String";
  5161.                  INPUT A$
  5162.  
  5163.        ASIC will issue the prompt:
  5164.  
  5165.                  Enter a String?
  5166.  
  5167.        It will then wait until you enter a string or press enter.  If you
  5168.        pressed enter with no characters A$ would contain "" (ie its length
  5169.        would equal 0), otherwise A$ would contain the string entered.
  5170.  
  5171.  
  5172.  
  5173.  
  5174.  
  5175.  
  5176.  
  5177.  
  5178.  
  5179.  
  5180.  
  5181.  
  5182.                                        Page - 80
  5183.  
  5184.  
  5185.  
  5186.  
  5187.  
  5188.                                    INPUT (Continued)
  5189.  
  5190.        Example 2:
  5191.  
  5192.                  INPUT I
  5193.  
  5194.        In this example ASIC will issue the prompt:
  5195.  
  5196.                  ?
  5197.  
  5198.        ASIC will then wait for you to enter a valid number.  If you enter an
  5199.        invalid number, say "x", ASIC will reissue the "?" prompt and wait for
  5200.        you to retype your input.  Once the input has been edited by ASIC, "I"
  5201.        would contain the number entered.
  5202.  
  5203.        Example 3:
  5204.  
  5205.             LOOP:
  5206.                  PRINT "YOUR CHOICE?";
  5207.                  INPUT A;
  5208.                  IF ERROR=1 THEN
  5209.                       PRINT "THE NUMBER YOU ENTERED WAS INVALID"
  5210.                  END IF
  5211.                  GOTO LOOP:
  5212.  
  5213.        This example uses Format 2.  Notice that since ASIC will not issue a
  5214.        prompt, we must include the "?" on the PRINT statement or it will not
  5215.        appear on the screen.  Also note that errors fall through.  If an error
  5216.        is detected the message "THE NUMBER YOU ENTERED WAS INVALID" will be
  5217.        displayed, and the program will branch to the label "LOOP:" to ask for
  5218.        the input again.
  5219.  
  5220.  
  5221.        See Also:
  5222.  
  5223.             INKEY$
  5224.  
  5225.  
  5226.  
  5227.  
  5228.  
  5229.  
  5230.  
  5231.  
  5232.  
  5233.  
  5234.  
  5235.  
  5236.  
  5237.  
  5238.  
  5239.  
  5240.  
  5241.  
  5242.  
  5243.  
  5244.  
  5245.  
  5246.                                        Page - 81
  5247.  
  5248.  
  5249.  
  5250.  
  5251.  
  5252.                                         INPUT#
  5253.  
  5254.        Format:        INPUT# number1, number1                 <-Format 1
  5255.                       INPUT# number1, string1                 <-Format 2
  5256.                       INPUT# number1, string1 CRLF            <-Format 3
  5257.                       INPUT# number1, string1 NONULL          <-Format 4
  5258.                       INPUT# number1, string1 BYTE            <-Format 5
  5259.  
  5260.  
  5261.        Description:
  5262.  
  5263.             This statement will read a variable from a file identified by file
  5264.        number number1.  It will be stored in number1/string1.  If an error
  5265.        occurs during a read, the system variable ERROR will be set to a non-
  5266.        zero value.  The possible errors are listed in the error messages
  5267.        section the of the ASIC Manual.  If you read a file past its end, the
  5268.        contents of variable1 are undefined.
  5269.  
  5270.             Five formats of this statement are provided to provide greater
  5271.        flexibility in reading files written by ASIC and non-ASIC programs.  The
  5272.        five formats are summarized below:
  5273.  
  5274.        Format 1 -- Read numeric data from a file previously written by ASIC.
  5275.  
  5276.        Format 2 -- Read string data from a file previously written by ASIC.
  5277.  
  5278.        Format 3 -- Read strings from a non-ASIC file.  Assumes the strings
  5279.        (CRLF)      will be terminated by a CR/LF (carriage return/linefeed).
  5280.                    Note that ASIC still considers a NULL character, if
  5281.                    encountered, as an end of string character.  Also ASIC
  5282.                    terminates the string if 80 characters are read before
  5283.                    encountering a CR/LF pair.
  5284.  
  5285.        Format 4 -- Read strings from a file until 80 characters or the end
  5286.        (NONULL)    of the file is reached.  Note that ASIC still considers a
  5287.                    NULL character, if encountered, as an end of string
  5288.                    character.
  5289.  
  5290.        Format 5 -- Reads a single byte from a file and stores it in string1.
  5291.        (BYTE)      If ASIC has read a NULL byte, the string will be set to
  5292.                    NULL and its length will be 0.
  5293.  
  5294.        Example 1:
  5295.  
  5296.             OPEN "I",1,"TEMP.DAT"
  5297.             INPUT#1, A$
  5298.             IF ERROR=99 THEN ENDOFFILE:
  5299.  
  5300.        In this example, a string will be read from file "TEMP.DAT", and it will
  5301.        be stored in A$.  The system ERROR variable is then checked to see if
  5302.        End of file was reached.  Note, other ERRORS could also be returned by
  5303.        INPUT#, besides error code 99.  Refer to the error messages section for
  5304.        more information.
  5305.  
  5306.  
  5307.  
  5308.  
  5309.  
  5310.                                        Page - 82
  5311.  
  5312.  
  5313.  
  5314.  
  5315.  
  5316.                                   INPUT#  (Continued)
  5317.        Example 2:
  5318.  
  5319.             OPEN "I",1,"TEMP.DAT"
  5320.             INPUT#1, A$ NONULL
  5321.             IF ERROR=99 THEN ENDOFFILE:
  5322.  
  5323.        In this example, ASIC will read 80 characters from the file "TEMP.DAT",
  5324.        or up until the next NULL character in the file, which ever comes first.
  5325.  
  5326.        Example 3:
  5327.  
  5328.             OPEN "I",1,"CONFIG.DAT"
  5329.             INPUT#1, A$ BYTE
  5330.             IF ERROR=99 THEN ENDOFFILE:
  5331.  
  5332.        In this example, ASIC will read a single character from the file
  5333.        "CONFIG.DAT", and place it in the variable A$.
  5334.  
  5335.        Example 4:
  5336.  
  5337.             OPEN "I",1,"TEST.DAT"
  5338.             INPUT#1, A
  5339.             IF ERROR=99 THEN ENDOFFILE:
  5340.  
  5341.        In this example, ASIC will read an integer value from the file
  5342.        "TEST.DAT", and place it in the integer variable "A".
  5343.  
  5344.        Example 5:
  5345.  
  5346.             OPEN "I",1,"ASCII.DAT"
  5347.             OPEN "O",2,"ASCII.NEW"
  5348.             CR$=CHR$(13)
  5349.             LF$=CHR$(10)
  5350.             CRLF$=CR$+LF$
  5351.        READMORE:
  5352.             INPUT #1, A$ CRLF
  5353.             IF ERROR=96 THEN WRITE:
  5354.             IF ERROR>0 THEN ENDOFFILE:
  5355.        WRITEWITHCRLF:
  5356.             PRINT #2,A$ NONULL
  5357.             PRINT #2,CRLF$ NONULL
  5358.             GOTO READMORE:
  5359.        WRITE:
  5360.             PRINT #2, A$ NONULL
  5361.             GOTO READMORE:
  5362.        ENDOFFILE:
  5363.             CLOSE 1
  5364.             CLOSE 2
  5365.  
  5366.        This example copies file ASCII.DAT to file ASCII.NEW.  Note:  Even
  5367.        though ASIC can only handle 80 character strings, this example shows
  5368.        that by checking the ERROR variable for a value of 96, it is possible to
  5369.        read the file in up-to-80-character chunks and reassemble the strings in
  5370.        their original forms in the new file.  Also note that ASIC will still
  5371.        treat any NULL characters in the file as an end of string character.
  5372.  
  5373.  
  5374.                                        Page - 83
  5375.  
  5376.  
  5377.  
  5378.  
  5379.  
  5380.                                   INPUT# (Continued)
  5381.  
  5382.        Comments:
  5383.  
  5384.             Note that number1 must be a constant in the range of 1-3.  It
  5385.        identifies a file by file number which must have previously been opened
  5386.        by an OPEN command for modes INPUT or RANDOM.
  5387.  
  5388.             ASIC assumes that integers will be stored in files in 2-byte binary
  5389.        format, which is the format ASIC writes integers.  Consequently, If a
  5390.        file contained a string "123", but you told ASIC to read integer "X",
  5391.        then ASIC would read two bytes from the file and interpret "12" as two
  5392.        binary bytes that it would then combine and store as "X".  "X" would
  5393.        contain the integer value 12849.  Thus to read an integer correctly, you
  5394.        will have had to previously written it with an ASIC program.
  5395.  
  5396.        See Also:
  5397.  
  5398.             OPEN, CLOSE, PRINT#, FILEPOS
  5399.  
  5400.  
  5401.  
  5402.                                          INSTR
  5403.  
  5404.        Format:        number1 = INSTR (string1,string2)
  5405.  
  5406.        Description:
  5407.  
  5408.             This statement is used to determine if a given substring exists
  5409.        within a string, and if so, the character position at which the
  5410.        substring first appears in the string.  String1 is the string to be
  5411.        searched.  String2 contains the substring to find within string1.  The
  5412.        character position of string2 within string1 is returned in number1.  If
  5413.        the string is not found then number1 is set to zero.
  5414.  
  5415.        Example 1:
  5416.  
  5417.             A=INSTR("THE QUICK BROWN FOX","QUICK")
  5418.  
  5419.        After execution of this statement, variable "A" will contain the value
  5420.        5, which is the offset of the string "QUICK" within the string "THE
  5421.        QUICK BROWN FOX".
  5422.  
  5423.             B=INSTR("FOX","HEN")
  5424.  
  5425.        After the execution of this statement, variable "B" will contain 0,
  5426.        since the string "HEN" is not found within the string "FOX".
  5427.  
  5428.        See also:
  5429.  
  5430.             LEFT$, RIGHT$, MID$, LEN
  5431.  
  5432.  
  5433.  
  5434.  
  5435.  
  5436.  
  5437.  
  5438.                                        Page - 84
  5439.  
  5440.  
  5441.  
  5442.  
  5443.  
  5444.                                          INT86
  5445.  
  5446.        Format:        INT86(number1,AX,BX,CX,DX,DI,SI,BP,DS,ES)
  5447.  
  5448.        Description:
  5449.  
  5450.             This statement is used to call a DOS, BIOS, or custom-written
  5451.        Interrupt.  Number1 must be a constant, and should identify the number
  5452.        of the interrupt to be called.  The fields following number1 represent
  5453.        the CPU registers.  For example, ASIC will move the value from the ASIC
  5454.        variable "AX" to the CPU register "AX" prior to performing the interrupt
  5455.        call.  After the call, ASIC will move the value from the CPU register
  5456.        "AX" to the ASIC variable "AX".  Your ASIC program can then use this
  5457.        "AX" variable just like any other integer variable in the rest of the
  5458.        program.  Each of the registers listed (AX,BX,CX,DX,DI,SI,BP,DS,ES) must
  5459.        be included on the INT86 statement in the same order as shown in the
  5460.        Format statement above.  The exception to this rule, is that you can
  5461.        substitute "NA" for any register you do not need for the call.  The BP
  5462.        register may be used to pass values to the INT86 call, however, unlike
  5463.        all of the other registers, ASIC does not return the value of the BP
  5464.        register following the INT86 call.
  5465.  
  5466.        Example 1:
  5467.  
  5468.                  INT86(5,NA,NA,NA,NA,NA,NA,NA,NA,NA)
  5469.  
  5470.        The above example shows the code to perform a screen print to the
  5471.        printer.  This example will call INT 5 (BIOS Print Screen Interrupt),
  5472.        pass no parameters to the call, and receive no return values from the
  5473.        call.
  5474.  
  5475.        Example 2:
  5476.  
  5477.                  AX=&hex3600
  5478.                  DX=0
  5479.                  INT86(&hex21,AX,BX,CX,DX,NA,NA,NA,NA,NA)
  5480.                  PRINT "Default Drive has:"
  5481.                  PRINT
  5482.                  PRINT "Sectors/Cluster";
  5483.                  PRINT AX
  5484.                  PRINT "Available Cluster Count";
  5485.                  PRINT BX
  5486.                  PRINT "Bytes/Sector";
  5487.                  PRINT CX
  5488.                  PRINT "Total Clusters";
  5489.                  PRINT DX
  5490.  
  5491.  
  5492.  
  5493.  
  5494.  
  5495.  
  5496.  
  5497.  
  5498.  
  5499.  
  5500.  
  5501.  
  5502.                                        Page - 85
  5503.  
  5504.  
  5505.  
  5506.  
  5507.  
  5508.                                    INT86 (Continued)
  5509.  
  5510.        This example show a more complex call to DOS to find out free disk space
  5511.        information for the current drive.  DOS Interrupt 21 (hex) function 36
  5512.        (hex) is used to retrieve this information.  The AX register is used to
  5513.        pass the function number.  The DX register is used to select the disk
  5514.        drive (0=the default disk drive).  Note that the BX and CX registers
  5515.        were included on the call.  No parameters are being passed to the call
  5516.        in these registers, however, we'll be receiving information back from
  5517.        DOS in them, so they need to be on the INT86 statement.  Since the
  5518.        SI,DI,BP,DS, and ES registers are not needed by the call, they have been
  5519.        substituted with "NA" which you can think of as meaning "Not Applicable"
  5520.        to this call.  After the call, the example program will display
  5521.        information about the default disk drive.
  5522.  
  5523.        Comments:
  5524.  
  5525.        This statement is intended for advanced programmers.  To use it
  5526.        properly, you must have some knowledge of assembler language, or (at
  5527.        least) the CPU registers in the IBM PC.  You also need a DOS or BIOS
  5528.        reference manual to identify which registers to pass to each interrupt,
  5529.        and to identify the values to place in those registers.
  5530.  
  5531.        One register was required for ASIC housekeeping after the INT86 call.
  5532.        This is why the BP register is unavailable to receive return values from
  5533.        calls.  The BP register was chosen, because none of the DOS or BIOS
  5534.        Interrupts use this register to return values.  If you write your own
  5535.        interrupts and want to call them from an ASIC program, remember that you
  5536.        can pass the BP register to the interrupt, but the ASIC "BP" variable
  5537.        will not be updated following the interrupt.
  5538.  
  5539.        If a register is not needed for the call, specify "NA" instead of the
  5540.        register name.  ASIC does not generate any code for "NA" registers, and
  5541.        this will reduce the size of your program.
  5542.  
  5543.  
  5544.  
  5545.  
  5546.  
  5547.  
  5548.  
  5549.  
  5550.  
  5551.  
  5552.  
  5553.  
  5554.  
  5555.  
  5556.  
  5557.  
  5558.  
  5559.  
  5560.  
  5561.  
  5562.  
  5563.  
  5564.  
  5565.  
  5566.                                        Page - 86
  5567.  
  5568.  
  5569.  
  5570.  
  5571.  
  5572.                                          KILL
  5573.  
  5574.        Format:        KILL string1
  5575.  
  5576.        Description:
  5577.  
  5578.             This statement is used to delete a file from disk.  It is similar
  5579.        to the DOS ERASE Statement.  Specify the file to delete in string1.  You
  5580.        can specify the full path to the file, or just the file name if it is in
  5581.        the current directory.  If an error occurs (eg, File not found), then
  5582.        ASIC will set the System ERROR variable.  A list of codes returned by
  5583.        KILL is listed in the ERROR Messages Chapter of the ASIC Manual.
  5584.  
  5585.        Example:
  5586.  
  5587.                  KILL "TEMP.DAT"
  5588.                  IF ERROR = 0 THEN NOERROR:
  5589.                  REM CHECK ERROR CODES HERE
  5590.  
  5591.        After this statement is executed, the file "TEMP.DAT" will have been
  5592.        erased from the current directory of the current drive, and will no
  5593.        longer be accessible from DOS or your programs.
  5594.  
  5595.  
  5596.  
  5597.  
  5598.                                         LCASE$
  5599.  
  5600.        Format:        string1=LCASE$(string2)
  5601.  
  5602.        Description:
  5603.  
  5604.             This statement will convert all of the letters in string2 from
  5605.        upper case to lower case, and store the result in string1.
  5606.  
  5607.        Example:
  5608.  
  5609.             A$=LCASE$("123 Main Street, USA")
  5610.  
  5611.        After the execution of this statement, the variable A$ will contain the
  5612.        string "123 main street, usa".
  5613.  
  5614.        See also:
  5615.  
  5616.             UCASE$
  5617.  
  5618.  
  5619.  
  5620.  
  5621.  
  5622.  
  5623.  
  5624.  
  5625.  
  5626.  
  5627.  
  5628.  
  5629.  
  5630.                                        Page - 87
  5631.  
  5632.  
  5633.  
  5634.  
  5635.  
  5636.                                          LEFT$
  5637.  
  5638.        Format:        string1=LEFT$(string2,number1)
  5639.  
  5640.        Description:
  5641.  
  5642.             This statement will copy number1 characters from the left of
  5643.        string2 to string1.
  5644.  
  5645.        Example:
  5646.  
  5647.             A$=LEFT$("RED RIDING HOOD",3)
  5648.  
  5649.        After the execution of the above statement, the variable A$ will contain
  5650.        the string "RED".
  5651.  
  5652.        See also:
  5653.  
  5654.             MID$, RIGHT$
  5655.  
  5656.  
  5657.  
  5658.                                           LEN
  5659.  
  5660.        Format:        number1 = LEN (string1)
  5661.  
  5662.        Description:
  5663.  
  5664.             This statement returns the length (number of characters) of a
  5665.        string, and stores the length in number1.
  5666.  
  5667.        Example:
  5668.  
  5669.                  A$="abc"
  5670.                  LENGTH1 = LEN(A$)
  5671.  
  5672.        After execution of these statements, LENGTH1 would contain 3.
  5673.  
  5674.  
  5675.  
  5676.  
  5677.  
  5678.  
  5679.  
  5680.  
  5681.  
  5682.  
  5683.  
  5684.  
  5685.  
  5686.  
  5687.  
  5688.  
  5689.  
  5690.  
  5691.  
  5692.  
  5693.  
  5694.                                        Page - 88
  5695.  
  5696.  
  5697.  
  5698.  
  5699.  
  5700.                                         LOCATE
  5701.  
  5702.        Format:        LOCATE row,column
  5703.  
  5704.        Description:
  5705.  
  5706.             This statement is used to position the cursor to a row and column.
  5707.        Row and Column should be integers.  Row has the range 0-24, Column has
  5708.        the range 0-79.  This function does not perform edits on the ranges of
  5709.        row and column.  Consequently using this function with values outside
  5710.        these ranges will have unpredictable results.
  5711.  
  5712.        Example:
  5713.  
  5714.                  LOCATE 10,20
  5715.                  PRINT "HELLO"
  5716.  
  5717.  
  5718.        After execution of these statements, the message "HELLO" will appear
  5719.        beginning at row 10, column 20.
  5720.  
  5721.  
  5722.  
  5723.  
  5724.  
  5725.  
  5726.  
  5727.  
  5728.  
  5729.  
  5730.  
  5731.  
  5732.  
  5733.  
  5734.  
  5735.  
  5736.  
  5737.  
  5738.  
  5739.  
  5740.  
  5741.  
  5742.  
  5743.  
  5744.  
  5745.  
  5746.  
  5747.  
  5748.  
  5749.  
  5750.  
  5751.  
  5752.  
  5753.  
  5754.  
  5755.  
  5756.  
  5757.  
  5758.                                        Page - 89
  5759.  
  5760.  
  5761.  
  5762.  
  5763.  
  5764.  
  5765.  
  5766.  
  5767.                                         LPRINT
  5768.  
  5769.        Format:        LPRINT printobject [;]        <--Format 1
  5770.  
  5771.  
  5772.        Description:
  5773.  
  5774.             This statement is used to send the contents of printobject to an
  5775.        attached printer.  "printobject" can be any valid ASIC datatype:
  5776.        integer, string, or decimal number.  Optionally, a ";" can be included
  5777.        with this statement to suppress a carriage return/line feed which ASIC
  5778.        normally also sends to the printer following each LPRINT.  This can be
  5779.        used to string several printobjects together on a single print line.
  5780.  
  5781.        Example:
  5782.  
  5783.                  A=12345
  5784.                  LPRINT "The value of A is: ";
  5785.                  LPRINT A
  5786.  
  5787.        After execution of these statements the printer would print:
  5788.  
  5789.                  The value of A is: 12345
  5790.  
  5791.        Comments:
  5792.  
  5793.             Note that if the printer is not "online" that DOS will issue a
  5794.        message to "Abort, Retry, or Ignore".  This could overwrite a portion of
  5795.        the program display, unless not planned for.
  5796.  
  5797.             Note also, that some printers do not begin printing until they
  5798.        receive a carriage return/line feed sequence.
  5799.  
  5800.  
  5801.  
  5802.  
  5803.  
  5804.  
  5805.  
  5806.  
  5807.  
  5808.  
  5809.  
  5810.  
  5811.  
  5812.  
  5813.  
  5814.  
  5815.  
  5816.  
  5817.  
  5818.  
  5819.  
  5820.  
  5821.  
  5822.                                        Page - 90
  5823.  
  5824.  
  5825.  
  5826.  
  5827.  
  5828.                                         LTRIM$
  5829.  
  5830.        Format:        string1=LTRIM$(string2)
  5831.  
  5832.        Description:
  5833.  
  5834.             This statement will remove all leading spaces from string2 and
  5835.        store the result in string1.
  5836.  
  5837.        Example:
  5838.  
  5839.             A$="   XYZ"
  5840.             A$=LTRIM$(A$)
  5841.  
  5842.        After execution of these statements, the variable A$ will contain the
  5843.        string "XYZ" with no leading spaces.
  5844.  
  5845.        See also:
  5846.  
  5847.             RTRIM$
  5848.  
  5849.  
  5850.  
  5851.                                          MID$
  5852.  
  5853.        Format:        string1 = MID$(string2,number1,number2)
  5854.  
  5855.        Description:
  5856.  
  5857.             This statement is used to extract a substring from string2
  5858.        beginning at position number1 within string2 and continuing for number2
  5859.        bytes.  This value is then stored in string1.
  5860.  
  5861.        Example:
  5862.  
  5863.                       A$="THE QUICK BROWN FOX"
  5864.                       B$=MID$(A$,1,4)
  5865.                       C$=MID$(A$,11,9)
  5866.                       D$=B$ + C$
  5867.  
  5868.        After execution of these statements, the contents of A$ will be
  5869.        unchanged.  The contents of B$ will be "THE ".  The contents of C$ will
  5870.        be "BROWN FOX", and the contents of D$ will be "THE BROWN FOX".
  5871.  
  5872.        See also:
  5873.  
  5874.             LEFT$, RIGHT$
  5875.  
  5876.  
  5877.  
  5878.  
  5879.  
  5880.  
  5881.  
  5882.  
  5883.  
  5884.  
  5885.  
  5886.                                        Page - 91
  5887.  
  5888.  
  5889.  
  5890.  
  5891.  
  5892.                                          MKDIR
  5893.  
  5894.        Format:        MKDIR string1
  5895.  
  5896.        Description:
  5897.  
  5898.             This statement is used to create a new DOS directory.  Specify the
  5899.        directory to create in string1.  If ASIC is unable to create the
  5900.        directory, it will set the System ERROR variable.  A list of ERROR codes
  5901.        may be found is the Error Messages Chapter of the ASIC Manual.
  5902.  
  5903.        Example:
  5904.  
  5905.                  MKDIR "WORK"
  5906.                  IF ERROR = 0 THEN NOERROR:
  5907.  
  5908.        This code would create a directory called "WORK" under the current
  5909.        directory of the current drive.
  5910.  
  5911.        Example 2:
  5912.  
  5913.                  MKDIR "C:\WORK"
  5914.  
  5915.        This code would create a directory called "WORK" under the root
  5916.        directory of drive "C".
  5917.  
  5918.        See also:
  5919.  
  5920.             CHDIR,RMDIR
  5921.  
  5922.  
  5923.  
  5924.                                           MOD
  5925.  
  5926.        Format:        integer1 = number2 MOD number3
  5927.  
  5928.        Description:
  5929.  
  5930.             This statement will perform modulo division of number2 by number3
  5931.        and store the remainder (instead of the quotient) in integer1.
  5932.  
  5933.        Example:
  5934.  
  5935.                  A = 8
  5936.                  B = 5
  5937.                  C = A MOD B
  5938.  
  5939.        After execution of these statements, variable "C" will contain the value
  5940.        "3" which is the remainder of the division of 8 by 5.
  5941.  
  5942.  
  5943.  
  5944.  
  5945.  
  5946.  
  5947.  
  5948.  
  5949.  
  5950.                                        Page - 92
  5951.  
  5952.  
  5953.  
  5954.  
  5955.  
  5956.                                          NAME
  5957.  
  5958.        Format:        NAME string1 AS string2
  5959.  
  5960.        Description:
  5961.  
  5962.             This statement will allow you to rename a file.  String1 should
  5963.        contain the current file name, and string2 should contain the new name
  5964.        for the file.  If ASIC is unable to rename the file, it will set the
  5965.        System ERROR variable.  A list of ERROR codes is contained in the Error
  5966.        Messages Chapter of the ASIC Manual.
  5967.  
  5968.        Example:
  5969.  
  5970.             NAME "olddata.txt" AS "newdata.txt"
  5971.             IF ERROR = 0 THEN SUCCESS:
  5972.  
  5973.        After execution of these statements, file "olddata.txt" will have been
  5974.        renamed to "newdata.txt"
  5975.  
  5976.        Comments:
  5977.  
  5978.             You cannot rename a file to a new disk drive.
  5979.  
  5980.  
  5981.  
  5982.                                          OPEN
  5983.  
  5984.        Format:        OPEN string1, number1, string2
  5985.  
  5986.        Description:
  5987.  
  5988.             This statement is used to open a file for input or output.  Up to
  5989.        three files may be open concurrently, these are known as file 1, 2, or
  5990.        3.  You must specify with number1 which file number you wish to open
  5991.        this file as.  Number1 may only be a constant.  The file mode is
  5992.        specified in string1.  The valid values are "I" for INPUT, "O" for
  5993.        OUTPUT, "A" for APPEND, and "R" for RANDOM INPUT/OUTPUT.  The file name
  5994.        is specified with string2.  Any errors returned from DOS on the OPEN
  5995.        call will be returned in the system variable "ERROR".
  5996.  
  5997.        Example:
  5998.  
  5999.                  OPEN "I",3,"INFILE"
  6000.                  IF ERROR > 0 THEN PROCESSERROR:
  6001.                  OPEN "O",1,"A:\NEWFILE.DAT"
  6002.                  IF ERROR > 0 THEN PROCESSERROR:
  6003.  
  6004.        In this example, two files are opened.  File "INFILE" from the current
  6005.        disk drive and directory will be opened as file number 3 for input.  The
  6006.        file "A:\NEWFILE.DAT" will be opened for output as file number 1.  Note
  6007.        that if "A:\NEWFILE.DAT" previously existed, it contents will be
  6008.        destroyed in preparation for writing.
  6009.  
  6010.        See also:
  6011.  
  6012.        CLOSE, FILEPOS, INPUT#, PRINT#
  6013.  
  6014.                                        Page - 93
  6015.  
  6016.  
  6017.  
  6018.  
  6019.  
  6020.                                         OPENCOM
  6021.  
  6022.        Format:        OPENCOM(number1,number2,number3,number4,number5)
  6023.  
  6024.        Description:
  6025.  
  6026.             This statement is used to initialize the serial port.  Number1 is
  6027.        used to specify the baud rate.  Number2 specifies parity.  Number3
  6028.        specifies stop bits.  Number4 specifies bytesize, and Number5 identifies
  6029.        which port to open (see the tables below).  OPENCOM does not check the
  6030.        validity of the values you give it.
  6031.  
  6032.                  (number1)                          (number2)
  6033.                  BAUD RATE                          PARITY
  6034.             ------+-----------                 ------+------------
  6035.             VALUE | DESCRIPTION                VALUE | DESCRIPTION
  6036.               0   | 110  baud                    0   | No Parity
  6037.               1   | 150  baud                    1   | Odd Parity
  6038.               2   | 300  baud                    3   | Even Parity
  6039.               3   | 600  baud
  6040.               4   | 1200 baud                      (number3)
  6041.               5   | 2400 baud                      STOP BITS
  6042.               6   | 4800 baud                  ------+------------
  6043.               7   | 9600 baud                  VALUE | DESCRIPTION
  6044.                                                  0   | One Stop Bit
  6045.                                                  1   | Two Stop Bits
  6046.  
  6047.                  (number4)                          (number5)
  6048.                  BYTE SIZE                          COM PORT
  6049.             ------+------------                ------+------------
  6050.             VALUE | DESCRIPTION                VALUE | DESCRIPTION
  6051.               2   | 7 Bits                       0   | Com1
  6052.               3   | 8 Bits                       1   | Com2
  6053.  
  6054.        Example:
  6055.  
  6056.                  OPENCOM(2,0,0,3,0)
  6057.  
  6058.        This statement would open COM1 at 300 baud, No parity, 1 Stop bit, 8 bit
  6059.        bytesize.
  6060.  
  6061.  
  6062.  
  6063.        See also:
  6064.  
  6065.             COMSTAT,RECEIVE,SEND
  6066.  
  6067.  
  6068.  
  6069.  
  6070.  
  6071.  
  6072.  
  6073.  
  6074.  
  6075.  
  6076.  
  6077.  
  6078.                                        Page - 94
  6079.  
  6080.  
  6081.  
  6082.  
  6083.  
  6084.                                           OUT
  6085.  
  6086.        Format:        OUT (number1,number2)
  6087.  
  6088.        Description:
  6089.  
  6090.             This statement writes a byte to a port.  Number1 should contain the
  6091.        port to write to.  Number2 should contain an integer value in the range
  6092.        of 0-255 to be written to the port.
  6093.  
  6094.        Example:
  6095.  
  6096.             OUT 512,0
  6097.  
  6098.        The above statement would send a byte with the binary value of "0" to
  6099.        port number 512.
  6100.  
  6101.  
  6102.        See also:
  6103.  
  6104.             INP
  6105.  
  6106.  
  6107.  
  6108.                                          PEEK
  6109.  
  6110.        Format:        number1 = PEEK (number2)
  6111.  
  6112.        Description:
  6113.  
  6114.             This statement is used to examine actual memory location values
  6115.        directly.  By default, the ASIC DS address is assumed.  However, this
  6116.        may be overridden with the use of the DEFSEG command.  The value of the
  6117.        byte at address number2 is stored in number1.
  6118.  
  6119.        Example:
  6120.  
  6121.             DEFSEG = &hexB800
  6122.             A = PEEK (0)
  6123.  
  6124.        The above statements will retrieve the first byte of video memory for a
  6125.        CGA/EGA/VGA card and store it in variable "A".
  6126.  
  6127.        Comments:
  6128.  
  6129.             Since the Intel 8088 architecture is segmented in 64k segments,
  6130.        number2 is limited to the range of 0-65535.
  6131.  
  6132.  
  6133.  
  6134.        See also:
  6135.  
  6136.             DEFSEG, POKE
  6137.  
  6138.  
  6139.  
  6140.  
  6141.  
  6142.                                        Page - 95
  6143.  
  6144.  
  6145.  
  6146.  
  6147.  
  6148.                                          POINT
  6149.  
  6150.        Format:        number1 = POINT (number2,number3)
  6151.  
  6152.        Description:
  6153.  
  6154.             This statement is used to determine the color of a given pixel in
  6155.        medium and high resolution graphics modes.  The row to test is specified
  6156.        with number2, the column with number3.  The color of the pixel is stored
  6157.        in number1.
  6158.  
  6159.        Example:
  6160.  
  6161.                  PCOLOR = POINT (10,20)
  6162.  
  6163.        After execution of this statement, PCOLOR will contain the color of the
  6164.        pixel in row 10 column 20.
  6165.  
  6166.        Comments:
  6167.  
  6168.             No range checking is performed on row and column.  If the specified
  6169.        row or column is outside the valid range for the given graphics mode,
  6170.        the results are unpredictable.
  6171.  
  6172.        See also:
  6173.  
  6174.             PSET, PRESET, SCREEN
  6175.  
  6176.  
  6177.  
  6178.  
  6179.  
  6180.  
  6181.  
  6182.  
  6183.  
  6184.  
  6185.  
  6186.  
  6187.  
  6188.  
  6189.  
  6190.  
  6191.  
  6192.  
  6193.  
  6194.  
  6195.  
  6196.  
  6197.  
  6198.  
  6199.  
  6200.  
  6201.  
  6202.  
  6203.  
  6204.  
  6205.  
  6206.                                        Page - 96
  6207.  
  6208.  
  6209.  
  6210.  
  6211.  
  6212.                                          POKE
  6213.  
  6214.        Format:        POKE number1, number2
  6215.  
  6216.        Description:
  6217.  
  6218.             This instruction is used store the byte value number2 at the memory
  6219.        address specified by number1.  By default, ASIC uses its default data
  6220.        segment address, however, this may be overridden with the DEFSEG
  6221.        statement.
  6222.  
  6223.        Example:
  6224.  
  6225.             DEFSEG = &hexB800
  6226.             POKE 0,1
  6227.  
  6228.        The above statements will store a byte with the binary value of "1" in
  6229.        the first byte of video memory for a CGA/EGA/VGA card.
  6230.  
  6231.        Comments:
  6232.  
  6233.             This statement is NOT RECOMMENDED FOR BEGINNERS.  Directly
  6234.        overwriting memory locations can be disastrous, unless you know what is
  6235.        stored at that address.  This can cause program "hangs", system crashes,
  6236.        etc.
  6237.  
  6238.             Since the Intel 8088 architecture is segmented in 64k segments,
  6239.        number2 is limited to the range of 0-65535.
  6240.  
  6241.  
  6242.        See also:
  6243.  
  6244.             DEFSEG, PEEK
  6245.  
  6246.  
  6247.  
  6248.                                           POS
  6249.  
  6250.        Format:        number1 = POS (number2)
  6251.  
  6252.        Description:
  6253.  
  6254.             This statement finds the column number of the cursor and stores it
  6255.        in number1.  number2 is a dummy argument included only because a dummy
  6256.        argument is required in BASICA/GWBASIC.
  6257.  
  6258.        Example:
  6259.  
  6260.                  A = POS(0)
  6261.  
  6262.        After this statement executes, A will contain the column number of the
  6263.        cursor.
  6264.  
  6265.        See also:
  6266.  
  6267.             CSRLIN
  6268.  
  6269.  
  6270.                                        Page - 97
  6271.  
  6272.  
  6273.  
  6274.  
  6275.  
  6276.                                         PRESET
  6277.  
  6278.        Format:        PRESET (number1,number2)
  6279.  
  6280.        Description:
  6281.  
  6282.             This statement is used to set the color of a pixel to the
  6283.        background color. The row of the pixel is specified in number1, and the
  6284.        column is specified in number2.  This statement only works in graphics
  6285.        modes.
  6286.  
  6287.        Example:
  6288.  
  6289.                  PRESET (10,20)
  6290.  
  6291.        The pixel at row 10 column 20 would be set to the background color.
  6292.  
  6293.        See also:
  6294.  
  6295.             PSET, SCREEN, POINT
  6296.  
  6297.  
  6298.  
  6299.  
  6300.  
  6301.  
  6302.  
  6303.  
  6304.  
  6305.  
  6306.  
  6307.  
  6308.  
  6309.  
  6310.  
  6311.  
  6312.  
  6313.  
  6314.  
  6315.  
  6316.  
  6317.  
  6318.  
  6319.  
  6320.  
  6321.  
  6322.  
  6323.  
  6324.  
  6325.  
  6326.  
  6327.  
  6328.  
  6329.  
  6330.  
  6331.  
  6332.  
  6333.  
  6334.                                        Page - 98
  6335.  
  6336.  
  6337.  
  6338.  
  6339.  
  6340.  
  6341.  
  6342.  
  6343.                                          PRINT
  6344.  
  6345.        Format:        PRINT [printobject1 [;]]           <--Format 1
  6346.  
  6347.        Description:
  6348.  
  6349.             This statement is used to print to the screen.  Printing begins at
  6350.        the current cursor location.  Printobject1 is defined as any valid ASIC
  6351.        data type:  integer constant, integer variable, decimal constant,
  6352.        decimal variable, string constant, string variable, and arrays.  The
  6353.        semicolon is optional and is used to tell ASIC if you want a carriage
  6354.        return/line feed issued.  A semicolon at the end of a PRINT statement
  6355.        will suppress the carriage return/line feed ASIC normally issues.  If no
  6356.        operands are supplied, ASIC will simply issue a carriage return and line
  6357.        feed.
  6358.  
  6359.        Example 1:
  6360.  
  6361.                  A=1000
  6362.                  PRINT "A=";
  6363.                  PRINT A
  6364.                  PRINT
  6365.                  PRINT "DONE!"
  6366.  
  6367.        After execution of these statements your screen would display:
  6368.  
  6369.                  A=  1000
  6370.  
  6371.                  DONE!
  6372.  
  6373.        See also:
  6374.  
  6375.             COLOR, SCREEN, LOCATE
  6376.  
  6377.  
  6378.  
  6379.  
  6380.  
  6381.  
  6382.  
  6383.  
  6384.  
  6385.  
  6386.  
  6387.  
  6388.  
  6389.  
  6390.  
  6391.  
  6392.  
  6393.  
  6394.  
  6395.  
  6396.  
  6397.  
  6398.                                        Page - 99
  6399.  
  6400.  
  6401.  
  6402.  
  6403.  
  6404.                                         PRINT#
  6405.  
  6406.        Format:        PRINT# constant1, printobject1 [NONULL]
  6407.  
  6408.        Description:
  6409.  
  6410.             This statement is used to write integers, decimals and strings to
  6411.        disk.  Constant1 identifies the file number that the file was opened as.
  6412.        This must be a constant with a value of 1, 2 or 3.  The file must have
  6413.        been previously opened with the OPEN command.  If printobject1 is a
  6414.        string, you can also add the optional argument "NONULL", which will
  6415.        cause ASIC to suppress the trailing NULL character it would normally
  6416.        write to disk.  DOS errors are returned in the system variable "ERROR".
  6417.        A list of these error codes may be found in the error messages section
  6418.        of the ASIC Manual.  Also, refer to the technical details section of the
  6419.        ASIC Manual for more information on the format in which ASIC writes the
  6420.        data to disk.
  6421.  
  6422.        Example:
  6423.  
  6424.                  PRINT# 1, "HELLO"
  6425.                  IF ERROR = 255 THEN DISKFULL:
  6426.                  PRINT# 1, "WORLD"
  6427.                  IF ERROR = 255 THEN DISKFULL:
  6428.  
  6429.        After successful execution of the print statements the file identified
  6430.        by file number 1 would contain "HELLO0WORLD0" . Note that the "0"
  6431.        following HELLO and WORLD in our example represents the ASCII null
  6432.        character.  Strings in ASIC are always internally terminated with ASCII
  6433.        null characters.  By default, these nulls are also written to disk.
  6434.  
  6435.                  PRINT# 2, "HELLO" NONULL
  6436.  
  6437.        In this example, the string "HELLO" would be written to file #2, and no
  6438.        trailing NULL will be written to disk.
  6439.  
  6440.                  PRINT #3, 1234
  6441.  
  6442.        In this example, the number "1234" would be written to file #3 as two
  6443.        bytes in Intel binary format (the file would contain the two hexadecimal
  6444.        bytes:  D2 04).
  6445.  
  6446.  
  6447.  
  6448.  
  6449.  
  6450.  
  6451.  
  6452.  
  6453.  
  6454.  
  6455.  
  6456.  
  6457.  
  6458.  
  6459.  
  6460.  
  6461.  
  6462.                                       Page - 100
  6463.  
  6464.  
  6465.  
  6466.  
  6467.  
  6468.                                   PRINT# (Continued)
  6469.  
  6470.        Comments:
  6471.  
  6472.          Note that while ASIC doesn't generate carriage returns and line feeds
  6473.        for you as it does with the PRINT command, you can write these
  6474.        characters to disk as follows:
  6475.  
  6476.                  A$=CHR$(13)
  6477.                  B$=CHR$(10)
  6478.                  A$ = A$ + B$
  6479.                  PRINT #1, A$
  6480.  
  6481.        You might be wondering about the purpose of the NONULL option.  ASIC
  6482.        normally writes trailing NULLs with strings.  This is desirable if you
  6483.        plan to read the file exclusively with other ASIC programs.
  6484.  
  6485.        However, sometimes you may want to write a string for use by another
  6486.        program.  In this case, the NULL character sometimes confuses the other
  6487.        program.  Specifying the NONULL option will cause ASIC to suppress the
  6488.        offending NULL character.
  6489.  
  6490.        What happens if you read a string that is terminated by a Carriage
  6491.        Return/Line Feed Sequence (such as GWBASIC/BASICA produces)?  In this
  6492.        instance, specify the CRLF option on the INPUT# statement.  Then ASIC
  6493.        will read the string until it finds a CR/LF or until it reads 80
  6494.        characters, whichever comes first.
  6495.  
  6496.        See also:
  6497.  
  6498.                  OPEN, CLOSE, INPUT#, FILEPOS
  6499.  
  6500.  
  6501.  
  6502.  
  6503.  
  6504.  
  6505.  
  6506.  
  6507.  
  6508.  
  6509.  
  6510.  
  6511.  
  6512.  
  6513.  
  6514.  
  6515.  
  6516.  
  6517.  
  6518.  
  6519.  
  6520.  
  6521.  
  6522.  
  6523.  
  6524.  
  6525.  
  6526.                                       Page - 101
  6527.  
  6528.  
  6529.  
  6530.  
  6531.  
  6532.                                          PSET
  6533.  
  6534.        Format:        PSET (number1,number2),number3
  6535.  
  6536.        Description:
  6537.  
  6538.             This statement is used to set a pixel to a specified color in
  6539.        graphics modes.  The row is specified in number1, the column in number2,
  6540.        and the color in number3.  Note that no range checking is performed on
  6541.        number1 or number2.  A row or column specified outside the range allowed
  6542.        by the graphics mode in use can result in unpredictable results.
  6543.  
  6544.        Example:
  6545.  
  6546.                  PSET (10,20),1
  6547.  
  6548.        In this example the pixel defined at row 10 and column 20 will be set to
  6549.        color 1.
  6550.  
  6551.        See also:
  6552.  
  6553.             PRESET, SCREEN, POINT
  6554.  
  6555.  
  6556.  
  6557.                                        RANDOMIZE
  6558.  
  6559.        Format:        RANDOMIZE
  6560.  
  6561.        Description:
  6562.  
  6563.                  This statement will cause the seed for the random number
  6564.        generator to be reseeded using the system timer.  This statement should
  6565.        always precede the first RND statement in your program, unless you want
  6566.        the same sequence of random numbers generated.
  6567.  
  6568.        Example:
  6569.  
  6570.             RANDOMIZE
  6571.  
  6572.        The above statement would insure that each time your program runs, any
  6573.        subsequent RND numbers generated would be different.
  6574.  
  6575.        See also:
  6576.  
  6577.             RND
  6578.  
  6579.  
  6580.  
  6581.  
  6582.  
  6583.  
  6584.  
  6585.  
  6586.  
  6587.  
  6588.  
  6589.  
  6590.                                       Page - 102
  6591.  
  6592.  
  6593.  
  6594.  
  6595.  
  6596.                                          READ
  6597.  
  6598.        Format:        READ variable1
  6599.  
  6600.        Description:
  6601.  
  6602.             This statement reads a constant from DATA statements into a
  6603.        variable.  Variable1 is a string, decimal or integer type variable.
  6604.  
  6605.        Example:
  6606.  
  6607.             DATA 7,"CARGO"
  6608.  
  6609.             READ A
  6610.             READ B$
  6611.  
  6612.        After execution of these statements, "A" will contain 7, and B$ will
  6613.        contain "CARGO".
  6614.  
  6615.        Comments:
  6616.  
  6617.             ASIC does not check to see that the data type on the READ statement
  6618.        matches the data type on the DATA statement.  It is up to the programmer
  6619.        to insure that the types match.  The above example is correct.  The DATA
  6620.        statement contains an integer, then a string.  This is the same sequence
  6621.        in which the DATA is READ (ie, integer, then string).  In the above
  6622.        example, if the read statements were reversed, the contents of A and B$
  6623.        are undefined.  Also note that ASIC does not check to see that you don't
  6624.        read past the end of the DATA you specified.  In the above example, if
  6625.        you had a third READ statement that contained "READ C$", then C$ would
  6626.        contain random garbage, since you read three values, but only provided
  6627.        data for two.
  6628.  
  6629.        See also:
  6630.  
  6631.             DATA,RESTORE
  6632.  
  6633.  
  6634.  
  6635.  
  6636.  
  6637.  
  6638.  
  6639.  
  6640.  
  6641.  
  6642.  
  6643.  
  6644.  
  6645.  
  6646.  
  6647.  
  6648.  
  6649.  
  6650.  
  6651.  
  6652.  
  6653.  
  6654.                                       Page - 103
  6655.  
  6656.  
  6657.  
  6658.  
  6659.  
  6660.                                         RECEIVE
  6661.  
  6662.        Format:        variable1 = RECEIVE(number2)
  6663.  
  6664.        Description:
  6665.  
  6666.             This statement will read a byte from the specified serial port.
  6667.        Number2 identifies which port to read (0=COM1, and 1=COM2).  The byte
  6668.        read is stored in variable1 (which may be an integer or string type
  6669.        variable).  Before executing this statement you should first check to
  6670.        see if there is data waiting to be read.  Executing this statement when
  6671.        data is not waiting can cause your PC to "hang" until data is received
  6672.        at the hardware serial port.  The example below illustrates how to
  6673.        determine if data is waiting to be received.
  6674.  
  6675.        Example:
  6676.  
  6677.             OPENCOM(2,0,0,3,0)
  6678.  
  6679.             PORTSTAT = COMSTAT(0)
  6680.             DATAREADY = ZBIT(8,PORTSTAT)
  6681.             IF DATAREADY = 0 THEN NODATAWAITING:
  6682.             A$=RECEIVE(0)
  6683.  
  6684.  
  6685.        These statements do the following.  The first retrieves the status of
  6686.        COM1 to the variable PORTSTAT.  The second checks to see if bit 8 is on,
  6687.        DATAREADY will contain 1 if so, otherwise it will contain 0.  Since Bit
  6688.        8 is used to determine if data is waiting to be received from the port,
  6689.        if DATAREADY NOT = 0 then the program will RECEIVE data from the port to
  6690.        variable "A$".
  6691.  
  6692.        Comments:
  6693.  
  6694.             Variable1 can be either a string or integer type variable.
  6695.        However, if variable1 is a string, bear in mind that you cannot directly
  6696.        receive a NULL (ASCII Code 0), since NULL is used to delimit the end of
  6697.        a string in ASIC.  However, if in the above example data was waiting at
  6698.        the port but A$ contained "" after the receive, you would know that the
  6699.        character received was a NULL.  This is not a problem if variable1 is an
  6700.        integer variable.
  6701.  
  6702.        See also:
  6703.  
  6704.             OPENCOM,SEND,COMSTAT
  6705.  
  6706.  
  6707.  
  6708.  
  6709.  
  6710.  
  6711.  
  6712.  
  6713.  
  6714.  
  6715.  
  6716.  
  6717.  
  6718.                                       Page - 104
  6719.  
  6720.  
  6721.  
  6722.  
  6723.  
  6724.                                           REM
  6725.  
  6726.        Format:        REM  free form comments
  6727.  
  6728.        Description:
  6729.  
  6730.             This statement is used to insert comments into your program.
  6731.        Everything following REM is treated by ASIC as a comment.
  6732.  
  6733.        Example:
  6734.  
  6735.             REM The compiler will ignore this line
  6736.  
  6737.  
  6738.  
  6739.                                         RESTORE
  6740.  
  6741.        Format:        RESTORE
  6742.  
  6743.        Description:
  6744.  
  6745.             This statement allows you to READ data from DATA statements after
  6746.        you have already READ it once.
  6747.  
  6748.        Example:
  6749.                  DATA 0
  6750.  
  6751.                  READ A
  6752.                  RESTORE
  6753.                  READ B
  6754.  
  6755.        In this example, "READ A" causes variable "A" to be set to 0.  Now, the
  6756.        DATA statement is "used up".  There is no more data left on it to be
  6757.        read.  The RESTORE resets the DATA so that the next statement "READ B"
  6758.        will result in "B" being set to 0.  If the RESTORE was not done, the
  6759.        contents of B would be undefined.
  6760.  
  6761.        See also:
  6762.  
  6763.             READ, DATA
  6764.  
  6765.  
  6766.  
  6767.  
  6768.  
  6769.  
  6770.  
  6771.  
  6772.  
  6773.  
  6774.  
  6775.  
  6776.  
  6777.  
  6778.  
  6779.  
  6780.  
  6781.  
  6782.                                       Page - 105
  6783.  
  6784.  
  6785.  
  6786.  
  6787.  
  6788.                                         RETURN
  6789.  
  6790.        Format:        RETURN
  6791.  
  6792.        Description:
  6793.  
  6794.             Used to return from a GOSUB call.
  6795.  
  6796.        Example:
  6797.  
  6798.             GOSUB PRINTIT:
  6799.             END
  6800.  
  6801.             PRINTIT: PRINT "IT"
  6802.             RETURN
  6803.  
  6804.        In the above example, the word "IT" will be printed on the screen.  The
  6805.        RETURN statement causes program execution to resume on the statement
  6806.        following the corresponding GOSUB statement.  In this example, control
  6807.        will be returned to the END statement.
  6808.  
  6809.        Comments:
  6810.  
  6811.             Executing a RETURN statement without having first executed a GOSUB
  6812.        statement could cause unpredictable results.
  6813.  
  6814.        See also:
  6815.  
  6816.             GOSUB
  6817.  
  6818.  
  6819.  
  6820.                                         RIGHT$
  6821.  
  6822.        Format:        string1 = RIGHT$(string2,number1)
  6823.  
  6824.        Description:
  6825.  
  6826.             This statement will copy the rightmost number1 characters from
  6827.        string2 to string1.
  6828.  
  6829.        Example:
  6830.  
  6831.             A$=RIGHT$("RED RIDING HOOD",4)
  6832.  
  6833.        After the execution of the above statement, the variable A$ will contain
  6834.        the string "HOOD".
  6835.  
  6836.        See also:
  6837.  
  6838.             MID$, LEFT$
  6839.  
  6840.  
  6841.  
  6842.  
  6843.  
  6844.  
  6845.  
  6846.                                       Page - 106
  6847.  
  6848.  
  6849.  
  6850.  
  6851.  
  6852.                                          RMDIR
  6853.  
  6854.        Format:        RMDIR string1
  6855.  
  6856.        Description:
  6857.  
  6858.             This statement will delete an empty directory from disk.  String1
  6859.        should contain the name of the directory to delete.  If ASIC is unable
  6860.        to delete the directory, it will set the System ERROR variable.  A list
  6861.        of ERROR codes is listed in the Error Messages Chapter of the ASIC
  6862.        Manual.
  6863.  
  6864.        Example:
  6865.  
  6866.                  RMDIR "C:\WORK\TEST"
  6867.                  IF ERROR = 0 THEN SUCCESS:
  6868.  
  6869.        After execution of this code, the directory TEST under directory WORK
  6870.        will be deleted (if it had no files or subdirectories in it, and if it
  6871.        is not the current directory for drive "C").
  6872.  
  6873.        See also:
  6874.  
  6875.             MKDIR,CHDIR
  6876.  
  6877.  
  6878.  
  6879.  
  6880.  
  6881.  
  6882.  
  6883.  
  6884.  
  6885.  
  6886.  
  6887.  
  6888.  
  6889.  
  6890.  
  6891.  
  6892.  
  6893.  
  6894.  
  6895.  
  6896.  
  6897.  
  6898.  
  6899.  
  6900.  
  6901.  
  6902.  
  6903.  
  6904.  
  6905.  
  6906.  
  6907.  
  6908.  
  6909.  
  6910.                                       Page - 107
  6911.  
  6912.  
  6913.  
  6914.  
  6915.  
  6916.                                           RND
  6917.  
  6918.        Format:        number1 = RND (number2)
  6919.  
  6920.        Description:
  6921.  
  6922.             This statement will return an integer number in the range of 0
  6923.        through 32767 for normal integers, and in the range of 0 to
  6924.        2,147,483,647 for long integers. This random number will be stored in
  6925.        number1.  Number2 is a dummy argument and can be any valid integer
  6926.        value.  If number1 is a decimal variable, the random number returned
  6927.        will be an integer in the range of 0 to 2,147,483,647.
  6928.  
  6929.        Example 1:
  6930.  
  6931.                  A& = RND(0)
  6932.  
  6933.        After execution of this statement "A" will contain a number between 0
  6934.        and 2,147,483,647 inclusive.
  6935.  
  6936.        Example 2:
  6937.  
  6938.                  RANDOMIZE
  6939.  
  6940.                  DIEROLL=RND(0)
  6941.                  DIEROLL=DIEROLL MOD 6
  6942.                  DIEROLL=DIEROLL+1
  6943.                  PRINT "YOU ROLLED A";DIEROLL
  6944.  
  6945.        The above example demonstrates how to generate a number in a given
  6946.        range.  In this case, the range will be 1-6, which would be suitable for
  6947.        simulating the roll of a die.  The above example will generate the
  6948.        simulated die roll, and print the result.
  6949.  
  6950.  
  6951.        Comments:
  6952.  
  6953.                In BASICA/GWBASIC, RND always returns a value between 1 and 0.
  6954.  
  6955.  
  6956.  
  6957.  
  6958.  
  6959.  
  6960.  
  6961.  
  6962.  
  6963.  
  6964.  
  6965.  
  6966.  
  6967.  
  6968.  
  6969.  
  6970.  
  6971.  
  6972.  
  6973.  
  6974.                                       Page - 108
  6975.  
  6976.  
  6977.  
  6978.  
  6979.  
  6980.                                         RTRIM$
  6981.  
  6982.        Format:        string1=RTRIM$(string2)
  6983.  
  6984.        Description:
  6985.  
  6986.             This statement will remove all trailing spaces from string2 and
  6987.        store the resulting string in string1.
  6988.  
  6989.        Example:
  6990.  
  6991.             A$=RTRIM$("XYZ   ")
  6992.  
  6993.        After the execution of this statement, the variable "A$" will contain
  6994.        "XYZ".
  6995.  
  6996.        See also:
  6997.  
  6998.             LTRIM$
  6999.  
  7000.  
  7001.  
  7002.  
  7003.  
  7004.  
  7005.  
  7006.  
  7007.  
  7008.  
  7009.  
  7010.  
  7011.  
  7012.  
  7013.  
  7014.  
  7015.  
  7016.  
  7017.  
  7018.  
  7019.  
  7020.  
  7021.  
  7022.  
  7023.  
  7024.  
  7025.  
  7026.  
  7027.  
  7028.  
  7029.  
  7030.  
  7031.  
  7032.  
  7033.  
  7034.  
  7035.  
  7036.  
  7037.  
  7038.                                       Page - 109
  7039.  
  7040.  
  7041.  
  7042.  
  7043.  
  7044.                                           RUN
  7045.  
  7046.        Format:        RUN string1
  7047.  
  7048.        Description:
  7049.  
  7050.             This function can be used to load and execute other programs
  7051.        compiled with ASIC or another compiler.  String1 represents the name of
  7052.        the program to execute.  If an error occurs when ASIC attempts to RUN
  7053.        the program, it will set the system ERROR variable to 255.  Otherwise,
  7054.        the ERROR variable will be set to the value of the return code of the
  7055.        called program (which is 0 unless the called program specifies
  7056.        otherwise).
  7057.  
  7058.        Example:
  7059.  
  7060.             RUN "OTHER.COM"
  7061.  
  7062.        Comments:
  7063.  
  7064.             String1 must contain the FULL pathname of the program
  7065.        (ie,"\directory\progname.COM") only if the program is NOT in the current
  7066.        directory.  You must include the file extension on the file name (for
  7067.        example, use "MYPROG.COM" instead of just "MYPROG", or use "MYPROG.EXE"
  7068.        instead of "MYPROG").
  7069.  
  7070.             At this time, RUN and CALL are functionally equivalent, with one
  7071.        exception.  RUN does not accept program arguments, but CALL does.
  7072.  
  7073.             It is recommended (but not required) that you compile your program
  7074.        using the EXE format (instead of the COM format) when your program uses
  7075.        this statement, since an EXE program will release more memory when
  7076.        calling the program.  This will allow you to call a slightly larger
  7077.        program than is possible with the COM format.
  7078.  
  7079.        CAUTION:
  7080.  
  7081.             You may use the debugger with programs which contain "CALL" or
  7082.        "RUN" statements.  However, the programs you call should not themselves
  7083.        contain debugging code.  For example, if A.ASI calls B.ASI, then make
  7084.        sure you compile B.ASI with the "Debugging Code" option OFF before you
  7085.        try to debug program A.ASI.  Failure to do so will cause the debugger to
  7086.        behave erratically.  This also applies to programs you write using other
  7087.        compilers, since they also use the same interrupt that ASIC uses (INT 3)
  7088.        for debugging purposes.
  7089.  
  7090.        See also:
  7091.  
  7092.             CALL
  7093.  
  7094.  
  7095.  
  7096.  
  7097.  
  7098.  
  7099.  
  7100.  
  7101.  
  7102.                                       Page - 110
  7103.  
  7104.  
  7105.  
  7106.  
  7107.  
  7108.                                         SCREEN
  7109.  
  7110.        Format:        SCREEN number1
  7111.  
  7112.        Description:
  7113.  
  7114.             This statement will transfer the computer between text mode and
  7115.        graphics modes.  Number1 must be an integer constant with a value of 0,
  7116.        1, 2, 7, 9, or 13.  These modes are described in the table below.  The
  7117.        "Mode" column identifies the value of number1 to specify on the SCREEN
  7118.        command to select that graphics mode.  The "Graphics Resolution" column
  7119.        has three numbers.  The first identifies the number of rows of pixels
  7120.        supported in this mode.  The second number identifies the number of
  7121.        columns.  The third number identifies the number of colors which may
  7122.        displayed on screen at one time.  The numbers in the "Text Resolution"
  7123.        column tell you how many rows, columns and colors you may display on the
  7124.        screen when displaying text.  The adapters column identifies the type of
  7125.        graphics adapter required to use this mode.
  7126.  
  7127.        Mode      Graphics Resolution      Text Resolution     Adapters
  7128.        -----     -------------------      ---------------     -------
  7129.          0       None                     25 x 80 x 16        Any Adapter
  7130.          1       200 x 320 x 4            25 x 40 x 4         CGA/EGA/VGA
  7131.          2       200 x 640 x 2            25 x 80 x 2         CGA/EGA/VGA
  7132.          7       200 x 320 x 16           25 x 40 x 16        EGA/VGA
  7133.          9       350 x 640 x 16           25 x 80 x 16        EGA/VGA
  7134.         13       200 x 320 x 256          25 x 40 x 16        VGA
  7135.  
  7136.  
  7137.  
  7138.        Example:
  7139.  
  7140.                  SCREEN 13
  7141.  
  7142.        After execution of this statement, the PC will be in Graphics Mode 13
  7143.        which will allow you to display 200 rows by 320 columns of pixels in 256
  7144.        different colors.  Up to 25 rows and 80 columns of text can be displayed
  7145.        in up to 256 colors.  And finally, mode 13 requires a VGA Graphics Card.
  7146.  
  7147.        Comments:
  7148.  
  7149.             Any program which uses the SCREEN command should issue a "SCREEN 0"
  7150.        command before terminating.  Otherwise, the screen will not be reset
  7151.        properly when you return to DOS.
  7152.  
  7153.        See also:
  7154.  
  7155.             PSET, PRESET, POINT, ZMODE
  7156.  
  7157.  
  7158.  
  7159.  
  7160.  
  7161.  
  7162.  
  7163.  
  7164.  
  7165.  
  7166.                                       Page - 111
  7167.  
  7168.  
  7169.  
  7170.  
  7171.  
  7172.                                          SEND
  7173.  
  7174.        Format:        SEND (data1,number2)
  7175.  
  7176.        Description:
  7177.  
  7178.             This statement is used to send one character to a serial port.  The
  7179.        port should initialized with OPENCOM prior to using this statement.
  7180.        Data1 may be any valid data type (integer or string, variable or
  7181.        constant) and it should contain the character to be sent to the port.
  7182.        Number2 identifies which COM port to send to (0=COM1, 1=COM2).
  7183.  
  7184.        Example:
  7185.  
  7186.                  OPENCOM(2,0,0,3,0)
  7187.                  SEND ("X",0)
  7188.  
  7189.        The above code will open COM1 at 300baud, 1 stop bit, 8bit character
  7190.        size, with no parity.  It will then send the character "X" to COM1.
  7191.  
  7192.        See also:
  7193.  
  7194.             RECEIVE,COMSTAT,OPENCOM
  7195.  
  7196.  
  7197.  
  7198.                                          SOUND
  7199.  
  7200.        Format:        SOUND number1,number2
  7201.  
  7202.        Description:
  7203.  
  7204.             This statement will generate a sound on your computer speaker with
  7205.        a frequency of number1, and a duration of number2.  Frequency should be
  7206.        in the range of 0 to 32767.  ASIC, however, only checks to see that it
  7207.        is non-negative.
  7208.  
  7209.        Example:
  7210.  
  7211.                  SOUND  400,20
  7212.  
  7213.        Execution of the above statement will produce a short beep.
  7214.  
  7215.        Comments:
  7216.  
  7217.             ASIC "frequencies" values go from high to low.  That is, a
  7218.        frequency of 0 is the highest, and 32767 is the lowest.
  7219.  
  7220.  
  7221.  
  7222.  
  7223.  
  7224.  
  7225.  
  7226.  
  7227.  
  7228.  
  7229.  
  7230.                                       Page - 112
  7231.  
  7232.  
  7233.  
  7234.  
  7235.  
  7236.                                         SPACE$
  7237.  
  7238.        Format:        string1=SPACE$(number1)
  7239.  
  7240.        Description:
  7241.  
  7242.             This statement will return a string containing number1 ASCII space
  7243.        characters.
  7244.  
  7245.        Example:
  7246.  
  7247.             A$=SPACE$(10)
  7248.             B$="<"+A$
  7249.             B$=B$+">"
  7250.  
  7251.        After execution of these statements, variable "B$" will contain the
  7252.        string "<          >".
  7253.  
  7254.        See also:
  7255.  
  7256.             STRING$
  7257.  
  7258.  
  7259.  
  7260.                                          STR$
  7261.  
  7262.        Format:        string1 = STR$ (number1)
  7263.  
  7264.        Description:
  7265.  
  7266.             This statement will convert number1 to a string format and store
  7267.        the string format in string1.
  7268.  
  7269.        Example:
  7270.  
  7271.                  A=1234
  7272.                  A$ = STR$(A)
  7273.  
  7274.        After execution of these statements, A$ would contain the string "1234".
  7275.  
  7276.        See also:
  7277.  
  7278.             VAL
  7279.  
  7280.  
  7281.  
  7282.  
  7283.  
  7284.  
  7285.  
  7286.  
  7287.  
  7288.  
  7289.  
  7290.  
  7291.  
  7292.  
  7293.  
  7294.                                       Page - 113
  7295.  
  7296.  
  7297.  
  7298.  
  7299.  
  7300.                                         STRING$
  7301.  
  7302.        Format:        string1=STRING$(number1,number2)  <--Format 1
  7303.  
  7304.                       string1=STRING$(number1,string2)   <--Format 2
  7305.  
  7306.        Description:
  7307.  
  7308.             This statement will return a string containing number1 characters
  7309.        of ASCII value number2 (Format1).  If format 2 is used, this statement
  7310.        will create a string containing number1 characters. Each of these
  7311.        characters will be the same as the first character of string2.
  7312.  
  7313.        Example 1:
  7314.  
  7315.             A$=STRING$(8,111)
  7316.  
  7317.        After execution of these statements, variable "A$" will contain the
  7318.        string "oooooooo".
  7319.  
  7320.        Example 2:
  7321.  
  7322.             A$=STRING$(5,"xyz")
  7323.  
  7324.        After execution of these statements, variable "A$" will contain the
  7325.        string "xxxxx".
  7326.  
  7327.        See also:
  7328.  
  7329.             SPACE$
  7330.  
  7331.  
  7332.  
  7333.  
  7334.  
  7335.  
  7336.  
  7337.  
  7338.  
  7339.  
  7340.  
  7341.  
  7342.  
  7343.  
  7344.  
  7345.  
  7346.  
  7347.  
  7348.  
  7349.  
  7350.  
  7351.  
  7352.  
  7353.  
  7354.  
  7355.  
  7356.  
  7357.  
  7358.                                       Page - 114
  7359.  
  7360.  
  7361.  
  7362.  
  7363.  
  7364.                                          TIME$
  7365.  
  7366.        Format:        string1 = TIME$
  7367.  
  7368.        Description:
  7369.  
  7370.             This statement will retrieve the current time from the PC's system
  7371.        clock.  The time will be retrieved and stored in String1, in the format:
  7372.        "HH.MM.SS".
  7373.  
  7374.        Example:
  7375.  
  7376.             CURTIME$=TIME$
  7377.             PRINT CURTIME$
  7378.  
  7379.        After execution of the above statements the current time (as per the
  7380.        PC's internal clock) will be displayed on the screen.
  7381.  
  7382.        Comments:
  7383.  
  7384.             Note:  if the time printed is wrong, you have probably not set the
  7385.        system clock.  Most older XTs and PCs do not have a battery to preserve
  7386.        the DATE and TIME in the system clock, so you have to set them each time
  7387.        you power up the PC.  Most ATs and newer PCs have a battery backup, so
  7388.        that the date is preserved for you.
  7389.  
  7390.             Unlike GWBASIC/BASICA, you cannot set the system time with TIME$,
  7391.        however, you can set the system time from DOS by typing TIME.
  7392.  
  7393.        See also:
  7394.  
  7395.             DATE$, TIMER
  7396.  
  7397.  
  7398.  
  7399.  
  7400.  
  7401.  
  7402.  
  7403.  
  7404.  
  7405.  
  7406.  
  7407.  
  7408.  
  7409.  
  7410.  
  7411.  
  7412.  
  7413.  
  7414.  
  7415.  
  7416.  
  7417.  
  7418.  
  7419.  
  7420.  
  7421.  
  7422.                                       Page - 115
  7423.  
  7424.  
  7425.  
  7426.  
  7427.  
  7428.                                          TIMER
  7429.  
  7430.        Format:        number1 = TIMER
  7431.  
  7432.        Description:
  7433.  
  7434.             This statement will retrieve a timer count from the PCs hardware
  7435.        circuitry.  The timer count will be placed in number1.  The timer count
  7436.        is in "clock ticks".  A "clock tick" occurs in the PC approximately 18.2
  7437.        times per second.  The PC is continually incrementing this clock
  7438.        counter.  This statement can be used to time the duration of events.
  7439.  
  7440.        Example:
  7441.  
  7442.  
  7443.             CLS
  7444.             PRINT "PRESS A KEY"
  7445.             STARTCNT&=TIMER
  7446.        LOOP:X$=INKEY$
  7447.             IF X$="" THEN LOOP:
  7448.             ENDCNT&=TIMER
  7449.             ELAPSED&=ENDCNT&-STARTCNT&
  7450.             ELAPSED&=ABS(ELAPSED&)
  7451.             ELAPSED&=ELAPSED&/18
  7452.             PRINT "IT TOOK YOU APPROXIMATELY";
  7453.             PRINT ELAPSED&
  7454.             PRINT " SECONDS TO PRESS A KEY"
  7455.  
  7456.  
  7457.        The above code fragment will time how long you wait to press a key in
  7458.        seconds.  You could modify it easily to display in clock ticks, which
  7459.        would provide much more accuracy, if you deleted the statement which
  7460.        divides the ELAPSED count by 18.
  7461.  
  7462.        Comments:
  7463.  
  7464.             Note that it is necessary to use the absolute value of ELAPSED&
  7465.        since the clock counts is stored as unsigned integers.  ASIC integers,
  7466.        on the other hand, are signed.  If number1 is a long integer variable,
  7467.        then TIMER retrieves the full PC timer value.  However, if a normal
  7468.        integer variable is specified as number1, then ASIC retrieves the least
  7469.        16 significant bits from the PC timer.
  7470.  
  7471.        See also:
  7472.  
  7473.             DATE$,TIME$
  7474.  
  7475.  
  7476.  
  7477.  
  7478.  
  7479.  
  7480.  
  7481.  
  7482.  
  7483.  
  7484.  
  7485.  
  7486.                                       Page - 116
  7487.  
  7488.  
  7489.  
  7490.  
  7491.  
  7492.                                         UCASE$
  7493.  
  7494.        Format:        string1=UCASE$(string2)
  7495.  
  7496.        Description:
  7497.  
  7498.             This statement will convert all lowercase letters in string2 to
  7499.        uppercase, and store the resulting string in string1.
  7500.  
  7501.        Example:
  7502.  
  7503.             A$=UCASE$("123 Main St, USA")
  7504.  
  7505.        After execution of this statement, the variable "A$" will contain the
  7506.        string "123 MAIN ST, USA".
  7507.  
  7508.        See also:
  7509.  
  7510.             LCASE$
  7511.  
  7512.  
  7513.  
  7514.                                           VAL
  7515.  
  7516.        Format:        number1 = VAL (string1)
  7517.  
  7518.        Description:
  7519.  
  7520.             This statement will attempt to convert string1 into an integer
  7521.        value, and it will store the result in number1.
  7522.  
  7523.        Example:
  7524.  
  7525.                  A$ = "12345"
  7526.                  A = VAL (A$)
  7527.  
  7528.        After execution of these statements, variable "A" would contain the
  7529.        value 12345.
  7530.  
  7531.  
  7532.        See also:
  7533.  
  7534.             STR$
  7535.  
  7536.  
  7537.  
  7538.  
  7539.  
  7540.  
  7541.  
  7542.  
  7543.  
  7544.  
  7545.  
  7546.  
  7547.  
  7548.  
  7549.  
  7550.                                       Page - 117
  7551.  
  7552.  
  7553.  
  7554.  
  7555.  
  7556.                                         VARPTR
  7557.  
  7558.        Format:        number1 = VARPTR (variable1)
  7559.  
  7560.        Description:
  7561.  
  7562.             This statement will return the address of a variable  variable1 and
  7563.        store it in number1.  This may be used to peek and poke values directly
  7564.        into a variable.
  7565.  
  7566.        Example:
  7567.  
  7568.                  A$ = "XYZ"
  7569.                  B = VARPTR(A$)
  7570.                  C = PEEK (B)
  7571.                  PRINT C
  7572.  
  7573.        After execution of these statements the screen would display the number
  7574.        88 which is the number for the ASCII character "X".
  7575.  
  7576.        See also:
  7577.  
  7578.             PEEK, POKE
  7579.  
  7580.  
  7581.  
  7582.                                       WHILE/WEND
  7583.  
  7584.        Format:        WHILE condition
  7585.                       WEND
  7586.  
  7587.        Description:
  7588.  
  7589.             This statement will execute those statements which are between the
  7590.        WHILE and the WEND statements as long as the "condition" is true.  The
  7591.        operand "condition" is one of the following:
  7592.  
  7593.                       number1 > number2
  7594.                       string1  > string2
  7595.                       number1 = number2
  7596.                       string1  = string2
  7597.                       number1 < number2
  7598.                       string1  < string2
  7599.  
  7600.        Example:
  7601.  
  7602.                  PRINT "PRESS A KEY TO CONTINUE"
  7603.                  A$=""
  7604.                  WHILE A$=""
  7605.                       A$=INKEY$
  7606.                  WEND
  7607.  
  7608.        In this example, the program will pause until the user presses a key.
  7609.        WHILE statements may be nested 25 levels deep.
  7610.  
  7611.  
  7612.  
  7613.  
  7614.                                       Page - 118
  7615.  
  7616.  
  7617.  
  7618.  
  7619.  
  7620.                                          WIDTH
  7621.  
  7622.        Format:        WIDTH number1
  7623.  
  7624.        Description:
  7625.  
  7626.             This statement will set the screen to 40 column text or 80 column
  7627.        text mode only.  The only two valid values for number1 are thus 40 and
  7628.        80.  In ASIC, WIDTH 80 is equivalent to executing SCREEN 0.  Also, WIDTH
  7629.        40 is equivalent to executing SCREEN 1.  If you use WIDTH 40, you should
  7630.        always reset the screen back to WIDTH 80 before terminating your program
  7631.        with END.  Otherwise, your PC will be left in 40 column mode.
  7632.  
  7633.        Example:
  7634.  
  7635.             WIDTH 40
  7636.  
  7637.        The above statement would put the PC in 40 column mode.
  7638.  
  7639.  
  7640.  
  7641.                                          ZBIT
  7642.  
  7643.        Format:        number1 = ZBIT(number2,number3)
  7644.  
  7645.        Description:
  7646.  
  7647.             This statement is used to determine if a single "bit" in an integer
  7648.        variable is set to "1".  Number2 represents the bit to be tested.  It
  7649.        should be in the range 0 to 15.  Number3 represents the integer variable
  7650.        or constant to be tested.  The result of the test is returned to
  7651.        number1.  If the bit was set, number1 will be set to "1", otherwise,
  7652.        number1 will be set to "0".
  7653.  
  7654.        Example:
  7655.  
  7656.                  GAMEPORT = INP(513)
  7657.                  TRIGGER = ZBIT(4,GAMEPORT)
  7658.                  IF TRIGGER = 1 THEN TRIGGERPRESSED:
  7659.  
  7660.        In this example, the joystick port is read, and its status is placed in
  7661.        the variable "GAMEPORT".  The bit which represents the trigger for
  7662.        joystick 1 is then tested using ZBIT.  If the trigger bit is set, then
  7663.        the program would transfer to the label "TRIGGERPRESSED:".  Note that
  7664.        the above code assumes that a game card is present in the computer.
  7665.  
  7666.        Comments:
  7667.  
  7668.             This statement is an extension over GWBASIC/BASICA, although it is
  7669.        possible to perform similar tests in GWBASIC/BASICA with the boolean AND
  7670.        statement.
  7671.  
  7672.  
  7673.  
  7674.  
  7675.  
  7676.  
  7677.  
  7678.                                       Page - 119
  7679.  
  7680.  
  7681.  
  7682.  
  7683.  
  7684.                                          ZMODE
  7685.  
  7686.        Format:        integer = ZMODE
  7687.  
  7688.        Description:
  7689.  
  7690.             This command returns a code which indicates whether a color or
  7691.        monochrome card is active in the system.  ZMODE returns a value of 1
  7692.        when a color card is detected, and a value of 0 for monochrome.
  7693.  
  7694.        Example:
  7695.  
  7696.                  A = ZMODE
  7697.                  IF A = 0 THEN
  7698.                       PRINT "This program requires a Color Card to Run"
  7699.                       END
  7700.                  ENDIF
  7701.  
  7702.        The above code fragment will check for a color card; if not found, the
  7703.        program will terminate with an appropriate message.  Otherwise, the
  7704.        program will continue.
  7705.  
  7706.        Comments:
  7707.  
  7708.             This statement is an extension over BASICA/GWBASIC.
  7709.  
  7710.  
  7711.  
  7712.  
  7713.  
  7714.  
  7715.  
  7716.  
  7717.  
  7718.  
  7719.  
  7720.  
  7721.  
  7722.  
  7723.  
  7724.  
  7725.  
  7726.  
  7727.  
  7728.  
  7729.  
  7730.  
  7731.  
  7732.  
  7733.  
  7734.  
  7735.  
  7736.  
  7737.  
  7738.  
  7739.  
  7740.  
  7741.  
  7742.                                       Page - 120
  7743.  
  7744.  
  7745.  
  7746.  
  7747.  
  7748.  
  7749.  
  7750.  
  7751.                                         A S I C
  7752.  
  7753.                                        Chapter 8
  7754.  
  7755.                            Compatibility with GWBASIC/BASICA
  7756.  
  7757.  
  7758.        In general, although ASIC does not support all options on every BASIC
  7759.        statement, those it does support work like they do in BASICA/GWBASIC.
  7760.        The known exceptions are listed in this chapter.
  7761.  
  7762.  
  7763.        INKEY$
  7764.  
  7765.             This statement is compatible, however ASIC does provide an
  7766.        extension over GWBASIC/BASICA.  If an extended key is pressed (e.g. F1-
  7767.        F10), ASIC returns the scan code for the extended key, and sets a
  7768.        special system variable "EXTENDED" to a value of 1.  For non-extended
  7769.        keys, the "EXTENDED" variable will contain 0.
  7770.  
  7771.  
  7772.        FILE HANDLING
  7773.  
  7774.             ASIC provides no EOF statement or ON ERROR statements.  Instead,
  7775.        ASIC sets a special system variable when an error occurs during file
  7776.        I/O.  This special variable is called "ERROR" and it is set after every
  7777.        file I/O statement (OPEN/INPUT#/PRINT#/CLOSE, etc) to either 0 to
  7778.        indicate no errors, or a non-zero value.  If a non-zero value is
  7779.        present, an error has occurred.  The specific errors are identified in
  7780.        chapter 10.
  7781.  
  7782.  
  7783.        FILE FORMAT
  7784.  
  7785.             ASIC Files are written with 2/4 bytes per normal/long integer in
  7786.        binary format, instead of string format as in BASICA/GWBASIC.  Strings
  7787.        are written as a sequence of ASCII characters terminated by an ASCII
  7788.        null, or optionally with no NULL terminator.
  7789.  
  7790.  
  7791.        PUNCTUATION
  7792.  
  7793.             ASIC permits use of punctuation that it does not require to allow
  7794.        you to enter statements in their familiar GWBASIC/BASICA Formats.  For
  7795.        example:
  7796.  
  7797.                  A = ABS (B(1))
  7798.  
  7799.             This statement is valid in both ASIC and in GWBASIC/BASICA.
  7800.        However, ASIC ignores the parenthesis and comma.  Thus ASIC will
  7801.        actually accept the following formats as alternatives to the above:
  7802.  
  7803.             A = ABS B 1
  7804.             A = ABS B 1,,,,,,)))))
  7805.  
  7806.                                       Page - 121
  7807.  
  7808.  
  7809.  
  7810.  
  7811.  
  7812.        FOR/NEXT
  7813.  
  7814.             FOR/NEXT loops always fall through the body of the FOR at least one
  7815.        time in ASIC.  This does not happen in BASICA/GWBASIC.  For more
  7816.        information on this, refer to Chapter 7.
  7817.  
  7818.  
  7819.        RND
  7820.  
  7821.             RND (N) returns a value from 0-32767 for normal integers and     0-
  7822.        2,147,483,647 for long integers instead of 0 to 1 as in BASICA/GWBASIC.
  7823.  
  7824.  
  7825.        LOCATE/CSRLIN/POS
  7826.  
  7827.             Coordinates are specified in range 0-24 and 0-79 instead of 1-25
  7828.        and 1-80.
  7829.  
  7830.  
  7831.        PSET/PRESET/POINT
  7832.  
  7833.             Coordinates are specified in row/column order instead of column/row
  7834.        order.
  7835.  
  7836.  
  7837.        BLOAD/BSAVE
  7838.  
  7839.             File formats are not compatible with GWBASIC/BASICA.  BLOAD
  7840.        requires offset and the number of bytes to read.
  7841.  
  7842.        OPENCOM/COMSTAT/SEND/RECEIVE
  7843.  
  7844.             These statements provide serial port support in ASIC.  In
  7845.        GWBASIC/BASICA this is provided by OPEN/INPUT#/PRINT#.
  7846.  
  7847.        DATE$/TIME$
  7848.  
  7849.             ASIC allows you to retrieve the system date and time, but will not
  7850.        allow you to set new system date/time values.
  7851.  
  7852.        CALL/RUN
  7853.  
  7854.             These statements perform functions similar to their GWBASIC/BASICA
  7855.        counterparts, but function differently.  Refer to the keyword reference
  7856.        for the appropriate keyword for details on their operation.
  7857.  
  7858.  
  7859.  
  7860.  
  7861.  
  7862.  
  7863.  
  7864.  
  7865.  
  7866.  
  7867.  
  7868.  
  7869.  
  7870.                                       Page - 122
  7871.  
  7872.  
  7873.  
  7874.  
  7875.  
  7876.  
  7877.  
  7878.        EXTENSIONS OVER BASICA/GWBASIC
  7879.  
  7880.  
  7881.        CODE                COMMAND$
  7882.        INT86               FILEPOS
  7883.        FIND                LCASE$
  7884.        LTRIM$              MOD
  7885.        RTRIM               UCASE$
  7886.        ZBIT                ZMODE
  7887.        EXTENDED
  7888.  
  7889.             The statements above are extensions over BASICA/GWBASIC.
  7890.  
  7891.  
  7892.  
  7893.  
  7894.  
  7895.  
  7896.  
  7897.  
  7898.  
  7899.  
  7900.  
  7901.  
  7902.  
  7903.  
  7904.  
  7905.  
  7906.  
  7907.  
  7908.  
  7909.  
  7910.  
  7911.  
  7912.  
  7913.  
  7914.  
  7915.  
  7916.  
  7917.  
  7918.  
  7919.  
  7920.  
  7921.  
  7922.  
  7923.  
  7924.  
  7925.  
  7926.  
  7927.  
  7928.  
  7929.  
  7930.  
  7931.  
  7932.  
  7933.  
  7934.                                       Page - 123
  7935.  
  7936.  
  7937.  
  7938.  
  7939.  
  7940.  
  7941.  
  7942.  
  7943.                                         A S I C
  7944.  
  7945.                                        Chapter 9
  7946.  
  7947.                                 Technical Details/Tips
  7948.  
  7949.  
  7950.        This chapter contains technical information and tips regarding ASIC.
  7951.  
  7952.  
  7953.  
  7954.                                     COMPILER LIMITS
  7955.  
  7956.  
  7957.        Maximum Source Program Size:   Command Line Compiler - Unlimited
  7958.                                       Integrated Environment - Limited only by
  7959.                                       available memory
  7960.  
  7961.        Maximum Object Program Size:   64k bytes--.COM Format:
  7962.                                                     64k code/data/stack
  7963.                                      130k+ bytes--.EXE Format:
  7964.                                                     64k code
  7965.                                                     64k data
  7966.                                                     up to 64k stack
  7967.                                      130k+ bytes--.OBJ Format:
  7968.                                                     64k ASIC code
  7969.                                                     64k ASIC data
  7970.                                                     up to 64k stack
  7971.                                                     PLUS up to ~500k externally
  7972.                                                     assembled ".OBJ" files can
  7973.                                                     be linked into your ASIC
  7974.                                                     program and called using
  7975.                                                     the CALL SUB statement.
  7976.        Maximum Source Line Length     128 bytes - Command Line
  7977.                                       80 bytes - Integrated Environment
  7978.  
  7979.        Compiler Symbol Table Size:    Unlimited - can use all available memory
  7980.  
  7981.        Maximum Number of Arrays:      25
  7982.  
  7983.        FOR/NEXT Nesting Depth         25
  7984.  
  7985.        IF/THEN/ELSE Nesting Depth     25
  7986.  
  7987.        WHILE/WEND Nesting Depth       25
  7988.  
  7989.        Compiler Memory Requirements  305k - Command Line
  7990.                                      405k - Integrated Environment
  7991.  
  7992.  
  7993.  
  7994.  
  7995.  
  7996.  
  7997.  
  7998.                                       Page - 124
  7999.  
  8000.  
  8001.  
  8002.  
  8003.  
  8004.  
  8005.  
  8006.                                   COMPILER OPERATION
  8007.  
  8008.  
  8009.             ASIC is a single pass compiler written entirely in C (Borland C
  8010.        Version 3.1).  Each source statement is translated directly into machine
  8011.        code.  ASIC compiles 100% in memory for maximum speed.  The compiler
  8012.        does not require any disk work space.  ASIC generates a minimum of error
  8013.        checking code.  This is because the ASIC philosophy stresses execution
  8014.        speed.  This does place greater responsibility on the programmer to
  8015.        check for out of bounds conditions, etc...
  8016.  
  8017.  
  8018.                                   MEMORY OPTIMIZATION
  8019.  
  8020.  
  8021.             ASIC provides 32 bit long integers in addition to 16 bit normal
  8022.        integers.  This allows you to store much larger numbers, however,
  8023.        nothing in life is free.  Long integers will increase the size of the
  8024.        resulting ".COM" file by approximately 475 bytes.  If you are not using
  8025.        long integers, be sure to compile with the "Extended Math" Option turned
  8026.        OFF so that ASIC does not include these unneeded bytes in your COM or
  8027.        EXE file. Otherwise, ASIC will include the long integer support code in
  8028.        your file, even if you never create a single long integer!  Note: by
  8029.        default, this option is turned off in both the command line and
  8030.        integrated versions of the compiler.
  8031.  
  8032.             Likewise, the "Decimal Math" option will allow math with fractional
  8033.        results of very large numbers, but this option will increase your
  8034.        program size.  Use integers or long integers unless you need this
  8035.        fractional precision, and turn off the "Decimal Math" option.  Note:  by
  8036.        default, this option is turned off in both the command line and
  8037.        integrated versions of the compiler.
  8038.  
  8039.             Also remember that ASIC's debugging option increases your ".COM"
  8040.        file size.  So don't forget to recompile your program with the
  8041.        "Debugging" Option turned off (after you have finished debugging it, of
  8042.        course).
  8043.  
  8044.             COM disk files will usually be smaller than EXE files by several
  8045.        hundred bytes.  However, COM files require 64k of memory to execute.
  8046.        Additionally, COM files (because of a DOS requirement), will
  8047.        automatically allocate all available memory at load time.  EXE files
  8048.        require the actual size of the program plus 2000 bytes for the stack
  8049.        (4000 bytes for the stack when compiling with debugging mode).  Thus,
  8050.        your program may be loadable in as few as 3-4k bytes of memory.  Also
  8051.        note that an ASIC EXE does NOT allocate all available memory to your
  8052.        program.  ASIC only allocates the amount of memory your program actually
  8053.        needs.  The following chart summarizes when it is usually best to use
  8054.        each type of file:
  8055.  
  8056.  
  8057.  
  8058.  
  8059.  
  8060.  
  8061.  
  8062.                                       Page - 125
  8063.  
  8064.  
  8065.  
  8066.  
  8067.  
  8068.  
  8069.  
  8070.                             MEMORY OPTIMIZATION (Continued)
  8071.  
  8072.  
  8073.             Use COM files when:
  8074.             -------------------
  8075.  
  8076.             o  You want to minimize the disk space a program occupies
  8077.             o  Your program is smaller than 64k in size
  8078.  
  8079.             Use EXE files when:
  8080.             -------------------
  8081.  
  8082.             o  Your program is larger than 64k in size
  8083.             o  You want to minimize your program's run-time memory requirements
  8084.             o  You are calling another program using the RUN or CALL Statements
  8085.  
  8086.             Use the OBJ option to create an EXE file when:
  8087.             ----------------------------------------------
  8088.  
  8089.             o To use the CALL SUB statement.
  8090.  
  8091.  
  8092.                                PERFORMANCE OPTIMIZATION
  8093.  
  8094.  
  8095.        This section contains tips for making your programs run as fast as
  8096.        possible.
  8097.  
  8098.        1)   VARIABLE TYPES - Don't use long integer variables or decimal
  8099.        variables to store numbers that can fit in a regular integer variable.
  8100.        Long integer variables are exponentially slower than regular integers,
  8101.        and decimal variables are exponentially slower than long integer
  8102.        variables.  If the number will exceed the range allowed by a regular
  8103.        integer, but is an integer in the range +/-2,147,483,647, then use a
  8104.        long integer.  If the number requires one or more decimal places of
  8105.        precision, or is an integer larger than +/-2,147,483,647, then use a
  8106.        decimal variable.  Always use integers on FOR/NEXT loops, when possible.
  8107.  
  8108.        2)   DECIMAL VARIABLES - When using decimal variables, be aware that the
  8109.        least efficient operation is screen I/O.  Don't PRINT a number unless
  8110.        you need to. (Note:  The decimal variable format used by ASIC was
  8111.        selected to optimize speed when adding, subtracting, multiplying,and
  8112.        dividing.  The trade off in using this format is that it takes longer to
  8113.        convert the internal format to printable form than it would have with a
  8114.        packed binary coded decimal (BCD) format.)
  8115.  
  8116.        3)   MATH FUNCTIONS - The math functions, in order of least efficient to
  8117.        most efficient, are:  Division, Multiplication, Subtraction and
  8118.        Addition.
  8119.  
  8120.        4)   DON'T MIX VARIABLE TYPES - When performing calculations using
  8121.        decimal variables, avoid mixing decimal variables with integer
  8122.        variables.  Although ASIC will automatically convert the integers to a
  8123.        decimal format internally, this conversion will slow down your
  8124.        calculations.
  8125.  
  8126.                                       Page - 126
  8127.  
  8128.  
  8129.  
  8130.  
  8131.  
  8132.  
  8133.  
  8134.  
  8135.                                     DEBUGGER LIMITS
  8136.  
  8137.  
  8138.        Maximum Concurrent Breakpoints     20
  8139.  
  8140.        Maximum Concurrent Watches         10
  8141.  
  8142.        Maximum Symbol Length              30 Characters
  8143.  
  8144.        Maximum Symbols                    Same as Compiler
  8145.  
  8146.        Maximum Source Statements          Unlimited
  8147.  
  8148.  
  8149.                                   DEBUGGER OPERATION
  8150.  
  8151.             When you select the "Debugging code" compiler option, the ASIC
  8152.        compiler inserts additional machine language instructions into your
  8153.        program.  It inserts a single statement at the beginning of your program
  8154.        (specifically, INT 3) which allows it to gain control.  When the ASIC
  8155.        editor is loaded, it saves the existing INT 3 vector, and installs the
  8156.        ASIC Debugger as INT 3.  In this way, when your program begins
  8157.        executing, the INT 3 statement that ASIC inserted in your program causes
  8158.        a transfer of control to the debugger.  Once the debugger gains control,
  8159.        it can set or remove additional breakpoints as needed in your program,
  8160.        plus provide access to the video memory and variable memory locations
  8161.        with the Swap, Watch, Unwatch, and Modify Commands.  When you exit the
  8162.        ASIC editor, ASIC deinstalls the debugger from INT 3, and restores the
  8163.        original interrupt 3 vector.
  8164.  
  8165.             The compiler also creates a file with a ".DBG" extension which
  8166.        contains the symbolic information needed by the debugger (ie, variable
  8167.        names and offsets, and source statement offsets).
  8168.  
  8169.  
  8170.                                    DEBUGGER OVERHEAD
  8171.  
  8172.             Running a program in debugging mode adds a small amount of overhead
  8173.        to your program (both compiled code size, and execution speed).
  8174.        Specifically, the size of the debugging code will be (approximately):
  8175.  
  8176.                  CodeSizeIncrease = 1 + LinesOfSourceCode
  8177.  
  8178.        Note that the actual increase will usually be less than the above, since
  8179.        DIM, DATA, REM, and blank source lines do not require debugging code.
  8180.        The reduction in execution speed is very slight in most cases (for you
  8181.        assembly language programmers out there, a single NOP instruction is
  8182.        executed for each source line).
  8183.  
  8184.             In EXE files, the stack size is increased by an additional 2k when
  8185.        debugging is enabled.
  8186.  
  8187.  
  8188.  
  8189.  
  8190.                                       Page - 127
  8191.  
  8192.  
  8193.  
  8194.  
  8195.  
  8196.  
  8197.  
  8198.  
  8199.                                     STORAGE FORMATS
  8200.  
  8201.  
  8202.             NORMAL INTEGERS are stored in ASIC as two bytes, with the low order
  8203.        byte appearing first (as per Intel conventions).
  8204.  
  8205.             LONG INTEGERS are stored in ASIC as four bytes, with the least
  8206.        significant word first, followed by the most significant word.  Within
  8207.        these two words, the least significant byte appears first followed by
  8208.        the most significant byte.
  8209.  
  8210.             STRING VARIABLES are stored as FIXED 80 character strings
  8211.        terminated by an ASCII null character for a total length of 81
  8212.        characters.
  8213.  
  8214.             STRING CONSTANTS are stored with 1 byte per character in the string
  8215.        followed by a terminating ASCII null character.
  8216.  
  8217.             DECIMAL VARIABLES AND CONSTANTS are stored in 8 bytes, from least
  8218.        significant byte to most significant byte.  They are stored as signed
  8219.        binary integers, with an implicit decimal point.  The integer values are
  8220.        adjusted after each multiplication or division to scale the result to
  8221.        the proper number of decimal places.
  8222.  
  8223.             ARRAYS - Each element in an array requires two bytes.  (Don't
  8224.        forget arrays have an element zero (ie  DIM A(2) is comprised of A(0),
  8225.        A(1), and A(2)).
  8226.  
  8227.        Examples:
  8228.  
  8229.                  Item      Data Type           Storage Requirements
  8230.                  A         Integer Variable              2 bytes
  8231.                  17        Integer Constant              2 bytes
  8232.                  A&        Long Integer Variable         4 bytes
  8233.                  55555&    Long Integer Constant         4 bytes
  8234.                  A$        String Variable               81 bytes
  8235.                  "ABC"     String Constant               4 bytes
  8236.                  "A"       String Constant               2 bytes
  8237.                  A@        Decimal Variable              8 bytes
  8238.                  1.23456   Decimal Constant              8 bytes
  8239.                  12345@    Decimal Constant              8 bytes
  8240.                  DIM A(10) Integer Array                 22 bytes
  8241.                  DIM A(1)  Integer Array                 4 bytes
  8242.                  DIM A&(10)  Long Integer Array          44 bytes
  8243.                  DIM A$(10)  String Array                891 bytes
  8244.                  DIM A@(10)  Decimal Array               88 bytes
  8245.  
  8246.        As you can see, string variables are expensive in terms of storage
  8247.        space.  Since string constants are stored at actual length +1, It is
  8248.        MUCH more efficient to store short strings as constants in ASIC in terms
  8249.        of storage space.  There is no performance advantage to constants over
  8250.        variables, however.
  8251.  
  8252.  
  8253.  
  8254.                                       Page - 128
  8255.  
  8256.  
  8257.  
  8258.  
  8259.  
  8260.                               STORAGE FORMATS (Continued)
  8261.  
  8262.        In disk files, strings, decimals, and integers are written out in the
  8263.        above formats.  Note that unlike GWBASIC/BASICA, integer and decimal
  8264.        values are NOT expanded into strings when written, and conversely, not
  8265.        converted from strings when read.  String variables and constants are
  8266.        written out as ASCII strings terminated by a null character (however,
  8267.        the null can be suppressed).  Thus, string variables when written to
  8268.        disk, take the same space byte for byte as string constants.
  8269.  
  8270.        The reason behind fixed length string variables was avoidance of string
  8271.        "garbage collection".  In addition to slight performance advantages,
  8272.        there is the added benefit of providing a string memory address which
  8273.        never changes.  Thus once VARPTR retrieves the address of a variable,
  8274.        you never have to worry about it changing.
  8275.  
  8276.  
  8277.  
  8278.  
  8279.  
  8280.  
  8281.  
  8282.  
  8283.  
  8284.  
  8285.  
  8286.  
  8287.  
  8288.  
  8289.  
  8290.  
  8291.  
  8292.  
  8293.  
  8294.  
  8295.  
  8296.  
  8297.  
  8298.  
  8299.  
  8300.  
  8301.  
  8302.  
  8303.  
  8304.  
  8305.  
  8306.  
  8307.  
  8308.  
  8309.  
  8310.  
  8311.  
  8312.  
  8313.  
  8314.  
  8315.  
  8316.  
  8317.  
  8318.                                       Page - 129
  8319.  
  8320.  
  8321.  
  8322.  
  8323.  
  8324.  
  8325.  
  8326.  
  8327.                                       MEMORY MAP
  8328.  
  8329.        COM File Memory Map
  8330.  
  8331.        The following describes the structure of the ".COM" file created by
  8332.        ASIC.  All addresses are in Hexadecimal.
  8333.  
  8334.  
  8335.  
  8336.             Description                   Address Range
  8337.        ------------------------------     -------------
  8338.        Program Segment Prefix (PSP)       0000 - 00FF
  8339.         (Created/Required by DOS)
  8340.  
  8341.        Transfer to Program Code           0100 - 0102
  8342.        String Conversion Buffer           0103 - 0109
  8343.        Input Buffer                       010A - 015B
  8344.        Screen Width                       015C
  8345.        Color/Attribute Byte               015D
  8346.        Screen Graphics Mode               015E
  8347.        Cursor Position                    015F - 0160
  8348.        File Control Table                 0161 - 0169
  8349.        ERROR System Variable              016A - 016B
  8350.        System Subroutine Vectors          016C - 017F
  8351.        EXTENDED System Variable           0180 - 0181
  8352.        RND Seed                           0182 - 0185
  8353.        Math Work Area                     0186 - 018D
  8354.        DEFSEG System Variable             018E - 018F
  8355.        Start DATA Block Pointer           0190 - 0191
  8356.        Current DATA Block Pointer         0192 - 0193
  8357.        Reserved for future use            0194 - 0195
  8358.        Optional Sys Subroutine Vectors    0196+
  8359.        and Work Areas (decimal math option)
  8360.        System Subroutines                 Address Varies
  8361.                  |
  8362.                  |
  8363.                  v
  8364.        Data Segment                       Address Varies
  8365.                  |
  8366.                  |
  8367.                  |
  8368.                  v
  8369.        Code Segment                       Address Varies
  8370.                  |
  8371.                  |
  8372.                  |
  8373.                  v
  8374.                  ^
  8375.                  |
  8376.                  |
  8377.        Program Stack  (builds downward)   FFFF
  8378.  
  8379.  
  8380.  
  8381.  
  8382.                                       Page - 130
  8383.  
  8384.  
  8385.  
  8386.  
  8387.  
  8388.  
  8389.                                 MEMORY MAP (Continued)
  8390.  
  8391.        EXE File Memory Map
  8392.  
  8393.        The following describes the structure of the ".EXE" file created by
  8394.        ASIC.  In the COM file format the code, data, and stack are all in the
  8395.        same memory segment.  In an ASIC EXE format file, the code, data, and
  8396.        stack each reside in their own segment.  Addresses are given as offsets
  8397.        from the CS (Code Segment), DS (Data Segment), or SS (Stack Segment)
  8398.        registers.
  8399.  
  8400.  
  8401.             Description                   Address Range
  8402.        ------------------------------     -------------
  8403.        Program Segment Prefix (PSP)       CS: minus 00FF
  8404.        (Created/Required by DOS, and
  8405.        immediately precedes the
  8406.        code segment)
  8407.                  |
  8408.                  |
  8409.                  v
  8410.        Code Segment (CS:)
  8411.             User Program                  0000 +
  8412.                  |
  8413.                  |
  8414.                  v
  8415.             System Subroutines            Address Varies
  8416.                  |
  8417.                  |
  8418.                  v
  8419.        Data Segment (DS:)
  8420.             Program Data Area #1          0000 - 0102
  8421.             String Conversion Buffer      0103 - 0109
  8422.             Input Buffer                  010A - 015B
  8423.             Screen Width                  015C
  8424.             Color/Attribute Byte          015D
  8425.             Screen Graphics Mode          015E
  8426.             Cursor Position               015F - 0160
  8427.             File Control Table            0161 - 0169
  8428.             ERROR System Variable         016A - 016B
  8429.             System Subroutine Vectors     016C - 017F
  8430.             EXTENDED System Variable      0180 - 0181
  8431.             RND Seed                      0182 - 0185
  8432.             Math Work Area                0186 - 018D
  8433.             DEFSEG System Variable        018E - 018F
  8434.             Start DATA Block Pointer      0190 - 0191
  8435.             Current DATA Block Pointer    0192 - 0193
  8436.             Reserved for future use       0194 - 0195
  8437.             Optional System Sub Vectors   0196+
  8438.             and Work Areas (decimal math option)
  8439.             Program Data Area #2          Address Varies
  8440.                  |
  8441.                  |
  8442.                  v
  8443.        Stack (SS:)  (builds downward)     0000 - 07D0 (0FA0--debug mode)
  8444.  
  8445.  
  8446.                                       Page - 131
  8447.  
  8448.  
  8449.  
  8450.  
  8451.  
  8452.                                 MEMORY MAP (Continued)
  8453.  
  8454.  
  8455.                  NOTE:  The format of an EXE file created using the
  8456.                  "B/OBJ" option is essentially the same as the one
  8457.                  produced by the "B/EXE" option, except that the
  8458.                  "B/OBJ" output file may contain additional code or
  8459.                  data segments linked in from other OBJ or LIB files.
  8460.  
  8461.  
  8462.  
  8463.  
  8464.  
  8465.  
  8466.  
  8467.  
  8468.  
  8469.  
  8470.  
  8471.  
  8472.  
  8473.  
  8474.  
  8475.  
  8476.  
  8477.  
  8478.  
  8479.  
  8480.  
  8481.  
  8482.  
  8483.  
  8484.  
  8485.  
  8486.  
  8487.  
  8488.  
  8489.  
  8490.  
  8491.  
  8492.  
  8493.  
  8494.  
  8495.  
  8496.  
  8497.  
  8498.  
  8499.  
  8500.  
  8501.  
  8502.  
  8503.  
  8504.  
  8505.  
  8506.  
  8507.  
  8508.  
  8509.  
  8510.                                       Page - 132
  8511.  
  8512.  
  8513.  
  8514.  
  8515.  
  8516.  
  8517.  
  8518.  
  8519.                                         A S I C
  8520.  
  8521.                                       Chapter 10
  8522.  
  8523.                               Mixed Language Programming
  8524.  
  8525.             ASIC programs can incorporate subroutines you write in assembly
  8526.        language.  This is a powerful feature, but it is a bit complicated until
  8527.        you have done it a few times.  This chapter describes how to use the
  8528.        CALL statement to call separately compiled assembly language programs.
  8529.  
  8530.                                        OVERVIEW
  8531.  
  8532.             Of course, the first thing you need is an assembler such as
  8533.        Borland's Turbo Assembler or Microsoft's Assembler.  You need to develop
  8534.        your assembly language subroutines and assemble them into OBJ format
  8535.        files.  Optionally, you can store these in a library file (.LIB) if you
  8536.        have Microsoft's LIB program or Borland's TLIB program.  Then, you
  8537.        develop the ASIC program which will call the subroutine, tell ASIC about
  8538.        the external object files and libraries, and compile your program.
  8539.        Thereafter, you may run and debug your program normally.
  8540.  
  8541.                            DEVELOPING ASSEMBLER SUBROUTINES
  8542.  
  8543.             The first step is to develop an assembler subroutine.  There are
  8544.        several things you need to be aware of, when developing an assembler
  8545.        program:
  8546.  
  8547.        1)   The entry point must be declared using the PUBLIC keyword.  If you
  8548.        do not do this, you will receive a linker error.
  8549.  
  8550.        2)   ASIC saves most critical registers prior to the CALL, however, in
  8551.        your assembler subroutine, you must take care to preserve the value of
  8552.        the SS and SP registers.  When you return to ASIC from your subroutine,
  8553.        you must insure that the SS and SP register values have not changed.
  8554.        This means that if you PUSH any values to the stack, you MUST POP them
  8555.        before the return instruction to ASIC.  Failure to do so will almost
  8556.        always crash your program.
  8557.  
  8558.        3)   ASIC calls external assembler subroutines using FAR calls
  8559.        (segment:offset), so you must declare the PROC as FAR, and must use the
  8560.        RETF (far return) instruction to return to ASIC.
  8561.  
  8562.        4)   ASIC passes parameters on the stack as far pointers (by reference).
  8563.        This means, that irregardless of whether the parameter being passed is a
  8564.        short integer, long integer, or string, ASIC will always place 4 bytes
  8565.        on the stack.  ASIC always pushes the segment portion (2 bytes) of the
  8566.        pointer to the stack first, followed by the offset (2 bytes).  Remember
  8567.        that these 4 bytes are not the value of the variable, but a pointer to
  8568.        the variable in memory.  If you look at the memory location pointed to
  8569.        by these 4 bytes, you will find the starting location of the variable.
  8570.        ASIC passes variables from the CALL SUB statement from left to right.
  8571.  
  8572.  
  8573.  
  8574.                                       Page - 133
  8575.  
  8576.  
  8577.  
  8578.  
  8579.  
  8580.        5.   When your subroutine receives control from ASIC, the stack will
  8581.        look like the following:
  8582.  
  8583.             etc
  8584.             SS:SP+10  (2 bytes) segment of next-to-last parameter
  8585.             SS:SP+8   (2 bytes} offset of next-to-last parameter
  8586.             SS:SP+6   (2 bytes) segment of last parameter
  8587.             SS:SP+4   (2 bytes) offset of last parameter
  8588.             SS:SP     (4 bytes) return address
  8589.  
  8590.        6) If your ASIC calling program passes constants to a subroutine, be
  8591.        aware that the subroutine can update the memory location used to store
  8592.        the constant values.  For example, if you modify the memory location
  8593.        used by ASIC to store the value of the constant "1" to "2", you will
  8594.        have inadvertently redefined the constant "1" to "2" throughout your
  8595.        ASIC program.  If you are not sure if a parameter will be updated by a
  8596.        subroutine, play it safe, use a variable for the parameter.
  8597.  
  8598.                               ASSEMBLING YOUR SUBROUTINE
  8599.  
  8600.             Before you subroutine can be used, it must be assembled.  Use your
  8601.        favorite assembler to do so.  If you like, you can store your object
  8602.        files in Microsoft LIB compatible format files for convenience.
  8603.  
  8604.                           DEVELOPING THE CALLING ASIC PROGRAM
  8605.  
  8606.             All that you have to do to call the subroutine, is insert a CALL
  8607.        SUB statement in your program.  The CALL SUB statement has the following
  8608.        format:
  8609.  
  8610.                  CALL SUB "subroutinename" [parm1...parmN]
  8611.  
  8612.             Where "subroutinename" is the name of the subroutine you wish to
  8613.        call (it must be in quotes).  No parameters are required, but you may
  8614.        provide one or more, if you like.  Any valid ASIC variable or constant
  8615.        type may be passed as a parameter.  "subroutinename" must match the name
  8616.        of the PUBLIC PROCedure you declared in your assembly language
  8617.        subroutine.
  8618.  
  8619.                             BUILDING THE EXECUTABLE PROGRAM
  8620.  
  8621.             Finally, you have to build the program.  You must do the following
  8622.        steps to create a valid EXE file:
  8623.  
  8624.             o  Load the edit buffer with the calling ASIC program
  8625.             o  Select the "Obj output file" option.
  8626.             o  Identify the names of any object modules to be linked with your
  8627.                 ASIC program, if any.
  8628.             o  Identify the names of any object libraries to be linked with
  8629.                 your ASIC program, if any.
  8630.             o  Tell ASIC where to find the MS DOS Linker
  8631.             o  Compile your program--ASIC will call the DOS linker
  8632.                 automatically.
  8633.  
  8634.             This can be made more clear through the use of an example.
  8635.        Included with your ASIC package are 2 files:
  8636.  
  8637.  
  8638.                                       Page - 134
  8639.  
  8640.  
  8641.  
  8642.  
  8643.  
  8644.             CALLSRCH.ASI
  8645.             SRCH.ASM
  8646.  
  8647.             The file CALLSRCH.ASI is an ASIC program which calls a subroutine
  8648.        called SRCH.  SRCH.ASM is the source to an assembly language program.
  8649.        Make sure these files are in your ASIC working directory for purposes of
  8650.        this example.  Also, copy the LINK.EXE file which comes with MS DOS to
  8651.        your ASIC directory or to the directory "C:\DOS".  Note:  if you don't
  8652.        want to make a copy of LINK.EXE, you don't have to, but you need to tell
  8653.        ASIC how to find LINK.EXE by using the LNK= compile option (see Chapter
  8654.        5 command line options, or the ADVANCED MENU OPTIONS section in chapter
  8655.        3, for information on setting the LINK path).
  8656.  
  8657.             The first step in producing the EXE file is to assemble the
  8658.        SRCH.ASM program.  If you have Borland's Turbo Assembler, type:
  8659.  
  8660.             TASM SRCH <return>
  8661.  
  8662.             Otherwise, if you have Microsoft's Macro Assembler, type:
  8663.  
  8664.             MASM SRCH <return>
  8665.  
  8666.             This should create a file called SRCH.OBJ in your working
  8667.        directory.  The second step is to build the ASIC program.  If you prefer
  8668.        the ASIC command line compiler, you can accomplish the build with a
  8669.        single command:
  8670.  
  8671.             ASICC CALLSRCH B/OBJ OBJ=SRCH
  8672.  
  8673.             That's all there is to it, if you are building from the command
  8674.        line.  You should be able to run the program now, try it--type:
  8675.  
  8676.             CALLSRCH <return>
  8677.  
  8678.             Read the comments in the programs for a description on what the
  8679.        program does.  You can also accomplish this easily from the integrated
  8680.        environment.
  8681.  
  8682.             First, load the program into ASIC:
  8683.  
  8684.             <Alt><f>
  8685.             <o>
  8686.             CALLSRCH <return>
  8687.  
  8688.             The above opens the "file" menu, selects the "open" option, and
  8689.        selects the file "CALLSRCH.ASI".  Next, set the compiler options:
  8690.  
  8691.             <Alt><c>
  8692.             <a>
  8693.             <o>
  8694.             <j>
  8695.             SRCH <return>
  8696.  
  8697.             This opens the  "compile" menu, selects the "advanced options"
  8698.        menu, sets the file output type to "obj" and set the "obJect names" to
  8699.        "SRCH".
  8700.  
  8701.  
  8702.                                       Page - 135
  8703.  
  8704.  
  8705.  
  8706.  
  8707.  
  8708.             <Alt><f>
  8709.             <s>
  8710.  
  8711.             This opens the "file" menu, and selects the "save" option.  This
  8712.        not only saves the CALLSRCH.ASI file to disk, it also saves all of the
  8713.        compile options you just set, to a file called CALLSRCH.PRJ.  So, the
  8714.        next time you enter ASIC, you won't have to re-set all those options for
  8715.        this program.
  8716.  
  8717.             Now compile the program:
  8718.  
  8719.             <F10>
  8720.  
  8721.             You should see the ASIC compiler screen compile the program, and
  8722.        you should then see a few messages as the Microsoft LINK program builds
  8723.        the EXE file.  In the future, from the integrated environment, you can
  8724.        rebuild the CALLSRCH program by loading it into the edit buffer and
  8725.        pressing <F10> to compile.  ASIC will remember all of the options you
  8726.        told it, so it will remember to link the "SRCH" module, automatically.
  8727.  
  8728.                                   OTHER LINK OPTIONS
  8729.  
  8730.             The above is a simple example; there are other compile examples in
  8731.        Chapter 5.  If you have one or more subroutine object modules stored in
  8732.        a library, you can use the "LIB=" option on the command line to specify
  8733.        the library names to ASIC.  You can also specify the library information
  8734.        inside the integrated environment (Open the "compile" menu, select the
  8735.        "Advanced options" option.  From the "Advanced options" menu that pops
  8736.        up, select the "liBrary names" option.
  8737.  
  8738.             When specifying object files, remember that the ".OBJ" file
  8739.        extension is optional, as is the ".LIB" extension on library files.  You
  8740.        don't have to give the full file spec (ie, disk drive and directory) if
  8741.        the file is in the ASIC directory.  See Chapter 3 and Chapter 5 for more
  8742.        information on setting these options from the integrated environment and
  8743.        command line compiler respectively.
  8744.  
  8745.                                        DEBUGGING
  8746.  
  8747.             You can use the debugger on ASIC programs which use the CALL SUB
  8748.        statement, however, you can't "trace into" the assembly language
  8749.        subroutine instructions.  When you press <F8> to trace one line, and you
  8750.        are positioned on a CALL SUB statement, the CALL SUB is executed, and
  8751.        ASIC advances to the next ASIC statement following the CALL SUB.  The
  8752.        called assembler subroutine should not contain INT 3 instructions.  If
  8753.        they do, the debugger will behave erratically.
  8754.  
  8755.  
  8756.  
  8757.  
  8758.  
  8759.  
  8760.  
  8761.  
  8762.  
  8763.  
  8764.  
  8765.  
  8766.                                       Page - 136
  8767.  
  8768.  
  8769.  
  8770.  
  8771.  
  8772.  
  8773.                                         A S I C
  8774.  
  8775.                                       Chapter 11
  8776.  
  8777.                                     Error Messages
  8778.  
  8779.  
  8780.        This chapter contains compiler messages, run-time error messages, and
  8781.        File I/O Error Codes.
  8782.  
  8783.  
  8784.  
  8785.                                     COMPILER ERRORS
  8786.  
  8787.  
  8788.  
  8789.             These messages indicate errors in your source program.  Those which
  8790.        begin with "** E" indicate "fatal" errors, which prevent ASIC from
  8791.        successfully compiling your program.  Warnings begin with "* W" and
  8792.        indicate possible errors and informative messages which will not prevent
  8793.        ASIC from generating an executable ".COM" or ".EXE" file.
  8794.  
  8795.  
  8796.                                      FATAL ERRORS
  8797.  
  8798.        ** E001 **  File Extensions must be '.ASI', '.PRJ' or omitted
  8799.  
  8800.             ASIC requires source programs to have the extension ".ASI".  Rename
  8801.        your source file with the DOS "RENAME" command to the name "file.ASI",
  8802.        where "file" is your source program name.  Then resubmit the compile.
  8803.        The ".ASI" extension is the only valid one for the ASIC Editor, but the
  8804.        command line compiler will also accept a ".PRJ" extension.
  8805.  
  8806.        ** E002 ** File Name specified is too long
  8807.  
  8808.             The source file may be identified by a file name up to 124
  8809.        characters long including disk drive specifiers and sub directory names.
  8810.        Move the source program to a directory which may be specified within
  8811.        this length.
  8812.  
  8813.  
  8814.        ** E003 ** Error Opening File:  xxxxxxxx.xxx
  8815.  
  8816.             The file indicated by "xxxxxxxx.xxx" could not be opened by ASIC.
  8817.        This error can be issued when ASIC attempts to read your source file, or
  8818.        when it writes any one of the possible output files (".COM", ".EXE",
  8819.        ".LST", or ".SYM").  If indicated file is your source program name,
  8820.        verify the spelling, and either make sure it is in the same directory as
  8821.        ASIC, or specify the full path name for the file.  If the indicated file
  8822.        is an output file, the error is usually a result of a write protect tab
  8823.        on the diskette or insufficient disk space.
  8824.  
  8825.  
  8826.  
  8827.  
  8828.  
  8829.  
  8830.                                       Page - 137
  8831.  
  8832.  
  8833.  
  8834.  
  8835.  
  8836.        ** E004 ** DIM Statements must precede all others except REMs
  8837.  
  8838.             In ASIC, DIM statements must appear before all other statement
  8839.        types, except REM statements (or blank lines).
  8840.  
  8841.  
  8842.        ** E005 ** Too many characters in source line
  8843.  
  8844.             Source program lines in ASIC are limited to 120 characters.  Change
  8845.        the indicated source line, so that it fits within this limit.
  8846.  
  8847.  
  8848.        ** E006 ** Unmatched Quote ('"') in source line
  8849.  
  8850.             A string constant was found with either no opening or closing quote
  8851.        mark.  Quotation marks must be matched in pairs within source lines.
  8852.  
  8853.  
  8854.        ** E007 ** Token in source line > 82 characters long
  8855.  
  8856.             Individual tokens in ASIC are limited to 82 characters in length,
  8857.        regardless of type.  A token is a group of letters and/or numbers
  8858.        delimited on either side by a space or math symbol.  Example, even
  8859.        though string constants are limited to 80 characters, ASIC considers the
  8860.        "token" to include the quotation marks.  In this case, however, ASIC
  8861.        detected a token longer than the longest possible token, the string
  8862.        constant.  Check for "tokens" or "words" more than 82 characters long in
  8863.        the indicated source line.
  8864.  
  8865.  
  8866.        ** E008 ** More than 30 tokens in source line
  8867.  
  8868.             Since all ASIC statements require less than 30 tokens, ASIC will
  8869.        flag any statement which contains more than this number.  A token is a
  8870.        group of letters and/or numbers delimited on either side by a space or
  8871.        math symbol.
  8872.  
  8873.  
  8874.        ** E009 ** Keyword Unknown:  xxxxxxxxx
  8875.  
  8876.             ASIC detected the symbol indicated by "xxxxxxxx" in your source
  8877.        line, but it was not a valid variable name, constant, label, or ASIC
  8878.        Function Name.
  8879.  
  8880.  
  8881.        ** E010 ** Symbol Table Space Exhausted
  8882.  
  8883.             The symbol table is used by ASIC to keep track of your variables,
  8884.        constants and labels.  It is also used to hold information used in
  8885.        FOR/NEXT processing, and internal system subroutine generation.  Reduce
  8886.        the number of LABELS, VARIABLE NAMES, or CONSTANTS in your program, and
  8887.        recompile.
  8888.  
  8889.  
  8890.  
  8891.  
  8892.  
  8893.  
  8894.                                       Page - 138
  8895.  
  8896.  
  8897.  
  8898.  
  8899.  
  8900.        ** E011 ** Symbol Incomplete Reference Space Exhausted
  8901.  
  8902.             This table is a sister table to the Symbol Table, it contains
  8903.        references to LABEL type symbols which have been defined in the symbol
  8904.        table.  Try to reduce the number of references made to LABEL symbols
  8905.        within the program and recompile.
  8906.  
  8907.  
  8908.        ** E012 ** No keywords in source line
  8909.  
  8910.             Every ASIC source program line must contain an ASIC keyword (eg.
  8911.        "PRINT", "=", "GOSUB", etc).
  8912.  
  8913.  
  8914.        ** E013 ** Syntax Error
  8915.  
  8916.             The "catch-all" error for ASIC.  This error is usually issued when
  8917.        ASIC has identified an error in the parameters for an ASIC keyword.  The
  8918.        best way to find this error is to refer to the entry in the Keyword
  8919.        Reference (chapter 7) for that particular keyword.
  8920.  
  8921.  
  8922.        ** E014 ** Undefined Symbol:  xxxxxx
  8923.  
  8924.             ASIC detected a LABEL "xxxxxx" which was referenced, but never
  8925.        defined in the program.  A label is considered to be defined when it is
  8926.        the first token on the source line.  A reference to a label occurs when
  8927.        a label name appears elsewhere in the source statement
  8928.  
  8929.             Example:           PRINTIT:   PRINT "hello"      <---Defined
  8930.                                GOTO PRINTIT:                 <--Referenced
  8931.  
  8932.  
  8933.        ** E015 ** Compiled Code Exceeds 64k-Can't fit in .COM file
  8934.  
  8935.             Your source program is too large to fit in the .COM file format.
  8936.        Recompile using the "Build EXE" option.  See Chapter 5 for more
  8937.        information.
  8938.  
  8939.        ** E016 ** Integer Constant Not in range +32767 to -32767
  8940.  
  8941.             The above range of numbers is the maximum which can be contained in
  8942.        integer format in ASIC.  Reduce the constant so that it falls within the
  8943.        specified range.
  8944.  
  8945.  
  8946.        ** E017 ** Duplicate Label:    xxxxxx
  8947.  
  8948.             The indicated label "xxxxxx" was defined more than once in the
  8949.        program.  Reduce the multiple definitions to a single definition and
  8950.        then recompile.
  8951.  
  8952.  
  8953.  
  8954.  
  8955.  
  8956.  
  8957.  
  8958.                                       Page - 139
  8959.  
  8960.  
  8961.  
  8962.  
  8963.  
  8964.        ** E018 ** Second FOR defined for variable with no intervening NEXT
  8965.  
  8966.             FOR/NEXT Statements cannot be nested with the same variable name.
  8967.  
  8968.                  VALID                              INVALID
  8969.  
  8970.                  FOR I=1 TO 10                      FOR I=1 TO 10
  8971.                       FOR J=1 TO 20                      FOR I=1 TO 20
  8972.                       NEXT J                             NEXT I
  8973.                  NEXT I                             NEXT I
  8974.  
  8975.  
  8976.        ** E019 ** For/Next Table Space Exhausted
  8977.  
  8978.             An unlimited of FOR/NEXT statements can exist, however, they can be
  8979.        "nested" to a maximum depth of 25.
  8980.  
  8981.  
  8982.        ** E020 ** NEXT without FOR
  8983.  
  8984.             A NEXT statement was found, however it was not preceded in the
  8985.        source program with a matching FOR statement.
  8986.  
  8987.  
  8988.        ** E021 ** FOR without NEXT at Source Line NNNNN
  8989.  
  8990.             The indicated source line NNNNN contains a FOR statement, for which
  8991.        no NEXT statement was ever found.
  8992.  
  8993.  
  8994.        ** E022 ** Invalid Option:  x
  8995.  
  8996.             An invalid compile option was specified.  Review Chapter 5 for a
  8997.        list of valid compile options.
  8998.  
  8999.  
  9000.        ** E023 ** More than 63000 bytes in Data Segment
  9001.  
  9002.             An ASIC program can be up to 64k bytes in size.  Of this total,
  9003.        63000 bytes can contain program variables and constants, leaving at
  9004.        least 1k for program code.  Reduce the number of variables and constants
  9005.        in your program.
  9006.  
  9007.  
  9008.        ** E024 ** Too many arrays defined
  9009.  
  9010.             A single ASIC source program can contain up to 25 arrays.
  9011.  
  9012.  
  9013.        ** E025 ** Re-DIMension of previously DIMensioned variable
  9014.  
  9015.             Only one DIM statement can be specified per array name.
  9016.  
  9017.  
  9018.  
  9019.  
  9020.  
  9021.  
  9022.                                       Page - 140
  9023.  
  9024.  
  9025.  
  9026.  
  9027.  
  9028.        ** E026 ** Invalid subscript on Array
  9029.  
  9030.             A subscript was found which is not valid.  Either ASIC expected
  9031.        more or less subscripts than were present, or ASIC detected a subscript
  9032.        which was itself an array.  Subscripts on arrays may only be non-array
  9033.        variables and/or integer constants.
  9034.  
  9035.  
  9036.        ** E030 ** Code Segment Memory Exhausted
  9037.  
  9038.             ASIC will attempt to allocate 64k of memory to use a work space to
  9039.        hold the code generated by your program statements.  This message
  9040.        indicates that the amount of memory it was able to allocate was not
  9041.        sufficient to hold the code generated by the program you are trying to
  9042.        compile.
  9043.  
  9044.  
  9045.        ** E031 ** Data Segment Memory Exhausted
  9046.  
  9047.             ASIC will attempt to allocate 64k of memory to use a work space to
  9048.        hold the data segment for your program.  This message indicates that the
  9049.        amount of memory it was able to allocate was not sufficient to hold the
  9050.        data generated by the program you are trying to compile.
  9051.  
  9052.  
  9053.        ** E032 ** Insufficient Memory to Run ASIC
  9054.  
  9055.             You don't have enough memory to run ASIC.  If you have any TSRs
  9056.        loaded, try removing them and re-compiling.
  9057.  
  9058.  
  9059.        ** E033 ** Edit Buffer Memory Allocation Failed
  9060.  
  9061.             ASIC attempted to allocate memory for the edit buffer in the
  9062.        integrated environment, but was unable to.  If you have any TSRs loaded,
  9063.        remove them from memory, and try again.
  9064.  
  9065.  
  9066.  
  9067.  
  9068.  
  9069.  
  9070.  
  9071.  
  9072.  
  9073.  
  9074.  
  9075.  
  9076.  
  9077.  
  9078.  
  9079.  
  9080.  
  9081.  
  9082.  
  9083.  
  9084.  
  9085.  
  9086.                                       Page - 141
  9087.  
  9088.  
  9089.  
  9090.  
  9091.  
  9092.        ** E034 ** DATA Statements Must Precede All Except DIMs or REMs
  9093.  
  9094.             If you wish to use the DATA statement in ASIC, you must place them
  9095.        all at the beginning of your program following any DIM and/or REM
  9096.        statements (or blank lines).
  9097.  
  9098.  
  9099.        ** E035 ** Requires 32 Bit Math--Recompile W/Math Option
  9100.  
  9101.             The compiler found a statement containing long (32bit) integer
  9102.        variables or constants.  You must compile with the Extended Math Option
  9103.        turned on to be able to use long integer math.  Turn on the "Extended
  9104.        Math" Option from the Compile Menu in the ASIC Integrated Environment,
  9105.        and recompile the program.  If you are compiling from the MS DOS command
  9106.        line, recompile using switch "E".
  9107.  
  9108.  
  9109.        ** E036 ** Error Allocating Debugger Screen Memory
  9110.  
  9111.             ASIC was unable to allocate memory to save the screen output from
  9112.        your programs when you run your program in debugging mode in the ASIC
  9113.        integrated environment.  You could try removing some TSRs from your
  9114.        AUTOEXEC.BAT file.  Then try running ASIC again.
  9115.  
  9116.  
  9117.        ** E037 ** IF Statements Nested Deeper Than 25 Levels
  9118.  
  9119.             An unlimited number of block IF statements may be used in your
  9120.        program, however, they may be nested to a maximum depth of 25 levels.
  9121.        See the IF statement documentation in Chapter 7 for more information.
  9122.  
  9123.  
  9124.        ** E038 ** ELSE Statement Without Preceding IF Statement.
  9125.  
  9126.             ASIC found an ELSE statement but did not find a preceding block IF
  9127.        statement.  See the IF Statement documentation in Chapter 7 for more
  9128.        information.
  9129.  
  9130.  
  9131.        ** E039 ** ENDIF Statement Without Preceding IF Statement.
  9132.  
  9133.             ASIC found an ENDIF statement with no preceding matching IF
  9134.        statement.  See the IF statement documentation in Chapter 7 for more
  9135.        information.
  9136.  
  9137.  
  9138.        ** E040 ** Block IF Statement Without Matching ENDIF Statement.
  9139.  
  9140.             When using the block IF format of the IF statement, you must always
  9141.        specify a matching ENDIF statement.  See the IF Statement documentation
  9142.        in Chapter 7 for more information.
  9143.  
  9144.  
  9145.  
  9146.  
  9147.  
  9148.  
  9149.  
  9150.                                       Page - 142
  9151.  
  9152.  
  9153.  
  9154.  
  9155.  
  9156.        ** E041 ** WHILE Statements Nested Deeper Than 25 Levels
  9157.  
  9158.             An unlimited number of WHILE statements may be used in your
  9159.        program, however, they may be nested to a maximum depth of 25 levels.
  9160.        See the WHILE statement in Chapter 7 for more information.
  9161.  
  9162.  
  9163.        ** E042 ** WEND Statement Without Preceding WHILE Statement
  9164.  
  9165.             ASIC found a WEND statement with no preceding matching WHILE
  9166.        statement.  See the WHILE statement documentation in Chapter 7 for more
  9167.        information.
  9168.  
  9169.  
  9170.        ** E043 ** WHILE Statement Without Matching WEND Statement
  9171.  
  9172.             Each WHILE statement must be followed by a matching WEND statement.
  9173.        See the WHILE statement documentation in Chapter 7 for more information.
  9174.  
  9175.        ** E044 ** This statement format is only valid when producing OBJ files.
  9176.  
  9177.             You used a format of a statement which does not make sense with the
  9178.        current compiler option.  For example, you specified "CALL SUB" when
  9179.        compiling with the B/EXE or B/COM option.  This is invalid, since CALL
  9180.        SUB will generate a reference for the linker to resolve the SUB
  9181.        procedure name.  ASIC will not resolve the SUB reference when using the
  9182.        B/COM or B/EXE option, since no OBJ file is produced with these options.
  9183.        Recompile with the B/OBJ option (select the OBJ option in the integrated
  9184.        environment).
  9185.  
  9186.        ** E047 ** Requires Decimal Math--Recompile w/DEC Option
  9187.  
  9188.             Your program contains a statement containing a decimal variable or
  9189.        constant (eg, A@ or 1.234).  To use decimal numbers, you must turn on
  9190.        the "Decimal Math" option from the "Compile" menu, or, if you are
  9191.        compiling from the command line, by specifying the command line option
  9192.        "DEC".  Turn on this option, and recompile your program.
  9193.  
  9194.        ** E048 ** 999999999999.99999 Is Max Constant Size
  9195.  
  9196.             You specified a decimal constant in your program which exceeds the
  9197.        maximum size that ASIC can handle.  Modify your program until the
  9198.        constant is within +/-999,999,999,999.99999 and recompile your program.
  9199.  
  9200.  
  9201.  
  9202.  
  9203.  
  9204.  
  9205.  
  9206.  
  9207.  
  9208.  
  9209.  
  9210.  
  9211.  
  9212.  
  9213.  
  9214.                                       Page - 143
  9215.  
  9216.  
  9217.  
  9218.  
  9219.  
  9220.                                   NON-FATAL WARNINGS
  9221.  
  9222.  
  9223.        * W002 * Printer Not Ready - 'P' Option Ignored
  9224.  
  9225.             You selected the "Printer" option, but ASIC was not able to access
  9226.        the printer.  Make sure the printer is online before compiling with the
  9227.        'P' option.
  9228.  
  9229.  
  9230.        * W004 * Edit Buffer Full--File Truncated
  9231.  
  9232.             While loading a file, the edit buffer filled before ASIC reached
  9233.        end-of-file.  The file is truncated in memory.  IF YOU SAVE THE FILE
  9234.        AFTER RECEIVING THIS MESSAGE, PART OF THE FILE WILL BE LOST ON DISK.  IT
  9235.        IS RECOMMENDED THAT YOU EITHER EXIT ASIC IMMEDIATELY, OR THAT YOU SAVE
  9236.        THE TRUNCATED FILE UNDER A NEW NAME SO THAT THE ORIGINAL FILE IS NOT
  9237.        DAMAGED.
  9238.  
  9239.  
  9240.        * W005 *  Edit Buffer Full
  9241.  
  9242.             ASIC issues this message when the edit buffer is full and you
  9243.        attempt to insert a line.  Delete some unnecessary source lines to
  9244.        create space in the edit buffer.
  9245.  
  9246.  
  9247.        * W006 * Source/Dest of Block Copy/Move May Not Overlap
  9248.  
  9249.             You attempted to move or copy a block of lines to a destination
  9250.        line which was within the source block of lines.  Execution of this
  9251.        block move/copy would result in an endless series of copies or moves.
  9252.        Move the cursor outside of the highlighted block of lines, and try
  9253.        again.
  9254.  
  9255.  
  9256.        * W007 * Source Program Modified.  Recompile? (Y/N)
  9257.  
  9258.             You selected the RUN or TRACE option of ASIC.  ASIC has noticed
  9259.        that you have modified the source.  You should answer "Y" here to cause
  9260.        ASIC to recompile your program before running it.  If you instead answer
  9261.        "N", ASIC will execute the existing copy of the compiled program, which
  9262.        will not contain your latest changes.
  9263.  
  9264.  
  9265.        * W009 * File has been modified.  Save File Now? (Y/N)
  9266.  
  9267.             You have told ASIC to exit back to DOS, but the edit buffer has
  9268.        been modified.  You should answer "Y" so that ASIC will save your
  9269.        changes back to disk.  If you answer "N" here, any changes you have made
  9270.        to your program since the last SAVE command will be lost.
  9271.  
  9272.  
  9273.  
  9274.  
  9275.  
  9276.  
  9277.  
  9278.                                       Page - 144
  9279.  
  9280.  
  9281.  
  9282.  
  9283.  
  9284.        * W010 * Too Much Debugging Info-Truncating
  9285.  
  9286.             ASIC could not handle all of the debugging information it found.
  9287.        This error should not occur.
  9288.  
  9289.  
  9290.        * W011 * Variable Not Found
  9291.  
  9292.             During the processing of a Watch, Unwatch, or Modify Command, you
  9293.        specified a variable name which ASIC could not find in the debugging
  9294.        information.  Checking your spelling for possible errors.  Also, verify
  9295.        that you have compiled your program with the Debugging compiler option
  9296.        turned ON.
  9297.  
  9298.  
  9299.        * W012 * Maximum Number of Variables Are Being Watched
  9300.  
  9301.             You are already "watching" the maximum number of variables that
  9302.        this version of ASIC supports.  "Unwatch" one of the variables in the
  9303.        watch window.  This will allow you to "Watch" a new one.
  9304.  
  9305.  
  9306.        * W013 * There Are No Variables Being Watched
  9307.  
  9308.             You selected the "Unwatch" command.  However, there are no
  9309.        variables in the watch window to "Unwatch".  Before this command may be
  9310.        used, you must first have added a variable to the Watch window using the
  9311.        "Watch variable" command.
  9312.  
  9313.  
  9314.        * W014 * Unable to Load/Run Program
  9315.  
  9316.             When ASIC attempted to load and run either the compiler or your
  9317.        program it detected an error.  This is due to one of two reasons.
  9318.        First, ASIC could not find the program on disk.  If compiling, make sure
  9319.        that the ASICC.EXE file is in the same directory as the ASIC.EXE file,
  9320.        and make that directory current.  The second reason that you might get
  9321.        this error is that there may be insufficient memory available on your
  9322.        PC.  In this case, you either need to free up more memory (by removing
  9323.        TSRs etc), or you could execute your program or the compiler from the
  9324.        DOS command line.  For more information on compiling from the command
  9325.        line, see Chapter 5--Stand-alone Compiler Options.
  9326.  
  9327.  
  9328.        * W015 * Can't Set Breakpoint--No Code Generated For That Source
  9329.                 Line
  9330.  
  9331.             You attempted to set a breakpoint and either 1) You haven't
  9332.        compiled with the Debugging Compiler Option turned on, or 2)  You have
  9333.        tried to set a breakpoint on a line which did not generate any object
  9334.        code.  Thus, breakpoints cannot be set on REM or DATA statements, for
  9335.        example.  If you are sure that you have compiled with the above option
  9336.        turned on, then try setting the breakpoint on another nearby statement.
  9337.  
  9338.  
  9339.  
  9340.  
  9341.  
  9342.                                       Page - 145
  9343.  
  9344.  
  9345.  
  9346.  
  9347.  
  9348.        * W018 * Your Program Must Be Running To Use This Function
  9349.  
  9350.             You selected a function which is only operable when you are running
  9351.        a program (which was compiled with the debugging compiler option turned
  9352.        on).  After your program terminates, this function is not available.
  9353.  
  9354.  
  9355.        * W019 * Function Unavailable Until You Terminate Your Program
  9356.  
  9357.             You selected a function while your program was running in debugging
  9358.        mode.  Before you can execute this function you must either Abort your
  9359.        program, or allow it to Run until normal termination.  Both the Run and
  9360.        the Abort Options are available on the "Run" Menu.
  9361.  
  9362.  
  9363.        * W020 * Invalid Debug (.DBG) File Format
  9364.  
  9365.             ASIC attempted to access the symbolic debugging information file
  9366.        created by the compiler for your program.  It was able to locate the
  9367.        file, but detected an error in the format while reading it.  Make sure
  9368.        that the version number of both the ASIC Integrated Editor and the ASIC
  9369.        Compiler are the same.  The version number is displayed on the top line
  9370.        of the editor screen, following the word "ASIC".  It is also displayed
  9371.        on the compiler status screen while a compile is executing.
  9372.  
  9373.  
  9374.        * W021 * Maximum Number of Breakpoints Already Set
  9375.  
  9376.             You have attempted to set another breakpoint, but the maximum
  9377.        number that this version of ASIC can support are already in use.  Remove
  9378.        one of the existing breakpoints you have set.  This will free one up for
  9379.        your use elsewhere.
  9380.  
  9381.  
  9382.        * W022 * Can't Open ASIC.IDX File
  9383.  
  9384.             You requested online help for an ASIC keyword.  This function
  9385.        requires a file called "ASIC.IDX" provided with your ASIC package, and
  9386.        ASIC could not find this file in the current disk directory.  Copy this
  9387.        file from your ASIC package to the directory in which you are running
  9388.        ASIC and try again.
  9389.  
  9390.  
  9391.        * W023 * Can't Open ASIC.DOC File
  9392.  
  9393.             You requested online help for an ASIC keyword or menu option.  This
  9394.        function requires a file called "ASIC.DOC" provided with your ASIC
  9395.        package, and ASIC could not find this file in the current disk
  9396.        directory.  Copy this file from your ASIC package to the directory in
  9397.        which you are running ASIC and try again.
  9398.  
  9399.  
  9400.  
  9401.  
  9402.  
  9403.  
  9404.  
  9405.  
  9406.                                       Page - 146
  9407.  
  9408.  
  9409.  
  9410.  
  9411.  
  9412.        * W024 * Can't Open ASICM.IDX File
  9413.  
  9414.             You requested online help for an ASIC menu option.  This function
  9415.        requires a file called "ASICM.IDX" which was provided with your ASIC
  9416.        package, and ASIC could not find this file in the current disk
  9417.        directory.  Copy this file from your ASIC package to the directory in
  9418.        which you are running ASIC and try again.
  9419.  
  9420.  
  9421.        * W025 * No Help Available For Selected Item
  9422.  
  9423.             There is no online help available for the item you selected.  The
  9424.        information should be available in the ASIC Manual.
  9425.  
  9426.  
  9427.        * W026 * Unable To Write ASIC.CFG File
  9428.  
  9429.             You told ASIC to save your current Integrated Environment Options.
  9430.        ASIC attempted to do so, but was not able to.  Your options were not
  9431.        saved to disk.  This is usually caused by one of two things: 1)  The
  9432.        disk is full, or 2)  The disk is write-protected.  If the disk is full,
  9433.        delete some unneeded files and try again.  If the disk is write-
  9434.        protected, remove the write-protect tab from the disk and try again.
  9435.  
  9436.  
  9437.        * W027 * Debugger Can't Fully Save User Screen--Insufficient Memory
  9438.  
  9439.             ASIC was not able to allocate enough memory to save the screen
  9440.        output from your program while it was running in debugging mode in the
  9441.        integrated environment.  As a result, the screen displays may become
  9442.        garbled.  You should normally only see this message when your program is
  9443.        using a high resolution EGA/VGA graphic mode on machines with very low
  9444.        memory, or you have many TSRs installed.  Either purchase more memory,
  9445.        go to a lesser graphics mode, remove some TSRs from the AUTOEXEC.BAT
  9446.        file, or run your program outside of the integrated environment.
  9447.  
  9448.        * W028 * Not Enough Memory To Build Full File List
  9449.  
  9450.             After you selected the Open or Save options from the File menu,
  9451.        ASIC attempted to build a list of existing file names in memory, but was
  9452.        unable to due to lack of memory.  Exit from the editor and try to free
  9453.        up more memory by removing TSR's, etc.
  9454.  
  9455.        * W029 * Out of Memory -- Allocating Debug Symbols
  9456.  
  9457.             The editor was trying to read the debugging information for your
  9458.        program, but was unable to allocate enough memory to store the
  9459.        information.  If you proceed, the Watch, Unwatch, Modify Variable,
  9460.        Trace, and Breakpoint commands may perform erratically.  Exit the editor
  9461.        and try to free up more memory by removing TSR's, etc.
  9462.  
  9463.        * W030 * Stack Size Must Be 16-32767
  9464.  
  9465.             You selected the Stack Option off of the Advanced Options Menu, and
  9466.        entered a stack size that is too small or too large.  Your entry was
  9467.        ignored--the stack size was not updated.
  9468.  
  9469.  
  9470.                                       Page - 147
  9471.  
  9472.  
  9473.  
  9474.  
  9475.  
  9476.  
  9477.        * W031 * Unable To Save Program Options
  9478.  
  9479.             ASIC attempted to save program compile options to disk, but was not
  9480.        able to.  This is usually caused by a disk that is full or has the write
  9481.        protect tab set.
  9482.  
  9483.        * W032 * Unable to run COMMAND.COM
  9484.  
  9485.             ASIC was unable to locate the COMMAND.COM file.  Because of this,
  9486.        it was unable to complete your request.
  9487.  
  9488.  
  9489.  
  9490.  
  9491.  
  9492.  
  9493.  
  9494.  
  9495.  
  9496.  
  9497.  
  9498.  
  9499.  
  9500.  
  9501.  
  9502.  
  9503.  
  9504.  
  9505.  
  9506.  
  9507.  
  9508.  
  9509.  
  9510.  
  9511.  
  9512.  
  9513.  
  9514.  
  9515.  
  9516.  
  9517.  
  9518.  
  9519.  
  9520.  
  9521.  
  9522.  
  9523.  
  9524.  
  9525.  
  9526.  
  9527.  
  9528.  
  9529.  
  9530.  
  9531.  
  9532.  
  9533.  
  9534.                                       Page - 148
  9535.  
  9536.  
  9537.  
  9538.  
  9539.  
  9540.                                     RUN TIME ERRORS
  9541.  
  9542.  
  9543.        Divide Overflow
  9544.  
  9545.  
  9546.             This message indicates that your program attempted to divide by
  9547.        zero.
  9548.  
  9549.  
  9550.  
  9551.  
  9552.  
  9553.  
  9554.  
  9555.  
  9556.  
  9557.  
  9558.  
  9559.  
  9560.  
  9561.  
  9562.  
  9563.  
  9564.  
  9565.  
  9566.  
  9567.  
  9568.  
  9569.  
  9570.  
  9571.  
  9572.  
  9573.  
  9574.  
  9575.  
  9576.  
  9577.  
  9578.  
  9579.  
  9580.  
  9581.  
  9582.  
  9583.  
  9584.  
  9585.  
  9586.  
  9587.  
  9588.  
  9589.  
  9590.  
  9591.  
  9592.  
  9593.  
  9594.  
  9595.  
  9596.  
  9597.  
  9598.                                       Page - 149
  9599.  
  9600.  
  9601.  
  9602.  
  9603.  
  9604.  
  9605.  
  9606.  
  9607.                                SYSTEM ERROR CODE VALUES
  9608.  
  9609.  
  9610.        After most commands which access the disk, ASIC sets a special "ERROR"
  9611.        variable to indicate success or failure of that command.  After you
  9612.        execute one of these commands, you can reference this variable as a
  9613.        regular variable in your program, to determine the outcome of the
  9614.        command(eg. "IF ERROR = 000 THEN OKAY:").
  9615.  
  9616.  
  9617.        ERROR Codes Set by BLOAD
  9618.  
  9619.        000       No Error
  9620.        002       File Not Found
  9621.        003       Path Not Found or File Doesn't Exist
  9622.        004       File Not Found
  9623.        005       File Access Denied
  9624.        006-255   Read Past End of File
  9625.  
  9626.        ERROR Codes Set by BSAVE
  9627.  
  9628.        000       No Error
  9629.        002       File Not Found
  9630.        004       File Not Found
  9631.        005       File Access Denied
  9632.        006-255   Disk Full
  9633.  
  9634.        ERROR Codes Set by CALL
  9635.  
  9636.        000-254   Return Code from Program (Zero If Not Set by User Program)
  9637.        255       Error Loading/Running Program
  9638.  
  9639.        ERROR Codes Set by CHDIR
  9640.  
  9641.        000       No Error
  9642.        003       Path Not Found
  9643.  
  9644.        ERROR Codes Set by CLOSE
  9645.  
  9646.        000       No Error
  9647.        006       Invalid Handle
  9648.        095       Cannot Close File -- File is not Open
  9649.  
  9650.        ERROR Codes Set by FILEPOS
  9651.  
  9652.        000       No Error
  9653.        001       Invalid Function Number
  9654.        006       Invalid Handle
  9655.        098       File mode not Random or Append
  9656.  
  9657.  
  9658.  
  9659.  
  9660.  
  9661.  
  9662.                                       Page - 150
  9663.  
  9664.  
  9665.  
  9666.  
  9667.  
  9668.                          SYSTEM ERROR CODE VALUES (Continued)
  9669.  
  9670.  
  9671.        ERROR Codes Set by FIND
  9672.  
  9673.        000       No Error
  9674.        002       File Not Found
  9675.        018       No More Files Match Search Criteria
  9676.  
  9677.        ERROR Codes Set by GETDIR
  9678.  
  9679.        000       No Error
  9680.        015       Invalid Disk Drive Specification
  9681.  
  9682.        ERROR Codes Set by INPUT (when using ";" option)
  9683.  
  9684.        000       No Error
  9685.        001       Invalid Input
  9686.  
  9687.        ERROR Codes Set by INPUT#
  9688.  
  9689.        000       No Error
  9690.        005       Read Access Denied
  9691.        006       Invalid File Handle
  9692.        096       Input String Truncated at 80 characters
  9693.                  (this error code is not set when you specify NONULL)
  9694.        098       File Not Open for Input or Random Modes
  9695.        099       End of File
  9696.  
  9697.        ERROR Codes Set by KILL
  9698.  
  9699.        000       No Error
  9700.        002       File Not Found
  9701.        005       Access Denied
  9702.  
  9703.        ERROR Codes Set by MKDIR
  9704.  
  9705.        000       No Error
  9706.        003       Path Not Found
  9707.        005       Access Denied
  9708.  
  9709.        ERROR Codes Set by NAME
  9710.  
  9711.        000       No Error
  9712.        002       File Not Found
  9713.        003       Path Not Found or File Doesn't Exist
  9714.        005       Access Denied
  9715.        017       Not Same Disk Drive
  9716.  
  9717.        ERROR Codes Set by OPEN --- Mode Input
  9718.  
  9719.        000       No Error
  9720.        002       File Not Found
  9721.        004       File Not Found
  9722.        005       File Access Denied
  9723.        254       File Number Already in Use
  9724.  
  9725.  
  9726.                                       Page - 151
  9727.  
  9728.  
  9729.  
  9730.  
  9731.  
  9732.                          SYSTEM ERROR CODE VALUES (Continued)
  9733.  
  9734.  
  9735.        ERROR Codes Set by OPEN --- Mode Output, Append, or Random
  9736.  
  9737.        000       No Error
  9738.        001       Invalid Append Function
  9739.        003       Path Not Found
  9740.        004       No File Handle Available
  9741.        005       File Access Denied
  9742.        006       Invalid Append Handle
  9743.        254       File Number Already in Use
  9744.  
  9745.        ERROR Codes Set by PRINT#
  9746.  
  9747.        000       No Error
  9748.        005       File Access Denied
  9749.        006       Invalid File Handle
  9750.        097       File Not Open for Output, Append, or Random Modes
  9751.        255       Disk Full
  9752.  
  9753.        ERROR Codes Set by RMDIR
  9754.  
  9755.        000       No Error
  9756.        003       Path Not Found
  9757.        005       Access Denied
  9758.        006       Can't Delete Current Directory
  9759.        016       Can't Delete Current Directory
  9760.  
  9761.        ERROR Codes Set by RUN
  9762.  
  9763.        000-254   Return Code from Program (Zero If Not Set by User Program)
  9764.        255       Error Loading/Running Program
  9765.  
  9766.        ERROR Codes Set by DECIMAL Math Routines
  9767.  
  9768.        000       No Error
  9769.        001       Division By Zero
  9770.  
  9771.  
  9772.  
  9773.  
  9774.  
  9775.  
  9776.  
  9777.  
  9778.  
  9779.  
  9780.  
  9781.  
  9782.  
  9783.  
  9784.  
  9785.  
  9786.  
  9787.  
  9788.  
  9789.  
  9790.                                       Page - 152
  9791.