UC-Builder

Der UC-Builder

Der UC-Builder ist ein Werkzeug (ein PC Programm), mit dem man eine Programm Sammlung erstellen kann. Diese Programmsammlung läuft in einem Modul für die Commodore Homecomputer C64, c128 und Plus/4.

Der UC-Builder läuft in der Kommandozeile (CMD.EXE) eines Windows PC.

Image Datei

Die Programm Sammlung für das Modul kann man frei zusammen stellen. Dazu dient das PC Programm (UC-Builder). Der UC-Builder erstellt eine sogenannte Image Datei. Diese Image Datei hat die Datei Erweiterung .bin und kann direkt in das EPROM (oder den FLASH) des C64 Modul gespeichert werden.

Die Größe der Image Datei darf den verfügbaren Platz im EPROM (im FLASH Speicher) nicht überschreiten. Bei Verwendung eines W27C040 darf die Image Datei eine maximale Größe von 512KB haben. Die Größe setzt sich zusammen aus der Summe der einzelnen C64 Programme plus der Größe des UC-Loader. Der UC-Loader ist ein C64 Programm, das für die Bedienung des Modul (UC-Menü) notwendig ist.

UC-Loader

Der UC-Loader ist die Betriebs Software in dem Modul. Nach dem Einschalten des C64 (bzw. des c128) startet der UC-Loader. Der UC-Loader schaut nach, welche Programme auf dem Modul gespeichert sind. Wenn es nur ein Programm ist, dann wird dieses direkt gestartet. Wenn sich mehr als ein Programm auf dem Modul befindet, dann zeigt der UC-Loader die Namen aller Programme am Bildschirm an (UC-Menü). Der Benutzer wählt das gewünschte Programm und der UC-Loader startet es.

Mit den Tasten <F7> oder <F8> kommt man in den normalen C64 Eingabemodus (C64 BASIC). Die Taste <F7> schaltet dabei das UC Modul aus. Man kann dann immer noch auf die UC-Register an der Adresse $DE0x zugreifen. Mit der Taste <F8> schaltet man zusätzlich auch die UC Register aus. Das Modul ist dadurch vollkommen unsichtbar und kann nur durch einen Modul Reset wieder aktiviert werden.

UC-Menü

Das UC-Menü ist Bestandteil des UC-Loader. Es ist die Liste der Programme in der Programm Sammlung in der Imagedatei. Jedem Programm wird automatisch eine Taste zugeordnet. Das gewünschte Programm kann dann per Knopfdruck gestartet werden.

Wenn sich ein File Browser (UC-FB) in der Image Datei befindet, dann kann man das Programm über die Taste <F1> starten. Der File Browser ist ein modifiziertes FB (File Browser) Version 2. Man kann damit Dateien auf einem Disketten Laufwerk oder einem SD2IEC anzeigen und starten. Dateien mit der Dateiendung .CRT startet der UC-FB automatisch als Modul, vorausgesetzt die Modul Hardware unterstützt ladbare Programme.

Das UC-Menü ist aber etwas mehr als nur eine Liste von Programm Namen. Zu jedem Programm enthält das Menü einen Datensatz. Der Datensatz enthält Informationen zu dem Programm. Neben dem Programm Namen sind das Informationen, die der UC-Loader benötigt, um das Programm zu laden und zu starten.

Unterstütze Modul Hardware

Die folgenden Module für den C64, c128 und Plus/4 werden vom UC-Builder unterstützt.

Universal Cartridge

Die Universal Cartridge gibt es in drei Versionen. Alle UC Module unterstützen alle C64 Betriebsarten, nur der Speicherausbau unterscheidet die Module. Das UC-2 kann auch im c128 Modus betrieben werden, das UC-1 und das UC-1.5 starten den Commodore c128 im C64 Modus.

Universal Cartridge 1

Das UC-1 Modul läuft an einem C64. Es hat 128K EPROM und 32K SRAM. Es werden alle Betriebsarten unterstützt.

Der UC-Builder unterstützt alle verfügbaren Modi: UC-RAM, UC-ROM, UC-XROM, 8K, 16K, UltiMax, OFF und Invisible.

Universal Cartridge 1.5

Das UC-1.5 Modul läuft an einem C64. Es hat 512K EPROM und 32K SRAM. Es werden alle Betriebsarten unterstützt.

Der UC-Builder unterstützt alle verfügbaren Modi: UC-RAM, UC-ROM, UC-XROM, 8K, 16K, UltiMax, OFF und Invisible.

Universal Cartridge 2

Das UC-2 Modul läuft an einem C64, einem c128 oder in einer MAX Machine. Es hat 512K EPROM und 512K SRAM. Es werden alle Betriebsarten unterstützt.

Der UC-Builder unterstützt alle verfügbaren Modi: UC-RAM, UC-ROM, UC-XROM, 8K, 16K, UltiMax, OFF und Invisible.

Hucky-64K

Das Hucky-64K Modul läuft an einem C64. Es hat ein 64K EPROM und unterstützt die Betriebsart 8K und OFF.

Der UC-Builder unterstützt alle verfügbaren Modi: 8K und OFF

MagicDesk

Das MagicDesk Modul läuft an einem C64. Es hat bis zu 1MB EPROM oder FLASH und unterstützt die Betriebsart 8K und OFF. Je nach Bauart wird OFF gemeinsam mit Invisible geschaltet. Das MagicDesk Modul ist sehr verbreitet und tritt in verschiedensten Formen und Varianten auf. Das MagicDesk kann man sehr einfach selbst nachbauen.

Der UC-Builder unterstützt alle verfügbaren Modi: 8K und OFF

EasyFlash

Das EasyFlash Modul läuft an einem C64. Es hat 1MB FLASH und unterstützt die Betriebsarten 8K, 16K, Ultimax und OFF.

Der UC-Builder unterstützt alle verfügbaren Modi: 8K, 16K, Ultimax und OFF.

MagicDesk-128

