Programmer 7500

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

/ Programmer 7500 / MAX_PROGRAMMERS.iso / INFO / BASIC / SWISS.ZIP / SWISS.TXT < prev next >

Wrap

Text File | 1985-01-05 | 30.8 KB | 1,055 lines

===================================================== SWISS ARMY KNIFE BASIC Programming Tools for the IBM Personal Computer Version 1.0.0 ===================================================== Copyright (C) 1984, John R. Layman. All rights reserved. Layman & Layman 1344 Blair House Columbus, OH 43220 CompuServe 75216,3557 Swiss Army Knife User's Guide Table of Contents Introduction 2 Description of ALIAS utility 3 Description of STRIP utility 4 Description of LIST utility 6 Description of XREF utility 7 Description of BOXER program 9 Operating Instructions 10 Error Messages 12 User-supported Concept 14 Permission to Copy 15 29-Dec-84 Page 1 of 15 Swiss Army Knife User's Guide INTRODUCTION The Swiss Army Knife is an aid to BASIC programming on the IBM PC and look-alikes. Its blades are utility programs which provide: program compaction line optimization alias substitution formatted program listing cross-reference generation These tools allow you to: * dramatically improve the performance of your programs. * write larger programs than are possible using BASIC alone. * program using meaningful variable names and sound programming style without being penalized by the BASIC interpreter. * print neatly formatted program listings, including an optional cross-reference of critical program elements. In short, this is the basic tool kit for BASIC programming. The utilities which make up The Swiss Army Knife are written in BASIC and compiled with the IBM BASIC Compiler. They are readily portable to any system which uses Microsoft's GW-BASIC, and because the source code is available to users, you can tailor them to suit any special need you may have. You will find the internals to be of superior quality; professional software, available in "user-supported" form. 05-Jan-85 Page 2 of 15 Swiss Army Knife User's Guide ALIAS You can use ALIAS to replace long variable names with short aliases. Doing so improves the performance of an interpreted BASIC program without sacrificing the clarity of its source form. Using ALIAS to rename variables is particularly effective when you run it prior to compacting and optimizing the program using the STRIP utility. To use ALIAS you must prepare a list of the variable names you wish to change and the aliases which are to be given. You may rename all variables, or just a select few. You may also assign the same alias to more than one variable. This flexibility allows you to tune the performance of your program. It also permits you to leave certain names unchanged (such as those in COMMON), or to separately process segments of a program which are to be MERGEd at execution time. The alias list is an ASCII text file. Each line in the file contains a variable name and its alias (an "alias pair"). For example: ITEM.DESCRIPTION$=D$ is an alias pair which instructs the utility to substitute the alias, D$, for every occurrence of the string name, ITEM.DESCRIPTION$. An alias may be a literal, rather than a variable name. This allows you to replace variables with constants, such as: TRUE=-1 or ARRAY.SIZE=500 or PROGRAM$="PAY010 vn 1.0" This capability is useful for both interpreted and compiled programs. The BASIC Compiler often generates considerably more efficient and concise code when literals are used. ALIAS has the following characteristics and restrictions: * The alias list may be in any sequence. * The utility is unable to differentiate between subscripted and unsubscripted variables of the same name. * You are responsible for ensuring that aliases do not violate any variable naming scheme which uses the DEFINT, DEFSNG, DEFDBL, or DEFSTR instructions, and that the alias list contains no errors of explicit typing (e.g. ADDRESS$=A!). * At termination, a line count and byte length are displayed for both input and output files. The length shown is that of the ASCII text; not the size of the tokened form of the program. 05-Jan-85 Page 3 of 15 Swiss Army Knife User's Guide STRIP STRIP is a program compactor. It condenses a BASIC program so that it will load and execute more efficiently and require less disk space. By using STRIP, you can write well-organized, well-formatted programs without being penalized by the overhead inherent in inter- preted execution. You can also use this utility to reduce the size of compiled BASIC programs. You normally compact a program after you have tested it and are ready to place it into production. The compaction process is similar to compilation in that it produces an "object" version of the program which is distinct from the "source" version. Compaction is most effective when you assign aliases beforehand using the ALIAS utility. No special preparation is required to make a program compactable, but you must observe one restriction: do not use comment lines as the destination of line-referencing statements such as GOTO or GOSUB. The reason for this restriction is explained below. STRIP condenses a program by removing insignificant spaces, words, and symbols. Full comment lines are deleted, and comments or REMs which appear at the right of a line are discarded. Notice that full REM lines are left in place so that they can be used as pseudo tags (the destination of line-referencing statements), or for permanent remark text such as a copyright notice. Note that the term "comment line" is used here to mean only those remark lines which are defined by the single quote (apostrophe) character. STRIP includes an optional line optimization feature. This feature combines the lines in a program, wherever possible, to reduce its overall size. The BASIC interpreter uses an efficient scheme for managing program lines, and it is not particularly sensitive to the number of lines in a program. The primary advantage of optimization lies in reducing the size of a program rather than in improving its performance. Some options of the BASIC Compiler generate extra code for each program line, so it is frequently advantageous to optimize a program prior to compiling it. STRIP has these additional characteristics and restrictions: * References to nonexistent lines are considered legitimate and are ignored. This makes it possible for you to independently compact program fragments and subroutines. 05-Jan-85 Page 4 of 15 Swiss Army Knife User's Guide * Those BASIC instructions which are normally used only in the direct mode (e.g. AUTO, EDIT, LIST, LLIST, RENUM) are not recognized as line referencing statements. STRIP may eliminate lines which are referred to by these statements if you optimize a program which includes them. * The line optimization feature increases the run time of the utility because it requires a preliminary pass of the source program. * Line optimization will not combine DATA statements, even when they adjoin. The DATA keyword will be repeated for each statement. * The anomalous syntax of the DATA statement is ignored. Any series of spaces that occur within an alphanumeric data constant which is not surrounded by quotes will be reduced to a single space. You can avoid this by always using quotes for such constants. * At termination, a line count and byte length are displayed for both input and output files. The length shown is that of the ASCII text; not the size of the tokened form of the program. 05-Jan-85 Page 5 of 15 Swiss Army Knife User's Guide LIST LIST produces a formatted program listing which you can control by observing certain source code conventions. These are: * If the first line of the program is a REM of 40 characters or less, the text of the REM is used as a page heading. Otherwise, the file name is used. * REM lines and comment lines which contain a caret (^) as the first comment character are preceded by a page change. * REM lines and comment lines are printed in bold-face on standard IBM dot matrix printers or compatibles. * Comments can be boxed using frames of line graphics characters in the configuration (shown as ASCII values): [218][196]...[196][191] [179] text here [179] [192][196]...[196][217] These boxes print size-as, double-width, or compressed, depending on the length of the comment line. If it fits within 80 positions with the framed portion enlarged, the box is printed double-width (the remainder of the line prints at normal pitch). If the line is between 80 and 132 characters long, the entire line is compressed. Otherwise, the line prints at normal pitch. Boxes can be printed only on standard IBM dot matrix printers or compatibles. Original IBM 80cps and Epson MX80 printers without the Graftrax option cannot print the actual frame characters. For these printers, LIST translates the displayable frame characters into their printable counterparts. LIST splits long lines at rational breaking points and indents the continuation according to the indentation of the base of the line. It does not impose any indentation or formatting scheme. When you edit a long line so that there is enough white space at the breaking point to naturally indent the continuation, LIST will print the line just as it appears when listed by the interpreter. At run time, you can stipulate that line numbers are to be aligned on their units position (i.e. right-justified as 5-digits). LIST and XREF may automatically be run in tandem, producing a single output file. 05-Jan-85 Page 6 of 15 Swiss Army Knife User's Guide XREF XREF produces a cross-reference listing of the variable names and line numbers used in a program. Optionally, you can expand this listing to include reserved words and/or literals. XREF has the following characteristics and restrictions: * If the first line of the program is a REM of 40 characters or less, the text of the REM is used as a page heading. Otherwise, the file name is used. * Symbols print in emphasized mode and references print in compressed mode on standard IBM dot matrix printers or compatibles. * Each category of symbols is listed separately (i.e. variable names, line numbers, reserved words, numeric literals, string literals). * Line numbers appear with a "#" prefix and are correctly ordered in numeric sequence (e.g. #50 precedes #100). Numeric literals appear in alphabetic sequence (e.g. 100 precedes 50). * BASIC instructions which are normally used only in direct mode are not recognized as reserved words or line referencing statements. These include AUTO, EDIT, LIST, LLIST, RENUM, and the like. * Unary minus (negation) is not recognized. References to a negative numeric literal will appear as references to the absolute value of the literal. There is no restriction on the size of the subject program. If the internal data structures used to develop the cross-reference become saturated, XREF will open scratch files on the default drive to hold the overflow. Since disk accesses noticably degrade the throughput of the utility, you may wish to operate from a RAM disk when creating a voluminous cross-reference. (The capacities of the current version are: symbol tree = 200, reference list = 2,000. These permit XREF to be run on a 64k machine. You may wish to enlarge the arrays which comprise these data structures to take advantage of more memory.) XREF can automatically be run in tandem with LIST, producing a single output file. 05-Jan-85 Page 7 of 15 Swiss Army Knife User's Guide RESERVED WORDS To distinguish between variable names and reserved words, XREF uses a reserved word list. The list is external to the utility so that you can modify it to adapt to changes in BASIC or for your own special purposes. The list supplied with XREF is for BASIC Release 2.0. It includes such words as TIMER and WINDOW, which were not reserved in earlier versions. It also includes ABSOLUTE, a word reserved only by the BASIC Compiler. The list purposely excludes the names of BASIC's special variables; these include ERR, ERL, DATE$ and TIME$. You may add these to the list if you don't wish them to be listed as variable names. The list resides in the file named XREF.RSV. This is a simple ASCII text file which you can display using the DOS TYPE command. You can also edit this file using EDLIN or any other text editor which can handle DOS files. The list is required to be in alphabetic order and is limited to a maximum of 175 words in the delivered version of the program. While it is possible for you to tailor the reserved word list, there are potential undesirable side-effects to changing the list. XREF's lexical scan is not driven by a formal syntax, and its ability to recognize context can be damaged when certain key words are removed from the list. The effects of such damage could range from subtle (e.g. inability to determine the sense of the ambiguous word AS) to quite severe (e.g. unrecognized DATA statements). Clearly, it is safest to use the list as supplied. If you do decide to alter the list, be certain to preserve a copy of the original as a precaution. And remember that it is more blessed to add than to delete. 05-Jan-85 Page 8 of 15 Swiss Army Knife User's Guide BOXER You can use BOXER to frame your program comments. Framed comments (or "boxes") are an effective, professional way to present program preambles, module headings, copyright notices, and the like. The LIST utility recognizes these boxes and prints them in normal, double- width, or compressed mode, depending on their size (refer to LIST for a detailed description of these print conventions). BOXER accepts a single line of text and constructs a five-line series of comments which contains the framed text. By manipulating these lines with the BASIC editor, you can enlarge the frame to any size. You must run BOXER from the BASIC interpreter. The program asks for the starting line number, the line numbering increment, and the text string. There is no default starting line number, so you must enter the number of the first line. The default increment is 10. If you do not enter any text, the program will construct a frame which can accomodate 60 characters per line. When BOXER terminates, it clears itself from memory. You must then move the cursor to each line, in turn, and press the [Enter] key to actually place the lines into the interpreter's program space. Once all of the lines have been entered, they can be SAVEd or MERGEd with your source program. 05-Jan-85 Page 9 of 15 Swiss Army Knife User's Guide OPERATING INSTRUCTIONS The utilities in The Swiss Army Knife deal with ASCII text files, not with BASIC's shorthand tokened form. Input program files must have been written to disk using the ",A" variant of the SAVE command, and it is necessary to LOAD and SAVE an output file to convert it to tokened BASIC. All source lines must be acceptable to the BASIC interpreter. The BASIC Compiler language extensions are not recognized. The utilities (except for BOXER) are invoked from the DOS prompt, and use the same conventions for command line and switch settings as are used in other standard language facilities such as the assembler and the BASIC Compiler. A command line may consist only of the name of the called utility, or it may include a list of the file names to be used and/or switch settings to invoke optional features. When all files are not explicitly specified in the command and the file list ends with a semicolon, the remaining unspecified files will default without further prompting. When the file list does not end with a semicolon, the utilities will prompt for the unspecified files. A null source file name will always result in a prompt. The switches are never prompted for, but may be appended to the command line or to any file specification entered in response to a prompt. Because of the limitations of IBM's BASIC Compiler, the utilities do not recognize path names. A disk files must reside in the current directory of its particular disk. A device name may be substituted for a file name. The utilities require that device names be ended with a colon (e.g. PRN:). COMn: files are not supported. When specifying print ouptut from LIST and XREF, it may be necessary to indicate a printer type. The default type is 0, which is treated as a crude device having only a Form Feed capability. The original IBM 80cps printer and MX80 (without Graftrax) are printer type 1. The IBM graphics printer and later Epson models are printer type 2. There is no configuration facility for setting a standard printer type. Types other than zero must be specified each time one of these utilities is run. You can avoid this inconvenience by setting up a batch file to call these utilities, with the appropriate printer type specified in the batch command which calls the program. 05-Jan-85 Page 10 of 15 Swiss Army Knife User's Guide COMMAND LINE FORMATS --------------------------------------------------------------------- ALIAS <source>,<destination>,<aliases> Switches: none Source default: entry.ASC Destination default: entry.BAS Alias file default: entry.AKA --------------------------------------------------------------------- STRIP <source>,<destination>/O Switches: O - optimize lines Source default: entry.ASC Destination default: entry.BAS --------------------------------------------------------------------- LIST <source>,<printout>/n/A/X/R/L Switches: n - printer type (0..2) A - align line numbers X - print cross-reference R - include reserved words in cross-reference * L - include literals in cross-reference * * (X switch unnecessary with R and/or L) Source default: entry.ASC Printout default: LPT1: --------------------------------------------------------------------- XREF <source>,<printout>/n/R/L Switches: n - printer type (0..2) R - include reserved words in cross-reference L - include literals in cross-reference Source default: entry.ASC Printout default: LPT1: --------------------------------------------------------------------- 05-Jan-85 Page 11 of 15 Swiss Army Knife User's Guide ERROR MESSAGES Error messages are, for the most part, identical to the messages produced by the BASIC interpreter. The errors fall into three classes, shown below by example: 1) Disk not ready. Correct condition; then press any key: This is an example of a correctable condition. You should correct the fault and press a key to re-attempt the failed operation. You may also enter Ctrl/Break to abort the program. 2) Bad file mode. Unrecoverable. This is an example of a condition that cannot be corrected while the utility is loaded. The program will self-abort. You must correct the problem before retrying the utility. In the example above, you would have to convert the tokened program to an ASCII text file. 3) Error 2 at 6450. Unrecoverable. This is an example of an unexpected error. Such errors are fatal and may indicate a bug in the utility. If you should encounter such a failure, please mail a written description of your problem to Layman & Layman. Please include your name, address, and phone number, along with any pertinent supporting information. The following non-standard errors may also occur. All are Class 2. Bad switch. An unexpected switch appears in the DOS command line. Unrecognized line format. A source line has been encountered which does not have the form of an interpretive BASIC line. The progress monitor display shows the point at which the error occurred. Line out of sequence. Source line numbers are not in sequence. The progress monitor display indicates the location of the error. (continued on next page) 05-Jan-85 Page 12 of 15 Swiss Army Knife User's Guide ERROR MESSAGES (continued) Alias pair format error. An entry in the alias file does not have the expected A=B form. Alias table saturated. The limit of 3,000 aliases has been exceeded. Break table saturated. The optimizers limit of 9,000 referenced lines has been exceeded. Too many words. The limit of 175 reserved words has been exceeded. Word out of sequence. The reserved word list is not in alphabetic order. 05-Jan-85 Page 13 of 15 Swiss Army Knife User's Guide USER-SUPPORTED SOFTWARE --------------------------------------------------------------------- If you have received a copy of this suite of utility programs and have found it to be of value, your $35 contribution will be greatly appreciated. Layman & Layman 1344 Blair House Court Columbus, OH 43220 Whether or not you make a contribution, you are encouraged to copy the program for evaluation by other users. --------------------------------------------------------------------- The Swiss Army Knife is part of the growing body of "user-supported" software. User-supported software is an experiment in distributing computer programs, based on these principles: 1. The value and utility of software can best be assessed by the user on his/her own system. 2. The creation of personal computer software should be encouraged and supported by the computing community. 3. The copying of programs for evaluation should be encouraged, rather than restricted. Under this concept, anyone may request a copy of user-supported software by sending a blank, formatted diskette to the author, along with a self-addressed, postage-paid return mailer. A copy of the software and documentation will be placed on the diskette and sent by return mail. (Note: two single-sided, double-density diskettes are required to contain both object and source code). A second way to obtain an copy of the software is from a friend, a computer club, or bulletin board. After you have had an opportunity to evaluate the software, you are trusted to either forward payment to the author, or to discontinue use of the software. Free distribution of software and voluntary payment for its use eliminates the normal costs of promotion and distribution. Users obtain quality software at reduced cost. They try it out before buying, doing so at their own pace, and in the comfort of their home or office. The best programs will survive and thrive, based purely on their quality and usefulness. This honor system benefits the entire personal computer community. If you believe in these ideals, your contribution is solicited to help make them work. Please join the experiment. 05-Jan-85 Page 14 of 15 Swiss Army Knife User's Guide NOTICE: The Swiss Army Knife is a proprietary software product of Layman & Layman, protected under Title 17, USC, Copyrights. Limited license is granted to users of this product to reproduce or transmit the software on a private, non-commercial basis for the purpose of evaluation by prospective users. This license explicitly excludes: 1. distribution in a modified form. 2. distribution for consideration other than media or handling costs. 3. distribution in connection with any other product, except with the express written consent of Layman & Layman. 05-Jan-85 Page 15 of 15