Definitions of the technical jargon used in this guide.

A

A

The CPU's accumulator register. In this guide, the register name is written capitalized and in boldface to avoid confusion with the English word.

ASCII

"American Standard Code for Information Interchange." A code in which specific text characters have fixed values. The Unicode codepoints 0 through 127 have the same meaning in ASCII, and UTF-8 is a superset of ASCII, in order to maintain pre-Unicode compatibility. GEOS uses a subset of ASCII which includes the full set of printable ASCII characters. GEOS doesn't use PETSCII.

Autoexec

A type of application that, if present on the GEOS boot disk, runs automatically in between GEOS booting and the deskTop being loaded. They are sometimes called AUTO-EXEC files.

B

BCD

Binary-coded decimal. In BCD, each nybble of a byte is treated as a decimal number; that is, it's expected to have a value between 0 and 9 (or between $0 and $9, or between %0000 and %1001). In the absence of any other context, the high nybble contains the 10's place digit, and the low nybble contains the 1's place digit. In BCD arithmetic, unlike in binary arithmetic, adding 1 to a nybble containing 9 results in the nybble containing 0 and a carry into the next nybble. The 6502-series CPU has a decimal mode flag for BCD arithmetic, but only the adc and sbc instructions use decimal mode. Most of the CIA chips' clock data is handled in BCD instead of binary.

bit

A binary digit, the smallest unit of data in the computer. A bit is in one of two states: set or clear. In most assemblers, the states are written as "%1" and "%0" respectively.

box

Any rectangular region on the screen. The box edges are always horizontal and vertical, defined by the pixel row of the top and bottom edges and the pixel column of the left and right edges.

Boyce

Alex Boyce analyzed a version of the GEOS Kernal and wrote a programmer's reference guide based on his findings. The guide is riddled with errors, but programming documentation was hard to come by at the time, and it was complete and correct enough that intrepid programmers could figure out how GEOS really works. Bo Zimmerman later revised and corrected Boyce's guide. These two guides and the incompleteness of BSW's documentation served as the inspiration for Ariel's GEOS Programmer's Reference Guide.

BSW

Berkeley Softworks, the company that made GEOS. "BSW" is also the name of the GEOS system font.

BSW 9

The GEOS proportional-width system font and size: 9 pixels high.

byte

The smallest atom of data in the computer. A byte is composed of eight bits. Depending on context, a byte can represent a byte-size flag, a collection of bit flags, an integer (signed or unsigned), an ASCII character code, an unusual combination, or other data. In this guide, decimal numbers are written unmodified, hexadecimal numbers are written with leading dollar signs ($), and binary numbers are written with leading percent signs (%). Hex bytes are always written as two hex digits, and binary bytes are always written as eight binary digits, both forms with leading zeros if needed.

byte, high

The byte of a word value stored at the higher address in memory, or the second byte of a word value in memory dumps or fills. The fact that the high byte holds the most significant bits is due to the 6502 series of CPUs being little-endian.

byte, low

The byte of a word value stored at the lower address in memory, or the first byte of a word value in memory dumps or fills. The fact that the low byte holds the least significant bits is due to the 6502 series of CPUs being little-endian. In memory, the low byte's address is the address of the word.

byte, signed

The most significant bit of a signed byte is the sign bit, clear for 0 or positive, set for negative. The positive range of values is 0 through 127, and the negative range of values is -128 through -1. Note that hex and binary numbers are never written as signed numbers; the negative range is always written as $80 through $ff and %10000000 through %11111111.

C

C128PRG

The Commodore 128 Programmer's Reference Guide, Commodore's official programming manual for the 128.

C64PRG

The Commodore 64 Programmer's Reference Guide, Commodore's official programming manual for the 64.

clear

With regard to bit flags, this is the bit state %0. The opposite state, %1, is called "set." The clear state is often called "reset," but this guide strives to call it "clear" to avoid confusing set and reset with each other.

click