Das MagicDesk-128 Modul läuft an einem c128. Es hat bis zu 1MB EPROM oder FLASH und unterstützt keine besondere Betriebsart.

Der UC-Builder unterstützt alle verfügbaren Modi: c128 Modul

MegaBit 128

Das MegaBit 128 ist kein Modul, sondern ein Adapter für den internen ROM Sockel U36 in einem c128. Der Adapter unterstützt Banking und funktioniert ganz ähnlich wie ein MagicDesk-128. Es hat bis zu 1MB EPROM oder FLASH und unterstützt keine besondere Betriebsart.

Der UC-Builder unterstützt alle verfügbaren Modi: c128 Modul

Internes Function-ROM im c128 (U36)

Das U36 ROM ist kein Modul, sondern ein interner ROM Sockel in einem c128. Es hat bis zu 32K EPROM oder FLASH und unterstützt keine besondere Betriebsart.

Der UC-Builder unterstützt alle verfügbaren Modi: c128 Modul

MagicDesk-264

Das c264 Magic ist ein Modul für die Commodore 264 Serie (C16, C116, Plus-4). Das Modul unterstützt Banking und ist von der Hardware fast identisch zu dem MagicDesk Modul. Es unterstützt alle gängigen Flash und EPROM Speicher bis zu der Größe von 2MB (128 Banks zu 16Kb).

Das Banking Register kann auf unterschiedliche Adressen eingestellt werden: $FD17,$FDA0,$FDFE,$FE00 (Standard:$FDFE).

Der UC-Builder unterstützt alle verfügbaren Modi: 264 Modul

TED:  

$FF3E .. select ROM
$FF3F .. select RAM 

$FDDx .. LO: xx00=BASIC,  xx01=Func.ROM, xx10=Ext1, xx11=Ext2
$FDDx .. HI: 00xx=Kernal, 01xx=Func.ROM, 10xx=Ext1, 11xx=Ext2

Banking Register:

$FDFE .. Bank 0 - 127

Internes Function-ROM im Plus/4

Das interne ROM (Function ROM) ist kein Modul, sondern ein interner ROM Sockel in einem Plus/4. Es hat bis zu 32K EPROM oder FLASH und unterstützt keine besondere Betriebsart.

Der UC-Builder unterstützt alle verfügbaren Modi: c264 Modul

Erstellen einer Programmsammlung

Der UC-Builder erstellt eine Image Datei aus einem oder mehreren C64 Programmen. Die Image Datei enthält alle Programme der Sammlung sowie den UC-Loader samt UC-Menü. Für die Erstellung der Image Datei benötigt der UC-Builder alle Programm Dateien sowie eine Text Datei (CSV Datei), in der Informationen zu jedem Menüpunkt stehen.

Das benötigt man für die Erstellung einer Image Datei:

• den UC-Builder (UC-builder.exe)
• die einzelnen Programm Dateien
• eine CSV Datei

Die Programm Dateien

Die Programm Dateien sind einfach Programme für den ausgewählten Computertyp (C64 oder c128). Es können einige der Dateitypen verwendet werden, die auch im Emulator VICE funktionieren:

• .PRG
• .P00
• .CRT
• .BIN

Die CSV Datei

Die CSV Datei ist eine normale Text Datei und kann mit jedem Editor erstellt werden. In der CSV Datei wird beschrieben, wie das Programm Menü aufgebaut ist. Im wesentlichen besteht es aus einem oder mehreren Menüeinträgen. Ein Menüeintrag kann ein Programm sein oder eine Textzeile.

Menüeintrag als Programm:

• Name des Programm
• Art des Programm
• Den Dateinamen des Programm
• Optional Zusatzangaben zu dem Programm

Menüeintrag als Textzeile:

• Text

Der Name des Programm bzw. der Text wird dann beim Modul Start im UC-Menü vom UC-Loader angezeigt. Die Art des Programm benötigt der UC-Loader, damit das Programm korrekt gestartet werden kann. Die Dateiname des Programm benötigt der UC-Builder, damit er es in die UC Image Datei integrieren kann.

Aufruf Parameter

Der UC-Builder ist ein Programm für die Windows Kommandozeile. Die CSV Datei kann man als Parameter angeben. Wird der UC-Builder ohne Parameter aufgerufen, dann sucht das Programm nach einer CSV Datei namens 'menu.csv'. Wenn keine Fehler auftreten beim bilden des Image, dann erfolgt nur die Ausgabe der Image Datei Größe sowie des freien Speicherplatz. Die Berechnung des freien Speicher beruht auf der Annahme, dass das für den Modultype grösst mögliche EPROM bzw. Flash verwendet wird. Alternativ kann man die EPROM Größe als Option angeben.

Optionen:

Beim Aufruf des UC-Builder kann man folgende Optionen angeben. Einige Optionen brauchen zusätzlich ein Argument.

Mit der Option '-h' oder '--help' bekommt man eine Ausgabe aller verfügbaren Optionen zum UC-Builder.
Mit der Option '-V' oder '--version' wird die Version des UC-Builder angezeigt.

Mit der Option '-1' oder '--UC1' wird der UC-Builder angewiesen, eine Image Datei für ein UC-1 Modul zu erstellen.
Mit der Option '-2' oder '--UC2' wird der UC-Builder angewiesen, eine Image Datei für ein UC-2 Modul zu erstellen. Diese Image Dateien laufen auch in der UC-2
Mit der Option '-5' oder '--UC1.5' wird der UC-Builder angewiesen, eine Image Datei für ein UC1.5 Modul zu erstellen. Diese Image Dateien laufen auch in der UC-1.5

