ugBASIC User Manual

Pragma (and directives)

This page collects the commands and options that allow you to change the behavior of the compiler and/or the compiled program.

Introduction Language Features Hardware

Introduction

The ugBASIC language allows you to modify the behavior and parameters of the compilers, as well as the functionality it exposes. To this end it introduces what are called "pragmas" (or directives). In a nutshell, there are three kind of directives:

  • the language directives, which modify the behavior of the actual language, and are prefixed by the OPTION keyword;
  • the feature directives, which modify the behavior of some available features, such as the management of dynamic strings, and are prefixed by the DEFINE keyword;
  • the hardware directives, which modify the integration with dedicated hardware, such as the address where the sound cards are located, which are prefixed by the CONFIGURE keyword.
The syntax of each of these directives is different, and so we address them in separate sections.

Language directives

Language directives allow you to modify the behavior of the language or compiler, to ensure that it behaves as expected. They are all prefixed by the OPTION keyword, and they work from the next instrucion. Below is the concise list of options supported by the language.

OPTIONDESCRIPTION
OPTION TYPE WIDEChange the way ugBASIC interpret constants, possibly using the default type. See integers on datatype chapter, for a more specific explanation.
OPTION TYPE NARROWChange the way ugBASIC interpret constants, using the minimum size type. See integers on datatype chapter, for a more specific explanation.
OPTION TYPE SIGNEDChange the way ugBASIC interpret variables and constants, allowing signed type.
OPTION TYPE UNSIGNEDChange the way ugBASIC interpret variables and constants, allowing unsigned type.
OPTION EXPLICIT
OPTION EXPLICIT ON		From this point on, ugBASIC will require that each variable or constant used has been previously defined, to be used. It will therefore no longer be possible to use variables defined "on the fly" but they will have to be, at least, defined using DIM. See variables on variables chapter, for a more specific explanation.
OPTION EXPLICIT OFFFrom this point on, ugBASIC will not require that each variable or constant used has been previously defined, to be used. See variables on variables chapter, for a more specific explanation.
OPTION READ
OPTION READ SAFE		From this point on, ugBASIC will will try to identify the type of data stored with the DATA instruction, and convert it into the variable type used by the READ command.
OPTION READ FASTFrom this point on, ugBASIC will will store directly values with the DATA instruction, and will read it using the destination variable on READ command.
OPTION CLIP
OPTION CLIP ON		Enable globally the clipping on PLOT instruction. See clipping on graphics chapter, for a more specific explanation.
OPTION CLIP OFFDisable globally the clipping on PLOT instruction. See clipping on graphics chapter, for a more specific explanation.
OPTION CALL AS GOSUBUse CALL as synonym for GOSUB, so that the execution will return back to the calling point (default behaviour).
OPTION CALL AS GOTOUse CALL as synonym for GOTO, so that the execution will not return back to the calling point.
OPTION EXEC AS GOTOUse EXEC as synonym for GOTO, so that the execution will not return back to the calling point.
OPTION EXEC AS GOSUBUse EXEC as synonym for GOSUB, so that the execution will return back to the calling point (default behaviour).
OPTION DIALECT nameSelect a specific behaviour for the compiler:
UGBASICEnable ugBASIC behaviour (default)
TSBEnable Tuned Simons' BASIC behavi our
OPTION DEFAULT TYPE typeChange the default type of variables, if not specified.

Feature directives

Features directives allow you to modify the behavior of the some available features, to ensure that it behaves as expected. They are all prefixed by the DEFINE keyword, and they work globally (unless specified). Below is the concise list of defines supported by the language.