A press of the main button on the input device. This term comes from the clicking sound that early computer mice made when their buttons were pressed. To "click a thing" or to "click on a thing," such as a menu, button, or icon, means to move the mouse pointer so that its hot-spot is over the thing, then while it is there, to press the main button. A click causes GEOS to call the appropriate service routine or to jump through the appropriate API vector based on the thing clicked on. The main button in GEOS-provided input drivers is the fire button on a joystick and the left button on a mouse.

click, double

A double-click is two clicks in rapid succession. Icon service routines can perform different actions based on whether the corresponding icon was double-clicked or not. GEOS maintains a counter, dblClickCount, to tell whether a second click is a double-click or not. The double-click window in GEOS is 0.5 seconds (0.6 seconds on PAL Commodores).

click box

An icon. Boyce's guide called icons click boxes, and Zimmerman kept the term in his revision.

CRT

Cathode ray tube. This was the most common type of display in the 1980s. Most 8-bit computers using external displays produce NTSC or PAL video signals so that an ordinary CRT television could be used. CRTs use an electron beam sweeping horizontal lines across the screen from left to right, whole lines from top to bottom, to show a picture, and this technique allows light pens to be used with CRTs as input devices. CRTs were eventually succeeded by thinner TV display technologies, such as plasma, LCD, and LED, which don't use an electron beam.

cursor

Also called the text cursor and, in modern GUIs, the caret. GEOS uses sprite 1 for the text cursor, making it an unadorned vertical bar equal in length to the font height, and blinking it on and off about once a second.

D

desk accessory

A special kind of program designed to run without having to quit an application program. GEOS suspends the application, saves its state, runs the desk accessory, then restores the application's state and resumes the application.

dialog box

A built-in GEOS structure designed for interacting with the user in any combination of simple or complex manner. All GEOS dialog boxes are modal.

diskTurbo

Commodore's floppy disk drives, especially the 1541, are notorious for being slow, but shortly after the 1541's release it was realized that clever programmers could upload their own faster data transfer code to the disk drive and run it on their built-in computers. Such programs came to be called turbo software. Berkeley Softworks made their own GEOS-specific turbo software, but official GEOS documentation is inconsistent at best with regard for its name. Interestingly, the GEOS 2.0 Demo disk advertizes the feature as "diskTurbo." This guide calls it diskTurbo because that seems most consistent with BSW usage.

driver

A program that wedges into the GEOS Kernal in order to interface GEOS to a device. Disk drivers are built into GEOS (although custom drivers for unusual disk drives are suspected to exist). Input drivers are provided with GEOS, and the GEOS Kernal loads the first one found automatically during startup. Printer drivers are provided with GEOS, some printers, and some applications, but one is not loaded except on demand by programs needing printer access.

F

file header

Unlike regular Commodore files, GEOS files have a header block that is separate from the file's data. GEOS relies on a variety of information in this header to handle the file properly. Most of the data displayed by the deskTop's "get info" command is read from the file header.

flash

Inverting a box on the screen twice, quickly enough that the user perceives it as a flash, but not so quickly that the user can't tell what flashed. GUI items that typically flash are menu commands when clicked and icons when clicked.

flippy

A floppy disk that has been formatted on both sides for the single-sided Commodore 1541 disk drive. They are called flippy disks because the user removes the floppy disk from the drive, flips it over, and inserts it back into the drive upside down. GEOS itself and many GEOS programs shipped on flippy disks. Flippy disks are unique to single-sided disk drives that use 5.25-inch or 8-inch floppy disks.

font

The collection of graphics data that represent all of the displayable text characters. Every font has a name and a height size. Virtually all GEOS fonts are proportional fonts. The system font built into the GEOS Kernal is called BSW 9.

G

geoProgrammer

A suite of GEOS applications for creating GEOS programs in 6510 assembly language. It includes an assembler, a linker, and a debugger, along with example source code. The assembler takes geoWrite documents as source code, and it can process geoPaint photo scraps pasted into source code as inline graphics data ready for the BitmapUp routine. geoProgrammer also includes several important geoWrite documents:

• geosSym - GEOS symbols (variables, constants, routines), uncommented
• geosMac - GEOS macros, uncommented
• geosMacros - Macros frequently used in GEOS source code, fully commented
• geosMemoryMap - GEOS API variables with brief descriptions
• geosRoutines - API jump table addresses to GEOS routines
• geosConstants - Common values for variables and routines with comments

geoProgrammer also has many bugs, which you can read about in the geoProgrammer Errata.

geosSym

The uncommented symbols file included with geoProgrammer that is supposed to define every routine address, every variable address, and every constant value available in the GEOS API. This book tries to take care to point out the constants, variables, and routines listed in official GEOS programming documentation but not listed in any version of geosSym.

GUI

Graphical user interface, characterized by the presentation of program commands as menus and icons which are selected by a pointer. On Commodore 8-bit computers, GEOS is the epitome of the GUI.

H

hex

A shorter way of writing or saying "hexadecimal."

hexadecimal

A base-16 number or digit. The first ten digits are 0 through 9, same as decimal, while the remaining six digits are the letters A through F in English alphabetical order. Most assemblers understand hex numbers written with uppercase, lowercase, and mixed-case letters, but to aid readability mixed-case is rarely used in source code or documents. Most 6502 assemblers require hex numbers to be written with a leading dollar sign ($); geoProgrammer is one of them. This guide uses leading dollar signs and lowercase letters in hex numbers.

HHGG

The Hitchhiker's Guide to GEOS. Although it's an official BSW document, and very long and nearly complete at that, it's more a collection of still-incomplete programming notes than a single comprehensive manual.

hook

A routine that replaces the target routine of a vector. A program usually hooks into an API vector by saving the vector's value to a private vector address, then saving the hook routine's entry address to the API vector address. The hook routine is written so that, when it finishes, it jumps through the private vector, which points to the original target. A common synonym for hook is wedge.

hot-spot

The pixel of the mouse pointer's image that is said to be the mouse pointer's coordinates. This is the pixel that matters when GEOS determines which thing was clicked. On Commodores, when GEOS uses hardware sprite 0 for the mouse pointer, the hot-spot is always the upper-left pixel of the sprite, and this is why the default pointer's sprite image is an arrow pointing up and left diagonally, aligned to the upper-left corner.

I

icon

A rectangle on the screen that responds to mouse interaction. In GEOS, icons are part of an icon table; when a user clicks on an icon, GEOS calls the icon's service routine. GEOS provides icon-specific graphics routines to let you offload icon management to GEOS.

imprint

To copy a box from the foreground screen to the background screen. GEOS does this whenever it needs to display system elements like menus and dialog boxes.

information sector

The file header. Boyce's guide called it the information sector, and Zimmerman kept the term in his revision.

inline data

A short data structure present in the middle of a routine's code. Inline data is most often expected in the bytes immediately following a jsr to an inline routine.

inline routine

A GEOS Kernal routine that expects its parameters to be provided in the bytes immediately following the jsr instruction that called it, saving the programmer from the boilerplate code of loading and storing the routine's parameters. The inline routine computes the proper return address from the inline data it finds and modifies the stack appropriately. Care must be taken to ensure the inline data is properly formatted; if it is too long or too short, the Kernal routine will rts to a wrong address and probably crash the system.

input device

The hardware device that controls the GEOS mouse pointer. It interacts with GEOS through an input driver. Most input drivers need the input device connected to Control Port 1. The default input driver in a new GEOS installation is the joystick driver.

interleave

The number of disk sectors that should be skipped between consecutive blocks of a file. The Commodore 1541 floppy disk drive is notorious for its slow data transfer speed, and even with GEOS diskTurbo running in the drive's computer, the speed is still slow enough that several sectors pass under the read-write head in the time it takes to transmit or receive one sector's data over the serial bus. If a file is saved with the wrong interleave, then the drive has to wait for the disk to spin around, potentially all the way around, before the right sector passes under the head again. GEOS disk drivers choose an interleave such that, when the drive has finished transmitting one sector's data to the 64 or 128, the head is just about to start reading the next sector.