Mit der Option '-7' oder '--H64' wird der UC-Builder angewiesen, eine Image Datei für ein Hucky-64K zu erstellen (ab UC-Builder v1.13).
Mit der Option '-8' oder '--MD' wird der UC-Builder angewiesen, eine Image Datei für ein MagicDesk Modul oder ein MagicDesk-128 zu erstellen.
Mit der Option '-9' oder '--EF' wird der UC-Builder angewiesen, eine Image Datei für ein EasyFlash Modul zu erstellen.
Mit der Option '--MegaBit' wird der UC-Builder angewiesen, eine Image Datei für ein MegaBit 128 zu erstellen.
Mit der Option '--U36' wird der UC-Builder angewiesen, eine Image Datei für das interne ROM (U36) zu erstellen. (veraltet, bitte '--F-ROM' benutzen)
Mit der Option '--F-ROM' wird der UC-Builder angewiesen, eine Image Datei für das interne ROM (function ROM) des c128 oder Plus/4 zu erstellen.

Mit der Option '--c16' oder '--plus4' erstellt man eine Image Datei für einen C16, C116 oder Plus/4 (Computer Type 264).
Mit der Option '--c64' erstellt man eine Image Datei für ein Modul im C64 (Computer Type C64).
Mit der Option '--c128' erstellt man eine Image Datei für ein Modul im c128 (Computer Type c128).

Mit der Option '-m' oder '--menu-csv' kann man eine CSV Datei mit beliebigem Namen verwenden.

Mit der Option '-i' oder '--image-file' kann man den Namen der Ausgabe Datei (UC Image Datei) festlegen.
Mit der Option '-c' oder '--crt-file' kann man den Namen der Ausgabe Datei (CRT Datei) festlegen.

Mit der Option '-s' oder '--rom-size' stellt man die Größe des verwendeten EPROM oder Flash Speicher ein (ROM size in KB or in bytes)

Mit der Option '-d' oder '--dump' kann man die Programme aus einem UC-Image extrahieren. Das Ergebnis sind UCF Dateien, eine Datei pro Menüeintrag.
Mit der Option '-D' oder '--dumpDir' kann man das Datei Verzeichnis festlegen, wo die UCF Dateien extrahiert werden.

Mit der Option '-f' oder '--file-info' werden Informationen über eine Datei angezeigt, das funktioniert mit folgenden Typen: UCF, CRT, P00, Imagefile
Mit der Option '-F' oder '--file-dump' zeigt Datei Informationen und erzeugt Dump Dateien aus einer UCF Datei (je nach Inhalt PRG und P00 oder BIN und CRT)

Mit der Option '-I' oder '--info' kann man Informationen über eine Datei erhalten (UCF, CRT oder Imagefile).

Mit der Option '-v' erhöht man die Anzahl der Meldungen, das UC-Builder wird 'gesprächiger'. Die Option kann mehrfach verwendet werden. Ab drei '-vvv' erhält man detaillierte Informationen über den Aufbau der Image Datei, also die Adresse, Bank und Länge jedes Programmes in dem Image. Es wird auch angezeigt wie das Programm geladen und gestartet wird und ob das IO Register verborgen wird.

Am Ende wirft der UC-Builder zwei Dateien aus. Die BIN Datei (EPROM Abbild) ist die Image Datei, die direkt in das EPROM für das Modul gebrannt werden kann. Die CRT Datei ist ein CRT für den VICE, damit kann man die Image Datei gleich testen.

Allerdings kann der VICE die UC Module nicht interpretieren. Es werden zur Zeit bei UC Images nur Standard 8KB CRT Module erzeugt. Deswegen können nur Programme in Bank 0 richtig starten.

Die anderen Modul Typen (Hucky 64K, EasyFlash, MagicDesk und MagicDesk-128) werden vom VICE (aktuelle Version 3.7!) erkannt und funktionieren voll umfänglich.

• 
• 
• 
• 
• 
• 
• 
• 
• 
• 

Datei Typ .UCF

Dateinamen die mit '.UCF' enden sind UC-Apps. Diese Dateien sind C64 Programme, die für den Start aus einem UC Modul (und allen anderen Module die vom UC Builder unterstützt werden) vorbereitet sind. UC-Apps enthalten zusätzliche Informationen (UCF Header) die benötigt werden, um das Programm zu laden und auszuführen.

UCF steht für alles, was man in einem UC Modul starten kann.

Informationen im UCF Header:

• UCF Kennung
• Name im UC Menü
• LOAD Optionen
• RUN Optionen
• Cartridge Einstellungen

Diese Informationen muss man normalerweise in der CSV Datei für den UC-Builder angeben. Die Verwendung einer UCF Datei vereinfacht den Eintrag in der CSV Datei für das Programm. In der CSV Datei muss nur noch der Pfad zur UCF Datei stehen. Als Dateityp kann man 'UCF' angeben, das ist aber nicht zwingend notwendig, weil der UC-Builder eine UCF Datei ohnehin automatisch erkennt.

Die UCF Dateien sind ähnlich zu den CRT Dateien. Auch CRT Dateien werden automatisch erkannt und aus dem Header liest der UC-Builder die LOAD und RUN Optionen. Allerdings sind CRT Dateien beschränkt auf C64 Module. Die UCF Datei kann jedes Programm sein, das man in einem UC Modul verwenden kann.

Die UCF Dateien arbeiten prinzipiell auch für Fremd Module (MagicDesk, EasyFlash, Hucky-64 ...). Die Voraussetzung dafür ist allerdings, dass das Modul die passende Hardware Plattform anbietet. Ein UltiMax Programm kann man zb. NICHT in einem MagicDesk Modul ausführen.

UCF Dateien kann man aus einem UC-Image gewinnen. Der UC-Builder erzeugt UCF Dateien aus allen Programmen in einem UC-Image indem man die Option --dump verwendet. Die Option --dumpDir ermöglicht die Angabe eines Datei Verzeichnis, wohin die extrahierten UCF Dateien geschrieben werden. Es funktioniert mit jedem UC-Image ab Version 1.13, dabei ist es völlig egal, für welche Plattform das UC-Image gebildet wurde.

Eine UCF Datei kann auch mehrere Dateien beinhalten. Wenn man zb. auf einer Diskette mehrere PRG Dateien hat, die alle zu einem Programm gehören, dann kann man die auf einmal laden und starten. Mit anderen Worten, wo man früher mehrere LOAD Befehle gebraucht hat um ein Programm zu starten, das kann man auch in eine UCF Datei packen.

