Merging modules
Programming How-To - Merging in Modules
The following notes are intended to help you when merging an optional "spare command" module into your Color 64 overlays.
- 1) Make sure that the module was written for your BBS program version. If it is for a previous version, then you will need to find the correct version of the module or use the included module converter program (see the section on the module converter in the upgrade documentation).
- 2) Load a programmer’s utility. Good options are BAID64, since it is in the public domain, and it does a true merge (not just an append), and Solidus SYSRES.
- 3) Make sure the module that you are going to merge will not overwrite any lines already existing in the intended overlay program. Just load the overlay program and list the line range used by the module and if you don't see anything... it is ok. If not, consider placing the module in one of the other overlays. The exception to this case is if the module was intended to replace some of the standard BBS routines.
- Once you have determined that the module will not overwrite any existing code, just enter the following command (this is for BAID64): merge "module/name"
- Make sure that the BBS overlay program is already in memory. In just a few moments, the lines from the module will be merged with your system overlay file.
- 4) The next thing you need to do is to modify the code so that one of the spare commands will execute the module. There are 9 spare commands available in Color 64 BBS. Each of these spare commands will load a pre-defined overlay file and execute a pre-defined line number. The table below summarizes the defined overlays and lines executed for spare commands 1-9. Note that Spare 1 and Spare 2 are in use for Color 64 v8.10a:
| Spare Assignment | Overlay Assignment | Line Execution |
|---|---|---|
| Spare 1 (games) | √bbs.msgs | 13430 |
| Spare 2 (user profile) | √bbs.xfer | 13440 |
| Spare 3 | √bbs.ovl | 13450 |
| Spare 4 | √bbs.ov2 | 13455 |
| Spare 5 | √bbs.ov3 | 13460 |
| Spare 6 | √bbs.ovl | 13465 |
| Spare 7 | √bbs.ovl | 13470 |
| Spare 8 | √bbs.ovl | 13475 |
| Spare 9 | √bbs.ovl | 13480 |
As you may notice, there is only one spare command pointing to √bbs.ov2 and √bbs.ov3. I intended that these overlays be used by modules that would require the whole overlay (like the included Mod Menu program), or that you use a menu program to access several subprograms in the same overlay.
You will need to modify the spare line at the appropriate line number based on the overlay program you are merging with. When you list 13430-13480, you will see the available space command lines for the overlay program loaded into memory. They look like:
134xx goto13100:rem spare x
You will not see all the lines in the above table, just the lines that apply for the overlay program you have loaded. You will want to use the insert key to push the "goto13100" over and enter a gosub pointing to your newly merged module. Example:
134xx gosubxxxxx:goto13100:rem spare x
- 1) Save this modified version of your overlay program back onto the disk. If you list line 1 of the program, then delete "1 rem" and hit return, the line will automatically scratch the old overlay program and then save your modified version on your disk. After it is saved, do a directory to see the size of the new file. This file must always be smaller than the √bbs.init overlay. If the file is too large, you will need to use a different overlay or take something else out of this overlay.
- 2) Run the SETUP program and edit the BBS Commands section. In this section, you will want to set the access level for the intended spare command to the desired value. You can also change the command key required to execute the module. If you do change the command, make sure you don’t select a command that is already used.
Well, that will do it. You may want to write down the line numbers occupied by this module so that if you decide to remove it to make space for another one you will know exactly which lines to delete (using your programming utility - like SYSRES or BAID64) and to change the spare command line back to normal.
Next Section: Tools