• GEOS also has a variable in the memory map called interleave.

Interrupt Level

The subsystem of GEOS that manages time-based and time-sensitive events. On Commodores, Interrupt Level is the subsystem that responds to IRQ triggers, which are more or less reliably generated by the VIC-II chip. On Apples, Interrupt Level is most often a phase of the Main Loop subsystem because there's no guaranteed-present IRQ source. (The reality is more complicated than this simplification.)

invert

Changing the pixels of a point, line, or box so that on pixels are turned off and off pixels are turned on, creating a color-swapped or color-inverted image. A box that's inverted twice in rapid succession is said to flash.

J

jump table

A region of the GEOS API which allows your programs to call GEOS Kernal routines. Each entry in the jump table is three bytes long and contains a jmp instruction to the routine. The jump table ensures that every routine is accessible at the same address in every version of GEOS supporting it, regardless of where it exists in the Kernal from version to version.

• Note: The jump tables in Apple versions of GEOS are incompatible with the jump table in Commodore versions of GEOS, and vice versa.

K

Kernal

The kernel, heart, or core of an operating system. Commodore accidentally used the misspelling "kernal" in VIC-20 programming guides, then they retroactively applied it as the name of all their 8-bit ROM-based operating systems. Berkeley Softworks adopted the misspelling as the name of the GEOS kernel; it is called the GEOS Kernal.

L

light pen

A pen-shaped input device designed to use a CRT's screen as a drawing surface. The tip of the pen is fitted with a sensor that detects when the CRT's electron beam sweeps past; the computer uses the timing of that detection to determine which pixel on the screen that detection coincides with. The close relationship with CRT displays makes light pens unusable on non-CRT displays.

M

Main Loop

The subsystem of GEOS that manages processes, scans for events, and dispatches their handler routines. GEOS is designed so that the overwhelming majority of the system's running time is spent in Main Loop.

menu

A hierarchical structure of commands and options for the user to select from. An individual menu item can open a submenu, activate a command or set a configurable option, or both.

menu, main

The root menu of the menu structure. By convention, the main menu should be a horizontal menu rooted in the upper-left corner of the screen, every menu item in the main menu should open a submenu, and no menu item should activate a command. Your programs are free to be exceptions, but you should make sure its users understand that from context. (On other GUIs, where such rare menus are used, one way they indicated that a main menu item was a command is by adding an exclamation point (!) to the item name.)

menu, sub

A menu within the menu structure below the main menu in the hierarchy. By convention, submenus should be vertical menus. First-level submenus should appear directly beneath the main menu item that caused it to open. Second-level and lower submenus should appear to the right of the higher-level submenu, with the menu's first item on the same row as the item in the higher-level submenu that caused it to open.

mouse

Either a hardware input device, such as the Commodore 1351, or the main non-text pointer on the screen, regardless of hardware input device. The main pointer image used in GEOS is called the mouse or the mouse pointer. Through an input driver, GEOS moves the pointer according to the motions of the input device, and GEOS interprets a click according to the main button of the input device. GEOS reserves sprite 0 (or soft-sprite 0) for the mouse pointer, and on Commodores the pointer's hot-spot is always the upper-left pixel of the sprite.

N

null byte

A zero byte. The value is $00 and is usually named NULL in assemblers. GEOS typically uses null bytes as sentinels indicating the end of strings and structures with a variable number of members.

null-terminated

Terminated with a null byte. Strings are the structures most often referred to as null-terminated.

nybble

One half of a byte, or four bits. Bits 0-3 are the low nybble, and bits 4-7 are the high nybble. When a byte's value is written in hex, the 16's place digit is the high nybble value, and the 1's place digit is the low nybble value. Nybbles are most often used in BCD encoding and the Commodore 64's color map.

O

OGPRG

