UTILITIES by  Ron Wiesen 6/2/91

Described here are a utility "Backbone" and various general purpose utilities.  All are in BASIC. The utilities have mutually exclusive line numbers, and at least one line number common to the Backbone. Up to 198 utilities may be combined with the Backbone, thus the utility scheme consumes memory according to need. 

        Backbone
File "UTIL.DO" is the Backbone. It is the user interface to all utilities and its line numbers bracket the user as shown below:
  LINE 0 Transparent Backbone link
  LINE 1 - 54999 User program area
  LINE 65000 - 65529 Backbone/utilities
The Backbone has one built-in utility named "ULIST" which reports the presence of all utilities, including itself.

        Utility/Backbone Relationship
All utilities are ".DO" files. Each one has a "DATA name:READ:IF THEN line#" statement in one line number that is common to the Backbone. This line contains the utilities unique name and program control linkage. The line number is mutually exclusive to other utilities. When you MERGE a utility file, this line overlays one fo the Backbone lines within the range shown below:
  LINE 65101 - 65198 utility overlays
On demand, "ULIST" reads the names in this overlay area and reports all the utilities that you have MERGEd.
The executable statements of your utilities must be confined to lines within the range shown below:
  LINE 65201 - 65498 utility code area

        Utility/Backbone Error Control
The Backbone prints the standard BASIC errors as whole phrases, rather than 2-letter codes. It also has two errors of its own. Up to 19 of your utilities may have up to 10 error phrases each. The phrases are supplied as string items in a DATA line. The line is mutually exclusive to error DATA lines of other utilities. It overlays one of the Backbone lines within the range shown below:
  LINE 65510 - 65528 error overlays

        Variable Name Convention
All variable names that begin with "U" are reserved for utilities and the Backbone. The convention has three rules:

1. "U$" is the utility command string. A call to a utility is shown below:
        "U$=command string:GOSUB"
The command string contains from 1 to 10 arguments, the first one is the utility name. The GOSUB has no line number (BASIC defaults as 0) and refers to the Backbone which parses the arguments. One or more spaces delimit arguments. Alternately, you can use a pair of double quotes to bracket arguments that contain imbedded spaces (or are nul).

2.  All single-letter-U numeric variables (U%, U!, and U#) are used for numeric parameter exchange between the user and a utility.

3.  String parameter exchange is mediated by file buffers or filenames. Filenames of unopened files are supplied in the command string, or are implied. File buffer numbers of opened files are supplied in the command string (string equivalent) or in single-letter-U numeric variables.

Items 1, 2, and 3 above are the utilities external user interface. The utilities internal interface, important for inter-utility coordination, are "U$", "UB%", and arrays "U$()","UU$()", and "UU%()". Their use is shown below:
  U$  - command string (internal and external). Syntax is: [COMMAND NAME (1st argument)] [2nd ARGUMENT] ... [10th ARGUMENT]
  U$()  - parse of current command. Structure is shown below:
    U$(0) - n (# of arguments, 1 to 10)
    U$(1) - COMMAND NAME (1st argument)
    U$(2) - 2nd argument (if any)
     ...
    U$(n) - last argument (if any)
    U$(n+1) - nul
  UB%  - utility nest level (1 to 10). Utilities may call other utilities and can nest 10 deep. The Backbone advances UB% each time a utility is started and decreases UB% each time a utility finishes.
  UU$()  - command string stack. Structure is shown below:
    UU$(0) - user's command
    UU$(1) - 1st utility's command
     ...
    UU$(10) - 10th utility's command
  UU%()  - numeric parameter stack. Structure is shown below:
    UU%(0) - user's parameter
    UU%(1) - 1st utility's parameter
     ...
    UU%(10) - 10th utility's parameter

The Backbone/utilities use two-letter integer variables as shown below:
  UA% - Backbone active flag.
  UB% - utility nest level (1 to 10).
  UI% ... UP% - general purposes.
The Backbone saves/restores the user's DATA pointer in "UD!", thus all utilities may freely read data items.

        Utility Exit Requirements
The exit of a utility back to the Backbone two rules:
1. Unlike numeric parameters exchanged in floating point variables (U! and U#), the Backbone stacks integer parameters in array U%(). Any integer parameter returned by a utility (to user or prior utility) must be placed in the stack. The proper index is "UU%(UB%)".
2. Control returns to the Backbone by a "GOTO 65499" statement.