C64 OS USER'S GUIDE

Chapter 7: Utilities

Utilities are small C64 OS programs that load to a dedicated area of memory, and can be opened and used concurrently with any C64 OS Application.

Utilities typically display a floating panel that can be moved around the screen. Usually these Utility panels are not modal, and allow you to interact with a use the underlying Application at the same time. In many cases, Utilities are designed to exchange messages with the Application allowing them to extend and enhance the functionality of the Application.

See Chapter 4: User Interface → Applications and Utilities for more general information about Utilities.

In a few cases, indicated below, a Utility panel is modal. This means that, while it is open, it blocks the ability to click on the Application below and disables its menu options. This is quite rare, and only occurs in circumstances where it is imperative that the Application not change its state while the Utility does its work.

Below is a reference to the most common Utilities included with C64 OS. This is not a definitive list; new Utilities continue to be written. The Utilities listed below are given in three main groups:

Stand-alone Utilities

These do not require any particular interaction with the main Application, but are useful all on their own. These are like mini Applications.

Helper Utilities

These are meant to be used in conjunction with the main Application to provide it with features that can be used by multiple Applications. These may not be of much use if opened manually above an Application that can't make use of them.

Open and Save Utilities

There are two additional Utilities, Open and Save. These could have been grouped as Helper Utilities, but their functionality is advanced. They share common user interface elements with each other and with File Manager. They interact with the file system and are important to C64 OS at a lower level. For this reason, they warrant special discussion which is covered in Chapter 8: File System → Open and Save.

How to install/uninstall Utilities

A Utility consists of a single executable file. In order to install a Utility and make it accessible and launchable by C64 OS, use File Manager to copy the Utility into the system's Utilities directory:

//os/utilities/

When a Utility is run, it creates a temporary state file in one of two places. Either in the system's settings directory, or inside the Application bundle of the Application that is running when the Utility is opened.

To uninstall a Utility, use File Manager to move the Utility file from the system's Utilities directory to some alternative directory for backup and safe keeping. A Utility's state file is named based on the name of the Utility, but ends with a .i extension. These files are very small and are typically left behind. A state file can always be safely scratched, as its Utility will recreate it automatically the next time it's run.

The Utilities Menu

The Utilities menu is available from the far left end of the menu bar. This menu is available in every Application, automatically and without requiring special support by the Application.

The Utilities menu definitions file enables Utilities to be organized with spacers, and hierarchically into sub-menus. It also enables common Utilities to have keyboard shortcuts.

In version 1.0 of C64 OS, the Utilities menu is pre-populated with a core set of useful Utilities:

  • About This App
  • Settings
  • Utilities
  • -
  • Peek
  • Calculator
  • Clipboard

With these Utilities available at all times from the Utilities menu, you can view the name, version, author, Application icon and copyright information of the Application currently running; access Utilities for configuring system settings; access any Utility from a master list of all installed; inspect the C64's memory; perform quick calculations; and view the contents of the clipboard.

Remember, in addition to those available in the Utilities menu, the menu bar clock and the available memory indicator in the status bar can be used to open one Utility each, with a double-click.

Editing the Utilities Menu

The contents of the Utilities menu comes from utilties.m, a menu definitions file found in the system's settings directory.

//os/settings/:utilities.m

This file can be edited by a programmer or a competent hacker, but is not intended to be edited by ordinary users. See the C64 OS Programmer's Reference Guide for further information about how menu definitions files are structured.


Stand-alone Utilities


About C64 OS

Gives the version number of C64 OS that you are running. It also shows the C64 OS logo, and gives some copyright information. About C64 OS can be opened by choosing About from the General section of the Settings Utility.

There are two tabs at the bottom, info is the main tab whose content is described above. The mods tab gives an alphabetical list of C64 OS KERNAL modules and the memory address where each one begins. This is useful for hackers and programmers.

Beginning in C64 OS v1.04, the version number can be clicked to toggle between the version number and the build number. The build number is in the format {primary_version}.{secondary_version}.{YYMMDD} where YYMMDD is a 2-digit year, month and day when the current build of C64 OS was packaged up. E.g., 1.02.230105 means version 1.02, built on January 5, 2023.

About C64 OS Utility, Info Tab. About C64 OS Utility, Mods Tab.

Calculator

A basic desktop calculator, with some scientific features.

Press COMMODORE+C, or double-click the calculator's screen, to copy the number displayed on it to the clipboard. Press COMMODORE+V to paste a number from the clipboard to the Calculator. Only clipboard data of type text/number may be pasted.

Click on DEG to change from Degress to Radians (RAD). Click on RAD to change from Radians to Degrees.

The number keys and period can be used to trigger the number buttons and decimal point button. Plus, minus, asterisk and slash keys can be pressed to trigger the add, subtract, multiply and divide buttons. The X key can be used as an alternative for the multiply button. The equals key or RETURN both trigger the equals button. Press CLR to trigger the clear button. The up arrow key triggers the Xx button. The DELETE key can be used to delete numbers that have been typed when the screen is in edit mode.

The memory functions can also be controlled by the keyboard. COMMODORE+0 for memory clear, stores the value zero into the calculator's memory. COMMODORE+PLUS adds the value displayed on the screen to the running memory total. COMMODORE+MINUS subtracts the value on the screen from the running memory total. Press R to recall the memory value.

