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 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 betaEffects and notes are played synchronously, so no need to wait for completition for executing the next command.
DEFINE AUDIO ASYNC betaEffects 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 beta 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 DEFAULT TYPE typeChange the default type of variables, if not specified.
DEFINE DOUBLE BUFFER ONEnable the double buffer mode, if available.
DEFINE DOUBLE BUFFER OFFDisable the double buffer mode, if available.
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 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.
DEFINE INPUT DELAY value
DEFINE KEYBOARD DELAY value		Change the typematic delay of keyboard input.
DEFINE PALETTE PRESERVEEnable the palette preservation on targets with limited palette.
DEFINE PALETTE NOT PRESERVEDisable the palette preservation on targets with limited palette.
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!