Den Inhalt einer UCF Datei kann man wieder extrahieren. Dazu dient der UC-Builder mit der Option '-F' (--file-dump). Der Inhalt einer UCF Datei ist entweder ein Modulcode oder ein Programmcode. Im Falle von Modulcode erzeugt der File-Dump eine CRT Datei (für den VICE Emulator) und eine BIN Datei (EPROM Inhalt). Im Falle von Programmcode erzeugt der Dump eine PRG Datei und eine P00 Datei. Beide Dateien kann man im VICE ausführen, die PRG Datei kann man zB. mit dem Tool DirMaster in ein D64 Image kopieren.

Aufbau der CSV Datei

Das UC-Builder liest die benötigten Informationen aus einer Text Datei (CSV Datei). Jede Zeile in der CSV Datei steht für ein Programm (bzw. einen Menü Eintrag). Mit der Option -m sagt man dem UC-Builder den Namen der CSV Datei (-m menuFile.csv). Wenn das UC-Builder ohne CSV Dateinamen aufgerufen wird, sucht es automatisch nach der CSV Datei menu.csv.

Beispiel einer CSV Datei:

Programm;           Typ;      Dateiname
Hello World;        PRG;      10-Zeiler\hello world.prg
Fort Apocalypse;    PRG;      Games\Fort Apocalypse.prg
Jupiter Lander;     UltiMax;  Ultimax\Jupiter_Lander.crt
ExBasic-II;         CRT;      CRT\ExBasic II.crt
Test $C003;         BIN;      Test\UC-testc01.prg;               SYS $C003
TSB;                BIN;      BIN\tsb.obj.prg;                   RESET
Help+;              !$8000;   BIN\Help+-C64.bin;                 RESET
-;                  UCF;      UCF\Exass.ucf

Aus der CSV Datei entsteht eine UC-Image Datei mit einem Menü und vier C64 Programmen. Die zweite Spalte enthält den Typ des C64 Programm. Diese Information benötigt der UC-Loader, damit das Programm richtig gestartet werden kann (Ausnahmen sind CRT und UCF).

Programm Zeilen im UC-Menü

Das UC-Menü enthält Menü Einträge. Am Bildschirm können bis zu 36 Menü Einträge stehen, 18 auf der linken Seite und 18 auf der rechten Seite. Jeder der 36 Menüeinträge hat eine feste Position am Bildschirm.

Manche Menüeinträge sind startbare Programme. Jedem Programm im Menü ist eine Taste zugeordnet. Wenn man die Taste drückt, dann wird der zugehörige Menüeintrag (das Programm) geladen und gestartet.

Ausnahme: wenn dem Menüeintrag ein Hilfetext zugeordnet ist, dann wird beim ersten Druck der Hilfetext angezeigt. Beim zweiten Druck wird das Programm gestartet.

Die Tasten werden automatisch den startbaren Menüeinträgen (Programme) zugeordnet. Optional kann man aber auch bestimmen, welche Taste einem Menüeintrag zugeordnet wird. Dazu wird dem Namen des Menüeintrag die Taste voran gestellt.

Die gewählte Taste wird in geschwungenen Klammern gesetzt und muss sich ganz am Anfang des Namen befinden

Beispiel einer CSV Datei mit Tasten Zuordnung:

{ArrowLeft}Hello World; PRG;      10-Zeiler\hello world.prg
{F}Fort Apocalypse;     PRG;      Games\Fort Apocalypse.prg
{£}Jupiter Lander;      UltiMax;  Ultimax\Jupiter_Lander.crt
"{;}ExBasic-II";        CRT;      CRT\ExBasic II.crt
{%}Test $C003;          BIN;      Test\UC-testc01.prg;               SYS $C003
{+}Help+;               !$8000;   BIN\Help+-C64.bin;                 RESET

Ausnahme Strichpunkt:

Der Strichpunkt (";") als Taste für den Start eines Programm hat eine Besonderheit. Der Strichpunkt ist das Trennzeichen in der CSV Datei. Der Parser sieht also eine weitere Spalte anstatt eine 'Taste'. Damit der Strichpunkt als Zeichen gesehen wird anstatt als Trenner, muss man einfach nur die gesamte Namensspalte in Anführungszeichen setzen (siehe Beispiel oben).

Tasten für den Programm Start:

PETSCII	ASCII	Token	Short	Beschreibung
A..Z	{A}..{Z}			Buchstaben von A bis Z
0..9	{0}..{9}			Ziffern von 0 bis 9
"=".."@"	{=}..{@}			Sonderzeichen: =-+*/.,;:!?#$%&'()<>[]@
$5E	{ | }	{ArrowUp}	{AU}	Pfeil nach oben
$5F	{_}	{ArrowLeft}	{AL}	Pfeil nach links
$5C	{£}	{Pound}	{GBP}	Pfund Zeichen

Spalte 1 -- Programm Name

Der Programm Name wird nur für die Darstellung im UC-Menü benutzt. Der Name wird automatisch in PETSCII konvertiert, sofern dies möglich ist. Die Länge wird automatisch auf 17 Zeichen reduziert, damit es am C64 problemlos dargestellt wird.

Sonderfall 1 - der File Browser

Ein Sonderfall ist der Text 'F1'. Wenn der Programm Name exakt 'F1' ist, dann betrachtet der UC-Builder diesen Eintrag als 'File Browser'. Im UC-Menü wird kein Eintrag gebildet, aber es erscheint ganz unten links die Auswahl 'F1-File Browser'. Mit der Taste 'F1' wird dieser Eintrag als File Browser gestartet. Der File Browser wird immer mit aktiviertem IO Register gestartet, damit ggf. später eine Konfiguration des UC Modul erfolgen kann.

Der File Browser kann entweder ein externes Programm oder der interne UC-FB sein. Im Falle des internen UC-FB ist der Programm Typ immer als '---' anzugeben. Und es ist natürlich kein Dateiname nötig, die Spalte drei kann also einen beliebigen Inhalt haben.

