7.37 Module Conversion

Conversion - Converting 7.37 modules to 8.10a

Converting BASIC Code

This section is intended for SYSOPs who want to convert old version 7.37 and Super ML merge-in code to version 8.0 and above. Also, those who were running separate overlay modules through a menu will want to read this section.

Starting with Color 64 version 8.0 the traditional SYSC(x) and PEEK(C(x)) methods of interfacing with the ML have been completely replaced. These methods were fine for when the system was simpler but would not be able to adequately handle more complex features like SwiftLink compatibility. For this reason, BASIC was modified to interpret new commands when the ML is active.

In the 8.X versions, the ML interface is divided into "commands" and "variables". The ML commands all begin with a "." period character. For example, the equivalent of the SYSC(5) command is .01 (get line of disk input).

The ML variables can be used in expressions just like normal BASIC variables but are defined differently. All ML variables begin with the "!" exclamation point character and are followed by two digits. For example, the equivalent of PEEK(C(22)) is the ML variable !05 (graphics mode). To assign values to these ML variables, a format like the POKE command is used. For example, the equivalent of POKE(C(35)),9 would be !14,9 (set file device number to 9).

The table below redefines the old C(X) references to their new substitutions. Note that more than a few references are now obsolete, and no substitution is listed. Also, the old output commands like SYSC(0) have been replaced by special one-character commands like the "#" command. For more information on the ML commands and ML variables, consult the programming section.

Redefined SYSC(X) Calls to Special Character Command Reference
Old	New	Old	New	Old	New	Old	New	Old	New
C(0)	#	C(11)		C(22)	!05	C(33)	.11	C(44)	.14
C(1)	$	C(12)	!00	C(23)	!06	C(34)	!13	C(45)	.15
C(2)	!01	C(13)		C(24)	.07	C(35)	!14	C(46)	.16
C(3)	!02	C(14)		C(25)	%	C(36)	!15	C(47)	.17
C(4)	.00	C(15)		C(26)	&	C(37)	.12	C(48)	.18
C(5)	.01	C(16)	!07	C(27)	!10	C(38)	!16	C(49)	.19
C(6)	!04	C(17)		C(28)	!11	C(39)	!17	C(50)	!21
C(7)	!03	C(18)		C(29)		C(40)	!18	C(51)	!22
C(8)	.02	C(19)	.04	C(30)		C(41)	!19	C(52)
C(9)		C(20)	.05	C(31)	!12	C(42)	!20	C(53)
C(10)		C(21)	!09	C(32)	.10	C(43)	.13	C(54)

Converting BASIC Code

When you load a 7.37 module/program in, you will find the old “SYSC” and “PEEKC” calls which must be converted for the program to work with 8.0/8.1. This is a relatively easy task.

Step 1: For the module to be converted, determine the core source code. This is usually depicted by a GOSUB routine at line 5 (example: GOSUB 30000). If it is just some sort of mod that updates existing overlay code, then this step may not be applicable (as well as step 2)

Here the GOSUB we are seeing is line 30000, so the "core code" should be starting there (sometimes they may sneak in lines before that you might have to copy over).

Step 2: Delete all other code except the core code. In this case, we are deleting code up to 29999, keeping the lines 30000 and beyond.

SYSRES users: “delete0-29999”

LTK users: "del 0-29999"

Step 3: Begin replacement of SYSC and PEEKC statements using the conversion chart as the replacement code for these statements

Conversion Chart
	SYSRES commands: 1. changec@sysc(0)@@#@ 2. changec@sysc(1)@@$@ 3. changec@sysc(5)@@.01@ 4. find@peekc(@ (find instances and change accordingly) example: pokec(23),0 would become… !06,0 5. Make sure you tackled all SYSC statements by searching for SYSC(: find@sysc(@

While there may be others, SYS(0), SYS(1), SYS(5), and PEEKC(23) are the most common.

Step 4: Save a temporary version of this core file

Step 5: Merge in Overlay 2 or the “XXX SMALL” overlay from 8.0 or 8.1 (whichever version applies)

SYSRES users: use MERGE command: merge “xxx small” (or overlay 2)

Step 6: Update line 5 of new file to jump to the module’s core code as noted in "Merging in Modules" section

Step 7: Save file and groom / clean up any other outliers.

From the above example I showed in Step 1, after I completed the merge, this was how the first few lines looked. In this example, I did change the "GOSUB30000" to "GOTO30000" only because it appeared the game did not do a proper exit (left the GOSUB on the stack).

Note that once you are complete and program seems to be functioning, you can further refine how the old 7.37 statements are listed out. In most cases:

a$=”something”:# becomes #"something"

a$=”something”+cr$+str$(ba)+na$+i$ becomes #”something”cr$bana$i$

a$=”Do you want something?”:$ becomes $”Do you want something?”

Note that if the a$ in the code is using the same information for the caller log (look for a gosub8004 nearby), then you would not want to perform the above refinement of that particular instance.

Look around for other modifications. Another thing I’ve noticed - particularly in games - is that the programmers use a LOT of replicative code. If I see a statement that looks familiar, I can use SYSRES and see where those instances are and create a subroutine to consolidate:

Example - we have the following code:

30050 #"Okay! Let's do that":gosub31000:gosub32000:goto30000 
30XXX …. other lines of stuff 
30600 #"No? All right then":gosub31000:gosub32000:goto30000

For SYSRES users, you can find the instances using find@gosub31000:gosub32000:goto30000@

We can add a routine in a good spot and consolidate:

30500 #"Okay! Let's do that":goto50000 
30XXX …. other lines of stuff 
30600 #"No? All right then":goto50000 
50000 gosub31000:gosub32000:goto30000

And for SYSRES users, it’s even better with: changec@gosub31000:gosub32000:goto30000@@goto50000@

** just note that this would also change line 50000 as well. You would need to change it somehow so it would not qualify. I typically would add an extra “b” to “gosub”:

50000 gosubb31000:gosub32000….

and then change it back after you do the replacements.

Another point on 7.37 conversions is to make sure the file calls are going to the places you want them to. Games, REL files, SEQ file calls – if you have placed them somewhere other than what the game is expecting, you have to update those calls. Data calls in particular are below:

and

So, my games are all stored in AUX 3. Those old 7.37 games loved the Systems file drive, so in the CORE code only, I would change all instances of GOSUB202 to GOSUB203 and GOSUB481 to H=14:GOSUB460 which points to AUX3. Make sure you do this only to the core code of the game! You don’t want to impact the rest of the lines contained in the overlay!

Changes from 7.37 to note

New Carrier Detect Test

One change is the way that the BBS program detects if the carrier is still present. The old method looked like this:

ifcd=(peek(56577)and16)thenprint"carrier lost!"

ifcd<>(peek(56577)and16)thenprint"carrier present"

The new method replaces these with an ML variable (!25) that is updated with the status of the carrier every 1/60th of a second. The reason this is done because the standard RS-232 routines and the SwiftLink RS-232 routines detect the carrier in much different ways; a simple PEEK will no longer work with both methods. Here is what the new method looks like:

if!25=0thenprint"carrier lost!"

if!25<>0thenprint"carrier present"

As you can see the new method is much easier to remember (and type!) than the old method.

New Modem Output Command

Another change involves the way that output is sent straight to the modem, and how characters are read in from the modem. In the old method, to print something straight to the modem, you would use the following format:

print#5,"atdt";p$

With the new method the command looks like this:

'"atdt";p$

In effect the new command is shorter and must be used because file number 5 is no longer opened when the BBS is in operation. This is to maintain compatibility with the new SwiftLink routines.

The New Modem Input Function

Finally, the way characters are read in from the modem has changed also. Here is the old format:

get#5,a$

The new method uses one of the built-in functions of the Color 64 ML. Here is an example of the new method:

a$=@4

The @4 function reads in a character from the modem and returns it as a string. For more information on the "'" apostrophe command and the @4 function, consult the programming documentation.

The Automatic Module Converter

Included with the Color 64 package is a program called "m-con 50000", which is an ML program that you can use to convert BASIC code from Color 64 version 7.37 and Super ML. This program was intended only to convert the small optional merge-ins for version 7.37 and Super ML, although you can use it to convert game and utility modules if you have a little programming skill. To use this program, you must load it into memory by using LOAD"m-con*",8,1. Then enter a NEW command to make sure that BASIC memory is cleared.

Once this program is in memory, all you need to do is load the BASIC program that you wish to convert, then type SYS50000 to start the conversion process. You don't need to load m-con again if the computer is turned on and you haven't used any programs that alter the memory where m-con resides.

M-con will convert all the SYSC(x), POKEC(x), and PEEK(C(x)) references, as well as the PRINT#5 statements that print output to the modem. M-con also converts the Super ML MCI commands and CTRL/O characters to the version 8.0 format.

Things that m-con cannot do is:

It cannot convert references to the old carrier detect test; this must be done manually (see above section on the new carrier detect test)
It cannot convert GET#5 statements used to read information straight in from the modem; this must be done manually (see above section on the new modem input function).

This conversion program cannot be used to convert an entire overlay, especially any of the main overlays--these must be totally replaced. However, if you have modules and games that are separate overlays, then there are a few requirements to convert them. The subroutines in lines 0 to 27000 are the core subroutines of any Color 64 overlay, and most of them have been revised with the new version, especially the caller log routine. To convert overlays that still have these lines, then you need to strip the lines out (being careful not to take any of the module with it), and then re-merge an appropriate "xxx" skeleton overlay into the module after using m-con to convert the older module. For most games and small modules, the "xxx small" overlay (weighing in at a small 13 blocks) is perfect for installing the necessary core subroutines. You should consult the programming section regarding these overlays for more information on their use.

SYSOPs who were using previous versions of the add-drive mod should also note that the "H" setting for the three auxiliary file groups is now 12, 13, and 14. This means that to select AUX 1, you would need to use H=12:GOSUB460. If you were using the old add-drive mode, you may need to change some of your overlays that selected AUX 1 with "H=11", because Network now uses that number to select the Network drive. Any easy way to convert to the new system would be to do this: For AUX 2 and AUX 3, all you will need to do is change the drive settings in SETUP so that they are now AUX 1 and AUX 2 (because they are already using H=12 and H=13), then change all references to "H=11" in modules to "H=14", and then configure AUX 3 in setup to what was once your AUX 1 files.

Note: The m-con program will convert all references to CTRL/A (the Super ML MCI character) inside of quotes to an english pound sign (the version 8.0 MCI character “£”), EXCEPT if the CTRL/A is part of a PRINT#15 statement. This is because programs that use relative files often use the CTRL/A character in the relative file position command sent to file number 15. If you are converting a program that uses relative files, then you may want to check all references to CTRL/A first to see if they will be used as part of a relative file command. If so, then just change these references to use CHR$(1) instead, so they will be protected during the conversion.