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

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 ,,


Switches: none

Source default: entry.ASC
Destination default: entry.BAS
Alias file default: entry.AKA

---------------------------------------------------------------------

STRIP ,/O


Switches: O - optimize lines

Source default: entry.ASC
Destination default: entry.BAS

---------------------------------------------------------------------

LIST ,/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 ,/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