7.37 Module Conversion

Conversion - Converting 7.37 modules to 8.10a

Converting 7.37 Modules Overview

This section is intended for SYSOPs who want to convert older version 7.37 and Super ML merge-in code for use with version 8.0 and above. It is also relevant to SYSOPs who previously ran separate overlay modules through custom menus.

Beginning with Color 64 version 8.0, the traditional SYSC(x) and PEEK(C(x)) methods of interfacing with the ML were replaced. Those methods worked well when the system was simpler, but they were not flexible enough to support newer features such as SwiftLink compatibility. For this reason, BASIC was modified to interpret a new ML interface while the ML is active.

In the 8.x versions, the ML interface is divided into commands and variables.

The ML commands begin with a period (.). For example, the equivalent of the old SYSC(5) command is .01, which gets a line of disk input.

The ML variables can be used in expressions much like normal BASIC variables, but they are referenced differently. All ML variables begin with an exclamation point (!) followed by two digits. For example, the equivalent of PEEK(C(22)) is the ML variable !05 (graphics mode).

To assign values to ML variables, use a format similar to a POKE statement. For example, the equivalent of POKE(C(35)),9 would be:

!14,9

which sets the file device number to 9.

SYSC(X) and PEEK(C(X)) Conversions

The table below redefines the old C(X) references using their newer replacements. Note that several references are now obsolete and therefore have no direct substitution listed.

Also note that many of the old output-related calls such as SYSC(0) have been replaced by special one-character commands such as #.

For more information on the ML commands and ML variables, consult the programming section.

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

Note: Your original layout attempted to fit five Old/New column pairs across the page. That does conserve vertical space, but on many wiki skins it becomes cramped and harder to read, especially on smaller displays. A three-block layout like the one above is usually the best compromise between density and readability. If you want to preserve every grouping exactly as originally arranged, that can be done, but for general readability this version is easier to scan.

Converting BASIC Code Steps

When you load a 7.37 module or program, you will find old SYSC and PEEKC calls that must be converted for the program to work properly under 8.0 / 8.1. In most cases, this is a fairly straightforward process.

Step 1: Determine the core source code for the module being converted.

 This is usually indicated by a GOSUB in line 5, such as GOSUB 30000. If the file is only a small modification to an existing overlay, this step, and possibly Step 2, may not apply.

In the example above, the line 5 GOSUB points to line 30000, so the "core code" most likely begins there. Occasionally, a few lines immediately before that point may also need to be copied over.

Step 2: Delete all code except the core code.

 In this example, delete everything up to line 29999 and keep line 30000 and above.

SYSRES users: delete0-29999

LTK users: del 0-29999