Sonderfall 2 - Kein Menüeintrag Name (ab v1.13):

Bei Verwendung von UCF Dateien, kann man auf den Namen des Menüeintrag verzichten. Dazu wird in der CSV Datei als Name nur ein '-' (Bindestrich) verwendet. Im UC Menü wird dann der Name verwendet, der in der UCF Datei gespeichert ist.

Bei UCF Dateien muss man keinen Namen angeben, da der Name in der UCF Datei steht. Natürlich kann man trotzdem einen eigenen Namen wählen und hier angeben. Der Name in der UCF Datei wird in diesem Fall ignoriert.

Sonderfall 3 - Referenzzeile (Datei oder eine Dateigruppe ohne Menüeintrag, ab v1.14):

Wenn der Text in Spalte 1 mit einem Doppelkreuz (§) beginnt, dann handelt es sich um eine Datei ohne Menüeintrag.

Nicht jede Zeile in der CSV Datei wird zu einem Menü Eintrag. Diese Zeilen erzeugen keinen Menüeintrag und dienen nur dazu, eine Datei in das UC Image File zu schreiben. Diese Datei kann dann geladen werden über ein oder mehrere Menü Einträge.

Für 'Datei ohne Menüeintrag' muss die erste Spalte mit einem '§' beginnen. Die Zeichen nach dem '§' ist der Referenzname. Die Datei kann dann in jedem Menüeintrag durch den Referenznamen (zum Beispiel '§ABC') adressiert werden. In einem Menüeintrag kann man dann in Spalte 3 anstatt des Dateinamen einen oder mehrere Referenznamen verwenden. Die Referenzen lassen sich auch stapeln, also eine Referenzzeile kann statt der Datei auch Referenzen enthalten.

Das hat folgende Vorteile:

• ein Menüeintrag kann mehrere Dateien laden
• eine Datei kann von mehr als einem Menüeintrag geladen werden
• die Reihenfolge der Menüeinträge muss nicht mit der Anordnung der Dateien im Image übereinstimmen

Spalte 2 -- Programm Typ

Der Programm Typ steuert, wie das Programm geladen wird. Zudem bestimmt es die Konfiguration der UC Hardware vor dem Programm Start. Zudem wirkt sich der Programm Typ aus auf die Start Option, sofern diese nicht manuell eingestellt wird (siehe Spalte 4).

Folgende Kürzel sind in der Spalte Typ erlaubt

PRG

normales BASIC Programm oder OneFiler, das an der Adresse $0801 (C64), $1001 (C16, C116, Plus-4) oder $1C01 (c128) geladen und mit RUN gestartet wird

BAS2

ein BASIC 2 Programm (zumindest ein SYS xxx) für den c64, das an der Adresse $0801 geladen und mit RUN gestartet wird

BAS3

ein BASIC 3.5 Programm (zumindest ein SYS xxx) für den c16, das an der Adresse $1001 geladen und mit RUN gestartet wird

BAS7

ein BASIC 7 Programm (zumindest ein SYS xxx) für den c128, das an der Adresse $1C01 geladen und mit RUN gestartet wird

BIN

ein Programm mit Ladeadresse, das an beliebiger Adresse geladen und mit SYS oder RESET gestartet wird

BLK nnn

! nnn

eine Datei OHNE Ladeadresse, die an beliebiger Adresse geladen und mit SYS oder RESET gestartet wird

es kann entweder 'BLK' oder '!' verwendet werden, das Ergebnis ist das selbe.

die Datei wird an die angegebene Adresse 'nnn' geladen. Die Adresse kann dezimal, hexadezimal (beginnt mit '$' oder '0x') oder Oktal (beginnt mit '0') angegeben werden

ohne Adresse Angabe wird als default 0x8000 angenommen

8KB

das Programm wird als 8KB Modul gestartet

16KB

das Programm wird als 16KB Modul gestartet

32KB

das Programm wird als 32KB Modul gestartet

UltiMax

das Programm wird als Ultimax Modul gestartet

CRT

der Modul Typ wird selbsttätig erkannt, - nur bei CRT Dateien

UCF

die UCF Datei enthält alle Informationen, die der UC-Builder benötigt

"---"

Sonderfall für die Verwendung des internen UC-FB, wenn der Programm Name exakt 'F1' ist.

es kann aber auch verwendet werden für CRT und UCF Dateien, weil der UC Builder diese Dateien automatisch erkennt.

Spezial Steuerzeichen

"|"

Wenn das erste Zeichen ein senkrechter Strich (|) ist, dann wird für diesen Menü Eintrag das IO Register des UC Modul NICHT deaktiviert. Das bedeutet, man kann nach dem Start des Programm weiterhin auf die Konfiguration des UC Modul zugreifen. Zum Beispiel ist das so bei dem internen File Browser FB.

Spalte 3 -- Dateiname

Der Dateiname am PC, damit der UC-Builder die Datei lesen und in die Image Datei einbinden kann. Es sind alle Arten von Pfade erlaubt, die dem OS bekannt sind (Unterverzeichnisse, andere Laufwerke, absolute Pfade, Netzlaufwerke, Pfad Aliase ...). Dateien werden einfach als Byte Stream gesehen. Es gibt aber Ausnahmen, Dateien die inhaltlich interpretiert werden: P00 und CRT

P00

Diese Dateien werden besonders behandelt, der P00 Header wird überlesen und ab Byte [0x1A] wird als Inhalt verwendet

CRT

Diese Dateien sind 'Modul Dateien' für den Emulator. Sofern es CRT Dateien vom Typ 0 (8K, 16K, 32K, Ultimax oder MagicDesk128) sind, werden sie vom UC Builder und vom UC-FB richtig interpretiert.

UCF

Diese Dateien sind 'UCF Dateien' für den UC-Builder. Die Datei enthält alle relevanten Informationen, die für den Ladevorgang (LOAD) und dem Programmstart (RUN) nötig sind. Die Informationen in der Datei werden sowohl vom UC Builder als auch vom UC-FB interpretiert.

