BBC BASIC Utility commands ========================== J.G.Harston - jgh@mdfs.net 70 Camm Street, Walkley, Sheffield, S6 3TR Most of these utilities have an embedded version number or date in them. If you *DUMP them, you can check the version to see if it's newer than a version you already have. *Assem Assemble from multiple files v1.16 ---------------------------------------------------------------------------- When writing very long machine code programs (eg ROMs, etc.) using the in-built BASIC assembler, there comes a point where you cannot fit both the source code and the generated object code into the machine memory at the same time. The *Assem command allows you to assemble from files rather from the program in memory. The source files can be BASIC files or text files and must be laid out the same as a BASIC source file. One file can link to another one by the last line being: >filename Two passes are made through the source files as usual. *Assem does not save the object code for you, the source code must save the resultant object code itself with the normal *SAVE commands. Only runs on BBC without Tube. *BDiff Difference between BASIC files 0.01 ---------------------------------------------------------------------------- Lists the difference between two BASIC files. *BList (-) List saved BASIC file v1.13 ---------------------------------------------------------------------------- *BList lists a BASIC file in a similar way that *LIST lists a text file. If the '-' option is used then lines numbers are omitted. *BList ensures that LFs are not sent to any SPOOL file, so it can be used to create a text version of a BASIC file with, for example: OSCLI"Spool PROG/BAS":OSCLI "BList PROG":*Spool Runs with all versions of BASIC from either side of any Tube. *Chain CHAIN BASIC file 0.01 ---------------------------------------------------------------------------- *Chain loads and runs a BBC BASIC file as though run with CHAIN from the BASIC prompt. Works on on BBC computer on either side of any Tube processor. *Crunch Crunch BASIC program in memory 1.05 ---------------------------------------------------------------------------- This crunches the 6502 BBC BASIC program in memory. It does this by removing the following: - all REMs - all assember \ or ; comments - lines starting with a | character - all empty lines - all superflous colons - all spaces before and after tokens - all spaces before and after statements It does not crunch variable names, or remove spaces within statements that are not adjacent to a token. Also, no check is made that an empty line is not a destination of a GOTO/GOSUB/RESTORE, so make sure they refer to a non-empty line. Note that crunching a program can make it completely uneditable, so you should save the resulting program as a different file to the source code. If you run *Crunch from an executing program you will get unpredicatable errors as the program gets moved while the command is executing. *Crunch is ideal to use as part of a build sequence to build a BASIC program from multiple source files. Runs on 6502 BBC BASIC on either side of the Tube. *Link Link BASIC program in memory 1.03 ---------------------------------------------------------------------------- *Link does the equivalent of the "link" stage of machine code compilers where a finished program is built from several source files. It scans through the 6502 BBC BASIC program in memory and removes unused and duplicate DEFPROCs and DEFFNs. This allows you to build a BASIC program from libraries of common code, and use *Link to remove the subroutines in the library that the program does not use. *Link removes all DEFPROCs and DEFFNs where there is no matching PROC or FN in the program. Sometimes you need a subroutine to remain in the program when there is no FN or PROC in the program code, such as where you create a function to call with EVAL, eg A%=EVAL("FN_"+STR$K%). You can tell *Link to keep the subroutine by putting the tokenised function name in an unused part of the program. The easiest way to do this is to put it in a semicolon command, and then remove the comment with *Crunch, for example: ; Keep FN_00, FN_40, FN_80, FN_C0 DEFFN_00 ... etc. The comment must not be a REM as the FN/PROC tokens are not tokenised in a REM statement. A ';', '\' or '|' is a suitable comment that tokenises the line, and is stripped out by *Crunch. If you run *Link from an executing program you will get unpredicatable errors as the program gets moved while the command is executing. Runs on 6502 BBC BASIC on either side of the Tube. *MCode () Makes BASIC program *RUNable v1.35 ---------------------------------------------------------------------------- Adds a machine code footer to a BASIC program so it can be called with *RUN. If an address is given, it is used as the file's load address, otherwise the file relocates down to the value of PAGE when run. On running, the program has Q% set to the original PAGE, and the full command line, including the command used to start the program, is placed in the general string accumulator, (at $&600 in 6502 BBC BASIC) where it can be retrieved with the standard FNOS_GetEnv function. To exit to the previous environment if no -quit processing is carried out, the program can use: PAGE=Q%:END MCoded programs will run in a standalone I/O processor or will copy over the Tube to whatever language processor is being used. Note, that if the MCoded program itself relies on specifiy CPU facilities, such as the 6502 assembler, then it will only run on that appropriate second processor. *MCode itself, as it assembles a piece of 6502 code, will only work on a BBC or 6502 CoPro, and will give an appropriate error in other CPU environments. *Repair Repair a Bad program v1.02 ---------------------------------------------------------------------------- Attempts to repair a bad program in memory, prompting you through the actual repair. Runs on 6502 BASIC on either side of the Tube. *VList List out variables v1.12 ---------------------------------------------------------------------------- Lists out the variables currently defined in BASIC. Runs on 6502 BASIC on either side of the Tube. Building BASIC programs from multiple files =========================================== The *Link command makes it easy to build a BASIC program from multiple source files, such as libraries of common routines. The *Crunch command can then be used to create a compact executable, and the *MCode command can be used to allow the final program to be *RUN. The BBCUnZip program uses the following build file, called MkUnZip: *Basic *| Make UnZip command *Access UnZip_ wr/r LO."UnZip/src" OS."LOAD %.BLib.Close "+STR$~(TOP-2):END OS."LOAD %.BLib.ProgEnv "+STR$~(TOP-2):END OS."LOAD %.BLib.CmdLine "+STR$~(TOP-2):END OS."LOAD %.BLib.Number "+STR$~(TOP-2):END OS."LOAD %.BLib.FileIO "+STR$~(TOP-2):END OS."LOAD %.BLib.Generic.NetFS "+STR$~(TOP-2):END *LINK *CRUNCH 1REM > UnZip v1.10 REN. SA."UnZip_" *MCode UnZip_ It is built by typing *Exec MkUnZip which then builds the program by loading the core code "UnZip/src", then adding several libraries to the end of the program. *LINK then removes from the program the routines in the libraries that the program doesn't actually uses, then *CRUNCH crunches down the program. A comment is added as the first line labelling the program, it is renumbered and saved. Finally, the *MCODE command adds some code to make it *RUNable. Building programs like this has multiple advantages. It allows you to build up libraries of common code and reuse them without having to re-invent them or retype them into new programs. It also allows you to be more free-flowing and copious with comments in the code, and it remains seperate from the final code that is run. If *Link finds duplicated DEFPROCs/DEFFNs, then the earlier definitions are removed, and the later one is kept. If your source files have duplicate subroutines, and there is one definition that you want to take priority over the others, put it later in the build list. If all the source files will not fit into memory before being crunched, then you can crunch them as you load them by replacing the END commands with *Crunch, for example: LO."UnZip/src" OS."LOAD %.BLib.Close "+STR$~(TOP-2):*CRUNCH OS."LOAD %.BLib.ProgEnv "+STR$~(TOP-2):*CRUNCH etc. Don't do this if you have comment-protected subroutine names to prevent *Link from removing them, as the comments will get removed before *Link can see them. Re-arrange the build order so that the source files with comment- protected subroutines are at the end of the build list just before *Link then the final *Crunch, for example: *Basic *| Make UnZip command *Access UnZip_ wr/r LO."UnZip/src" OS."LOAD %.BLib.Close "+STR$~(TOP-2):*CRUNCH OS."LOAD %.BLib.ProgEnv "+STR$~(TOP-2):*CRUNCH OS."LOAD %.BLib.CmdLine "+STR$~(TOP-2):*CRUNCH OS."LOAD %.BLib.Number "+STR$~(TOP-2):*CRUNCH OS."LOAD %.BLib.FileIO "+STR$~(TOP-2):END:REM Don't strip ;comments OS."LOAD %.BLib.Generic.NetFS "+STR$~(TOP-2):END:REM Don't strip ;comments *LINK *CRUNCH 1REM > UnZip v1.10 REN. SA."UnZip_" *MCode UnZip_