The Calculator is found in the Utilities menu by default, and can be opened with the keyboard shortcut SHIFT+CONTROL+COMMODORE+C. This allows you to open the Calculator, from within any Application, enter basic calculations, copy the result to the clipboard, and close the Calculator without ever having to touch the mouse.

When the Calculator is closed and later reopened, it retains its memory and DEG/RAD mode.

Calculator Utility.

BASIC Math Operations

The Calculator Utility makes use the C64's BASIC ROM to perform all of its floating point math operations. The BASIC ROM's implementation is known for having a number of idiosyncracies and precision errors. C64 OS's calculator exhibits exactly the same issues, on account of its use of the BASIC math routines.

A charitable interpretation is that it retains the charm of the C64's BASIC math abnormalities.


Clipboard

The clipboard is stored in files in the system's clipboard directory. The file 0.t contains the metadata about the clipboard content's datatype and size. The file 0.d holds the clipboard's data.

The Clipboard Utility lets you see that metadata. The data and time comes from the timestamp saved on the clipboard data file when it was last written. In order to be accurate, the system device must have an RTC, set with the correct date and time.

The preview area shows a sample of the content, if the data's type is text. A preview is not available for non-text data types.

The Clipboard Utility can be found in the Utilities menu, by default.

Clipboard Utility.

See Chapter 4: User Interface → Clipboard for more information about how the clipboard works.


Drives

The Drives Utility can be opened from the Hardware section of the Settings Utility.

Drives shows the list of currently available storage devices. C64 OS can have access to up to 5 drives at the same time. C64 OS maintains a detected devices table that allows Applications and Utilities to know what device types are on each device number. They can get this information by referencing the table, rather than performing complicated detection work.

The listed devices shows the device number, from 8 to 30, followed by the device type. On one device, a flag icon follows. The flag indicates which is the C64 OS system device. The Drives Utility can be used to reconfigure the set of available drives without needing to reboot C64 OS.

To enable a new drive, physically turn the drive on, then click the Rescan button. The bus is scanned and the new drive is detected and added to the list. It is also added to the detected devices table so that other C64 OS Applications know of its existence and can make use of it.

To disable a drive, select it in the list, and click the eject button on the righthand side of the Utility. It will disappear from the list, and is uninstalled from the C64 OS detected devices table. You may now physically turn the drive off.

The system device cannot be turned off while C64 OS is running. When the system device is selected, the eject button is disabled.

Drives Utility.

What is the Open Button?

The Open button is reserved for future use. It will be used to open a Utility designed to manage and show details about the selected device. Each device family will get its own Utility that handles the special features and options available to those devices. Something to look forward to.


Memory

By default the Memory Utility can be opened by double-clicking the available memory indicator at the right end of the status bar. In C64 OS 1.0 to 1.04, Memory can be opened from the Hardware section of the Settings Utility. In C64 OS 1.05+ Memory can be opened using the Utilities Utility, as it has been superseded by the newer Usage Utility in the Hardware section of Settings.

This shows a realtime map of your C64's main memory, and how that memory is allocated. It starts with a color-coded legend for six different kinds of allocation.

Memory Utility, Summary Mode. Memory Utility, Available Mode.
Type Color Notes
Workspace Light Blue The Operating System, File System and CPU's workspace memory.
Application Blue The Application binary's static memory, and
Heap memory allocations that belong to the Application.
Utility Purple Heap memory allocations that belong to the Utility.
Reserved Light Red A region of high memory reserved for special purposes.
A Utility binary's static memory, bitmap graphics, etc.
System Orange Memory occupied by the C64 OS KERNAL, and
Heap memory allocations that belong to the Operating System.
Free Black Unused heap memory that is free to be allocated by anything that needs it.

The Memory Utility automatically updates its display with a timer. You can adjust the frequency with which it updates using the radio buttons at the bottom. Fast updates occur every half-second and reflect changes to memory availability almost immediately. Slow updates only pick up on changes a few seconds after they occur.

Just below the memory map is a summary. R: Shows how much REU memory has been detected, from 128KB up to 16MB. U: Shows how much heap memory has been used, out of a total of 30KB. A: Shows how much heap memory is still available, or free. Click on any one of these summary blocks to expand and focus on just that metric.

In the memory map, each horizontal row shows an 8KB block of the C64's main memory. In an 8KB block there are 32 pages of 256 bytes each. However, each row in the map has only 16 cells. Each cell must represent 2 pages. The actual memory page allocator has twice the resolution that this visual map has.

A double-click on a memory map cell opens the Peek Utility at the memory page that was clicked, allowing you to inspect the contents of page. Because of the resolution issue, double-clicking the left half of a cell selects the lower of its two pages, while the right half of a cell selects the upper of its two pages.

Applications and Utilities are able to send low memory warnings to each other if there is insufficient memory for a task. Applications and Utilities are sometimes able to respond to these messages by freeing up memory they don't absolutely need. For instance, File Manager can deallocate an unfocused tab in response to a low memory warning, because it can just load it back in later when the tab is selected. From the Memory Utility you can send a low memory warning to the Application by double-clicking the word Free in the legend.


Mouse

The Mouse Utility can be opened from the Hardware section of the Settings Utility.

Most of these settings can be set in the Configure Tool, but the Mouse Utility lets you make the changes while running C64 OS. Changing the pointer style happens immediately. Changing the inner and outer colors of the pointer happen in realtime so you can see how the color combinations look in context.

