















                  =====================================================

                                    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
                                                                                                                                                                                          