LnSOS BOOT 1.1 SOS.KERNEL SOS KRNLI/O ERRORFILE 'SOS.KERNEL' NOT FOUND%INVALID KERNEL FILE: xةw,@  ȱlmi8#)!) B A S I C G T O - version 1.98 Program Accelerator & Partial Compiler For ApplePSERIALNO.0239 $0, +USER.MANUALvF FLASHNAME.DATJ (HELLO !1HELLO.TEXT!1III.DAD.081951Bu' -ADDENDUM.1.98+ DISKNAME.DAT11&LEGACY J J *MENU.MAKER Z1 'READ.ME $ -READ.ME.FIRST >dLԡm#i㰼m#iЕOLԡȱfg hi !dLԡ憦  Ljmkm l y`2 Lԡ8(Je稽)ʈ@L /// Business Basic USER GUIDE D A DataSystems - 1984   !"#$%&'()*+,-./0123456789:;<=>?@ABCDEFGHIJKLMNOPQRSTUVWXYZ[\]^_`abcdefghijklmnopqrstuvwxyz{|}~ 22 Program Limitations 22 Syntax Checking 24 Error Handling 25 Appendix A - Program Chainin Running the Level Two Compiled Pgm 20 Compilation SUMMARY 21 Chapter 5 - Caveats 22 System Requirements One Level or Two Level Compile 13 Level One Compile - GTO.1 14 Running the Level One Compiled Pgm 15 Level Two Compile - GTO.2 18 lers vs Interpreters 7 BASIC GTO - A Partial Compiler 8 Chapter 3 - Distribution Disk Contents 11 Chapter 4 - Compiling a Program 13 2 License 4 Chapter 2 - Introduction & Overview 5 Compilers & Interpreters 5 Compi D A DataSystems TABLE OF CONTENTS Chapter 1 - Upfront 2 Getting Started Rochester, NY 14619 716-328-3661 Basic GTO LL MAKE EVERY REASONABLE EFFORT to assist you with any problems or questions that may arise. D A DataSystems 229 Ravenwood Ave oftware may be made for use on a SINGLE COMPUTER ONLY. Multiple system usage must be applied for. Although every effort has been made to ascertain correct performance of BASIC GTO, we cannot guarantee that it is bug free. WE WIment. ... thanks. The BASIC GTO software supplied to you is Copyrighted 1984 by D A Datasystems. BASIC GTO is provided in an FULLY COPYABLE format to the PURCHASER ONLY. Unlimited copies of the sgramming technique known as the Subroutine (wherein the program goes and does something then comes back to where it left off), we heretofore and whomsoever request that you please go now and read the last page of this docu read it, makes Faust's arrangement with the devil sound positively cozy. Well our learned counsel plans to contact Mr. Faust soon, but in the meantime he suggests that we toe the line. Borrowing from a pro We have a pet peeve with software documentation that welcomes you with an intimidating and litiginous statement which, if you do try to g 27 Appendix B - Technical Notes 30 INDEX 35 Detailed Contents 37 Basic GTO D A DataSystems e distribution disk now. 1.1.4.3 Program Enhancements We will make every reasonable effort to assist you with problems or questions; and to make available enhanced or upgraded versions of the pro particular program or application that you want compiled but are uncomfortable working directly with the compiler feel free to contact us for contract rates. Otherwise, go ahead and make one or two backup copies of th2 If you are unhappy If you are unhappy with the licensing restrictions or uncomfortable with the slope of the technical learning curve feel free to return the package within 10 days for a full refund. If you have a .4 Your Benefits 1.1.4.1 Greatly improved program speed Over the long run the time you put in UP FRONT, here will be more than compensated for by program performance improvements. 1.1.4.written the entire program. Consider running parallel systems for one or two months. Don't let your small investment in BASIC GTO cause you to forget your large investment in your existing programs and data. 1.1so HOW IT WORKS will go a long way to bypassing problems or confusion. 1.1.3.2 Testing TEST EVERY COMPILED VERSION of every program against BACKED UP real data EXTENSIVELY. TEST as if you had re- Basic GTO D A DataSystems of the product leaves room for unigue problems, bugs, or simple misunderstandings. Your familiarity with not simply HOW TO WORK IT, but aldgeable use Although we have made every effort to clearly document its features and limitations and to test and debug it technically, the unigueness -2- is not a word processor you've got here ?! BASIC GTO is a fairly complex, one-of-a-kind technical tool which requires intelligent and careful use. 1.1.3 Your responsibilities 1.1.3.1 Knowleons therein. 1.1.2 Please Read Please read the ENTIRE MANUAL before using the BASIC GTO software. Don't let the sometimes chatty nature of the background material lead you into skimming. This 1.1 GETTING STARTED 1.1.1 Software License Please read the section entitled "LICENSE" first and be certain you understand and are comfortable with the restrictiction of Apple /// Business Basic and machine-language programs which will translate other Business Basic programs into a form which executes 10% to 900% faster. Typical performance improvements liew in the 25%-75% range. Basic GTO D A DataSystems Chapter 1 Upfront BASIC GTO is a colle -1- grams. -3- Basic GTO D A DataSystems 1.2 LICENSE 1.2.1 Single CPU License Your copy of BASIC GTO is sold for use on a single Apple /// system only. We supply it in a fully copyable format for your convenience and security in making multiple bac Basic GTO D A DataSystems Apple /// Business Basic is an "interpreted" language. When you boot Basic you load a program named SOS.INTactually specifies the sequence of low level actions necessary to cause the computer & operating system program to actually print HELLO. 2.1.1.3 Apple /// Business Basic -5- which are collectively labelled MACHINE LANGUAGE. Typically the interpreted instructions arestated in a more 'human readable' forms or a programming language such as 'PRINT "HELLO"' while the raw interpreter machine language ng the interpreter to perform certain actions. Ultimately the computer/cpu can only perform a limited set of simple operations using a limited number of starage areas or registers (three on the Apple /// cpu) ontents of the datafile, the series of actions specified by the data will be carried out by the interpreter. 2.1.1.2 Machine Language & Human Language The contents of the program/datafile are simply a means of directi The special function of an INTERPRETER is to accept rigididly structured input datafiles that the rest of us call "programs". As long as the datafile/program is properly formatted and depending upon the unigue crograms, accepts input data from the keyboard or a datafile and, depending upon the nature of that input, performs a variety of different processing functions. 2.1.1.1 The Special Function of an Interpreter Introduction & Overview 2.1 COMPILERS & INTERPRETERS 2.1.1 INTERPRETERS An interpreter is a program written in executable machine language that, like many other p -4- Basic GTO D A DataSystems Chapter 2 We offer very generous licensing arrangements for GTO.RUNTIME including "per copy" and "unlimited copying" pricing. Please contact us for details. ME. If you wish to compile a program for later sale you will need to include GTO.RUNTIME on the diskette you sell and you will need to license that inclusion from us. 1.2.4 Licensing Arrangements 1.2.3 Commercial Use We reserve ownership of GTO.RUNTIME and reserve the right to license it to you for commercial use. Your purchase of BASIC GTO DOES NOT entitle you to sell our software, specifically GTO.RUNTIe the presence of the "runtime program" named GTO.RUNTIME in order to function. Your purchase of BASIC GTO entitles you to unlimited copying of this runtime program ONLY onto your own in-house applications disks. kup copies. We offer very generous multiple-use or unlimited copying licenses for those of you with a number of Apple ///'s in house. 1.2.2 Runtime Program Programs compiled by BASIC GTO requirERP which immediately begins running. At this initial point the interpreter looks for a datafile/program named HELLO and if found proceeds to read it as a series of instructions. If HELLO is not found the built-in editor portion of the interpreter loops around waiting for keyboard/data input matching to another series of acceptable instructions such as LOAD or RUN. 2.1.2 COMPILERS A compiler is a program Once, finally, you've got the monster debugged and running all those variables and locations are fixable somewhere in memory "jump to 12349" and "load from 22456 then store into 21007" are perfectly fine and are through internal tables of 'variables' for "B" then gets the value then searches for "A" then stores the value there. 2.2.0.4 The Feature of Compilers The feature of a compiled program is SPEED.able keywords then find the location of the GOTO routine or PRINT routine, then execute it. This allows for the occasional GOGO or PRJNT. Each time a stored piece of information is needed, as in A=B, the interpreter searches The problem with an interpreted program is that its ultimate execution of the desired operations is SLOW. Each time it encounters any KEYWORD such as GOTO 100 or PRINT ..., it must check it in its table of acceptis not stored as 'absolute location 12945' but just as 100. Ths interpreter can scan memory to find that "100" then move everything around to accomodate your new line 99. 2.2.0.3 The Problem with Interpreters The feature of an interpreter is that it is "interactive". Since it is keeping track of where the data/program is in memory, it is a straightforward matter to move everything around to accomodate changes. Line 100 uage instruction which means, for example, "Jump to location 12945" will not function properly since adding 2 or 3 or 100 bytes now put that desired location somewhere else. 2.2.0.2 The Feature of Interpreters a directly executable program, then execute that program. Then find a bug...re-edit the source...re-compile...re-test...ad nauseum. The re-compile is necessary since any minor change to the source mean that a machine lang 2.2 COMPILERS vs INTERPRETERS 2.2.0.1 The Problem with Compilers The problem with a compiler is that typically you have to create your 'source' program with an editor, then run the compiler to produce -6- Basic GTO D A DataSystems ram is usually structured in humanly readable form much like or exactly like the programs that the interpreter 'interprets'. The latter, "object" code is usually raw machine language. tly executable machine language instructions. 2.1.2.2 Compiler Input & Output Thus both the input and output of a compiler are different forms of 'programs'. The former, usually termed the "source" progspecial function of a COMPILER is to accept rigidly structured input datafiles, which we call programs, and, based upon the contents of the input datafile/program, to produce an output datafile which contains direc that, like many other programs, accepts as input a datafile, performs certain actions based upon the contents of the input data, AND produces an output datafile. 2.1.2.1 The Special Function of Compilers The translated to directly executable machine language. -7- Basic GTO D A DataSystems 2.3 BASIC GTO - A Partial Compiler 2.3.1 WHAT BASIC GTO DOES BASIC GTO is a partial compiler for Apple /// Business Basic. It retains many of the featured of the Interpreted environment while offerin functions. A part of the GTO.RUNTIME program, which must be loaded and run at the beginning of the compiled program, intercepts the Basic variable reference routine and bypasses the variable table d for that variable. The section of reserved memory is set aside by DIMensioning an array named gto.tables%() at the beginning of the compiled program. This prevents Basic from using that space for later in the source program into different NAMES in the object program that it produces. The new variable names are set up so that the name itself is a coded form of a memory address that is reserve memory and always found there. This scanning and assignment is essentially the function performed by GTO.1 2.3.3.3 GTO.1 translation GTO.1 translates or compiles all the variable NAMES and running there's no need for this anticipation of new variables. All variables used by the program could be found by scanning it and each type has a fixed length. So each could conceivably be assigned a set location in a number of variables and access them regularly so this table searching adds a significant amount to processing 'overhead'. 2.3.3.2 Fixing variable references But once you've got your program writtenble in the Basic program it searches through this table for a match on the variable name then sets a special location in memory to point to the actual value part of the entry to be used for later processing. Most programs maintainhe appropriate new entry inserted. This approach manages the anticipated growth and change of the program being developed in the interpreter environment. EACH AND EVERY TIME the interpreter encounters a varial tables for storing data associated with variables. With each variable's data it keeps its name and type (e.g. Integer, Real, Long Integer, or String). Each time a new variable is encountered this table is enlarged and t -8- Basic GTO D A DataSystems 2.3.3 GTO Variable Reference Compilation 2.3.3.1 Interpreted Basic Variable Tables Interpreted Basic maintains interna will execute much faster with the help of the runtime machine language program named GTO.RUNTIME. se are the variable references (e.g. A=B*C) and the control transfer (GOTO and GOSUB) commands. BASIC GTO consists of two programs, aptly named GTO.1 and GTO.2 which translate these two command forms into formats whichge the enhanced functions. 2.3.2 HOW IT WORKS BASIC GTO targets two of the slowest interpreter functions, two that involve frequent searches of large internal tables for values or locations. Theg faster program execution by selectively compiling particularly inefficient pieces of the interpreted program. The interpreter is modified and augmented by a "runtime" package of machine language routines that mana search, performing instead its own Fast Variable Access (FVA) function of scanning the translated variable name and directly -9- Basic GTO D A DataSystems calculating its encoded location. This location is then returned to the Basic interpreter and Basic resumes doing whatever it would ha -12- Basic GTO D A DataSystems program typically prevents LISTing it to -11- Basic GTO D A DataSystems a printer or the screen. ransfers control from the inerpreter to the specified machine language routine. 2.3.4.4 A side effect A side effect of this later translation is that the inclusion of 'raw' binary numbers in the ic expects to find it after its table search. These machine language routines are found in GTO.RUNTIME and are 'attached' to Basic using the standard INVOKE "GTO.RUNTIME" function of the language. The PERFORM varb of Basic tl transfer targets into absolute memory references and all control transfer commands into commands which cause the Basic Interpreter to instead PERFORM machine language routines which simply transfer that offset to where Basetermine that line 100 is at memory offset 1237 and consider all GOTO 100 statements as "jump to 1237", avoiding the search through memory. 2.3.4.3 GTO.2 Translation GTO.2 translates all controaltering the targetting of earlier GOTOs and GOSUBs; but, you guessed it, EACH AND EVERY TIME the transfer is encountered this search is repeated. But, again, once your program is written and running we could actually don about line lengths to allow the search to skip over the contents of an unmatched line. 2.3.4.2 Fixing control xfer referrents This approach allows easy insertion and deletion of lines without oking for a match on the 'tokenized' line number. It optimizes this process a bit by starting the search from the beginning only if the target line number is less than the current one and by maintaining informatinumbers as two byte values. Every time the interpreter encounters an explicit control transfer command (GOTO 100 or GOSUB 200) or an implicit one (IF X=1 THEN 1000) it searches through the program code stored in memory lopilation 2.3.4.1 Interpreted Control Transfer Basic keeps the entirety of the executing program in memory compressing things a bit so Keywords are kept as easily recognizable one byte 'tokens' and line -10- Basic GTO D A DataSystems 2.3.4 GTO.2 - Control Transfer Comve done with the value. Chapter 3 DISTRIBUTION DISK CONTENTS Your BASIC GTO distribution disk contains 11 files as follows : (1) SOS.KERNEL the Apple /// SOS (operating system) (2) SOS.INTERP the Apple /// Business Basic Interpreter Since BASIC GTO is written primarily in Apple /// Business Basic we supply a licensed version of the interpreter to configure the Distribution Disk asy be run without the GTO.RUNTIME (and associated speedup) for testing. The output of the second level (GTO.2) is unlistable and unmodifyable. We assume a one-level compile using GTO.1 and a two-level compile usi 4.1 One Level or Two Level Compile You may choose either a one-level or two-level compile of your program. The output of the first level (GTO.1) is modifiable and listable and ma Basic GTO D A DataSystems Chapter 4 COMPILING A PROGRAM -14- d changeable source code program files GTO.1.SRC and GTO.2.SRC. In the event that modifications to the programs need to be made, these source programs can be easily modified and re-compiled. irst thing we did is use it to compile itself, sounds kinky - no. This means the programs GTO.1 and GTO.2 are neither readable or changeable. This GTO.SOURCE subdirectory contains two listable an D A DataSystems (10) HELLO Boot up Intro program (11) GTO.SOURCE Uncompiled versions of GTO programs Since Basic GTO speeds up Basic programs, the fnchant to abort if it encounters a reference to a line that does not exist in the program. -13- Basic GTO lly run a compiled application (9) RENUMBER.INV Apple's Business Basic program renumberer You should have gotten one of these when you purchased Business Basic. But we have altered it to eliminate its pe These assembler routines are used by the GTO.1 and GTO.2 program during compilation. Both programs invoke BASICGTO.INV so it must remain on your compiler disk or directory. It IS NOT REQUIRED to actuam. IN ADDITION it must remain invoked to allow running any program compiled with GTO.2 (7) GTO.TEMP.1 temporary file used by GTO.1 (8) BASICGTO.INV assembler programs used DURING COMPILATION the goto/gosub compiler BASIC program (6) GTO.RUNTIME the BASIC GTO machine language support routines This collection of assembler language routines MUST be INVOKED prior to running any GTO compiled progra slot 4 (.PROFILE), a parallel/UPIC printer in slot 1 (.PRINTER), and a built in serial/rs232 printer (.SERPRINT). (4) GTO.1 the variable table compiler BASIC programs (5) GTO.2 a bootable disk. (3) SOS.DRIVERS the device drivers for the application We configure the drivers file to handle up to four Apple /// floppy disk drives (.D1,.D2,.D3,.D4), a Profile Hard disk in ng GTO.1 then GTO.2 in sequence. It is possible to use GTO.2 alone but NOT GTO.2 THEN GTO.1 in sequence. GTO.1 offers more significant performance improvements than GTO.2 for smaller or medium programs. In addition its production of modifiable and interpreter-runnable code allow more flexibility in testing. Adding the GTO.2 compile offers significant additional speedup particularly for large (30K plus) programs but rigidill be expanded by 6 characters total. By the same token this.val%=that.val% shrinks 10 bytes. In addition GTO.1 removes the contents of REM statements. Typically, GTO.1 can be expected to produce a smaller object program. as the RUNnable module. 4.2.1.2 program size changes Program Size will have changed via the GTO.1 compilation. Since every variable has been replaced by a 4 charactger variable, all I=J's wshould, after compiling, rename, ACCOUNTS -----> ACCOUNTS.SRC ACCOUNTS.GT1 -----> ACCOUNTS thus saving the original source file for reference and renaming the output of GTO.1 to substitute 4.2.1 Compilation Notes 4.2.1.1 renaming programs YOU ARE RESPONSIBLE for appropriate RENAMING of the output file. If, for example your application runs a program named ACCOUNTS you ice or file. (9) The compilation is complete. -16- Basic GTO D A DataSystems wish to print out the Variable Map. This is a cross reference listing of the varible names in your Source program and the new names they received from the ...GT1 program. This list can be printed or sent to any devCHAINING for details. (7) The program will display a message concerning the optimum size of the gto.table%() array. This value should be recorded. Its use is detailed below. (8) The program will ask if you on the screen as it is compiled. (6) The program will ask about saving a Chaining Data File The program will request an optional Chain-To Module Answer "no" for standalone programs. See the section on It will be on the same directory with the suffix ".GT1" appended or overlayed. In this case .PROFILE/SOURCECODE/TEST/PGM1.GT1 (5) While it is running GTO.1 will display the current source program line numberl request an optional "Chain Data File". None is necessary for compiling standalone programs. See the section on chaining programs for other details. (4) The program will create an output Program. 1) The program is run by the command : RUN GTO.1 [ret] (2) The program asks you for the SOURCE program name. Type in the full pathname, e.g., .PROFILE/SOURCECODE/TEST/PGM1 (3) The program wil D A DataSystems 4.2 Level One Compile - RUNNING GTO.1 GTO.1 runs the first level and produces a modifiable and listable program (although not particularly readable). (t to develop familiarity then experiment with the second level. -15- Basic GTO ly requires specific alterations to the source code before the compilation and prohibits changes afterward. 4.1.1 Recommendation We recommend that you work with level-one (GTO.1) compiles at firs 4.3 RUNNING THE LEVEL ONE COMPILED PROGRAM 4.3.0.1 Listing and viewing the modified program The xxxxx.GT1 program output may be LOADed, LISTed and RUN as is. HOWEVER, running it like this will NOT include any of the Fast Variable Access (FVA) features. 4.3.1 Linking the compiled program to the FVA routines In order to "Link" the xxxxx.GT1 module to the speedup functions you fast-variable-access (FVA) code into the space previously occupied by the list. This keyword table is never accessed during program execution, but if, after a program completes but prior to PERFORMING FINI, you (*) Among other things, the INIT routine finds the part of the interpreter that maintains the list of "keywords" (e.g. LIST, RUN, NEW, GOTO...) and saves this list elsewhere in memory then loads its new (j) This routine, FINI, reverses the changes in the interpreter caused by INIT and eliminates Fast Variable Access (FVA). It also cuts off access to any data values developed under FVA. e the line 1 INVOKE "GTO.RUNTIME"; since the module is still loaded in memory. -18- Basic GTO D A DataSystems access to the values of variables used earlier in the program and remove FVA from the program but otherwise appear to run normally. (i) This INVOKE is not necessary if no other INVOKE has occurred sincIME that alters the basic interpreter for fast variable access (FVA). (h) Actual line number is up to you. This code should be the last executed in the program. If it is placed before the end it will cut offd functions. The latter reverses this alteration. (f) the PERFORM verb is the standard way to begin execution of an assembler/machine language routine. (g) In this case the INIT routine in GTO.RUNT assembler language routine to basic. (e) GTO.RUNTIME contains only two routines which are used by GTO.1, INIT and FINI. The former will, when PERFORMed, alter the basic interpreter to add the high spee You free up 2 bytes of memory for each "dim" value less than 4095 so optimising to DIM gto.tables%(1000) frees up 6190 bytes for other program uses. (d) The INVOKE verb is the standard way of attaching an at this point but ALL added variable's names must begin with a lower case letter. (c) the dimension value can be reset to the number specified at the end of the GTO.1 compiler run "...table optimum size is nnnn". mmand then this line must be inserted in 200 bumping down whatever was there. (b) the variable name "gto.table%" must be in lower case. In fact other lines and variables can be added to the xxxxx.GT1 program (j) (a) the line number need not be 1. This line must, however, be the first executable statement in the program. If you are in the habit of commencing the program with a RUN 200 co 1 DIM gto.tables%(3000):INVOKE "GTO.RUNTIME":PERFORM INIT (a) (b) (c) (d) (e) (f) (g) and one at the end... 63399 INVOKE "GTO.RUNTIME":PERFORM FINI (h) (i) must ADD ONE LINE AT THE BEGINNING OF THE PROGRAM... -17- Basic GTO D A DataSystems type LIST or NEW or RUN, you'll get a syntax error as Basic goes and scans its presumed table of keywords looking for a match on L-I-S-T, finding instead out FVA code. (*) The FINI routine reverses this and once PERFORMED, you may freely use Immediate mode Commands such as LIST. (*) Note that we DO NOT overlay the section of Basic Keywords containing INVOKE and PERFORM so you can INVOKE "GTO.RUNTIME" EST/PGM1.GT1 It will be renumbered with lines from 10000 stepping 1.(**) It will be essentially unLISTable. It CANNOT BE MODIFIED IN ANY WAY. (**) This renumbering is necessary to allow GTT/PGM1.GT1 (3) The program will create an output OBJECT Program. It will be on the same directory The suffix ".GT2" will be appended or overlayed on the pathname. In this case .PROFILE/SOURCECODE/TO.2 (1) The program is run by the command : RUN GTO.2 [ret] (2) The program asks you for the SOURCE program name. Type in the full pathname, e.g., .PROFILE/SOURCECODE/TESust alter line 225 to read: 225 INVOKE "TTTSORT.INV","GTO.RUNTIME" this assures that the "G" and "GS" routines are available for any further control transfer logic. 4.4.2 RUNNING GTKE "TTTSORT.INV" -20- Basic GTO D A DataSystems 230 PERFORM SORTIT(@AAA$,@NN%) you m YOU MUST MODIFY THAT INVOKE COMMAND TO RE-INVOKE GTO.RUNTIME ALONG WITH THE OTHER ROUTINE. Thus, if your program invokes and performs a high-speed sort using code similar to the following: 225 INVOly string their names out together, in quotes, after the INVOKE verb. 4.4.1.2 Pre-Edit of the GTO.2 Source program IF YOUR SOURCE PROGRAM CONTAINS ANY INVOKES OTHER THAN THAT OF GTO.RUNTIMEere in the program will wipe out the GTO.RUNTIME code for "G" and "GS" and cause the program to crash with an UNDEFINED FUNCTION ERROR. The INVOKE verb does, however, allow you to INVOKE multiple modules; you simp One feature of the INVOKE verb is that INVOKing one machine language module clears any previously INVOKed code out of memory. This can cause a problem for GTO.2 compiled program, however, since an INVOKE "SORT.INV" somewhprogram via an INVOKE of the GTO.RUNTIME package and actually caused to execute by PERFORM G..., and PERFORM GS... statements written into the Basic code by GTO.2. Thus G and GS must be constantly available throughout the program. produced by GTO.2 will actually use when running are accessed in a slightly different way than those of GTO.1. These two routines are G and GS which execute fast GOTO and GOSUB respectively. They are made available to the Basic NON-LISTABLE program. 4.4.1 Prior to Running GTO.2 4.4.1.1 Setting & Maintaining LINKing information The Fast Control Transfer (FCT) routines which the object program Basic GTO D A DataSystems 4.4 Level Two Compile - RUNNING GTO.2 GTO.2 runs the second level and produces a NON-MODIFIABLE and and PERFORM FINI in immediatede mode to restore things to normal. -19- O.1 room to update the object "in place" with the Perform token and Name and transfer offset value. (4) While it is running GTO.2 will display status messages. (5) The compilation is complete. -21- Basic GTO D A DataSystems 4.4.3 Compilation Notes 4.4.3.1 renaminor possible modifications allowing re-compile of GTO.2 only. ------------------------------------------------------------------ -23- ------------------------------------- Program "XXXXX" is now a fully two-level compiled version of the original "XXXXX" which is saved as "XXXXX.SRC" for future modifications. The intermediate program "XXXXX.GT1" is saved f as the output program. 9. Rename "XXXXX" to "XXXXX.SRC" and "XXXXX.GT1.GT2" to "XXXXX". 10. TEST. Run "XXXXX" (now compiled) against real, damageable data. --------------------------------------------------------------- 7. Find all other INVOKE statements in the "XXXXX.GT1" program and add to them a re-invoke of GTO.RUNTIME. 8. Run GTO.2 using "XXXXX.GT1" as input producing "XXXXX.GT1.GT2" . ------------------------------------------------------------------- Program "XXXXX.GT1" is now a level-one compiled and runnable version of "XXXXX" (w/wout renaming). ---------------------------------bles%() array optimum size printed by GTO.1. 4. Add the LINK line to the "XXXXX.GT1" program at either line 1 or the program RUN entry line. 5. Change the DIMension in the gto.tables%() array to the optimum. 6RY 4.6.1 What you must do do accomplish a full compile 1. Verify that the original source program "XXXXX" is error free. 2. Run GTO.1 to produce program "XXXXX.GT1". 3. Record the gto.ta -22- Basic GTO D A DataSystems 4.6 COMPILATION SUMMAcessary, the program runs via normal commands. If the program is involved in a system of CHAINING programs, some pre-GTO.2 changes must have been made; see the Appendix on CHAINING. two bytes so no change in object code size occurs there... only the xfer referrents are stored as charaacter text. 4.5 RUNNING the Level-Two Compiled Program No further changes are ne Typically, GTO.2 can be expected to produce a 5%-10% larger object program. Be aware of this limit with very large (>60K) source programs. Note that the actual line number in the program line header is always stored in 4.4.3.2 program size changes Program Size will have changed via the GTO.2 compilation. Since the object program is renumbered from 10000, each control transfer referrent will require 5 characters of code.ACCTS.SRC ACCTS.GT1 -----> no change ACCTS.GT1.GT2 -----> ACCTS thus saving the original source file for reference and renaming the output of GTO.2 to substitute as the RUNnable module. g programs YOU ARE RESPONSIBLE for appropriate RENAMING of the output file. If, for example your application runs a program named ACCTS you should, after compiling, rename, ACCTS -----> Basic GTO D A DataSystems Chapter 5 CAVEATS 5.1 System requirements 5.1.1 Configuration BASIC GTO, as currently configured, assumes some sort of secondary storage device, either floppy .D2 or Hard Disk and uses .D1 for its own permenent Basic GTO D A DataSystems 5.2.4 GTO.2 Xfer Refs Limits As currently implemented, GTO.2 can manage programs with up to 1000 control transfers internally (e.g. As currently implemented, GTO.2 can manage programs with up to 2000 source lines of code. This is approximately 30 pages LISTed. -25- within a level-one compiled program. 1000 ABAS=100:BFE%=DAE%+100 1002 test.var=test.var+1:IF test.var=10 THEN STOP 1005 GOTO 2000 5.2.3 GTO.2 Source Lines Limits code without re-compiling. Any lower-case variable added to the program will be accessed in the old, slower manner; although searching through a much smaller variable table. So you can 'patch' line 1002 in t following examplefollowing: 1000 FOR I=1 to 1000 1010 J=I+5 1020 A(J)=B(I) 1030 NEXT I Note also that you can take advantage of this lower-case bypass as a means of modifying level-one compiledariable table. Note that variable array subscripts will be FVA's. This is ultimately where performance degradation was encountered and is eliminated by GTO.1 FVA... e.g. "I" and "J" access in the r. This means that the array reference will go through the regular search of the separate array variable table in memory - usually containing a smaller number of entries to be matched against than the simple vis accomplished by translating the first character of the array variable name to lower case and by having the FVA handlers jump out to the old Basic variable reference routine upon encountering this lower-case first characte Basic GTO D A DataSystems 5.2.2 GTO.1 Handling of Arrays As currently implemented, GTO.1 does not put arrays into the FVA format. This of certain programs. Typically those with few comments and non-meaningful variable names. These programs will have to be split up for compilation. -24- The absolute maximum size of a Business Basic program is 64535 bytes (64K) or 128 blocks. Since GTO.1 can either expand or contract a program and GTO.2 will typically expand, this limit may be exceeded by compilation ensed versionb we supply on the boot/distribution disk. Please contact us if you plan to work with version 1.0 or the newer 1.2. 5.2 Program Limitations 5.2.1 Object program Size he Profile. Systems with no secondary disk should contact us. 5.1.2 Business Basic Version BASIC GTO is developed to run under the standard Apple Business Basic version 1.1, this is also the licly resident boot diskette. Although we have not tested it under the environment we have tried to design for avoidance of .D1 requirements so you should be able to move it up to a Profile subdirectory and work everything off of t total GOTOs, GOSUBs & implicits). 5.2.5 GTO.1 variable table limits GTO.1 will currently manage up to 1000 distinct simple variables. This ceiling could shrink depending upon the types of the variables. (Total space is 6100 bytes with reals, ints, strings, and long ints requiring 4,2,3 and 8 bytes per varible). This is well above anything reasonably to be expected in even a very large progrc GTO D A DataSystems 5.4 Error Handling 1. Errors in program logic or processing have been tested for extensively, however, we expect that some circumsttely verified and tested in the interpreter environment before re-compiling with BASIC GTO. -27- Basi which runs correctly in the interpreter environment will do so in the compiled environment. Changes to a compiled program, especially noting the GTO.1 compiled form which can be more easily altered, should always be compleor message but if you have error trapping on and continue, further references to the variable TESTFILE/BQQS can cross things up a bit. 5.3.2.1 Rule of Thumb Any program or portion of a program T, TESTFILE will be mis-translated by GTO.1. The character data 'TESTFILE' will be assumed to be a variable an translated to 100 OPEN#1 AS INPUT, BQQS or somesuch. Now either of these forms will fail with an errotes around the file/pathname to be opened. GTO.1 in scanning for variables bypasses anything enclosed in quotes but translates character-data not enclosed in quotes. The INCORRECT Basic statement 100 OPEN#1 AS INPU assumptions that they make of syntactic correctness can lead to significant mis-translations if such errors are scanned and translated. 5.3.2 example As an example: The Basic OPEN syntax requires quCORRECT source program. You are presumed to have run the original program under the interpreter environment and isolated and syntax or structural errors. Since the BASIC GTO packages do not check for most source-code syntax, theGTO D A DataSystems 5.3 Syntax Checking 5.3.1 Correct Syntax In Source Programs Assumed Both GTO.1 and GTO.2 assume they are processing a SYNTACTICALLY But we find that GTO.1, which is fairly small and I/O oriented runs 85% faster when compiled. -26- Basic icant amount of processing time doing I/O (input/output file operations) or complex computations (e.g. transcendental functions) will be less appreciably speeded up by BASIC GTO. 5.2.8 BUT... he BYTE Magazine short benchmarks. 5.2.7 I/O Bound or Computation Intensive Programs If you now understand HOW BASIC GTO alters a program, it should come as no surprise that programs which spend a signif BASIC GTO will not significantly improve the performance of very small programs, e.g. programs with only 5 or 6 variables and few lines to scan in control transfers will be only minimally speeded up. So don't try tam. In any case, if the limit is exceeded, further variables encountered are mapped into a form which does not cause entry into the FVA routines ( e.g lower case first letter). 5.2.6 Very Small Programs ances will arise which the programs will not handle and which will cause errors. These are 'trapped' by a general "UNEXPECTED ERROR..." message which will note the Basic error number and the Line in the program that manifested it. (Note that this is not the line in the 'data' program being processed. This later line number is displayed on the screen throughout GTO.1 compilation and may be useful to record if you contact us. Please DO contnext available 'slot' in the reserved memory GTO.RUNTIME will later set aside for the program. Assume program MENU chains to program DBASE at some point and you compile each separately. The variable page.len% A.2 The problem with CHAIN - GTO.1 GTO.1 defines a translation of all the variables in a program, based upon the order they are encountered in the source code. The translated value is simple a coded form of the require additions and.or alterations to source code, BASIC GTO has been designed to allow the CHAIN verb while minimizing program alterations required to obtain proper functioning. ing programs. Chaining has always been a bugaboo for compiler designers since it requires information to be available to two separate programs that may have been compiled at different times. While other compilerssiness Basic establishes the name of the Chain-To program AND its entry point. Chaining is typically used in designing systems of many programs with, for example one common entry/menu program and multiple chained-to process another program while preserving the values of variables established in the Chained-From program. The Chained-To program can be entered at any valid program line much like the RUN 100 format. The CHAIN verb of Apple /// Bu Appendix A Program CHAINING A.1 The Chain function CHAINING is the process by which a program transfers control to -28- Basic GTO D A DataSystems the GTO.1 program abort. 5. We have attempted to anticipate and trap for re-try, certain file related errors, e.g. Source file not found or mis-typed, and to allow for re-entry of this data. ugh we have no reason to expect any further appearance of these, we do trap for the manifestation (two values being out of sync), not any of the specific causes. The display "SYNC ERROR" will appear in this situation and or PRINT commands hit the disk. This situation is best remedied, immediately, by a re-boot. 4. We have identified one manifestation of a wide variety of error situations which came up early in development of GTO.1. Altho cannot normally access a file of type='basic program'. Because of this error termination situations have been known to leave file access paths 'open' below the level of Basic. After terminating you may find that simple LIST open or write to an unformatted disk may trap into the "UNEXPECTED ERROR... routine" 3. Note that both GTO.1 and GTO.2 do somewhat low-level file I/O when reading and writing source & object files; this because Basic act us if you run into a consistent and mysterious "UNEXPECTED ERROR..." message. 2. Note that neither program is "bullet-proofed" for some of the sillier error situations. Attempting to read a disk with drive door is used in each program. But the compilation/translation of GTO.1 on MENU may have assigned page.len% to ABQ% as it was encountered in reading through MENU while it occurs much later in DBASE and is assigned to MAE% there. Chaining will preserve the gto.tables%() array across -29- Basic GTO D A DataSystems prograa chained-to program, set and pass a chainval% then chain to the beginning then start the chained-to code with an ON chainval% GOTO target1,target2,target3. (d) IN GENERAL, be creative. Remember to make all program changes, the Chain-From program. (b) Chain To the beginning of the program and do a GOTO target from there. The renumber will recalculate the target. (c) If you are doing conditional chaining to different entry points in to the renumbering of the object program that GTO.2 must perform. These problems can be bypassed in a variety of ways. (a) Identify, via messy LISTing, or calculate, via counting up from 10000, the new line number and alter so this would occur at the beginning of "MENU" in our example. A.6 Accomodating Chain with GTO.2 The problems associated with the 'CHAIN pgm linenum' format arise entirely due A.5 Notes On GTO.1 Chaining Be certain to use the final, largest OPTIMIZED array dimension for the original DIM of gto.tables%(). In a chaining based system you can only DIMension an array onceountered in "PRINTIT" would receive unique mappings. -30- Basic GTO D A DataSystems u would specify "MENU.DBASE.CHN" as a CHAIN DATA Input file for this compilation. This would read in the variable mappings established for "MENU" and "DBASE" to be applied to "PRINTIT". Of course any new variables encd "DBASE" can chain to. You could do the level-one compile of "MENU" and "DBASE" consecutively then save the Variable Map as CHAIN DATA file "MENU.DBASE.CHN". Then end for the day. Upon returning to compile "PRINTIT", yo file. Upon re-starting GTO.1 to compile a new module you are allowed to specify a CHAIN DATA file for input to the compilation. If, in our example, we have an additional program named "PRINTIT" which both "MENU" an encountered. (2) SAVING AND RE-USING VARIABLE MAPS. After completing the GTO.1 compile of a program or programs you may specify that the Variable table/Map for that compile series be saved as a CHAIN DATA disk you answer yes in this case and continue conpiling "DBASE", the variable map developed for "MENU" is maintained and applied to "DBASE" as well. New variables encountered in "DBASE" are added to the map as they are ays. (1) CONSECUTIVE COMPILATION. After completing the GTO.1 compile of a program, say "MENU" following our ewxample, you are asked if you wish to continue compilation with a Chained-To module. If NU to CHAIN "DBASE",500 will not target the correct line. Accomodating CHAIN with GTO.1 GTO.1 allows for the SHARED MAPPING of common, chained variables between programs being compiled in two wms but each will reference an entirely different area of the reserveday. A.3 The problem with CHAIN GTO.2 Since GTO.2 renumbers the object program from line 10000 stepping by 1, a reference in ME and test them, before compilation, and especially before GTO.2 compilation. -31- Basic GTO D A DataSystems Appendix B Technical Details of Program Functioning s a renumber of the source program giving the object program renumbered from 10000 by 1. This is necessary since we will need up to five or six slots to update in place with... a. perform command token b. " B.2 GTO.2 The primary purpose of GTO.2 is to translate GOTO and GOSUB commands in the source code into PERFORM calls to the routines G and GS found in GTO.RUNTIME. GTO.2 first performibble of lo byte + 65) (4) Fourth char is type indicator, %,$,&,S for int,str,lint,real. THUS : BBAS maps to B ---> 1 B ---> 1 A ---> 0 S ---> real .. real data (4 bytes) at offset x'0110 in gto.tables%(). eader and next 256 are used to store the downloaded Basic literals, this leaves 6128 for data so thus max dim gto.tables%(3063). (2) Second char is chr$(hi nibble of low byte + 65) (3) Third char is chr$(lo nlows : (1) First char is chr$(hi-byte of gto.tables%() offset plus 65) range is 00-19 hex or 00-25 giving first characters A-Z thus max gto.tables% size is x'1900 or decimal 6400 bytes. since first 16 are h Basic GTO D A DataSystems returned and updated in the object pgm. If no match is found in the growing variable table a map value is created as fol These tables are accessed via a hashing algorithm based on the variable name first and last character. If a match is found the map value for the variable is -32- ollected and evaluated. Array variables names are altered to have lower-case first char in the object pgm. Other variables are matched against an internal table of variables hit and their associated map values. . The source program is read thru one byte at a time and each byte is mapped over to a regularly flushed output buffer. Variables are identified as initial byte-values between "A-Z". The rest of the variable is c file prior to access. This is accomplished by dummying-up a renumber of the GTO.TEMP.1 file over to the required object pgm. Thus we let the renumber do all the GET-FILE-INFO, CREATE, SET-FILE-INFO routines for usfiles is performed via low level SOS calling routines contained in the support module BASICGTO.INV. These functions include OPEN, CLOSE w FLUSH, READNXT and WRITENXT. The object program must be pre-created as a valid type=basic ffsets to be calculated within the table using the internal Basic pointer that tracks he beginning of array storage. GTO.1 reads input data file xxxxxxxx and produces output data file xxxxxxx.gt1. All I/O on these xed memory location reserved for the data/variable. This fixed location will be within a dummy array named gto.tables%() which must be the first array DIMmed in a program or program system. This allows absolute o B.1 GTO.1 The primary purpose of GTO.1 is to translate all variable references encountered in the SOURCE program into different variable names which contain information about a fiG" literal or "GS" c. ":" to stop scan of perform d. two byte absolute offset. Note that we always have a sixth byte, the GOTO or GOSUB token to overlay except in implied xfer mode. The perform GS requires that extra byte but cannot occur in implied xfer (IF x THEN 1000 is always a goto). Thus, remembering that GOTO,GOSUB and PERFORM are single byte tokens in the source, a sample translation is ... -35- Basic GTO D A DataSystems O.2 - must be resident via invoke. Must perform some housekeeping on "return stack" etc, taken from a Basic disassembly, then does a pseudo "goto" using G code. d sets them into the basic TXTPTR, leaving Basic to get its next scan at the eol byte just before the "goto"ed line. ----------------------------------------------------------------- GS - used by GT----------------------------------------------------------- G - used by GTO.2 - must be resident via invoke. Scans the pgm code from the txtptr stripping off the absolute offset for the pseudo "goto". Adjusts these values an------------------------ FINI - used by GTO.1 - must be resident via invoke Moves the saved Basic literals from gto.tables%(). Removes the jmp in the Basic var-ref routine and resets it. ------tables%()) to Basic. -34- Basic GTO D A DataSystems -----------------------------------------c routine. FVA code scans variable name and calculates offset; adds array-start value maintained by basic and adjusts for bank memory peculiarities then returns final pointer to the variable's data (within gto.of other INVOKES. Finds entry point to Basic's variable-reference processing code and alters it to jmp into our FVA code. Alter FVA code jmp out address (for arrays & lower case) to jmp back into regular Basi Moves 256 bytes of Basic literals down into the beginning of the gto.tables%() dummy array. Relocates our FVA code into the 256 bytes cleared in the top bank of interpreter memory. Thus permanently resident regardless GTO.RUNTIME contains four assembler/machine language routines, INIT, FINI, G, and GS. ---------------------------------------------------------------- INIT - used by GTO.1 - downloads resident portion is necessary since the Basic line scanner may be skipping over the rest of a line after a bypassed conditional and look to stop on x'3a (:) or the line terminator x'00. B.3 GTO.RUNTIME e number gg is extra garbage skipped by scanner eol is x/00 line terminator Absolute offsets with either x'00 or x'3a in either byte are not translated, the GOTO or whatever is left in place. This iftoken X thentoken gototoken 1 0 0 1 5 eol is mapped to ... ll ln ln iftoken X thentoken performtoken G : o1 o2 gg eol where o1 and o2 are absolute offset of 10015 in pgm ll,ln.ln are line len and lin -33- Basic GTO D A DataSystems 10010 IF X THEN GOTO 10015 which is internally stored as... ll ln ln Index absolute jump instruction 7 absolute memory references 7, 11 Apple Business Basic 5 arrays, handling by GTO.1 25 backup copies 4 Business Basic, version required 24 Business Basic, versions 1.0 or 1.2 24 CHAIN DATA files 30 chaining, com=nsecutive compilation 30 Chaining, example 29 Chaining, GTO.1 29 Chaining, GTO.2 30, 31 compilation, consecutive 30 compilation, summary 232 1.1.3 Your responsibilities 2 1.1.3.1 Knowledgeable use 2 1.1.3.2 Testing 3 1.1.4 Your Bene 2 1.1 GETTING STARTED 2 1.1.1 Software License 2 1.1.2 Please Read -38- Basic GTO D A DataSystems Table of Contents Chapter 1 Upfront two level compile 15 user manual 2 variable maps, saving as files 30 variable name translation 9 variable names 9 variable references 8 variable types 9 stems, using Basic GTO with 24 size of programs 24 slowest Interpreter functions 8 small programs 26 source code 6 system requirements 24 Testing Compiled Programs 3 tokenizing 11 tokens 11 size 24 program size, changes with GTO.2 22 programs 5 programs,small 26 re-invoking 18 renaming programs 17, 21 renumbering 21, 31 reserved memory 9 runtime routines 8 single drive sy one level compile 15 partial compiler 8 perform command 11 PERFORM verb 18 PERFORM, immediate mode 19 Program enhancements 3 program line number compression 11 program names 17, 21 program 4 LINKing 17 linking to high speed routines 17 LIST,RUN,NEW, etc don't work 19 machine language 5 machine language routines 11 Multiple INVOKES 20 object code 6 object code size 24 mmand 11 INVOKE verb 18 INVOKE verb feature/limitation 20 INVOKE, immediate mode 19 INVOKEs, multiple 20 invoking repeatedly 18 keywords table, changed by INIT 19 language keywords 7 License erhead 9 Interpreter speed 7 -37- Basic GTO D A DataSystems Interpreters 5 invoke cord disks, using Basic GTO with 24 INIT routine 17 INIT routine, actions of 19 Interactive nature of interpreters 7 Interpreted Basic Variable Tables 9 interpreter control transfer processing 11 interpreter ovS routine, FCT GOSUB 20 GT2 suffix 21 GTO.1 8, 9 GTO.2 8, 11 GTO.2 compilation, pre-edit required 20 GTO.RUNTIME 4, 8, 9, 11, 17, 20 gto.tables% array 9, 17 gto.tables% array, optimising 18 ha Fast Control Transfer Routines 20 Fast Variable Access 9, 17 FCT routines 20 FCT, Fast Control Transfer 20 FINI routine 17, 19 FVA 9, 17 G routine, FCT GOTO 20 GOSUB 8 GOTO 8 G compile, one level 15 compile,two level 15 compilers 6 configuration 24 Contract compiling 3 control transfer instructions 8 dimensioning gto.tables% array 17 explicit control transfer 11, 11fits 3 1.1.4.1 Greatly improved program speed 3 1.1.4.2 If you are unhappy 3 1.1.4.3 Program Enhancements 3 1.2 LICENSE 4 1.2.1 Single CPU License 4 1.2.2 Runtime Program 4 1.2.3 CoNG GTO.2 20 4.4.1 Prior to running GTO.2 20 4.4.1.1 Setting and Maintaining LINK information 20 4.4.1.2 Pre-Edit the of the GTO.2 Source progra m 17 4.3.1 Linking the compiled program to the FVA routines 17 4.4 Level Two Compile - RUNNIgrams 17 4.2.1.2 program size changes 17 4.3 RUNNING THE LEVEL ONE COMPILED PROGRAM 17 4.3.0.1 Listing and viewing the modified progra.1.1 Recommendation 15 4.2 Level One Compile - RUNNING GTO.1 16 4.2.1 Compilation Notes 17 4.2.1.1 renaming pro11 Chapter 3 DISTRIBUTION DISK CONTENTS 13 Chapter 4 COMPILING A PROGRAM 15 4.1 One Level or Two Level Compile 15 4ed Control Transfer 11 2.3.4.2 Fixing control xfer referrents 11 2.3.4.3 GTO.2 Translation 11 2.3.4.4 A side effect 2.3.3.2 Fixing variable references 9 2.3.3.3 GTO.1 translation 9 2.3.4 GTO.2 - Control Transfer Compilation 11 2.3.4.1 Interpret 8 2.3.2 HOW IT WORKS 8 2.3.3 GTO.1 - Variable Reference Compilation 9 2.3.3.1 Interpreted Basic Variable Tables 9 -39- Basic GTO D A DataSystems 2.3 BASIC GTO - A Partial Compiler 8 2.3.1 WHAT BASIC GTO DOES 2.2.0.2 The Feature of Interpreters 7 2.2.0.3 The Problem with Interpreters 7 2.2.0.4 The Feature of Compilers 7 Compilers 6 2.1.2.2 Compiler Input & Otput 6 2.2 COMPILERS vs INTERPRETERS 7 2.2.0.1 The Problem with Compilers 7 1.1.2 Machine Language & Human Language 5 2.1.1.3 Apple /// Business Basic 5 2.1.2 COMPILERS 6 2.1.2.1 The Special Function of 5 2.1.1 INTERPRETERS 5 2.1.1.1 The Special Function of an Interpreter 5 2.mmercial Use 4 1.2.4 Licensing Arrangements 4 Chapter 2 Introduction & Overview 5 2.1 COMPILERS & INTERPRETERS 20 4.4.2 RUNNING GTO.2 21 4.4.3 Compilation Notes 22 4.4.3.1 renaming programs 22 4.4.3.2 program size changes 22 -40- Basic GTO D A DataSystems 4.5 RUNNIhe buyer (and not D A DATASYSTEMS, its distributors or retailers) assumes the entire cost of all necessary servicing, repair, or correction and any incidental or consequential damages. In no event will D A DATASYSTEMS be liess for any particular purpose. D A DATASYSTEMS software is sold or licensed "as is". The entire risk as to its quality and performance is with the buyer. Should the programs prove defective following their purchase, tWARRANTIES AND LIABILITIES D A DATASYSTEMS makes no warranties, either express or implied, with respect to this manual or with respect to the software described in this manual, its quality, performance, merchantability, or fitn 34 -41- Basic GTO D A DataSystems DISCLAIMER OF ALL al Details of Program Functioning 32 B.1 GTO.1 32 B.2 GTO.2 33 B.3 GTO.RUNTIME 30 A.4 Accomodating CHAIN with GTO.1 30 A.5 Notes On GTO.1 Chaining 31 A.6 Accomodating Chain with GTO.2 31 Appendix B Technic 29 A.1 The Chain function 29 A.2 The problem with CHAIN - GTO.1 29 A.3 The problem with CHAIN - GTO.2 5.3.2 example 27 5.3.2.1 Rule of Thumb 27 5.4 Error Handling 28 Appendix A Program CHAINING 26 5.3 Syntax Checking 27 5.3.1 Correct Syntax In Source Programs Assumed 27 5.2.6 Very Small Programs 26 5.2.7 I/O Bound or Computation Intensive Programs 26 5.2.8 BUT... f Arrays 25 5.2.3 GTO.2 Source Lines Limits 25 5.2.4 GTO.2 Xfer Refs Limits 26 5.2.5 GTO.1 variable table limits 26 5.1.2 Business Basic Version 24 5.2 Program Limitations 24 5.2.1 Object program Size 24 5.2.2 GTO.1 Handling o 23 Chapter 5 CAVEATS 24 5.1 System requirements 24 5.1.1 Configuration 24 NG the Level-Two Compiled Program 22 4.6 COMPILATION SUMMARY 23 4.6.1 What you must do do accomplish a full compile able for direct, indirect, incidental, or consequential damages resulting from any defect in the software, even if D A DATASYSTEMS has been advised of the possibility of such damages. Some states do not allow the exclusion or limitation of implied warranties or liability for incidental or consequential damages, so the above limitation or exclusion may not apply to you. D A DATASYSTEMS reserves the right to make improvements in thto find the new target line or renumber from 10000 by 1 up front then list then alter ERRLIN target then GTO.2 compile. UNRESOLVED BUG(s) GTO.1 forces all variables to 4 characters. Long lines of code incute under normal interpreter speed. UNDOCUMENTED NOTE GTO.2 renumbers the source but the Apple RENUMBER module does not pick up ERRLIN= lineref. You must manually alter the lineref after careful listing adds some overhead and you may still wish to invoke & perform earlier in the program. UNDOCUMENTED LIMITATION GTO.2 does not alter ON GOTO's and ON GOSUB's. These are not translated in any way and will exepile with GTO.1, then add the LINK line (dim, invoke, perform init) at the beginning and end (optional invoke and perform fini). This module can then be merged or EXECed into existing code. Of course the INVOKE file load BASIC GTO - version 1.98 Documentation Addenda UNDOCUMENTED FEATURE You CAN compile program segments individually. Pull the code out as a separate module, com WITH SPECIFIC LEGAL RIGHTS. THERE MAY BE OTHER RIGHTS THAT YOU MAY HAVE WHICH VARY FROM STATE TO STATE. TWARE PACKAGE, ITS MERCHANTABILITY OR ITS FITNESS FOR ANY PARTICULAR PURPOSE. THE EXCLUSION OF IMPLIED WARRANTIES IS NOT PERMITTED IN SOME STATES. THE ABOVE EXCLUSION MAY NOT APPLY TO YOU. THIS WARRANTY PROVIDES YOU C GTO . When BASIC GTO has completed execution Apple software shall not be used by any other program. APPLE COMPUTER, INC. MAKES NO WARRANTIES, EITHER EXPRESS OR IMPLIED, REGARDING THE ENCLOSED COMPUTER SOFicensed to D A Datasystems to distribute for use only in combination with BASIC GTO. Apple Software shall not be copied onto another diskette (except for archive purposes) or into memory unless as part of the execution of BASIerous in licensing software allowing us to sell this as a more convenient 'boot disk' we ask that you note the following as well. APPLE SOS and APPLE BUSINESS BASIC are copyrighted programs of Apple Computer, Inc. le product described in this manual at any time and without notice. The word Apple is a registered trademark of Apple Computer. * * * Since Apple Computer has been extremely gen your source making frequent references to single or double character variables (e.g. initializing A=0:B=0:C=0: ...) may be expanded over the Business Basic limit of 255 characters per line with unpredictable results; alter your code accordingly. GTO.1 does not manage quoted IMAGE masks which contain colons. GTO.1 mismanages variable reference after CREATE statements of the form : CREATE F$, DATA : xxxx ... Business Basic uses the spt in early 1987, Anderson was left without any major royalties. That led to his decision in January, 1988 to place all his software programs into the public domain. What are some of the products going into the public domain? Here's a list,(511),C$(20),name$(20):=10:=0n: GOSUB 1120 x=+B$(I),16,B)140 PREFIX$=.D1 #1, ž#1180I=0I=I+1:#1;A$(I):170#1 L=I-1j=1:same=0:/#9,".D1/DISKNAME.DAT":#9;DISKNAME$:#9Ta$="{,|,~,}; 7 .d1/hello........."MENU.MAKER" (Version 4.53) =".d1":100: Coldstart 200: Warmstart (GOTO 30) (I=1L2(A$(I),A$))90<B$(J)=A$(I),1,31)!FJ/2<>J/2)=4:=+1:ۙ=44PB$(J);:J=J+1ZI:8dA$(1000),B$(1000),C%er-capitalized companies into or back into the /// market. In 1986, Daryl decided to sell many of his software products though Pair Software (Frank Moore) as well as through TAU, the Third Apple Users Group. But when Pair went bankru and supported by a word-of-mouth network, user groups, and the very timely /// Newsletter (which grew up to become the /// Magazine), we all made it thru '85 and expanded the locus of action enough to convince a handful of other bettct points for products and support. We tended to step into that gap and arrange with wavering developers and manufacturers to configure and offer their products to the /// market. Working with a few other small companies bothered to ADD to the products being offered so that we could keep up with the "newer" machines. He describes his companies early days this way: 1985 was a critical year for the /// and one when, at least early on there seemed to be few contaot to Daryl Anderson, a young man whose interest in our computer never wavered even though Apple discontinued making our wonderful machine. His was one of only a small handful of companies that bothered to continue supporting the ///, and in fact The Legacy of Daryl Anderson and D.A. Datasystems (Edited for inclusion on WAP PD disks from D.A. Datasystems) By David Ottalini /// SIG Co-Chairman (Originally published in the March, 1988 issue of the WAP Journal) Apple /// users owe a lIF nnnn PERFORM G:xx or IF nnnn PERFORM GS:xx which gives a syntax error. Formats IF nnnn THEN lineref, and IF nnnn THEN GOTO/GOSUB lineref are OK. Daryl Anderson ame token for the DATA keyword here as in a DATA statement ?! GTO.2 does not handle conditional transfers written without the THEN keyword, e.g the format: IF nnnn GOTO/GOSUB lineref. The translation is made to with edited descriptions by the developer himself: POWER KEYS Power Keys DM+ is a program which runs in conjunction with ANY other Apple /// program and allows you to substitute single keystroke shorthand or 'macro' commands for more lengthy sequences of frequently typed characters. In addition Power Keys DM+ itself can manage a collection of 'desktop utility' modules which put additional and useful functions at your fingertips while running any other program. POWERKEYS MOID#: 3DAD-08 BOOTABLE?: Bootable Basic GTO is a partial compiler and assembler for Business Basic. It will translate any Business Basic program into a format which executes between 50% and 500% faster. Typical applications might expect at least 75% /// SIG, Washington Apple Pi 12022 Parklawn Drive Rockville, MD. 20852 (301)-984-0300 WAP /// SIG PUBLIC DOMAIN LIBRARY PDS NAME: Basic GTO DISK yst Kache+3 Disk caching speedup via ramdisk Remote /// Control /// via remote dialup Daryl Anderson's address is: 3792 Windover Drive, Hamburg, NY 14075. Enahnced Titan 3+2 Ramdisks PCPI++ Allows running PCPI CPM from Catalyst LEGEND++ Autoboot 1 meg ramdisk for Legend card TWO-N-FRO /// Run 3+2 emulation from Selector/CatalWindow full-featured dis-assembler Disk Window disk block editor Data Window file examiner Other Programs: PC-COPY IBM/Apple file xfer (req. hardware) RAM+3 partial compiler and program accelerator Basic XRF program variable cross-referencer Basic Utils system utilities in Basic Basic XT language extensions including QuikSort Source r use by non-authorized person. TOOLS TIMES THREE The Retriever deleted file recovery utility Power Cat disk and file librarian Power Print software printer buffer Basic GTO Moduload Dynamic modula loader. QuikCrpt File encryptor/encoder. FileScan File viewer. FileDump File hex dumper. TypeRite Printer/typewriter. LockOut Prevents compute of a key. AsciTbl shows a table of Ascii character values as well as current system font. Dialer Phone dialer. QuikCalc Calculator. FontLoad Font switcher. r printer at any time. DiskMgr format floppy disks and copy files right in the middle of any other program. ShowTime display current system date & time at the touch ext screen on your printer or send it to a disk file. QuikCat list the directory of files on a disk or other subdirectory at any time. PrintMgr send complex 'setup' codes to youime. QuikDial allows modem owners to dial a telephone directly from the keyboard or from a number displayed on the screen by their program. QuikScrn print a copy of the current tDULES All are available as "background desktop utilities" at the touch of a key while running any Apple /// Program and they include: NotePad edit, load, save, alter and view small "scratchpad" files at any tperformance improvements. The translated programs are listable and can be modified. BASIC GTO targets two of the slowest interpreter functions, two that involve frequent searches of large internal tables for values or locations. These are the #4,B$(I),16,B)#5,".PRINTER" $ž#4120 .#4;a$ 8#5;a$ B1070LV:=24:=0::-`#8,".D1/FLASHNAME.DAT":#9;FLASH$:#8%jFLASH=110: FLASHER SUBROUTINEtSLOW=110~FLASH/2=FLASH/2):۴ =11:=07 FLAS:=".d1":=12:=0:120=+B$(I),16,B)1408A$(1000),B$(1000),C%(511),C$(20),name$(20):=10:=0 :120;::=23:=0::"79C";"WOULD YOU LIKE A HARD COPY?":1C$:C$<>"Y"C$<>"y"C$<>"N"C$<>"n"1010C$="N"C$="n"120$<>"y"C$<>"N"C$<>"n"850\C$="N"C$="n"1000;f:=23:=0::"79C";"PRESS ANY KEY TO HALT LISTING": p840z2,280,21K:=23:=0::"79C";"TO PRINT OR RETURN TO MENU, HIT THE SPACE BAR":C$:C$<>" "930:ۺ1000 (I),16,B)$=01:=0::"80C";A$;::12)E=23:=0::"79C";"PRESS ANY KEY TO HALT LISTING"::2,280,21 840#2,B$(I),16,B) ž#2910*#2;A$:A$:12304810 >:120*H:=23:=0::"79C";"CONTINUE...?":0RC$:C$<>"Y"CB$(I),"BASIC 0")700B$(I),"TEXT 0")740B$(I),"CAT 0")960B$(I),"FONT 0")1660B$(I),"FOTO 0")1730400A$="RUNNING "+B$(I),16,B)"79C";A$;:=0B$(I),16,B):A$="LISTING "+B$S=44:I/2<>I/2)I=I+1&I2=-1:I=I-2:NIBOTM<30XTHPOS=44I=IBOTM/2)*2:=+IBOTM/2)-1:0b=+IBOTM/2-.5):I=IBOTM:I/2=I/2)I=I-1lvB=B$(I),16)," ")-1 =Q:WW=0A=:A=21A=9oldprefix$=A=31110A=27:=".D1":980A=13630=THPOS:B$(I);A<8A>11400A-7500,520,550,580:=THPOS:B$(I);:380: 500THPOS=4:I/2=I/2)I=I-1I=IBOTM THPO"BASIC 0":40,A$="TEXT 0":406A$="CAT 0":40@A$="FONT 0":40JA$="FOTO 0":40TA$(L),"BLOCKS")370*^=27:=19:"FREE MEMORY AVAILABLE: ";h=7:=20:"80C";A$(L);$r:=5:THPOS=4:I=1:IBOTM=J-1:480|Q=:=26:=21:1400 selects; sets Prefix to .D1; aborts."12);::"80C";a$;:d$=DISKNAME$$=23:=0::"80C";d$;::12)1,180,22F=3:=14:"This /// SIG Disk is \^ 1991, Washington Apple `, Ltd."=4:B$(1)="":B$(2)="""A$=he help of the runtime machine language program named GTO.RUNTIME. Side One : BASIC GTO Files (including invokables and source code.) Side Two : User.Manual :Basic GTO manual. Read.Me :Basic GTO v.2.0 update. variable references (e.g. A=B*C) and the control transfer (GOTO and GOSUB) commands. BASIC GTO consists of two programs, aptly named GTO.1 and GTO.2 which translate these two command forms into formats which will execute much faster with tH$ SLOW FLASH :120#X=1100: TEXT SLOW-DOWN LOOPX810 Halt Subroutine::=23:=0::"79C";"PRESS ANY KEY TO HALT LISTING.": 1300(=23:=0::"79C";"CONTINUE...?":'(<>89<>121<>78<>11013202=78=11010<9F=23:=0::"79C";"PRESS ANY KEY TO HALT LISTING":P2,280,2 Z1310dn"x ..... "DATE.TIME.LINE" ....M=Ҡ,4,2))BM1430,1440,1450,1460,1470,1480,1490,1500,1510,1520,1530,1540M$="JANUARY"Returning you now to the Menu.Maker program."d".D1/MENU.MAKER"******** : œ15:""DATE IS: ";:"TIME IS ";L"PRESS IF OKAY, N)o TO CHANGE:";:OK$:"NO",OK$)"TIMESET"(#1,".RS232"%2A$=:="":"/APPLCOM/ACck$=".Co"console=1(console -ž#165 2#1;a$ 7#2;a$<50Aconsole=1:=23F0K"Would you like to print another file? ";b$5Pb$="Y"b$="y"b$="YES"b$="yes"b$="Yes"43Ub$="N"b$="n"b$="NO"b$="no"b$="No"903Z x=1100x9"Name the file you would like to print: ";inputfile$ #1,inputfile$ console=0;"Where would you like to print the file? ";outputfile$#2,Outputfile$check$=outputfile$,1,3)8#check$=".co"check$=".CO"cheXCVBNM ,<,<.>.>/?/?d0hp.>/?/?d0hp13П,2))-12;џ,6);:1580$"П,2))=0"12";џ,6);:ٟ;$,П,2))=>12" PM-":" AM-" 61630@WW=1390J=26:=21:1400 T1400 ^:WW=1:h +r ...... "MENU.MAKER" ":1550M$="FEBRUARY":1550M$="MARCH":1550M$="APRIL":1550M$="MAY":1550M$="JUNE":1550M$="JULY":1550M$="AUGUST":1550M$="SEPTEMBER":1550M$="OCTOBER":1550M$="NOVEMBER":1550M$="DECEMBER":1550826);"-";M$CESS3.INV"'<:=30::"WELCOME TO ACCESS ///":4F=3:=22:"WHICH SY Run Side Two Program#"TURN THIS DISK OVER, PLEASE."6"I WILL WAIT A FEW MOMENTS FOR YOU TO DO THAT..."(X=150002X<FK!P"OK RUNNING SIDE ONE NOW..."UZX=11000dXn".D1/MENU.MAKER"xhough we will continue to follow up on any 'bug' reports for this module we cannot assure a firm level of support. Bottom line is that you should stick to GTO.1 compiles unless you really find significant performance improvo much that it cannot be easily listed or modified by the over curious end-user. SO... we've decided to leave GTO.2 in with a big CAVEAT. The program GTO.2 is included as an "Unsupported Extra" element of the Basic GTO system. Alt1.00. In fact the program name derives from the GoTO transfer modification that it preforms (combined with a somewhat dated notion of a zippy model car !). And many of you still like the fact that GTO.2 scrambles your source code srms. And we do find that larger programs (>40K) still can exhibit 50%+ performance improvements with GTO.2 And, lets face it, we're sentimental about this. The GTO.2 program itself was the original and complete Basic GTO version h some of you use extensively. Now it turns out that we've figured out a way to force GTO.2 to skip over that particular format that it mis-manages thus removing the need to check source and edit code by hand for IF xxx GOTO nnn foeration of the source code that it does and (4) most significantly, could not handle the construct of a conditional control transfer without a THEN keyword... a format which never appeared in all 40-50000 lines of in-house coding but whic' GOTOs and GOSUBs) since it (1) did not typically offer the more significant part of the performance improvements of the system (2) forced a rigid pre-edit of the source (3) leads to cryptic and hard to debug code due to the type of alts will receive detailed notes on what has changed. Those of you receiving version 2.xx as your first look need not worry yourselves about history. GTO.2 Program Do note that we had originally planned to drop the GTO.2 program (which 'compiles BASIC GTO - version 2.01 Documentation Addenda VERSION 2.01 Version 2.01 includes fixes for a number of bugs and/or limitations of the earlier manifestations of the program(s). Those of you receiving upgrade diskements in the GTO.2. And if you experience problems with GTO.2 compiles, please contact us but expect that the prime directive will be to stick to GTO.1. BASIC Version 1.23 Apple recently, and rather surreptitiously, released the "last ever" version 1.23 of Business Basic which supports, most significantly, programs greater than 64K in size. Although Basic GTO translations typically shrink program code size, programs which use a significant number of one o 1/14/85B lineref are OK. Daryl Anderson 1/14/85 ments are limited since the FCT (Fast Control Transfer) routines of GTO aren't being called into play. Note that the two other formats for conditional transfer : IF nnnn THEN lineref, and IF nnnn THEN GOTO/GOSUnnnn PERFORM GS:xx The current version manages to bypass this format and leave it to be handled by a normal GOTO or GOSUB. If you use this structure for most of your conditional transfers you will find performance improve- GTO.2 does not handle conditional transfers written without the THEN keyword, e.g the format: IF nnnn GOTO/GOSUB lineref. Earlier versions made the the erroneous translation to : IF nnnn PERFORM G:xx or IF over the Business Basic limit of 255 characters per line with unpredictable results; alter your code accordingly. GTO.1 has been modified, in this version, to identify and report if this situation is encountered. ile. UNRESOLVED BUG(s) GTO.1 forces all variables to 4 characters. Long lines of code in your source making frequent references to single or double character variables (e.g. initializing A=0:B=0:C=0: ...) may be expanded module does not pick up ERRLIN= lineref. You must manually alter the lineref after careful listing to find the new target line or renumber from 10000 by 1 up front then list then alter ERRLIN target then GTO.2 comp GTO.2 does not alter ON GOTO's and ON GOSUB's. These are not translated in any way and will execute under normal interpreter speed. UNDOCUMENTED NOTE GTO.2 renumbers the source but the Apple RENUMBER perform fini). This module can then be merged or EXECed into existing code. Of course the INVOKE file load adds some overhead and you may still wish to invoke & perform earlier in the program. UNDOCUMENTED LIMITATION DOCUMENTED FEATURE You CAN compile program segments individually. Pull the code out as a separate module, compile with GTO.1, then add the LINK line (dim, invoke, perform init) at the beginning and end (optional invoke and the distribution channels being what they are, we don't see 1.23 basic being widely dispersed and continue to support version 1.10 as the baseline and largest installed base system. Note that the 1.1 routines work wih Basic 1.20. UN run the >64K program under Basic 1.23 but would appreciate your continued feedack on this. In addition we supply an alternate version of the GTO.RUNTIME module named GTO.RUNTIME.123 which must be used with Basic 1.23. Franklyr two digit variable names will expand. We noted the possibility that expansion would go beyond the old 64K limit and included a message/trap for this possibility in the current version. We believe you can ignore the message and