The tracking speed adjusts how quickly the mouse pointer moves around the screen. Double-click speed adjusts the amount of time that is allowed to pass between two clicks and still have them register as a double-click. If you're a speedy user and find that double-clicks are being registered when you don't want them to, consider setting the double-click value higher. If you are a slower user and have a hard time getting a double-click to register, consider lowering the double-click value.

The left hand and right hand options swap the role of the left and right mouse buttons. For right-handed people, the left button is the standard button, and the right button is the alternate button. For left-handed people this is reversed.

You can use the TestClick area to test standard clicks, alternate clicks, and also test the double-click sensitivity.

Beginning in v1.03, C64 OS has support for the mouse wheel on a PS/2 or USB mouse connected with a MicroMys, MouSTer or other adapter. Scrolling speed sets how many internal ticks of the mouse wheel have to be counted before a wheel event is generated. This can be adjusted to accommodate your preferences and different mouse sensitivities. The wheel can be configured for classic or natural scrolling directions. Classic means as you pull the wheel towards yourself you move downwards through the content. Natural reverses this. Classic is how the mouse wheel typically behaves in Windows and older versions of macOS. Natural shifts the perspective to make your finger feel like it's pushing or pulling the content directly.

If you make any change, the Save button becomes enabled. You can close the Mouse Utility without saving and the changes will only be active for this session. When you boot C64 OS the settings are loaded from what was last saved. Click the save button to keep your changes for longer than this session.

Mouse Utility.

Setting the Input Driver

The Mouse Utility is used to configure the parameters of the mouse pointer, but is not used to specify which input driver to use.

C64 OS has support for up to 8 standard drivers. There is one driver slot for each type in a fixed set of common hardware types. Which drivers are plugged into each of those slots is managed elsewhere. In version 1.0, drivers are assigned by the Configure Tool. In the future there will be a Drivers Utility.

See Chapter 8: File System → System Directory → Drivers for more information about drivers.


Peek

The C64 is famous for PEEKs and POKEs. The ability to read the value stored anywhere in memory and to change the value stored anywhere in memory is a hallmark of the 8-bit era. The Peek Utility in C64 OS lets you observe the contents of memory, 1 full page (i.e., 256 bytes) at a time, in realtime.

Peek Utility.

Unlike in BASIC, all memory addresses and values are shown in hexadecimal. At the bottom left is a memory page cycle button. Click the button to move through main memory one page at a time. The page button is periodic; to get to any page with less clicking, press and hold to cycle continuously. Cycle in reverse by holding the COMMODORE key while clicking the page button. Press PLUS and MINUS on the keyboard to move forwards or backwards through memory pages.

Of a complete 16-bit memory address, the high byte is shown on the page button at the bottom. The low byte is composed of the high nybble from the values running vertically down the left margin, and the low nybble from the values running horizontally in the top margin. (At address $03FD is $05, at address $03CF is $8A, in the screenshot above.)