The Official GEOS Programmer's Reference Guide. This, as far as ArielMT knows, is the only actually official programming manual for GEOS. It covers only the Commodore 64 versions of GEOS, and only up to V1.2. The book is also riddled with errors and in some ways highly incomplete. (For example, desk accessory programming is not covered and barely mentioned.)

P

PETSCII

An ASCII-like set of character codes used in Commodore 8-bit computers (originally on the Commodore PET). The Commodore 64 and 128 have two PETSCII sets, one with uppercase letters and graphics drawing symbols, and one with lowercase letters and uppercase letters. Neither PETSCII set is ASCII compliant because Set 1 is missing the lowercase letters, Set 2 has the sequences of uppercase and lowercase letters swapped, and both sets are missing characters such as the backslash, caret, and underscore. GEOS does not use PETSCII, and GEOS programs running on Commodore computers and accessing non-GEOS Commodore files have to take care of translating text between ASCII and PETSCII themselves.

pixel

A picture element, the smallest atom of an image on either screen. GEOS uses the double-hires mode of the Apple IIe and the standard bitmap mode of the Commodore 64 and 128. In these modes, a pixel's state is one of two colors, usually referred to as on and off, or foreground and background. In screen area memory, a set bit corresponds to an on pixel, and a cleared bit corresponds to an off pixel.

process

A kind of event that needs to happen on some kind of recurring schedule. GEOS manages process timers during Interrupt Level. When an unblocked process's timer expires, GEOS calls the process routine during Main Loop. Boyce and Zimmerman remark that GEOS processes are the beginnings of multitasking.

R

recover

To copy a box from the background screen to the foreground screen, causing the box contents to be displayed. GEOS does this whenever it needs to erase system elements like menus and dialog boxes.

recurring timed event

A process. Boyce's guide called them recurring timed events, and Zimmerman kept the term in his revision.

S

scanline

A row of pixels on the screen. More technically, the line drawn across the backside of a CRT's screen by the sweeping motion of CRT's electron gun. Plasma, LCD, and LED screens simulate this action to remain compatible with video signal standards. A scanline is synonymous with a pixel row for the most part.

screen

In GEOS, a screen is one of two memory areas corresponding to the image displayed on the monitor. Screen 1, also called the foreground screen, contains the actual image used by the video hardware to display a picture, and screen 2, also called the background screen, contains a virtual screen used for picture recovery. GEOS imprints a box on the background screen before drawing system elements like menus and dialog boxes, and GEOS recovers that box from the background screen when erasing those same elements. The background screen is also useful for picture staging.

set

With regard to bit flags, this is the bit state %1. The opposite state, %0, is sometimes called "reset" and sometimes called "clear." This guide calls the opposite state clear to avoid confusion with set. The word "set" is also used as a verb, but great effort has been made to ensure it means placing a bit in the set, not-clear state.

skew factor

See interleave. Boyce's guide called it the skew factor, and Zimmerman's revision kept the term.

sprite

An independently movable graphics object. The VIC-II chip in the Commodore 64 and 128 allows you to control up to eight sprites at a time, and the chip takes care of overlaying sprites on top of the displayed image without the need to draw, erase, and redraw anything on the screen. GEOS reserves sprite 0 for the mouse pointer and sprite 1 for the text cursor.

sprite, soft

A soft-sprite is a simulated sprite. GEOS 128 and Apple GEOS use soft-sprites to simulate many of the behaviors of the VIC-II chip's hardware sprites entirely in software.

string

A sequence of bytes, almost always ASCII character codes and control codes, terminated by a NULL ($00) byte. GEOS uses two types of strings: text and graphics. Text strings are displayed by the PutString routine, and graphics strings are displayed by the GraphicsString routine.

submenu

See "menu, sub" above.

T

turbodos

See diskTurbo. Boyce's guide calls it turbodos, and Zimmerman's revision kept the term. Berkeley Softworks documentation is inconsistent on the name of this feature.

V

variable

A memory address or range of addresses defined by a symbol name in the assembler, allowing its data to be conceptually treated like a variable in a higher-level programming language. GEOS provides several ranges of programmer-accessible variables as part of its API, and they are documented in the memory map. Many hardware I/O registers are also treated as variables.

