RISCOS.com

www.riscos.com Technical Support:
Programmer's Reference Manual

 

BASIC and BASICTrans


Introduction and Overview

Facilities were added to BASIC (and to BASIC64) in RISC OS 3 so that its messages can be translated for use in another territory. The BASIC interpreter issues calls to the BASICTrans module, which is responsible for providing messages appropriate to a particular territory. By replacing one BASICTrans module with another, you can change the language used by BASIC for its messages.

Both BASIC and BASIC64 issue the same calls to the same BASICTrans module, thus code and messages are shared between the two modules.

If you write a BASICTrans module, you can allocate memory for the translation from the RMA:

  • Memory inside the SWI call is invulnerable to the task swapping problem found when BASIC itself attempts to use RMA memory. 'Task manager' swapping between two BASIC programs does not occur when in SWI mode.

Using BBC BASIC

For the sake of completeness, this chapter documents the *BASIC and *BASIC64 commands used to enter BBC BASIC. For full details of using BBC BASIC, see the BBC BASIC Reference Manual, available from your Acorn supplier.

SWI Calls


BASICTrans_HELP
(SWI &42C80)

Interpret, translate if required, and print HELP messages

On entry

R0 = pointer to lexically analysed HELP text (terminated by &0D)
R1 = pointer to program's name (BASIC or BASIC64)
R2 = pointer to the lexical analyser's tables

On exit

R0 - R2 corrupted

Use

This call is made by BASIC to request that a BASICTrans module print a help message. BASIC lexically analyses the HELP text, converting keywords to tokens, before making this call. The currently loaded BASICTrans module then prints appropriate help text.

On entry R1 points to the program's name, and so is non-zero; if it is still non-zero on exit BASIC will print its own (short, English) Help text. Consequently, a BASICTrans module will normally set R1 to zero on exit - but the English version of BASICTrans sometimes preserves R1 so that its own help is followed by the default help.

In order to share the entirety of the HELP text between BASIC and BASIC64, this call is implemented for English, and both BASIC and BASIC64 are assembled without their own HELP text. About 15Kbytes are shared like this.


BASICTrans_Error
(SWI &42C81)

Copy translated error string to buffer

On entry

R0 = unique error number (0 - 112)
R1 = pointer to buffer in which to place the error

On exit

R0 - R3 corrupted

Use

This call is made by BASIC to request that a BASICTrans module provide an error message. The currently loaded BASICTrans module places a null terminated error string for the given error number in the buffer pointed to by R1. The error string is null terminated. BASIC then prints the error message, and performs other actions necessary to smoothly integrate the error message with BASIC's normal provisions for error handling.

An error is generated if the BASICTrans module is not present (ie the SWI is not found), or if BASICTrans does not perform the translation. BASIC then prints a default (English) message explaining this.

In order to share the entirety of the error string text between BASIC and BASIC64, this call is implemented for English, and both BASIC and BASIC64 are assembled without their error messages. About 6Kbytes are shared like this. Correct error numbers are vital to the functioning of the interpreter, and so - rather than being shared - these are held in BASIC or BASIC64.


BASICTrans_Message
(SWI &42C82)

Translate and print miscellaneous message

On entry

R0 = unique message number (0 - 25)
R1 - R3 = message dependent values

On exit

R0, R1 corrupted

Use

This call is made by BASIC to request that the BASICTrans module print a 'miscellaneous' message. Further parameters are passed that depend on the message you require to be printed.

An error is generated if the BASICTrans module is not present (ie the SWI is not found), or if BASICTrans does not perform the translation. BASIC then prints the full (English) version of the message that it holds internally.

The English BASICTrans module behaves as if this call does not exist, so that the default messages get printed. There are not many 'miscellaneous' messages, so no great saving is to be had in providing RISC OS 3 with a shared implementation.

The classic problem of the error handler's ' at line ' can now be handled as follows:

TRACE OFF
IF QUIT=TRUE THEN
 ERROR EXT,ERR,REPORT$
ELSE
 RESTORE:!(HIMEM-4)=@%
 SYS"BASICTrans_Message",21,ERL,REPORT$ TO ;@%
 IF (@% AND 1)<>0 THEN
  REPORT:@%=&900:IF ERL<>0 THEN PRINT" at line "ERL ELSE PRINT
 ENDIF
@%=!(HIMEM-4)
ENDIF
END

This allows the BASICTrans_Message code to print the string and optional ' at line ' ERL information in any order it likes.

* Commands


*BASIC
*BASIC64

Starts the ARM BBC BASIC interpreter

Syntax

*BASIC [options]

Parameters

options - see below

Use

*BASIC starts the ARM BBC BASIC V interpreter.

*BASIC64 starts the ARM BBC BASIC VI interpreter - provided its module has already been loaded, or is in the library or some other directory on the run path.

For full details of BBC BASIC, see the BBC BASIC Reference Manual, available from your Acorn supplier.

The options control how the interpreter will behave when it starts, and when any program that it executes terminates. If no option is given, BASIC simply starts with a message of the form:

ARM BBC BASIC V version 1.05 (C) Acorn 1989
Starting with 643324 bytes free

The number of bytes free in the above message will depend on the amount of free RAM on your computer. The first line is also used for the default REPORT message, before any errors occur.

One of three options may follow the *BASIC command to cause a program to be loaded, and, optionally, executed automatically. Alternatively, you can use a program that is already loaded into memory by passing its address to the interpreter. Each of these possibilities is described in turn below.

In all cases where a program is specified, this may be a tokenised BASIC program, as created by a SAVE command, or a textual program, which will be tokenised (and possibly renumbered) automatically.

*BASIC -help

This command causes BASIC to print some help information describing the options documented here. Then BASIC starts as usual.

*BASIC [-chain] filename

If you give a filename after the *BASIC command, optionally preceded by the keyword -chain, then the named file is loaded and executed. When the program stops, BASIC enters immediate mode, as usual.

*BASIC -quit filename

This behaves in a similar way to the previous option. However, when the program terminates, BASIC quits automatically, returning to the environment from which the interpreter was originally called. It also performs a CRUNCH %1111 on the program (for further details see the description of the CRUNCH command in the BBC BASIC Reference Manual). This is the default action used by BASIC programs that are executed as * commands. In addition, the function QUIT returns TRUE if BASIC is called in this fashion.

*BASIC -load filename

This option causes the file to be loaded automatically, but not executed. BASIC remains in immediate mode, from where the program can be edited or executed as required.

*BASIC @start,end

This acts in a similar way to the -load form of the command. However, the program that is 'loaded' automatically is not in a file, but already in memory. Following the @ are two addresses. These give, in hexadecimal, the address of the start of the in-core program, and the address of the byte after the last one. The program is copied to PAGE and tokenised if necessary. This form of the command is used by Twin when returning to BASIC.

Note that the in-core address description is fixed format. It should be in the form:

@xxxxxxxx,xxxxxxxx

where x means a hexadecimal digit. Leading zeros must be supplied. The command line terminator character must come immediately after the last digit. No spaces are allowed.

*BASIC -chain @start,end

This behaves like the previous option, but the program is executed as well. When the program terminates, BASIC enters immediate mode.

*BASIC -quit @start,end

This option behaves as the previous one, but when the BASIC program terminates, BASIC automatically quits. The function QUIT will return TRUE during the execution of the program.

Examples

*BASIC
*BASIC -quit shellProg
*BASIC @000ADF0C,000AE345
*BASIC -chain fred

Related commands

None

Related SWIs

None

Related vectors

None

This edition Copyright © 3QD Developments Ltd 2015
Last Edit: Tue,03 Nov 2015