Spalte 4 -- Start Optionen

Die Spalte 4 kann normalerweise einfach weg gelassen werden. Man kann hier eine bestimmte Startoption erzwingen. Wenn die Spalte weg gelassen wird, startet der UC-Loader alle PRG mit einem 'RUN' Befehl, alle Modul Dateien mit einem Soft RESET und alles andere gar nicht (springt nach dem LOAD ins BASIC).

Wenn man eine Startoption definiert, dann führt sie der UC-Loader nach dem LOAD aus, unabhängig davon ob es Sinn macht oder nicht.

Folgende Startoptionen sind erlaubt

RESET

Nach dem laden des Programmes wird ein Soft RESET ausgeführt. Der c128 wechselt vorher in den C64 Modus.

(Das ist Standard bei Programm Typ 8KB, 16KB, UltiMax und CRT für den C64)

RESET128

Nach dem laden des Programmes wird ein Soft RESET ausgeführt.

(Das ist Standard bei Programm Typ 32KB und CRT für den c128)

SYS nnn

Nach dem laden des Programmes wird ein SYS ausgeführt auf die Adresse 'nnn'. Die Start Adresse kann dezimal, hexadezimal (beginnt mit '$' oder '0x') oder Oktal (beginnt mit '0') angegeben werden. Der Commodore c128 wechselt in den C64 Modus.

SYS128 nnn

Nach dem laden des Programmes wird ein SYS ausgeführt auf die Adresse 'nnn'. Die Start Adresse kann dezimal, hexadezimal (beginnt mit '$' oder '0x') oder Oktal (beginnt mit '0') angegeben werden. Die Banknummer ist wie beim internen c128 Monitor die fünfte Hexziffer der Adresse.

RUN

Nach dem laden des Programmes wird ein RUN ausgeführt. Sofern es sich bei dem Programm um ein BASIC Programm handelt, wird es automatisch nach dem LOAD ausgeführt.

(Das ist Standard bei Programm Typ PRG)

READY

Nach dem laden des Programmes wird nichts gemacht. Der UC-Loader springt direkt nach dem LOAD in den Direktmodus des BASIC (Interpreter Loop).

(Das ist Standard bei Programm Typ BIN und BLK)

RAM

Das Programm wird direkt in den RAM des Computer geladen und da ausgeführt. Der UC Loader umgeht so den UC-RAM. Diese Einstellung ist Standard für nicht UC Module. Einige Module vom Typ 8K (auch CRT) können so auch auf nicht UC Module ausgeführt werden. Ultimax und 16K sind so aber nicht ausführbar und ergeben eine Fehlermeldung beim UC-Builder.

ROM

Das Programm wird direkt im ROM (EPROM/FLASH) ausgeführt, ohne zuerst ins RAM geladen zu werden. Der UC Loader selektiert die richtige Speicher Bank und startet dann per Reset. Module vom Typ 8K und 16K werden direkt an der unteren Grenze einer 16K Bank angeordnet. Ultimax Module mit 8K werden automatisch in dem oberen 8K Block einer Bank angeordnet, das ist Standard für Ultimax Module wegen dem Reset Vektor.

Diese Methode hat den Nachteil, dass ein Programm genau an den Block Grenzen einer Bank angeordnet werden muss, dadurch entstehen u.U. Lücken zu dem Programm vorher und der Speicher kann nicht mehr vollständig benutzt werden. Aber es eignet sich gut, wenn hauptsächlich Modul Programme (CRT Dateien) mit 8K und 16K Größe benutzt werden (zB. das Multi-MAX Modul). Im Falle von vielen 8K Modulen wird der Speicher ideal genutzt, wenn sich eine 8K und eine Ultimax immer abwechseln.

ROMX

Das Programm wird direkt im ROM (EPROM/FLASH) ausgeführt, ohne zuerst ins RAM geladen zu werden. Der UC Loader selektiert die richtige Speicher Bank und startet dann per Reset. Module vom Typ 8K werden direkt an der oberen Grenze (ROMH) einer 16K Bank angeordnet. Die Option ROMX ist gedacht für 8KB Ultimax Module. In Kombination mit einem 8KB Modul mit Option ROM wird die 16K Bank optimal genutzt und man verliert keinen Speicher wegen der Blockgrenzen.

Hinweis: für die optimale Nutzung der 16K Bank sollte abwechselnd die Option ROM (8K Modul) und ROMX (Ultimax) verwendet werden. Andernfalls entstehen Lücken wegen der Bank Grenze.

Textzeilen im UC Menü

Das UC-Menü enthält Menü Einträge. Am Bildschirm können bis zu 36 Menü Einträge stehen, 18 auf der linken Seite und 18 auf der rechten Seite. Jeder der 36 Menüeinträge hat eine feste Position am Bildschirm.

Manche Menüeinträge sind Textzeilen. Ab Version 1.13 des UC-Builder kann man Menüeinträge als Textzeile definieren. Der Textzeile ist keinem Programm zugeordnet, sie dient nur zur freien Gestaltung des Menü. Mit Hilfe der Textzeilen kann man den Bildschirm Aufbau etwas freier gestalten. Jede Textzeile belegt den Platz eines Menüeintrag, daher hat die Textzeile eine fixe Cursor Position. Eine leeren Textzeile schafft eine Leerzeile. Damit kann man zB. einen einen Abstand (eine Lücke) schaffen, alle weiteren Programme rutschen eine Position nach unten.

Jede Textzeile kann bis zu 200 Zeichen enthalten. Die Zeichen in der Textzeile können normale Zeichen sein oder Steuerzeichen. Steuerzeichen belegen keine Cursor Position, man verwendet sie um die Farbe einzustellen und um die Position des Cursors zu verändern. Mit den Cursor Steuerzeichen kann man zum Beispiel auch die Kopf- oder die Fußzeile erreichen und manipulieren. Insgesamt erlauben die Textzeilen eine große Freiheit bei der Gestaltung des Bildschirm.