Step 3: Begin replacing SYSC and PEEKC statements using the conversion chart above.

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 all `SYSC` statements were handled by searching for them directly: find@sysc(@

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

Step 4: Save a temporary version of the core file.

Step 5: Merge in Overlay 2 or the "XXX SMALL" overlay from 8.0 or 8.1, depending on the version you are targeting.

SYSRES users: use the MERGE command

merge "xxx small"

or merge Overlay 2 as appropriate.

Step 6: Update line 5 of the new file so that it jumps to the module’s core code, as described in the section on merging modules.

Step 7: Save the file and then groom or clean up any remaining issues.

From the example shown in Step 1, after the merge was completed, the first few lines looked like this:

In that example, GOSUB30000 was changed to GOTO30000 because the game did not appear to exit cleanly and was leaving the GOSUB on the stack.

Once the program is functioning, you can often further refine the old 7.37 statements into cleaner 8.x syntax. In many 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?"

However, if the value in A$ is also being used for the caller log, such as when a nearby GOSUB8004 is present, then that particular instance should probably not be refined in this way.

Also look for opportunities to simplify repetitive code. This is especially common in older games, where the same command sequences are repeated over and over.

Example:

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 repeated sequences using:

find@gosub31000:gosub32000:goto30000@

You can then consolidate them into a subroutine:

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

For SYSRES users, this can be made even easier with:

changec@gosub31000:gosub32000:goto30000@@goto50000@

** Be aware that this replacement would also affect line 50000 itself. One workaround is to temporarily alter that line so it will not qualify during the global change. For example, you might change:

50000 gosubb31000:gosub32000....

and then change it back after the replacements are completed.

Another important point during 7.37 conversions is to make sure all file calls are going to the correct locations. Games that use REL files, SEQ files, or other support files often expect them to be in the original Systems file area. If you place them elsewhere, the program must be updated accordingly.

Examples of these kinds of data calls are shown below:

and

For example, if your games are stored in AUX 3, but the old 7.37 game expects the Systems drive, then in the core code only you might change:

all instances of GOSUB202 to GOSUB203
all instances of GOSUB481 to H=14:GOSUB460

This redirects access to AUX3.

Be careful to make these changes only in the module’s core code. Do not alter the standard overlay support lines unless you fully understand the consequences.

Changes from 7.37 to Note

New Carrier Detect Test

One significant change is the way the BBS detects whether carrier is still present. The older method looked like this:

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

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

The new method replaces these direct hardware checks with ML variable !25, which is updated with carrier status every 1/60th of a second. This was necessary because the standard RS-232 routines and the SwiftLink RS-232 routines detect carrier differently, so a simple PEEK no longer works reliably across both methods.

The new method is:

if!25=0thenprint"carrier lost!"

if!25<>0thenprint"carrier present"

This new method is both shorter and easier to remember.

New Modem Output Command

Another change affects the way output is sent directly to the modem. In older versions, you would use:

print#5,"atdt";p$

In the newer method, this becomes:

'"atdt";p$

This new command is shorter and is required because file number 5 is no longer opened during BBS operation. This change is part of maintaining compatibility with the SwiftLink routines.

The New Modem Input Function

The method for reading characters directly from the modem has also changed. The old format was:

get#5,a$

The new method uses one of the built-in Color 64 ML functions:

a$=@4

The @4 function reads 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", an ML program that can be used to convert BASIC code from Color 64 version 7.37 and Super ML. It was designed primarily to convert small optional merge-ins, although with some programming skill it can also help convert games and utility modules.

To use it, first load it into memory with:

LOAD"m-con*",8,1

Then issue a NEW command to ensure BASIC memory is clear.

Once m-con is resident, load the BASIC program you wish to convert and type:

SYS50000

to begin the conversion.

You do not need to reload m-con as long as the computer remains on and no program overwrites the memory area where it resides.

M-con will convert:

SYSC(x) references
POKEC(x) references
PEEK(C(x)) references
PRINT#5 modem-output statements
Super ML MCI commands
CTRL/O characters into version 8.0 format

Things that m-con cannot do include:

Converting references to the old carrier-detect test. These must be changed manually.
Converting GET#5 statements that read directly from the modem. These must also be changed manually.

This conversion program should not be used to convert a full overlay, especially one of the main overlays. Those must be replaced entirely.

If you are converting separate overlay-based modules or games, there are additional requirements. The routines in lines 0 to 27000 are the standard core subroutines of a Color 64 overlay, and many of them were revised for the newer versions, especially the caller log routine.

To convert older overlays that still contain these lines, strip those lines out carefully, making sure not to remove any of the actual module code. Then merge in the appropriate "xxx" skeleton overlay after running m-con on the remaining code.

For most games and small modules, the "xxx small" overlay is ideal because it is compact while still providing the required support routines.

You should also consult the programming section for more information about these skeleton overlays and how they are intended to be used.

SYSOPs who used earlier versions of the add-drive mod should note that the H setting for the three auxiliary file groups is now 12, 13, and 14.

This means that to select AUX 1, the new method is:

H=12:GOSUB460

If you were using the old add-drive mod, you may need to update overlays that selected AUX 1 with H=11, because Network now uses that value to select the Network drive.

One practical way to convert to the new system is:

Change your SETUP definitions so that what was formerly AUX 2 and AUX 3 now become AUX 1 and AUX 2
Change all module references of H=11 to H=14
Configure AUX 3 in SETUP to hold what was formerly stored in AUX 1

Note: The m-con program converts all references to CTRL/A (the Super ML MCI character) inside quoted strings into the English pound sign (the version 8.0 MCI character, £), except when CTRL/A appears inside a PRINT#15 statement.

This exception exists because programs that use relative files often use CTRL/A as part of the relative-file position command sent to file number 15.

If you are converting a program that uses relative files, it is wise to first inspect all CTRL/A references to determine whether any of them are part of a relative-file command. If so, change those references to CHR$(1) before running the converter so they will be protected during conversion.