vector

A word variable whose value is the address of a routine's entry point. The variable is said to point to the routine, and the routine is said to be the vector's target. The indirect mode of the jmp instruction is what makes vectors powerful: when a vector named "MyVector" points to a routine named "MyRoutine," jmp (MyVector) has the same effect as jmp MyRoutine. Vectors can be changed to point to other routines without changing the code jumping through the vector.

• GEOS provides several vectors for your program to hook in custom routines.
• GEOS makes use of null vectors which, if used directly, will crash the system. GEOS provides the routine CallRoutine, which ensures null vectors are never jumped through.

vector, null

A vector pointing to $0000. GEOS uses the value $0000 as a sentinel to mean that there's no actual target routine for the vector, and so it shouldn't be jumped. Use CallRoutine to jump through a vector, and it will detect and avoid jumping through a null vector for you.

vertical refresh cycle

CRTs use an electron gun to sweep a beam across the screen. After drawing a scanline, the beam is turned off while it's aimed at the start of the next scanline, and after drawing a frame, the beam is turned off while it's aimed at the start of the first scanline. These two periods are called horizontal refresh and vertical refresh cycles, and the periods at the end of each cycle, where the beam is off, are the horizontal and vertical blank periods. The vertical refresh cycle is more interesting with respect to GEOS because, on the Commodore 64 and 128, the VIC-II chip triggers an IRQ at the start of the vertical blank period. GEOS uses the reliability of this IRQ as the basis for its Interrupt Level cycle.

VLIR

Variable Length Index Record, a kind of GEOS file with up to 127 data streams, not counting the file header block. Each data stream is a self-contained record with no fixed length, almost treated like a separate file in its own right. The geoWrite application and geoWrite documents are examples of VLIR files.

W

wedge

A routine or collection of routines that hook into API vectors, which usually finish by jumping through private vectors to the routines the API vectors initially pointed to.

window

See dialog box. Boyce's guide calls dialog boxes windows, which they sort of are, but it's the only built-in GEOS structure that conceptually could be.

word

A special grouping of two consecutive bytes to form a 16-bit integer value. Since 6502-series CPUs are little-endian, the least significant bits are in the first or low byte, and the most significant bits are in the second or high byte. The high byte's value is the quotient part of the word value divided by 256, and the low byte's value is the remainder part of that same division (or the word value modulo 256). An interesting effect is that when the word value and separate byte values are written in hex, the first two and last two hex digits are swapped; for example, the word value $d021 is stored as the byte values $21, $d0. (The same word value in decimal, 53281, is stored as the byte values 33, 208.)

word, signed

The sign of a signed word is the most significant bit of the high byte. Like a signed byte, the sign bit is clear for 0 or positive, and set for negative. The positive range of values is 0 through 32767, and the negative range is -32768 through -1. Like signed bytes, signed words are never written with signed values in hex or binary. In hex, the negative range is always written as $8000 through $ffff.

X

X

Depending on context, the screen's horizontal coordinate axis or one of the CPU's index registers. In this guide, the register name is written capitalized and in boldface to avoid confusion with a constant or variable, as well as to be consistent with describing the A register.

Y

Y

Depending on context, the screen's vertical coordinate axis or one of the CPU's index registers. In this guide, the register name is written capitalized and in boldface to avoid confusion with a constant or variable, as well as to be consistent with describing the A register.

Z

zero byte

A null byte. The value is $00 and is usually named NULL in assemblers. GEOS typically uses null bytes as sentinels indicating the end of strings and structures with a variable number of members.

Zimmerman

Bo Zimmerman recognized that Boyce's guide was both extremely useful and in need of correction and updating. Zimmerman's guide, a revision of Boyce's guide, has circulated since in user groups and later on the Internet. These two guides and the incompleteness of BSW's documentation served as the inspiration for Ariel's GEOS Programmer's Reference Guide.