Jedes Zeichen in der Textzeile kann in der gewünschten Farbe ausgegeben werden. Die eingestellte Farbe beeinflusst aber auch alle weiteren Menü Einträge. Wenn man die Menü Einträge im Standard Grün erhalten will, dann muss man am Ende der Textzeile das Farbcode Steuerzeichen für Grün setzen.

Um die Eingabe der Steuerzeichen zu erleichtern, sind Token implementiert worden für jedes Steuerzeichen. Anbei ist eine Liste der unterstützen Steuerzeichen Token.

Steuerzeichen:

PETSCII	Token	Short	Beschreibung
147	{clear}	{clr}	löscht den Bildschirm
19	{home}		Cursor in die Zeile 1 Spalte 1
29	{right}	{rgt}	Cursor nach rechts
157	{left}		Cursor nach links
17	{down}		Cursor nach unten
145	{up}		Cursor nach oben
144	{black}	{blk}	Farbe Schwarz
5	{white}	{wht}	Farbe Weiß
28	{red}		Farbe Rot
159	{cyan}	{cyn}	Farbe Cyanblau
156	{purple}	{pur}	Farbe Violett
30	{green}	{grn}	Farbe Grün
31	{blue}	{blu}	Farbe Blau
158	{yellow}	{yel}	Farbe Gelb
129	{orange}	{ora}	Farbe Orange
149	{brown}	{brn}	Farbe Braun
150	{lred}		Farbe Hellrot
151	{gray1}	{gr1}	Farbe Grau 1
152	{gray2}	{gr2}	Farbe Grau 2
153	{lgreen}	{lgr}	Farbe Hellgrün
154	{lblue}	{lbl}	Farbe Hellblau
155	{gray3}	{gr3}	Farbe Grau 3
18	{rvson}		Invertierte Schrift EIN
146	{rvsoff}		Invertierte Schrift AUS
13	{return}	{rtn}	Zeilenschaltung (Cursor in die nächste Zeile erste Spalte)
14	{letter}		Wählt den Zeichensatz Groß-/Kleinbuchstaben
142	{grafic}		Wählt den Zeichensatz Grafikzeichen

Commodore 264 Serie:

Die 264 Serie von Commodore (C16, Plus/4) haben teilweise andere Farben und auch viel mehr Farben (121). Daher gibt es neue Farbnamen und zusätzlich die Möglichkeit, beliebige PETSCII Code zu senden.

Eine Zahl von 0 bis 255 in geschwungenen Klammern sendet direkt den PETSCII Code (zB. {65} für 'A').

Die aktuelle Zeichen Farbe stellt man ein mit einem 'c' gefolgt von einem oder zwei HEX Zeichen (zB. {c3A}, Farbe A (10) / Helligkeit 3, entspricht: COLOR 1,11,3).
Bei einem Hex Zeichen stellt man die aktuelle Farbe ein (0 bis F).
Bei zwei Hex Zeichen stellt man die Helligkeit + die aktuelle Farbe ein, wobei das erste Zeichen die Helligkeit ist (0 bis 7).

PETSCII	Token	Short	Beschreibung
150	{yelgrn}	{yg}	Farbe gelb/grün
151	{pink}		Farbe pink
152	{blugrn}	{blgr}	Farbe blau/grün
153	{lblue}	{lbl}	Farbe Hellblau
154	{dblue}	{dbl}	Farbe Dunkelblau
155	{lgreen}	{lgr}	Farbe hellgrün

Hilfetextzeilen im UC Menü

Wenn eine Textzeile in der CSV Datei mit einem Fragezeichen (?) beginnt, dann handelt es sich um eine Hilfetext Zeile. Zu jedem Menü Eintrag kann man bis zu drei Hilfetext Zeilen definieren. Wenn Hilfetext Zeilen definiert werden, dann sind die untersten drei Zeilen reserviert für den Hilfetext. Der Hilfetext erscheint, wenn man den Menüeintrag selektiert. Um das Programm zu starten, muss der Menüeintrag ein zweites mal selektiert werden.

Bei einem Menüeintrag ohne Hilfetext wird das Programm sofort gestartet (nur einmal selektieren).

Hilfezeilen in der CSV Datei haben nur eine Spalte. Außer dem Hilfetext gibt es keine weiteren Parameter. Hilfezeilen in der CSV Datei müssen mit einem Fragezeichen (?) beginnen.

Referenzzeilen (Datei, Dateigruppen)

Wenn eine Textzeile in der CSV Datei mit einem Doppelkreuz (§) beginnt, dann handelt es sich um eine Datei ohne Menüeintrag.

Nicht jede Zeile in der CSV Datei wird zu einem Menü Eintrag. Diese Zeilen erzeugen keinen Menüeintrag und dienen nur dazu, eine Datei in das UC Image File zu schreiben. Diese Datei kann dann geladen werden über ein oder mehrere Menü Einträge.

Für 'Datei ohne Menüeintrag' muss die erste Spalte mit einem '§' beginnen. Die Zeichen nach dem '§' ist der Referenzname. Die Datei kann dann in jedem Menüeintrag durch den Referenznamen (zum Beispiel '§ABC') adressiert werden. In einem Menüeintrag kann man dann in Spalte 3 anstatt des Dateinamen einen oder mehrere Referenznamen verwenden. Die Referenzen lassen sich auch stapeln, also eine Referenzzeile kann statt der Datei auch Referenzen enthalten.

Das hat folgende Vorteile:

ein Menüeintrag kann mehrere Dateien laden eine Datei kann von mehr als einem Menüeintrag geladen werden die Reihenfolge der Menüeinträge muss nicht mit der Anordnung der Dateien im Image übereinstimmen

Bemerkungszeilen (remark)

