Image BBS Programming Reference Guide

Chapter III: Machine Language Subroutines

Jump Table Routines | Memory Locations | Using Modules | Using ML Modules | RS232 Routines | The Swapper | The Lightbar | The Editor

Using Modules

In IMAGE BBS, the "main" program, also known as the "im" file, resides at $4601 in memory. Other modules, called "plus files," load at $0801. The area designated for plus files is $0801-$4000, which is about 14k. (This is about 56 CBM 1541 "blocks.") The main file starts at line 1000. Modules start at line 1. When you enter a module, it is always entered with either a GOTO 1, or GOSUB 1.

When a module starts to become too large for the 14k buffer, you can further divide it into sub-modules. The most common way is to use "mini-modules." These are modules that can be up to 4k in length, or about 17 disk blocks. The mini-modules load at $3001 in memory. When one is loaded, it is effectively appended on to the end of the plus file that is currently in memory. Therefore, you cannot start a mini-module at line 1. All of the line numbers in the mini-module must come after the line numbers in the plus file. If there is an overlap, it may crash the system, forcing you to reboot. For this reason, be very careful when you program using modules.

There are a few restrictions that you must be aware of. First, the mini-module and the plus file must share the same area of memory. So, even though the maximum size of a plus file is 14k, if you are using a mini-module, the maximum size for the plus file becomes 10k, and the mini module is 4k, which is a total of 14k. There are other sizes of modules, and here is a chart to explain them:

Size of modules:

Plus file length:

Module length:

Module address:

No module

14k / 56 blocks

Mini-module

10k / 41 blocks

4k / 17 blocks

$3001

Small module

6k / 25 blocks

8k / 33 blocks

$2001

Large module

2k / 9 blocks

12k / 49 blocks

$1001

Using ML Modules:

If you wish to use ML modules, more commonly known as "++" files, the &,7,dv%,2 command will load them for you. You can call any of the normal IMAGE & routines by loading the Accumulator with the & number, and X and Y with the parameters. Then a JSR $DD01 will call the routine. The area set aside for ML modules is from $C000-CA7F.

RS232 Routines:

The RS232 routines that IMAGE uses reside in memory from $4300-$45FF. There is a jump table at $4300 which has the ONLY safe entry points into these routines. NOTE: Calling some of these routines will result in "strange" things happening, be very careful.

$4300 Install

This is the install routine that is called when the system is booted. Do not call this routine, since it will crash your system.

$4303 Enable

This routine enables the NMI interrupts that perform the RS232 I/O. Note that during such things as disk access these must be turned off, and then turned back on when disk access is finished. IMAGE handles this for you, and you should never need to call this routine.

$4306 Disable

See above for "Enable."

$4309 RSGet

This gets a character from the RS232 device. Note that RS232 has a 256-byte "ring" buffer so that characters which are received when the system is busy are not lost. The character is returned in the Accumulator.

$430C RSOut

This will output a character to the RS232 device. The character is passed in the Accumulator. Note that the routines use a technique called "double buffering" which means that while one character is being transmitted, another can be put into a "holding" buffer, until the first character is done. This allows the system to output a character, and then go back to doing more processing while it is being sent. This keeps the screen cursor sychronized with the cursor on the user's side, while still gaining the benefit of a buffered I/O system.

$430F SetBaud

This will set the baud rate as defined by an internal table. See the listing for &,41.

The Swapper

IMAGE uses a sort of virtual memory mechanism to allow the 12k of RAM that is "hidden" in the 64 to be used. RAM from $D000-$FFFF is used to store many of the routines that IMAGE does not need to use as often as others. Examples are the disk input routine (&,2) and the entire editor system! These routines are accessed using the "swapper." This is a routine that swaps the needed routines into memory, and swaps whatever is in that memory to the hidden RAM. The routines are then executed, and then swapped back to the hidden RAM. Thus, the 12k of hidden RAM can be used to store more ML for the IMAGE system. In IMAGE 1.2, all but 2k of this RAM is used, and in future versions, that last 2k will be used!

The swapper is located at $CA80. To use it, you set the Accumulator and the Y register with the starting page numbers to swap, and the X register to how many pages of RAM to swap. Thus, to swap memory from $C000-$C2FF with the memory from $C300-$C5FF, you would do this:

LDA #$C0
LDY #$C3
LDX #$03
JSR $CA80

To swap it back again, repeat the same sequence of commands. Be very careful when using this routine, since it does not care what it swaps, and will try to swap anything you tell it to!

The Lightbar

The lightbar is controlled by IRQ routines which read the function keys, and make the necessary screen/memory changes that are requested. There is an & [command] which allows you to get or set the status of the lightbar. This is &,52.

There are several functions implemented in this command in version 1.2. You can clear/set/toggle/read any individual checkmark. Here are some examples:

&,52,0,0 Clear the check on the left side of Sys.

&,52,0,1 Set the check on the left side of Sys.

&,52,0,2 Toggle the check on the left side of Sys.

&,52,0,3 Read the check on the left side of of Sys.

[Additionally, there is another function I discovered.

&,52,x,4 moves the "lit" section to positions 1-8 (page 1) or 9-16 (page 2). Very useful.

Also, mainly because I get tired of flipping through the sysop documentation for IMAGE, I'll include a section here on what the various positions on the Lightbar are for:

Left

L Chk R

Right

Sysop available

0 Sys 1

Trace mode on

Change access

2 Acs 3

Block 300 baud users

Local logon

4 Loc 5

Pseudo-local mode

Alter time

6 Tsr 7

Toggle prime time

Enter chat

8 Cht 9

Toggle local bells

Private system

10 New 11

Disable screen blanking

Print output

12 Prt 13

Print log entries

Close U/Ds

14 U/D 15

No 300 baud callers

ASCII translation on

16 Asc 17

Linefeeds on

ANSI graphics on

18 Ans 19

IBM graphics on

Expert mode on

20 Exp 21

Main prompt macros on

Credit when file validated

22 Fn5 23

Log off after file transfer complete

Undefined in stock system

24 Fn4 25

Undefined in stock system

Undefined in stock system

26 Fn3 27

Undefined in stock system

Undefined in stock system

28 Fn2 29

MCI off

Undefined in stock system

30 Fn1 31

Undefined in stock system

Certain mods like the Graphic Menu or Callback Validator will use the Fn areas for their own use.]

The Editor:

The programming of the IMAGE editor is best left to those who know a lot about the IMAGE system. There is an & [command] which will make the necessary calls into the editor ML. This ML resides from $D000-$DFFF, and is swapped into memory from $1000-$1FFF by the swapper when it is called. There are 3 legal entry points, which are accessed by &,54, &,54,1, and &,54,2. The first entry point is the "normal" entry. This puts the user into the editor with an empty buffer. The second entry does not clear the buffer. The last entry is the entry that you would use in [writing] an extended command, if the command which was typed was not a recognized command.

Jump Table Routines | Memory Locations | Using Modules | Using ML Modules | RS232 Routines | The Swapper | The Lightbar | The Editor