DEFINEDESCRIPTION
DEFINE AUDIO SYNC Effects and notes are played synchronously, so no need to wait for completition for executing the next command.
DEFINE AUDIO ASYNC Effects and notes are played asynchronously, so you need to wait for completition otherwise the following commands will be executed during the sound effect/note.
DEFINE AUDIO TARGET value Specify the output for audio commands, allowed values for value:
atari POKEY
atarixl POKEY
c128 SID
c128z
c64 SID
c64reu SID
coco DAC1
SN76489
coco3 DAC1
SN76489
coleco SN76489
cpc AY8910
d32
d64
mo5
msx1 AY8910
pc128op SN76489
plus4 TED
sc3000 SN76489
sg1000 SN76489
to8
vg5000
vic20 VIC1
zx
DEFINE CENTER WITH NEWLINE Enable implict newline instruction with CENTER command if ";" is not used (default behaviour).
DEFINE CENTER WITHOUT NEWLINE Disable implict newline instruction with CENTER command.
DEFINE CLS EXPLICIT Disable implict CLS instruction when resolution is changed (default behaviour).
DEFINE CLS IMPLICIT Enable implict CLS instruction when resolution is changed.
DEFINE COLOR EXPLICIT The color index used into graphical commands is exactly the color to use.
DEFINE COLOR IMPLICIT The color index used into graphical commands is one of the current supported palette.
DEFINE DOUBLE BUFFER ONLeave only the code for the double buffer mode, if available.
DEFINE DOUBLE BUFFER OFFLeave also code for non double buffer mode, if available.
DEFINE COMPRESSION RLE ON Enable the RLE compression of images, if needed / allowed.
DEFINE COMPRESSION RLE OFF Disable the RLE compression of images (default).
DEFINE FLOAT PRECISION precisionChange the precision for float representation.
DEFINE FONT schemaChange the preloaded font for graphical modes, and modes where characters can be redefined.
DEFINE LOAD BANKED ON Make all LOAD commands with an implicit BANKED (default only on pc128op) .
DEFINE LOAD BANKED OFF Make all LOAD commands without an implicit BANKED (default everywhere except pc128op) .
DEFINE INPUT SIZE sizeChange the maximum size for INPUT$() buffer.
DEFINE INPUT SEPARATOR valueChange the character used as separator.
DEFINE INPUT CURSOR valueChange the character used as cursor.
DEFINE INPUT RATE value
DEFINE KEYBOARD RATE value		Change the typematic rate of keyboard input (internally converted as INPUT DELAY ).
DEFINE INPUT DELAY value
DEFINE KEYBOARD DELAY value		Change the typematic delay of keyboard input.
DEFINE JOYSTICK RETRIES numberChange the number of readings when retrieving value from analogical joystick.
DEFINE JOYSTICK SYNCRead the position of joysticks in the moment the program asks for them.
DEFINE JOYSTICK ASYNCRead the position of joysticks during interrupt, and read the last position detected when asked (default for c128).
DEFINE KEY PRESS SYNC Change behaviour of KEY PRESS, to be like the one described by manual; otherwise, it will be an alias for KEY STATE.
DEFINE KEYBOARD SYNCRead the key at the moment the program asks for them.
DEFINE KEYBOARD ASYNCRead the key strokes during interrupt, and read the last key detected when asked.
DEFINE MSPRITE SYNC Multiplexed sprites are updated synchronously, so no need to explicit call for MSPRITE UPDATE.
DEFINE MSPRITE ASYNC Multiplexed sprites are updated asynchronously, and updates will be visible only using MSPRITE UPDATE.
DEFINE PALETTE PRESERVEEnable the palette preservation on targets with limited palette.
DEFINE PALETTE NOT PRESERVEDisable the palette preservation on targets with limited palette.
DEFINE PROGRAM START valueChange the starting address of the executable program to value.
atari atarixl Default starting address is &H2000. The address can be increased up to the low address of the frame buffer area.
c128 Default starting address is &H1c0e. The address can be increased, but the starting load address will be always &H1bff since this is the default address for BASIC V2 launcher.
c128z Default starting address is &H1c2f. The address can be increased, but the starting load address will be always &H1bff since this is the default address for BASIC V7.0 launcher with the code to activate Zilog Z80 processor.
c64 c64reu Default starting address is &H080e. The address can be increased, but the starting load address will be always &H0801 since this is the default address for BASIC V2 launcher.
coco coco3 Default starting address is &H2a00. The address can be increased, but the starting load address will be always &H2a00 since this is the default address that is used by BASIC launcher.
coleco This pragma is unavailable.
cpc Default starting address is &H0100.
d32 d64 Default starting address is &H2800. The address can be increased, but the starting load address will be always &H2800 since this is the default address that is used by BASIC launcher.
mo5 Default starting address is &H3000. Note that, if you change this address, you could need to reserve more space from embedded BASIC to load the program.
msx1 This pragma is unavailable.
pc128op Default starting address is &H3000. Note that, if you change this address, you could need to reserve more space from embedded BASIC to load the program.
plus4 This pragma is unavailable.
sc3000 This pragma is unavailable.
sg1000 This pragma is unavailable.
to8 This pragma is unavailable.
vg5000 This pragma is unavailable.
vic20 Default starting address is &H2000. The address can be increased, but the starting load address will be always &H1fff since this is the default address for BASIC V2 launcher.
zx This pragma is unavailable.
DEFINE PAINT BUFFER valueChange the size of buffer used as stack for PAINT instruction.
DEFINE SCREEN MODE UNIQUELimit the support to just one screen mode, discarding routines and data structures for the other.
DEFINE STRING COUNT countChange the maximum number of dynamic strings that can be stored at once.
DEFINE STRING SPACE sizeChange the maximum size of dynamic strings that can be stored at once.
DEFINE TASK COUNT countChange the maximum number of tasks that will be managed using multitasking.