Wenn eine Textzeile in der CSV Datei mit einem Doppelkreuz (#) beginnt, dann handelt es sich um eine Bemerkung zur Dokumentation der CSV Datei. Ebenso sind leere Zeilen erlaubt um eine optische Trennung der Bereiche in der Datei zu erreichen.

Alle Zeichen nach dem (#) Zeichen werden ignoriert.

Variablenzeile

Ab Version v1.16 kann man in der CSV Datei sogenannte Menü Variable setzen. Dazu muss der Text in Spalte 1 mit einem 'Ist gleich' Zeichen (=) beginnt. Menü Variable definieren Menü Eigenschaften wie zum Beispiel die verwendeten Farben (Zeichen, Rahmen, Hintergrund ...). Indem man die Menü Variable auf einen gewünschten Wert setzt, kann man die Menü Eigenschaften umdefinieren von einem Standard Wert zu einem individuellen Wert.

Menü Variable sind zum Beispiel Standardfarben (Zeichen, Rahmen, Hintergrund ...). Damit kann man Menü Eigenschaften umdefinieren von einem Standard Wert zu einem individuellen Wert.

Eine Menü Variable besteht aus dem Namen der Variable, einem 'Ist gleich' Zeichen (=) und einem Wert. Die Spalte 1 der CSV Datei kann mehrere Zuweisungen zu Menü Variablen enthalten. Die Zuweisungen werden durch einen Doppelpunkt getrennt.

Beispiel von Zuweisungen zu einer Menü Variable:

= colBorder=00 : colBack=71 

Die Bedeutung des Farbcodes für die Menü Variablen hängt ab von der Geräte Type:

• Im Falle von C64 und c128 ist es eine Zahl von 0 bis 15 (black, white, red, cyan, purple, green, blue, yellow, orange, brown, pink, dgrey, grey, lgreen, lblue, lgrey)
• Im Falle eines C16 oder Plus/4 ist es eine Zahl von 0 bis 255 (Bit 0-3: Farbe, Bit 4-6: Helligkeit)

Variablen Namen:

Variablen Name	Beschreibung
colBack	Hintergrund Farbe (Wert hexadezimal)
colBack2	Hintergrund Farbe 2 (nur c264)
colBack3	Hintergrund Farbe 3 (nur c264)
colBorder	Rahmen Farbe
colStat	Farbe für statischen Text (Rahmen etc.)
colEntry	Farbe für Menüzeilen (Programm Namen, Menü Text)
colHelp	Farbe für Hilfe Textzeilen
colKeyA	Farbe für aktive Tasten
colKeyP	Farbe für passive Tasten (Tasten die gerade inaktiv sind)
colPageA	Farbe für aktive Menü Seite
colPageP	Farbe für mögliche Menü Seiten

Mehrere Menü Seiten

Ab Version 1.14 werden mehrseitige Menüs unterstützt. Eine Menü Seite hat bis zu 42 Menü Einträge. Speziell bei 1 MB Module kann man da leicht an die Grenzen kommen. Wenn man viele kleine Programme hat, oder wenn man viele Textzeilen benutzt, dann reichen die 42 Menü Einträge nicht aus.

Der UC-Builder bildet automatisch eine neue Menü Seite, sobald man mehr als 42 Einträge hat.

Das UC-Menü zeigt in der Kopfzeile die aktuelle Seite (in hellgrau) an, alle anderen Seiten werden in dunklem Grau angezeigt. Der Wechsel zur nächsten bzw. vorherigen Seite erfolgt über die Cursortasten (<Cursor links>, <Cursor rechts>). Die Zeichen '<' und '>' symbolisieren die Cursortasten für den Seiten Wechsel. Wie immer im UC-Menü symbolisiert die Farbe weiß, dass der Seitenwechsel möglich ist. So ist '<' in grau dargestellt, wenn man sich auf der ersten Seite befindet. Und '>' ist in grau dargestellt, wenn man sich auf der letzten Seite befindet.

Bei bis zu 5 Menü Seiten ist das Format '<1..n>'. Bei mehr als 5 Menü Seiten wird nur noch die aktuelle Seite angezeigt im Format '<n>'.

Der File Browser (UC-FB)

Der UC File Browser wird vom UC-Menü gestartet mit der Taste <F1>. Der UC File Browser ist nur verfügbar, wenn im CSV File ein Dummy Eintrag gemacht wird. Der Menütext (erste Spalte) muss 'F1' lauten und die zweite Spalte enthält drei Bindestriche ('---'). Die dritte Spalte wird nicht ausgewertet. Optional kann man statt des internen UC-FB auch einen eigenen Browser einbinden, dazu muss nur die erste Spalte exakt 'F1' enthalten.

Der UC-FB läuft als 8KB ROM und ist sonst wie der normale FB v2. Er startet Programme, wechselt in Verzeichnisse oder Disk Image Dateien und verlässt diese auch wieder. So kann man sehr komfortabel auf einem SD basierten Laufwerk (wie das SD2IEC) navigieren.

Der UC-FB kann auch CRT Dateien vom Typ 0 starten. Es wird automatisch der Modul Typ (8K, 16K oder Ultimax) aus dem CRT File gelesen und entsprechend in den UC RAM geladen. Der Start erfolgt über einen Soft Reset.

• 

News

• 01.10.2021 -- Release UC-Builder v1.07
• 29.10.2021 -- Release UC-Builder v1.10
• 13.01.2022 -- Release UC-Builder v1.11
• 11.11.2022 -- Release UC-Builder v1.12
• 09.06.2023 -- Release UC-Builder v1.13
• 01.11.2023 -- Release UC-Builder v1.14
• 02.04.2024 -- Release UC-Builder v1.15

Downloads

• Aktuelle Version des UC-Builder: v1.15
• UC-Builder: v1.13

Links

• Allgemeines zu C64 Universal Cartridge
• Handbuch zur UC-1
• Handbuch zur UC-1.5
• Handbuch zur UC-2

• EasyFlash Entwickler Doku
• EasyFlash Sample Code
• 1MB MagicDesk Doku
• Hucky's Bastelbude - Hucky 64K Cartridge
• MagicDesk-128 Modul
• MagicDesk-264 Modul (c264 Magic Cart)