JBASICODE Help

JBASICODE is a BASICODE system developed in Java. It consists of an editor, interpreter and debugger, and supports the BASICODE-3C standard.

Please read the license terms before continuing to use JBASICODE!

The help is divided into the following topics:

1. Introduction

BASICODE is a standard developed in the Netherlands in the 1980s with the goal of enabling the development of BASIC programs that could be run, if possible without modification, on many of the 8-bit home computers common at the time. The software JBASICODE is intended to make it possible to run BASICODE programs easily and conveniently on today's desktop computers.

JBASICODE comes with an English and a German user interface. If you want to use the German version then start JBASICODE with the open -Duser.language=en (see Command Line in the next section).

2. Program Start

2.1. Command Line

The command line syntax looks like this:

java [-Duser.language=<Sprachcode>] -jar jbasicode.jar [-h] [-v] [[-r] <file>]

May be the path and name of the java command and the jar file need to be adjusted. Elements in square brackets are optional.

ArgumentDescription
-h
-H
JBASICODE shows a short help message about the command line arguments in the console and then exits.
-v
-V
JBASICODE shows the program version and copyright information in the console and then exits.
file JBASICODE starts as a window application and loads the specified file into the editor.
-r file JBASICODE starts as a window application, loads the specified file into the editor and then starts the BASICODE program in presentation mode.

2.2. Start And Stop A BASICODE Program

You can start a program in the editor via the Program menu. There you can also end (abort) a running program. You can also start and abort a program using the Start icon (green) and the Stop icon (red) in the toolbar.

Attention! In debugger mode, these two icons have a slightly different meaning.

The BASICODE program can also be aborted using the Escape key (can be disabled with GOSUB 280).

3. Implementation of the BASICODE Standard in JBASICODE

All functionalities specified in BASICODE-3C are implemented in JBASICODE. Unfortunately, not all BASICODE programs strictly adhere to the specification. To ensure that these programs also run, JBASICODE offers a certain degree of tolerance. However, a warning is issued if a program violates the specification. These warnings can be disabled in the settings.

3.1. Program Files

According to the BASICODE standard program files are pure ASCII files which is why they often have the filename extension *.asc. Other common extensions are *.bc, *.bc2, *.bc3 and occasionally *.bas and *.txt. To run a BASICODE program, it must first be opened in the JBASICODE editor. When saved the file is saved with the same encoding or character set and the same newline bytes as it was opened. A program newly written in JBASICODE is saved with UTF-8 encoding without byte order markings and with the newline bytes 0Dh, 0Ah. If the program contains only ASCII characters it is automatically an ASCII file.

JBASICODE allows non-ASCII characters. However, a warning appears during execution if a string contains a non-ASCII character thus makes the BASICODE program less portable. These warnings can be disabled in the settings.

For interoperability with 8-bit computers a program displayed in the JBASICODE editor can be exported to a sound file in WAV format. To import it into such an computer the WAV file must be played on the desktop computer and the sounds have to be transferred to the cassette interface of the 8-bit computer via a suitable connection.

For the reverse direction, namely for reading BASICODE cassette recordings into a desktop computer, there is the program JKCLOAD by the same author.

3.2. Data Files

BASICODE programs can also read and write files themselves. These files usually contain data and are therefore called data files here. When such a file is opened with GOSUB 500 a file selection dialog always appears. The file name field is pre-filled with the contents of the string variable NF$. The numeric variable NF contains the program's internal file number and is evaluated to determine whether the number is odd or even. The file is then opened either for reading or writing accordingly.

If you cancel the file selection dialog or the selected file cannot be opened, this is reported to the BASICODE program in the variable IN with the value -1. Otherwise IN has the value 0 which indicates success.

When reading, writing and closing a file with GOSUB 540, GOSUB 560 and GOSUB 580 the NF variable must have the same value as when the file was opened. This is necessary because JBASICODE allows multiple files to be open at the same time.

Each time GOSUB 560 (write file) is called an end-of-record identifier is written after the contents of the SR$ variable. By default this is byte 0Dh which corresponds to the behavior of many 8-bit computers. However, you can also select 0Dh, 0Ah (typical for DOS/Windows) or just 0Ah (typical for Linux/Unix) in the settings. When reading a file JBASICODE automatically recognizes all three variants as end-of-record identifiers, so nothing needs to be configured. Each time GOSUB 540 (read from file) is called, the byte 0Dh or 0Ah is read, and the read bytes, excluding the end-of-record bytes, are returned to the BASICODE program in the variable IN$.

Data files can be exported to a WAV file like program files.

3.3. Screen Format

In text mode JBASICODE operates with a screen resolution of 40 x 25 characters. In graphics mode it is 320 x 240 pixels, which corresponds to the standard aspect ratio of 4:3. However, many home computers of that time had a screen resolution of about 320 x 200 pixels, which corresponds to a 16:10 aspect ratio. As a result, there are also graphical BASICODE programs that are optimized for 16:10 and do not completely fill the screen vertically when outputting at 4:3. These programs may then leave horizontal stripes on the screen. To ensure that such programs can also produce proper graphical output in JBASICODE, you can change the aspect ratio to 16:10 in the settings.

