home *** CD-ROM | disk | FTP | other *** search
/ Power-Programmierung / CD1.mdf / basic / tools / bas2qb20 / basic2qb.doc next >
Text File  |  1991-06-23  |  14KB  |  312 lines
  1.  
  2.  
  3.  
  4. DOCUMENTATION FILE FOR BASIC2QB.EXE VERSION 2.0
  5.  
  6.                             = NOTE =
  7.  
  8.      In this text, the term "QuickBASIC" includes the QBASIC
  9.      interpreter found in Microsoft MS-DOS Version 5.0 and
  10.      later, and the QBASIC interpreter found in the book
  11.      "Learn BASIC Now"  from Microsoft Press.
  12.  
  13.  
  14. I.  Distribution
  15.  
  16.           This program is being distributed as shareware.  You
  17.      are free to copy and distribute this program so long as this
  18.      file accompanies it.  If you try the program and find you do
  19.      use it, you MUST register your copy.  In addition to
  20.      appeasing your conscience, registration provides the
  21.      following benefits:
  22.  
  23.           1.   Technical support - Available through CompuServe
  24.                Delphi, GEnie and PC-Link.  Customized versions of
  25.                this software are available to registered users at
  26.                no cost.
  27.  
  28.           2.   Free updates - Registered users will be sent
  29.                upgrades as they become available.
  30.  
  31.           Registration is simple.  Just send $10 to the address
  32.      listed and a copy of the form on the last page of this file
  33.      and you will receive the latest copy of this program.
  34.  
  35. II.  Background
  36.  
  37.           I wrote this program after spending long hours removing
  38.      colons from a BASIC program that I was trying to edit.  I
  39.      had a few new ideas to put into it and placing each
  40.      statement on separate lines made debugging easier.  But
  41.      after I'd finished editing and tried to run the program, the
  42.      compiler showed multiple errors in the sections of the
  43.      program that I hadn't done any work on.  Why, I thought,
  44.      would this program work in GW-BASIC and not QuickBASIC since
  45.      both are related and supposedly compatible?
  46.  
  47.           Microsoft's only documented requirements for conversion
  48.      is that the program be saved in ASCII-text format and that a
  49.      few commands had to be in a different format.  In actual
  50.      practice though, nested IF-THEN statements do not work
  51.      properly and in general the compiler has trouble
  52.      interpreting multi-statement program lines.  The only sort
  53.      of conversion software that Microsoft supplies with
  54.      QuickBASIC is a program that will remove any line numbers       that are not referenced by another line (i.e. via GOTO,
  55.      GOSUB, etc.).
  56.  
  57.           That's how we get to BASIC2QB.  It's made to take care
  58.      of most of the conversions necessary to make a GW-BASIC
  59.      program into a QuickBASIC one.
  60.  
  61. III.  Operation
  62.  
  63.           BASIC2QB uses a two-pass conversion system utilizing
  64.      "templates" of BASIC program structures.  The statement
  65.      lines are processed according to how they "fit" the
  66.      templates.  Any necessary statements (such as "END IF") are
  67.      added as needed.  The two-pass system is necessary for
  68.      removal of unreferenced line numbers and the production of
  69.      the referenced line number list.
  70.  
  71.           This program assumes that you are using BASIC programs
  72.      that have already been tried and debugged.  No effort is
  73.      made to check the correctness or completeness of input
  74.      source code.  BASIC2QB is not guaranteed to produce 100%
  75.      error-free code (no program can make that claim).  Every
  76.      effort has been made to insure that the changes made to the
  77.      source code are as error-free as possible.  If you find any
  78.      problems with the conversion process used in BASIC2QB,
  79.      please contact the author so that changes can be made.
  80.  
  81.                             WARNING!
  82.  
  83.           The statement processing algorithms cannot distinguish
  84.      between a colon used in a statement and one used to
  85.      designate a full path name for a drive designation or full
  86.      path designation i.e. C: or C:\directory\myfile.bas.  If you
  87.      use a drive designation or full path name in your program,
  88.      you need to review the output to insure that path names have
  89.      not been processed.
  90.  
  91. IV.  Features and Benefits
  92.  
  93.      *    Fast.  The two-pass approach and filter system used by
  94.           BASIC2QB insure that the files are processed as rapidly
  95.           as possible.  
  96.  
  97.      *    Easy to use.  Program inputs are obtained either
  98.           through prompts or through the command line, allowing
  99.           use in batch files or by inexperienced users.
  100.  
  101.      *    Places individual statements on separate lines.  Multi-
  102.           statement lines are not necessary in QuickBASIC since
  103.           the source code is not loaded into memory at execution
  104.           time.  Having statements on individual lines makes
  105.           future editing easier.
  106.  
  107.            *    Converts single line IF-THEN-ELSE statements to block
  108.           format.  This makes the statements easier to read and
  109.           allows for more error-free compiling since QuickBASIC
  110.           does not handle single line format well.
  111.  
  112.      *    Allows for indentation of the main body of such multi-
  113.           line statements as IF-THEN, WHILE-WEND, and FOR-NEXT to
  114.           make program structure more apparent.
  115.  
  116.      *    Removes unreferenced line numbers.  Line numbers are
  117.           only required as a label for certain commands (GOTO,
  118.           GOSUB, etc.).  Line numbers not referenced by one of
  119.           these commands are confusing and unnecessary.
  120.  
  121.      *    Produces a referenced line number list showing the line
  122.           number and the number of times reference is made to it. 
  123.           This makes program-flow editing easier by showing use
  124.           of procedures and allows once-called procedures to be
  125.           placed into the program flow, improving execution time
  126.           and helping to eliminate "spaghetti code".
  127.  
  128.      *    A copy of the output file can be sent directly to the
  129.           screen, printer, or both, so the user can view and edit
  130.           the output file easier.
  131.  
  132. V.  Requirements
  133.  
  134.           BASIC2QB requires an IBM PC/XT/AT/PS2/clone with at
  135.      least one floppy disk drive (although a hard disk or RAM
  136.      disk is much faster), 384K RAM (to allow the use of
  137.      QuickBASIC - BASIC2QB will run with less than 100K free
  138.      RAM), ASCII-text GW-BASIC or BASICA files to be converted
  139.      and Microsoft QuickBASIC or QBASIC (BASIC2QB has only been
  140.      tested with QuickBASIC version 4.0 and 4.5 but any version
  141.      that will accept GW-BASIC or BASICA as source code should
  142.      work).  BASIC2QB should also work with other BASIC compilers
  143.      with minor changes to the source code.
  144.  
  145. VI.  Usage
  146.  
  147.           To use the program, simply type "BASIC2QB <ENTER>". 
  148.      The program will ask for the input filename, the output
  149.      filename and any conversion options you desire.  Optionally,
  150.      the information can be input from the DOS command line in
  151.      the following manner:
  152.  
  153.      BASIC2QB sourcefile [destination file] [switches] 
  154.  
  155.      sourcefile     File to be converted.  If no drive/path 
  156.                     designation is given, the current drive/path
  157.                     is used.
  158.  
  159.      [destination file]  The converted file. If no destination is
  160.                               listed then the sourcefile name and
  161.                               drive/path is used with the
  162.                               extension ".CNV".  If the
  163.                               destination file already exists,
  164.                               you will be prompted to replace the
  165.                               existing file or enter a new file
  166.                               name.
  167.  
  168.      [switches]  Use spaces between each.
  169.  
  170.      /D   Use Disk for intermediate file storage.  If memory
  171.           becomes full, the program will automatically switch to
  172.           disk storage.
  173.  
  174.      /H   Displays Help screen.
  175.  
  176.      /L   Provide listing of referenced line numbers in output
  177.           file.  Along with this list is a count of how many
  178.           times the procedure is called.  This is useful to show
  179.           which procedures are only called once and can be
  180.           inserted into the main program flow, which makes the
  181.           program run faster.
  182.  
  183.      /P[device]     Send output file to any standard printer
  184.                     output (LPT1 - LPT3, COM1, COM2).  Default
  185.                     setting is LPT1.  Allows for hardcopy output
  186.                     of the converted file.
  187.  
  188.      /R   Remove unreferenced line numbers from the output file. 
  189.           Removing the unreferenced line numbers makes the
  190.           program easier to read and debug.  Also unreferenced
  191.           line numbers are unnecessary in compiled BASIC.
  192.  
  193.      /S   Send output text file to the screen.  This feature
  194.           allows you to view the converted file as it is being
  195.           processed.
  196.  
  197.      /Tn  Set tabs to n spaces.  Default setting is 8 spaces. 
  198.           Setting indentation allows for easier viewing. 
  199.           Statements between the ends of WHILE-WEND, FOR-NEXT and
  200.           IF-THEN statements are indented by the number of spaces
  201.           selected.  To save file space, long lines of spaces are
  202.           converted to ASCII tab characters in the final output
  203.           file.
  204.  
  205. VII.  Acknowledgements
  206.  
  207.           Here's where I get to give out the thank-yous.
  208.  
  209.           To Ben Stong - without your help version 2.0 would not
  210.           be.  You provided more than just "> 0".
  211.  
  212.           To Scott Ramsey - for listening even though the program
  213.           was written in BASIC.
  214.  
  215.           To Jack Dolby - for all the long talks we had.
  216.  
  217.           To the US Navy - for giving me six months in the
  218.           Mediterranean Sea with not much else to do.
  219.  
  220.           To Wendy - for listening to me rant and rave even when
  221.           she didn't know what the hell I was talking about, and
  222.           for being understanding of those long sessions at the
  223.           machine.
  224.  
  225. VIII.  History
  226.      
  227.      07/29/90  Initial release date of BASCNVRT.EXE
  228.                Original GW-BASIC to QuickBASIC conversion
  229.                program.
  230.      01/15/91  Release of BASIC2QB.EXE 1.1 
  231.                Fixed minor bugs in REM and RETURN statement
  232.                handling, tabs in source code are now recognized,
  233.                and a few of the little things are neater.  Very
  234.                limited because the code still had some unworkable
  235.                bugs.
  236.      06/25/91  Release of BASIC2QB.EXE 2.0 
  237.                Improved error- and statement-handling routines
  238.                and vastly improved operation.
  239.  
  240. IX.  Final Notes
  241.  
  242.      THIS PROGRAM IS DISTRIBUTED UNDER THE SHAREWARE CONCEPT
  243.             IT IS NOT FREE OR PUBLIC DOMAIN SOFTWARE
  244.            USERS ARE REQUIRED TO REGISTER THEIR COPIES
  245.  
  246.      THIS SOFTWARE IS DISTRIBUTED "AS IS" WITH NO WARRANTY OR
  247.      GUARANTEE OF ANY KIND.  USE OF THIS PRODUCT IS ALLOWED WITH
  248.      THE UNDERSTANDING THAT THE AUTHOR WILL BE HELD IN NO WAY
  249.      RESPONSIBLE FOR ANY LOSS OR DAMAGE RESULTING FROM THE USE OF
  250.      THIS SOFTWARE OR ANY SOURCE CODE GENERATED BY IT.  ALTHOUGH
  251.      EVERY EFFORT HAS BEEN MADE TO INSURE THAT THE OUTPUT SOURCE
  252.      CODE IS AS COMPLETE AND ERROR-FREE AS POSSIBLE, NO WARRANTY
  253.      OR GUARANTEE IS MADE OVER THE CORRECTNESS OR COMPLETENESS OF
  254.      ANY SOURCE CODE PRODUCED BY THIS PRODUCT.  (In simple terms
  255.      this means that if you suffer a loss through the use of this
  256.      software or any code generated by it, it's not my fault.  It
  257.      is also up to you to verify the accuracy of the source code
  258.      generated by BASIC2QB.)
  259.  
  260.           If you have any questions or problems with the use of
  261.      this software, or suggestions for improvement in the
  262.      documentation or software, contact me through CompuServe,
  263.      Delphi, GEnie, PC-Link or directly:
  264.  
  265.                       Michael M. Slivkoff  
  266.                   11033 Edgepark Court Apt. 201
  267.                        Manassas, VA 22110
  268.                    (703) 257-0030 (Voice Only)
  269.  
  270.                  CompuServe User ID:  73020,132
  271.                     Delphi Username:  KGBMAN
  272.               GE Mail Address (GEnie):  M.SLIVKOFF2
  273.                       PC-Link ID:  Mikey58
  274.  
  275.      BASCNVRT.EXE and BASIC2QB.EXE Version 1.1 were written in
  276.      QuickBASIC 4.5 on a Tandy 1000A computer.  Version 2.0 was
  277.      written on a Tandy 1000TX computer.
  278.  
  279.      BASIC2QB.EXE and this file Copyright (c) 1989-1991 Michael
  280.      M. Slivkoff, All Rights Reserved.
  281.  
  282.           Tandy is a trademark of Tandy Corporation.  Microsoft
  283.      and GW-BASIC are registered trademarks of Microsoft
  284.      Corporation.  IBM is a registered trademark of International
  285.      Business Machines Corporation.  XT and AT are trademarks of
  286.      International Business Machines Corporation.  CompuServe is
  287.      a registered mark of CompuServe Incorporated.  Delphi is a
  288.      trademark of General Videotex Corporation.  GEnie(sm) is a
  289.      service mark of GE Information Services.  PC-Link is a
  290.      service mark of Quantum Computer Services, Inc.
  291.                     REGISTRATION FOR BASIC2QB
  292.  
  293.      Send this form and $10 (check or money order) to:
  294.  
  295.                        Michael M. Slivkoff
  296.                   11033 Edgepark Court Apt. 201
  297.                        Manassas, VA 22110
  298.  
  299.      Name:  ____________________________________________________
  300.  
  301.      Address:  ________________________________  Apt No:   _____
  302.  
  303.      City:  ___________________  State:  ____  Zip:  ___________ 
  304.  
  305.      Telephone (Voice):  (______) ______-________
  306.  
  307.                 (Data):  (______) ______-________
  308.  
  309.  
  310.      Comments, questions, suggestions or complaints about
  311.      BASIC2QB:
  312.