Double-click on any value to jump to that page of memory. This is convenient for following pointers. If you know that two memory addresses constitute a pointer, remember the first value (that's the low byte) and double-click the second value to jump to that page. Look up the first value by row then column. That's where the pointer points.

Used in conjunction with the memory addresses listed in the mods tab of About C64 OS, Peek can be used to look at the C64 OS KERNAL while it's running.

The auto checkbox sets whether Peek should automatically refresh its display. The Reload button is used to manually refresh the display if auto is unchecked. There are instances where both modes are useful. Sometimes you want a snapshot of memory to read through without it changing on you, in this case, uncheck auto. There are other times when you need to see how memory changes while you're dragging something in the Application. You can't click Reload manually and be dragging something else at the same time. In this case, check auto on. Auto updates ever few seconds.

Peek can be opened from the Utilities menu, by default, or with the keyboard shortcut SHIFT+CONTROL+COMMODORE+P.


Settings

Settings can be opened from the Utilities menu. From a single entry in the Utilities menu, this provides access to 8 other Utilities, most of which are used for changing C64 OS settings. They are grouped into logical categories to make them easy to find.

  • General
  • Hardware, and
  • Date/Time
Settings Utility.

Each button opens the Utility so named, except About, which opens About C64 OS. The buttons can also be triggered using keyboard shortcuts COMMODORE+1 through COMMODORE+8.

Group Button Utility Shortcut
General About About C64 OS COMMODORE+1
General Themes Themes COMMODORE+2
Hardware Drives Drives COMMODORE+3
Hardware Mouse Mouse COMMODORE+4
Hardware WiFi Coming Soon... COMMODORE+5
Hardware Usage Usage COMMODORE+6
Date/Time Today Today COMMODORE+7
Date/Time Time Time COMMODORE+8

From C64 OS 1.0 to 1.04 the Settings Utility's Hardware section opened the Memory Utility, but was changed to Usage in C64 OS 1.05.


SID Preview

Available: 1.04+

SID Preview is a Utility for playing SID music, available starting in C64 OS v1.04. It uses the shared library, sidplay.lib, to load and play music in the PSID format, the format used in the High Voltage SID Collection.

PSID provides metadata for the song title, the author, and information about its release year. PSID music also supports multiple tracks, often used for intro music, level music, end sequence music, and sometimes sound effects for a game, all contained in a single file.

SID Preview Utility.

SID Preview is assigned as the default Utility to open files with a .sid extension. Changing the selected file while SID Preview is already open does not automatically load that file. Click the load button to change to the selected file. This allows you to navigate the file system without disrupting the song that's currently loaded.

There are several keyboard shortcuts. Press "i" to cycle through the info button that shows the chip (6581/8580) and system (PAL/NTSC) the song was written for. Press "+" and "-" to cycle through available tracks. Press SPACE or RETURN to trigger the play button. Press STOP to trigger the stop button.

SID Preview is also integrated with the clipboard. If a file reference to a SID file is on the clipboard, press COMMODORE+V to paste and load that file. In conjunction with copying a file reference from the Open Utility, any SID file can be selected and played from within any Application.

Compatibility Information

SID music is program code that has to be loaded to a fixed memory space and uses fixed zero page memory. This generally makes SID music unsuitable to be played by complex software such as an operating system with which the music was not originally intended to cooperate.

For more information about PSID music compatibility in C64 OS, and solutions to overcome the problem, see:

Chapter 10: Appendices → Frequently Asked Questions → Can C64 OS play SID music?


Switcher

Available: 1.05+

Switcher is a Utility for switching between any current Application and any other Application that is currently open in a Fast App Switching slot. This Utility requires the use of the Fast App Switching feature that was introduced in v1.05. This features requires an REU and it requires that at least 2 Fast App Switch slots have been configured. See: Chapter 3. Configuration and Settings → Configure Tool → Expansion memory for more information about configuring the REU for Fast App Switching.

Switcher Utility.

Switcher can be opened from the Utilities menu, or with the keyboard shortcut CONTROL+S. While Switcher is open, pressing CONTROL+S repeatedly moves the select down the list of Applications and then loops it back up to the top again. The cursor keys can be used to move the selection up and down the list. Press RETURN to trigger the default Switch button and switch to the selected Application.

Double-click any Application in the list to switch to that Application.

The state and memory usage of the selected Application are shown. There are three states that an Application can be in: Running, Frozen or Unsaved. The Running Application is the one that is currently open behind the Switcher Utility. It cannot be quit or switched to using the Switcher. A Frozen App can be Quit by clicking the Quit button. This immediately removes it from its Fast App Switching slot, and deallocates all of its REU banks.

If the selected Application is in the unsaved state, the Quit button appears as a Kill button. Clicking the Kill button does the same thing as clicking the Quit button, but all unsaved changes in that Application are lost.


Themes

C64 OS provides a system-wide theme to define the color of 21 user interface elements. The Themes Utility let's you choose between one of 3 themes: Daylight, Midnight and Custom. Themes can be opened from the General section of the Settings Utility.

The custom theme is fully customizable using the Themes Utility. It shows you a miniature mockup of a C64 OS screen, that includes a sample of every customizable user interface element. Click the element to select it. The label at the bottom indicates which element is currently selected. Click the cycle button to the right of the label to choose a color for that element. The mockup changes to that color immediately to show you how it will look in context.

Themes Utility.

The keyboard shortcuts CONTROL+A through CONTROL+U select each of the user interface elements.

Customizable User Interface Elements

Click the cycle button in the bottom left to change which theme to use. The theme is set and saved when the Themes Utility is closed.

To base the custom theme on one of the two built-in themes, but tweaked slightly, start by selecting either Daylight or Midnight. Select a user interface element. As soon as you change its color, all of the colors from this theme are copied to the custom theme, with the color of the currently selected element slightly changed. From there you can continue to change other elements, until your custom theme is the way you want it.

See Chapter 4: User Interface → Themes for more information about C64 OS themes.


Time

Time is a multi-purpose Utility. It let's you adjust the current date and time and write it out to the realtime clock device you have configured for your system. Additionally there are settings for the menu bar clock and time formatting throughout C64 OS. Besides being a Utility for changing settings, there is also a built-in stopwatch and timer. The Time Utility can be opened from the Date/Time section of the Settings Utility.

Time has a tabbed user interface for its 4 main sections: Clock, Watch, Timer, and Prefs. The Clock section displays the system's current date in a standard date picker, and the time, current to the moment when the Utility is opened, in a standard time picker. In the pickers each date and time segment is presented as a cycle button. Click the segment to increment, or hold COMMODORE and click to decrement. The date picker enforces valid dates, days per month including leap years.

After adjusting the date and time using the pickers, click Set, or press RETURN, to write that date and time to the RTC of the device you have selected to be the source device for the getting the system date and time at boot up.

Time Utility - Clock Time Utility - Preferences

In the Prefs section you can set whether the menu bar clock is shown or not, whether the colon between hours and minutes blinks to indicate seconds, whether it should appear in 12 or 24 hour mode, and which Utility should be opened when you double-click it. The options are to open the Today Utility, or to open the Time Utility itself. The 12 and 24 hour mode doesn't only affect the menu bar clock, but sets the preferred hour mode throughout C64 OS. Note that when you toggle between 12 and 24 hour modes, in the Clock section the time picker changes between those two modes.

If the Time Utility is closed without saving, the changes are used for this session only. Click Save to write the changes to settings, so they persist after the next C64 OS boot up.

Time Utility - Watch Time Utility - Timer

The Watch and Timer have similar user interfaces but with some subtle differences.

Watch always resets to 00:00:00, and when started it counts up continuously until 23:59:59.

Timer resets to a configurable value, and when started it counts down to 00:00:00. When the timer reaches zero it resets to its user defined value, displays an alert and loads and plays a PSID file (//os/settings/:timer.sid). To adjust the Timer's start value, first reset it. Its segments become two-toned. Click the top half of a segment to increment and the lower half to decrement.

Watch and Timer have precision to the second. Each can be paused and restarted from where it was paused. The Watch and Timer can be counting at the same time, even when their tabs are not selected or the Utility panel is shaded. They continue counting as you work in the Application behind it. They do not continue counting when the Time Utility is closed, but they do save their values and the state of whether they are running or paused. When Time is opened again, they immediately pick up where they left off.

Support for PSIDs

C64 OS has a library for playing PSID format SID music. However, due to the nature of SID music it is not safe to play just any PSID file. SID files load to arbitrary places in main memory and make unpredictable use of Zero Page memory. This usually makes them incompatible with any software with which they were not specifically designed to cooperate.

See Appendix IX. SID Music for more information about converting PSIDs to be C64 OS compatible.


Today

The Today Utility is a simple calendar. It can be configured via the Time Utility as the Utility to open by double-clicking the menu bar clock. It can also be opened from the Date/Time section of the Settings Utility.

When opened, today's date is shown by default. Week numbers run up the left side of the calendar. Days of the week are indicated along the top edge.

Managing Date Notes

Click on a date to select it. The selected date is indicated by color. Today's date is indicated by a check mark in the lower right. Dates that have notes are indicated by an exclamation point in the lower left.

When a date with notes is selected, the notes are displayed in the field at the bottom. A note can be up to 255 characters. Press RETURN in the notes field to save any changes. If the notes field is saved with no content the indicator on the date is removed. Notes can be cut, copied and pasted with COMMODORE+X, COMMODORE+C and COMMODORE+V.

To move a note from one date to another, press COMMODORE+A to select all content in the notes field. Press COMMODORE+X to cut it to the clipboard. Press RETURN to save the removal of the notes from the current date. Select a new date, press COMMODORE+V to paste the notes to the new date. Press RETURN to save.

Today Utility.

Date Navigation

To change month, click the back and forward arrows, or press COMMODORE+PLUS and COMMODORE+MINUS. Click the button between the back and forward arrows to return to today, or press COMMODORE+T.

In C64 OS 1.05+, to change year, hold CONTROL and click the back and forward arrows.

If the clipboard holds a datatype of date or datetime, it can be pasted to the Today Utility to jump directly to that date without having to tediously tick through the months. If the notes field is in focus, first click the date information at the top of the Utility to unfocus the notes field, then press COMMODORE+V to paste and jump directly to that date.

See the Date Utility for how to copy a date to the clipboard.



Calender Notes Storage

Notes are stored in the system's calendars directory, with subdirectories to organize by year and month.

//os/calendars/yyyy-mm/

Usage

Available: 1.05+

The Usage Utility supersedes the Memory Utility. Memory is still available, but Usage is more modern, has more features, and is built using Toolkit. The original Settings Utility offered Memory from the Hardware section, but in C64 OS 1.05+ it now offers Usage instead.

The Configure Tool offers Usage as the default Utility to be opened when the available memory indicator in the status bar is double-clicked.

The Usage Utility has three tabs: RAM, REU and CPU.

RAM Usage

A key runs along the top, Work, App, Util, Rsrv, Sys, and Free. These give the colors that are used in the main display to show how each 256-byte page of memory is currently allocated.

The allocation display is updated automatically on a periodic timer. The fast and slow radio buttons at the bottom of the Utility change the rate at which the automatic update occurs. Click the Reload button to force the display to update immediately.

Usage Utility - RAM.

Each row represents a 32 KB region of the C64's main memory. The number in the left-hand column is the first hexadecimal digit of the memory address for that row. The numbers along the top indicate the second hexadecimal digit of the memory address for that column.

Click on any page of memory and a checkmark appears over that page. Click the Peek button to open the Peek Utility to examine the memory contents of the currently selected page.

Total Memory

The Used and Available memory total to 30KB, not 64KB. This is because the used memory is only counted from the region that is capable of being allocated by the paged-memory allocator. This does not include workspace memory, memory that the C64 OS KERNAL occupies or the reserved memory from $E000 to $FFFF, which is used alternatively as a graphics buffer or for a Utility.

REU Usage

A key runs along the top, Work, App, Empty, Data, Free, and NA. These give the colors that are used in the main display to show how each 64KB bank of REU memory is currently allocated. App and Empty together represent the banks reserved for Fast App Switching. Empty means the bank is capable of having an App frozen to it, but it is currently empty.

Data is a bank that has been allocated by an Application for storing that App's data. Free is memory that is available to be allocated by an Application for data. And NA means that these banks are not available, which appear when the REU has less then 16MB of total capacity.

The allocation display is updated automatically on a periodic timer. The fast and slow radio buttons at the bottom of the Utility change the rate at which the automatic update occurs. Click the Reload button to force the display to update immediately.

Usage Utility - REU.

Click on a bank of memory allocated for an App and a checkmark appears on that bank. Additionally all data banks that have been allocated by that App are shown with a "+". Click on any bank allocated as data, and that bank and all others allocated by the same App are shown with a "+" and the checkmark appears on the App bank that owns that data bank.

CPU Usage

C64 OS is an event-drive operating system, it is not a multi-tasking OS. However, it is still possible to measure approximate CPU utilization.

The interrupt service routine increments a counter once every 60th (or 50th on PAL) of a second, up to a maximum of 255. Every 1 second it rotates this counter value onto a small history of 10 such sample bytes, bumping out the oldest sample. When this counter is 255 the interrupt service routine displays and animates the CPU busy indicator in the top left corner of the screen.

The main event loop, each time it runs, reduces this counter to zero. As long as the main event loop is looping, the counter never exceeds one before it is immediately reduced to zero again.

Usage Utility - CPU.

However, as the user clicks on the user interface and kicks off chains of activity, that takes processing time before returning to the main event loop. During this time the interrupt service routine is able to count up the counter, and numbers > 1 start to find their way into the 10 sample (1 sample per second) history.

The CPU Usage visualization is an animated bar graph that updates automatically every 1 second. It draws out the height of the bars according to the numbers in that 10 sample history. The scale is not linear, as the maximum height of the bars is only 13 characters, and most activity results in only small numbers. Therefore the height of the bars is roughly logarithmic. A bar will go to 100% only if the sample is somewhere close to 255. However, a bar will go to 50% even when the number is much smaller than 128.


Utilities

The Utilities Utility can be opened from the Utilities menu, or by pressing SHIFT+CONTROL+COMMODORE+U.

The Utilities Utility shows a list of all installed Utilities, and lets you open any one of them. It takes up only one place in the Utilities menu but gives access to all the others just one step removed.

The cursor keys can be used to move the selection, then click Open or press RETURN. You may also double-click an item in the list to open it.

Utilities Utility.

If Utilities are installed or uninstalled while this Utility is open, click the refresh button at the bottom left to update the list of installed Utilities.


Helper Utilities


About This App

About This App is available from the top of the Utilities menu. It shows you the metadata from the current currently running Application. This includes:

  • Name of the Application
  • Icon
  • Version Number
  • Copyright year
  • Author
About This App Utility.

About This App can also be left open to show information about a selected Application. In App Launcher when an Application alias is selected, About This App shows that Application's metadata. Similarly, in File Manager when an Application is selected from the system's Applications directory, About This App updates to show that Application's information.

Double-click the icon shown by About This App, or press COMMODORE+C to copy it to the clipboard.


Checksum

Available: 1.03+

The Checksum Utility is available starting in C64 OS v1.03. It can be opened using the Utilities Utility. It offers 3 standard checksum routines, CRC8, CRC16 and CRC32, which can be selected at the top.

Click the Run button to perform the selected checksum routine on the currently open or selected file. This can be used from File Manager, for example, to perform a checksum on a C64 OS update archive, to confirm its integrity before attempting to install it.

Checksum Utility.

The checksum result can be copied to the clipboard using the Copy button.


Colors

The Colors Utility is a standard color picker. An Application can launch the Colors Utility to let you pick a color, without needing to reimplement what it offers.

Often an Application will provide a means of opening the Colors Utility directly. For example, in App Launcher, Colors is listed in the Options menu. Some Applications may handle color selections and do something useful with them, even though they do not explicitly help you open the Colors Utility. TestGround provides an example of this.

The Colors Utility can be opened manually with the Utilities Utility.

Colors Utility.

The Colors Utility is available in two modes: Short and Tall. Short is pictured above, and shows the colors in two columns. Double-click the title bar of the Utility to toggle between the two modes. Tall shows all of the colors in a single column, with a taller narrower panel.

In addition to clicking colors to select them, you can use the standard keyboard shortcuts to select the colors: CONTROL+1 through CONTROL+8 for the first 8 colors, and COMMODORE+1 through COMMODORE+8 for the second set of 8 colors.


Copy, Move, Scratch

Copy, Move and Scratch are a suite of three Utilities whose behavior and appearence are related.

  • Scratch performs the job of recursively scratching a selection of files and subdirectories.
  • Copy performs the job of recursively copying files and subdirectories to another place.
  • Move performs a copy job on a set of items, and then scratches the originals.

These three Utilities cannot be used on their own; they require a valid job description to be provided by the Application that invokes them. If one of these Utilities is opened manually, it presents a message telling you what it is for. Such as shown below.

Copy Utility, manually opened.

File Manager opens these Utilities to perfom its tasks of copying, moving and scratching files. Other Applications can use them too, to perform similar tasks that they prescribe.

Copy Utility. Move Utility.

Examples of Copy and Move are shown above. There are two lines of text. The top line shows the current subdirectory being processed. The second line shows the name of the current file being copied, moved or scratched. Below this is a running count of the total number of items that have been copied, moved or scratched. At the top is an animation of a file moving between two folders, or from a folder to a trash bin.

Starting in C64 OS v1.04, the Copy and Move Utilities have gained a checkbox, labeled Over, to the left of the Start button. It is always unchecked by default for each new job. Check on Over before starting the job, and files that already exist at the destination are overwritten by the file being copied or moved.

Scratch Utility.

There is a single button at the bottom, Start. Click Start to confirm that this is what you want to do. To cancel, simply close the Utility instead of starting the job. While the job is in progress, the Start button changes to a Pause button. The mouse pointer is hidden while a job is running to speed up file transfers, but the Pause button can be triggered by pressing RETURN.

A paused job can be resumed from where it left off by clicking Start again. Or you can close the Utility to cancel. Canceling a partially run job does not undo any of the changes that were already made. The Utility closes automatically after a job runs to completion.

Power User Feature

Holding the CONTROL key while either the Copy, Move or Scratch Utility is opening bypasses the confirmation stage. The Start/Pause button is not shown, the job starts automatically, runs to completion, and the Utility closes automatically thereafter.

A job that is started in this manner can be interrupted only by closing the Utility with the keyboard shortcut COMMODORE+W. It cannot be paused and later resumed.

This feature can make interaction feel a bit faster and more streamlined, but it should be used with caution to avoid mistakes.


Date

If opened manually, the Date Utility shows you today's date and the time when the Utility was opened. However, it is meant to be invoked by Applications that require a date and/or time to be input. The Application can configure the appearence of this Utility and supply the date and time to be shown.

Date Utility.

The date picker is quite featureful, with support for leap years and validation for the correct number of days in each month. The time picker presents itself either in 12H or 24H mode, depending on your system-wide preference configured in the Time Utility.

The date and time segments are standard cycle buttons. Click to cycle forward, COMMODORE-Click to cycle in reverse. Click and hold to cycle continuously, COMMODORE-Click and hold to cycle continuously in reverse.

The Date Utility is also integrated with the clipboard. Press COMMODORE+C to copy the currently displayed date and time to the clipboard. Press COMMODORE+V to paste a date or datetime from the clipboard.

Date and Time Formats

If only the date picker is showing and it is copied to the clipboard, the datatype is set as text/date. The date is formatted as a string:

YYYY/MM/DD

If both the date picker and time picker are showing, a copy to the clipboard has datatype text/datetime. The datetime is formatted as a string:

YYYY/MM/DD HH:mm:ss

When pasting a text/date from the clipboard, whether the time picker is showing or not, only the date picker is affected. When pasting text/datetime both the date picker and the time picker are affected. If the time picker is not showing, the date picker is set and the time portion of the paste is ignored.


File Info

The File Info Utility is used to see and change information about the currently open or selected file. File Manager uses File Info to allow you to rename, lock/unlock and copy a file in place. See Chapter 6: File Manager → Rename Files. From File Manager the File Info Utility can be opened by choosing Info... from the File menu. You may also open File Info manually.

File Info Utility.

File Info offers many features. The file can be renamed, by editing the name in the text field and clicking Rename or pressing RETURN. A duplicate copy of the file can be made in the same place, by typing a new name and clicking Copy. Hold CONTROL while clicking the Copy button to create a copy with the new name and also change the currently opened file to the copy with the new name.

After modifying the name in the field, but before clicking Rename, the contents of the name field can be reverted to the current name of the file by pressing COMMODORE+Z.

Metadata about the file is shown. Its size in 256-byte blocks, its CBM file type, and last modified date and time. The file's lock status is also indicated at the top right.

The File Info Utility updates automatically to reflect whatever file is open or currently selected. In File Manager this Utility can be left open like a floating palette, and it updates as the file selection changes. If multiple files are selected or no files are selected File Info changes into an unselected mode, shown below.

File Info Utility, nothing selected.

Although File Manager provides a way to open File Info directly, it can also be opened manually to operate on any currently open or selected file. For example, in App Launcher, you can open File Info manually, and it shows information about the selected alias. An existing alias can be renamed with File Info. Although this does not change its type, an Application alias can be transformed to an alias to a different Application merely be changing its name. And a new alias can be copied from an existing alias with File Info's Copy feature. Reloading the current desktop is required afterwards to pick up the changes.

Locking a file prevents the file from being scratched. This can be used in App Launcher, for example, to lock an alias. Select all aliases on a desktop and scratch them. A subsequent reload restores all the aliases that were locked and thus prevented from being scratched.

Device Dependent Features

Not all features are available on all device types.

Date and time stamps are not available on legacy devices. And the accuracy of the date and time on a file on a modern device requires that device to have an RTC, and for that RTC to be set to the correct date and time.


Mount

Available: 1.03+

Beginning in C64 OS v1.03, File Manager has support for mounting and unmounting disk images stored on an SD2IEC. All the standard disk image file extensions (D64, D41, D71, D81, and DNP) are assigned by default to the Mount Utility. Simply double-click a disk image and the Mount Utility opens automatically.

Mount Utility.

While the Mount Utility is open, it updates itself automatically to reflect the currently selected file. Some information about the file and where it is stored is displayed, along with a message.

If the selected file is a valid image file and it can be mounted, the Mount button is enabled. Click it to mount the image, and close the Mount Utility automatically.

See Chapter 6: File Manager → Mount a Disk Image.


Opener

The Opener Utility is principally used by File Manager to manage which Application or Utility is used to handle a file being opened. The Opener is run automatically when you open a file with File Manager.

See Chapter 6: File Manager → Open a File.

Opener Utility.

Opener is used to assign Applications and Utilities to file types. A unique file type in C64 OS is the combination of its CBM file type (PRG/SEQ/USR/REL) and its filename extension. If no assign currently exists, Opener's user interface is shown. Select an Application or Utility with which to open the file, and click Open.

Clicking Open does not assign that Application or Utility, it just opens the file with that selection this one time. Alternatively, you can select an Application or Utility and click Assign to establish that selection as the default opener for this file type.

If opening a file whose type is already assigned to an Application or Utility, you can override that assign and force Opener to show its user interface by holding the CONTROL key as it opens. This allows you to change the assign, or make a one-time exception and open the file in an alternative Application or Utility.

How Assigns are Stored

Each assign that connects a file type to an Application or Utility is stored in a unique file in the assigns directory of the system's settings directory.

//os/settings/assigns/

For more information about how assigns work see Chapter 6: File Manager → Create an Assign.


Places

The File Manager offers a Go menu with four customizable places to which you can quickly jump either using the Go menu itself or with the four unmodified function keys.

These places are user customizable, and their file references are stored in the system's settings directory. Utilities and other Applications may tap into these customized places and use them when appropriate.

The Places Utility is used to configure these four standard places:

  • Documents
  • Games
  • Music
  • Pictures

This set may be extended in the future to include downloads, demos, or other standard places in the file system.

Places Utility.

The Places Utility can be opened by choosing Places from the Options menu in File Manager. A text field is provided for each place, into which you can manually type a C64 OS file reference. See Chapter 8: File System → File References for more information on the file reference format.

Alternatively, file references can be copied and pasted into the fields. Any changes are saved automatically when the Places Utility is closed. To revert the fields to their last saved values, click Reload.

Automatic Clipboard Integration

While the Places Utility is open, it actively listens for changes to the clipboard.

Put the text insertion point anywhere in one of the fields, then copy a place to the clipboard. This can be done in File Manager by choosing Copy Place from the Options menu. The Places Utility notices that the clipboard has changed, and sees that its datatype is text/fileref. It automatically clears that field of its current content and replaces it with the file reference on the clipboard.


PRG Runner

C64 OS is a platform for running Utilities and Applications that are native to its KERNAL, libraries and other infrastructure. However, there is a vast array of software written to run directly on the C64's hardware. Traditional C64 software cannot run at the same time as C64 OS.

PRG Runner is designed to reliably launch into ordinary C64 software, but kicking off from within C64 OS. Each C64 program requires a metadata file called a PRG alias that stores information about where the program is installed and how it is loaded and run.

App Launcher supports PRG aliases on the desktop. PRG aliases are opened by PRG Runner, which shows the metadata about that program. To leave C64 OS and launch cleanly into that other C64 software, click the Run button.

PRG Runner Utility.

PRG Runner is capable of swapping device numbers, and mounting disk images and swaplist files on SD2IEC. It also knows what joystick port is primary, whether a disk needs to be inserted and whether the program is capable of running while more than one device is connected to the serial bus. There are certain conditions under which it may be unable to run the program. PRG Runner presents all appropriate information and messaging.

PRG Runner Utility, nothing selected.

If PRG Runner is opened manually with out reference to a PRG alias, its fields are left blank and the Run button is disabled.

For more information about how PRG Runner works and how PRG aliases are structured, see the blog post series, Load and Run from 6502 ASM, Part 1 and Part 2.

See Appendix I. C64 Tools → PRGAlias Creator for a C64 Tool to make it easy to create and configure PRG aliases.


TextView

TextView is just as it sounds, a simple Utility for viewing text files and textual config and data files.

TextView supports PETSCII and 7-bit ASCII files. Use the radio buttons at the bottom to select between displaying as PETSCII or doing on-the-fly conversion from ASCII. The Wrap checkbox toggles soft-wrap on and off. Line endings, CR, LF and CRLF are autodetected and handled appropriately.

TextView also has automatic support for MText. MText is a lightweight marked-text format introduced with C64 OS that has support for left, right and center justification, standard, strong and emphatic text styles, text colors, horizontal rules, and inline links.

MText codes are byte values not defined by either PETSCII or ASCII. Therefore a plain text file does not accidentally get interpreted as MText.

TextView Utility.

When TextView opens, it loads the file currently open or selected by the Application. In File Manager a selected file can be opened explicitly in TextView by choosing TextView from the File menu, or by pressing COMMODORE+T.

As the selection in File Manager changes, TextView does not automatically change what it is presenting. To update TextView to show the file currently selected click the Reload button or choose TextView again from the File menu.

The main text area of TextView is a standard text view control that accepts keyboard input for navigation. CURSOR-UP and CURSOR-DOWN scroll the text few lines at a time. SPACE pages down, the letter B pages up. COMMODORE+DOWN scrolls to very bottom of the text. COMMODORE+UP scrolls to the very top of the text. HOME scrolls the text view to the top and to the very left if the text has been horizontally scrolled.


Open and Save Utilities

An operating system typically provides dialog boxes for picking files to be opened from within an Application, and for saving files that an Application is working on.

Open Utility. Save Utility.

In C64 OS, these Open and Save dialogs are implemented as standard Utilities. The Open and Save Utilities are rich in functionality and are explained in Chapter 8: File System → Open and Save.


Utilities Wrap Up

Above is presented an overview of the most common Utilities included with C64 OS. It is not an exhaustive list, and other Utilities can be installed later by copying them to the system's Utilities directory.

Utilities you don't want to use can be moved to a different directory. Alternatively a Utility could be scratched, but make sure you have a backup of anything you don't want to lose.

Do Not Uninstall Required Utilities

It is important not to uninstall any Utility that is required for critical system features. It is possible, and part of the design of the system, that a required Utility can be replaced by an alternative that meets the same functional needs but provides additional features or a different user interface. As long as something is there that meets the requirements.

The following are the lists of Utilities required by C64 OS for proper behavior.

General System

  • Memory
  • Time
  • Today

App Launcher

  • Open
  • Colors

File Manager

  • Copy
  • Move
  • Scratch
  • File Info
  • Opener
  • Places
  • TextView

Next Chapter: File System

Table of Contents



This document is subject to revision updates.

Last modified: Nov 16, 2023