3.4. Cursor

The cursor is displayed as a solid rectangle. By default, this is only visible during input using the INPUT statement. In the settings you can specify whether the cursor should always be visible.

There are four special codes for cursor control:

CodeDescription
8 Backspace:
If the cursor is not in the upper left corner, the character at the current cursor position is deleted and the cursor is moved back one position.
12 or 0Ch Form Feed:
The screen output is cleared and the cursor is placed in the upper left corner.
13 or 0Dh Carriage Return:
The cursor is placed at the beginning of the next line.
If it is already in the last line, the screen output is scrolled up one line.
127 or 7Fh Delete:
If the cursor is not at the left margin, it is moved back one position and the character at that position is deleted.

3.5. Keyboard Input

For keyboard input using GOSUB 200, GOSUB 210 and INPUT instructions, the screen output component must have the focus. JBASICODE sets the focus to this component when one of these three instructions is called. However, if you click somewhere else, the component loses focus and the BASICODE program no longer receives keyboard events. In this case, please click on the screen output component to re-enable keyboard input.

The Backspace key and the Delete key have the same meaning for the BASICODE program and return the code 127. The code 8, that the Backspace key normally returns, is not defined in the BASICODE standard.

3.6. Colors

BASICODE-3C defines 8 colors with the numbers 0 to 7. Because some programs use more colors, in JBASICODE the 8 official colors are adjustable at half brightness with numbers 8 to 15, whereby the color black remains unchanged in this case.

For color selection JBASICODE only evaluates the lower 4 bits of the color number. The block with the 16 colors is therefore repeated starting with numbers 32, 48, 64... Regardless of this, a warning is issued if a color with a number less than 0 or greater than 7 is selected.

3.7. Printing

The BASICODE standard defines printing functionality with GOSUB 350 and GOSUB 360. However, JBASICODE does not print the output characters directly but collects them in a print document. While a BASICODE program is running all printer output goes to one and the same document. A new print document may be created next time the program is run. You can view, print, save and delete print documents via the menu item ProgramPrinter Output.

3.8. Sound Output

GOSUB 250 emits a beep. To do this, JBASICODE calls a corresponding Java function. With it the actual output of the beep depends on the currently used Java runtime environment.

The second function for outputting a tone is GOSUB 400. The pitch is passed in the SP variable as a note number. JBASICODE plays the note using a synthesizer included in Java. Unfortunately, this synthesizer does not offer any way to influence the volume. For this reason, the SV variable, which specifies the volume, has no effect except that no sound is played if SV=0. However, the program still waits for the tone duration specified in the SD variable.

The sound output can be disabled and enabled using the corresponding icon in the JBASICODE toolbar. When it is disabled, the option Wait for sound duration even if sound output is disabled in the settings becomes relevant.

3.9. Program Termination

Pressing the Escape key aborts a running program. The Escape key can be disabled and re-enabled with GOSUB 280. Regardless of this, a program can always be aborted via the Program menu.

The program will also abort if an error occurs. Only errors related to file processing (GOSUB 500, 540, 560 and 580) do not abort the program. In this case, an error is reported to the BASICODE program with IN=-1.

3.10. Free Memory

When BASICODE was developed, software developers had to pay more attention to the memory usage of their programs than they do today. To make this possible BASICODE provides a way to determine free memory with GOSUB 270.

In JBASICODE memory is managed by the Java runtime environment. Calculating the free memory space is therefore not possible. However, to still provide adequate functionality, GOSUB 270 calculates the space requirements of all strings contained in the BASICDOE variables (for each non-empty string length + 1) and returns the difference to 32767 (largest signed 16-bit integer) in the variable FR.

4. Debugger

The debugger is used for troubleshooting. It allows you to pause the BASICODE program at any point and execute it step by step. The debugger is opened via the Debugger menu. This makes the program editor invisible.

The debugger can be opened both before and after the BASICODE program starts. If it is opened before the program starts, program execution stops before the first program line. The debugger closes automatically when the program ends.

The debugger is controlled using the actions in the Debugger menu and via the toolbar. The easiest way to set breakpoints at the beginning of a BASICODE line is via the context menu (right mouse button).

Attention! The Start icon (green) and the Stop icon (red) in the toolbar have a slightly different meaning in debugger mode than when running a program normally. In the debugger, they mean Run to the next breakpoint and Stop.

Attention! The debugger always stops before executing a BASICODE statement. If the program is currently executing a statement, e.g., waiting for a key to be pressed, you can click the stop icon in the toolbar, but nothing will happen at first. The debugger only stops when the BASICODE statement is finished, e.g. when a key is pressed in GOSUB 210 or the Enter key is pressed in the INPUT statement (The screen output component must have the focus for this!).

5. Settings

The settings you have made or changed can be saved. This also saves the positions and sizes of the open windows as well as the status of the sound output (on/off) and the set speed.

Saved settings can also be deleted. This deletes the directory created by JBASICODE in which the settings were saved. JBASICODE will then start with default settings the next time.