Hardware directives

In order to allow customization of the hardware, and the possibility of generating hardware selection menus via software. The configuration allows two types of manipulation: a static one, which is adopted at compilation time (useful for development and unconventional startup) and a dynamic one, which is adopted at execution time (useful for creating configuration menus).

Each hardware change request must begin with the CONFIGURE keyword followed by the name of the hardware to be configured, that is listed in the following table.

Static changes must begin with the CONFIGURE STATIC keywords, while dynamic changes must begin with the CONFIGURE DYNAMIC keywords. By default, the changes are to be considered static.

Each request for hardware modification must concern one or more parameters prefixed by the SET command, as present into the following table. The value that can be assigned to these variables must be consistent with the expected and acceptable values, as described next to the parameter. Note that this control will only take place on static configurations, since they must be constant. Finalli, it is possbile to assign multiple values consecutively, separating them with a comma, without using the SET command.

For example, this command will configure the audio for coco target, as the one given from Game Master Cartridge on slot 2 with SN76489:

CONFIGURE GMC SET SLOT = 2
CONFIGURE SN76489 SET ADDRESS = $FF41

List of hardware names

CPU(s)
NAMEDESCRIPTIONPARAMETERS
CPU6502Main CPU (MOS 6502)
CPU6809Main CPU (MOTOROLA 6809)
CPUZ80Main CPU (ZILOG Z80)
TARGETS
NAMEDESCRIPTIONPARAMETERS
ATARITarget Atari 400/800
ATARIXLTarget Atari XE/XL/XEGS
C128Target Commodore 128 (MOS 8502)
C128ZTarget Commodore 128 (ZILOG Z80)
C64Target Commodore 64
C64REUTarget Commodore 64+REU
COCOTarget TRS-80 Color Computer 1/2
COCO3Target TRS-80 Color Computer 3
COLECOTarget ColecoVision
CPCTarget Amstrad CPC 664
D32Target Dragon 32
D64Target Dragon 64
MO5Target Thomson MO5
MSX1Target MSX
PC128OPTarget Olivetti Prodest PC128
PLUS4Target Commodore Plus/4
SC3000Target SEGA SC-3000
SG1000Target SEGA SG-1000
VIC20Target Commodore VIC-20
ZXTarget ZX Spectrum
VIDEO CHIPSET
NAMEDESCRIPTIONPARAMETERS
M6847Motorola 6847
ANTICAtari ANTIC
EF9345Thomson EF9345
EF936XThomson EF936x
GIMEMorotola GIME
GTIAAtari GTIA
TEDCommodore TED
TMS9918Texas Instruments TMS9918
VDCMOS 8563 (MOS VDC)
VIC1Commodore VIC
VIC2Commodore VIC-II
AUDIO CHIPSET
NAMEDESCRIPTIONPARAMETERS
AY8910General Instrument AY-3-8910
POKEYAtari POKEY
SIDCommodore SID
SN76489Texas Instruments SN76489ADDRESS
TEDCommodore TED
VIC1Commodore VIC
DISK STORAGE
NAMEDESCRIPTIONPARAMETERS
D64Commodore 1541 Disk Image
OTHER HARDWARE
NAMEDESCRIPTIONPARAMETERS
GMCGame Master CartridgeSLOT


List of parameters

HARDWAREPARAMDESCRIPTIONRANGE
GMCSLOTThis is the slot where GMC is installed.coco: 0, 1, 2, 3
coco3: 0, 1, 2, 3
slot 3 is not available if disk image is used
SN76489ADDRESSAddress where the data and control port appears.pc128op: $A7F6, $A7F7, $A7FE, $A7FF
coco: $FF41
coco3: $FF41


Any problem?

If you have found a problem, if you think there is a bug or, more simply, you would like something to be improved, write a topic on the official forum, or open an issue on GitHub.

Thank you!