This is a cache of https://vccplus.brianholman.com/manuals/programming-in-c/disk-read/. It is a snapshot of the page as it appeared on 2026-11-21T00:01:24.246+0000.
Follow a word through FD0 · Programming in C on the CoCo 3 — CMOC and Its APIs · VCC Plus
← Manual LibraryVCC Plus 3.7.1 · Reading on the web

Try the exercises in VCC Plus. Example links download files here; open them in the app to work beside the emulator.

The complete book · PDF editionBook 6: Programming in C on the CoCo 3 — CMOC and Its APIs

198 pages · VCC Plus 3.7.1 · Keep a copy to read or print.

Download PDF
Contents

Chapter 6 of 9

Follow a word through FD0

When WORDS READ FROM THE FLOPPY: appears, the CoCo has printed a string built into the executable. The next line, HELLO, has made a longer journey. It began as a line of Mac text, crossed into a file on a virtual floppy, and came back as a sequence of bytes in guest RAM.

Set a desk for the disk library

Open src/disk.c in your Hello Disk project. Its three file-scope declarations reserve a drive record, a file record and a 256-byte reading area. Each uses static. The objects live for the whole program and belong to this source module. Reading a sector into a large local array on every call would spend part of the CoCo's limited stack instead.

static DECBDrive drives[1];
static DECBFile file;
static byte words[256];

byte showDiskWords(void)
{
    byte status = decb_init(drives, 1);
    if (status != DECB_OK)
        return status;
    status = decb_registerDrive(0);
    if (status == DECB_OK)
        status = decb_openSectorFile(&file, 0, "WORDS.DAT");

The 1 in decb_init tells the library how many drives it has room to manage. The 0 in decb_registerDrive identifies the guest drive. One record is enough for drive zero. The file-open call then asks that drive's directory for WORDS.DAT and fills in the caller's file record. On a real CoCo the controller would reach a physical floppy. Here the same guest routine reaches the disk image assigned to FD0. See where a file lives inside a floppy image.

Read a disk sector

    if (status == DECB_OK)
    {
        status = decb_readSector(&file, words, 0);
        words[255] = 0;
        if (status == DECB_OK)
            printf("%s\n", words);
        decb_closeSectorFile(&file);
    }
    decb_shutdown();
    return status;
}

The last argument to decb_readSector selects logical sector 0 of the open file. The words array supplies the memory into which the library can write all 256 bytes. The CoCo may store that sector anywhere allocated to the file. You didn't have to calculate a track or look through a disk-image header.

Once a successful read fills the buffer, printf walks bytes from the start until a zero byte ends the string. Each word in this particular file is followed by a carriage return. The generator writes a final zero and pads the sector; the reader also places a zero in the last byte. A different binary file could contain zeros in its data, so this string-printing technique belongs to this text format. For a longer file the program would have to read more than one logical sector and interpret the bytes it receives.

Trace the cleanup with your finger. If open succeeds, the program closes the file even when a read fails. If open fails, it skips that close. After successful initialization it shuts the disk library down before leaving. The sample returns the status retained from registration, opening or reading. It doesn't report an independent close result.

Tell the two outputs apart

After Launch Disk, read these five guest lines in order: HELLO, WORLD, CMOC, VCC, PLUS. Beneath them you should see DISK RESULT: 0 and GENERATED WORD COUNT: 5. You can find either number in the program without scrolling through the word list. One is a value returned by the disk operation; the other is the constant compiled into the executable.

The running CoCo printed five words from FD0. The last two lines report the successful disk operation and the count compiled into HELLO.BIN.

When the guest is back at OK, type DIR. Find the entries for HELLO BIN and WORDS DAT. The directory prints the name and extension in separate fields. When the C code opens the file, it supplies the dot. If you give a friend only the binary, the heading and count go along for the ride. To take the five words too, give them the image.

Try predicting the two numbers when the program asks for a nonexistent file. Then test your prediction in the debugger.

Read a planet name across two sectors

Save the Planet Survey project, expand the ZIP, then open its PlanetSurvey folder in Develop → C Development…. Use the Disk BASIC system profile for this exercise. Choose Build and Launch Disk. The project mounts SURVEY.dsk in FD0 and sends LOADM"SURVEY":EXEC. Click the CoCo display and press 2. Look for SURVEY: MARS, the traits RED and COLD, and orbit number 4. Run the same command again and press 1 to read the Earth record.

Where do the sectors meet? In the original file, the letters M and A occupy bytes 254 and 255, counting from zero. R and S begin the next sector. Hello Disk fetched one sector into its own buffer. Planet Survey opens the same kind of disk file with fopen and reads one line at a time with fgets. The stream reads the next sector as the name goes by. Text mode also presents each guest carriage return as a C newline. That is the character the program removes before it formats the answer.

The loop stops when it finds your record. If fgets returns a null pointer first, check ferror while the stream is still open to distinguish a disk error from the ordinary end of the file. fclose releases the handle. The complete example uses vcccompat followed by decbfile under Project Settings → Libraries.

The filename PLANETS.TXT means drive 0 inside the guest. In Hard Drive BASIC, use DRIVE OFF to reach FD0. In CoCo SDC, copy SURVEY.dsk into your card folder and mount it as drive 0, then enter the same LOADM and EXEC command. Keep the image mounted until the program finishes reading it.

Read the list inside a planet record

Find the last line in assets/planets.txt.

MARS|RED,COLD|4

Imagine drawing a box around each field. The vertical bars divide the record into three boxes. Inside the middle box, the comma separates two traits. If you used both punctuation marks at once to split the whole line, you'd lose the distinction between a trait and the next field. Give every field a value. The tokenizer skips adjacent separators, so two bars together cannot stand for a blank field.

In main.c, follow the calls to strtok_r. The function stores a position in a pointer variable you supply. In showRecord, the pointer named fields holds your place in the record. The pointer named traits holds your place inside the list. Follow the five calls that return text on the Mars line.

Scan Separator What the call returns
Start the record Vertical bar MARS
Continue the record Vertical bar RED,COLD
Start the traits inside that field Comma RED
Continue the traits Comma COLD
Resume the record Vertical bar 4

Which saved position gets you back to 4? After a third request for a trait returns NULL, strtok_r(NULL, "|", &fields) picks up the outer record where you left it. The 4 is still text at this point. strtoul converts it to the number the program prints.

Planet Survey displays the two Mars traits and its orbit number after reading one disk record.

Send a new report. Change the last line to MARS ORBIT|DUSTY,COLD|4. Save assets/planets.txt, rebuild, launch the new disk and press 2 again. Look for MARS ORBIT and DUSTY. The program can split the line in place because fgets gave it a writable copy in RAM. The original separators are still in the file for your next trip. For the BASIC version of reading fields from disk, see Hand the log to a second program.

Keep a field log as you fly

Two planets, two observations, one disk file. Can another reader see your Earth report while your flight is still in progress?

  1. Use the Disk BASIC profile. Save a copy of the initialized practice disk as Field Trip.dsk. In Media → Floppy Disks…, mount that copy in FD0. Under Disk options check that the row says Saves automatically. Each run of the original example replaces FIELD.LOG on the disk in drive 0.
  2. Create a Hello World project in Develop → C Development…. Replace its main.c with fieldlog.c. Under Project Settings → Libraries, add vcccompat, then decbfile to LIBS. Choose Build, then Run. The binary runs in RAM and uses the disk you already mounted.
  3. When the screen says CHECKPOINT READER SEES, look for EARTH: BLUE SEA. Your program still has its file open for writing. It opened a second stream to read that first line back from disk.
  4. Click the CoCo display and press Space. Look under FINAL READER SEES. You should now have EARTH: BLUE SEA and MARS: RED RIDGE. After SURVEY FILED, BASIC accepts commands again.
The running program reads the Earth report at the checkpoint, then reads both the Earth and Mars reports after closing the writer.

Find the two disk operations in the code that saves the first observation. fputs accepts the line and fflush publishes it.

    /* Publish the first observation while we still hold the writer. */
    ok = fputs("EARTH: BLUE SEA\n", writer) != EOF && fflush(writer) == 0;
    if (ok)
    {
        printf("CHECKPOINT READER SEES:\n");
        ok = showLog();
    }

A successful fputs means the stream accepted the characters. It can hold them in a sector buffer. A successful fflush writes pending output and updates the file length on the guest disk. At that point showLog can open its own reader and see the complete first line. Its reader starts at byte zero. Closing that reader leaves the writer ready for the Mars report. At the end, the program checks fclose on the writer because this last flush can also report a disk error.

Keep yesterday’s observations. Change the opening mode in main.c from "w" to "a". Save, build and run again with the same Field Trip.dsk in FD0. At the checkpoint, count the reports. Yesterday’s Earth and Mars come first, followed by today’s Earth. Landing on Mars adds the fourth observation. Text mode stores each C newline as a Disk BASIC carriage return. A fresh text reader presents those line endings as newlines again.

Try a protected landing. At BASIC’s OK, switch on Write protected for your practice disk and run the program again. Check the error on the screen. The previous log remains on disk. With Temporary changes enabled instead, a successful guest flush updates the disk in the emulator. Use Save As… in Floppy Disks to keep a separate copy on your Mac. Compare the floppy save modes.

Read your C file from BASIC. Back at OK, enter these lines and type RUN. The same FIELD.LOG is now supplying strings to a BASIC program. The first two reports should be Earth and Mars. You can also leave the practice disk write-protected for this read.

10 CLS:OPEN "I",#1,"FIELD.LOG"
20 LINE INPUT #1,A$:PRINT A$
30 LINE INPUT #1,A$:PRINT A$
40 CLOSE #1

Read yesterday’s log and add a return trip

Suppose you land on Mars tomorrow. How will your program remember that you already visited Earth? Leave yourself a numbered entry on the disk.

  1. Use Disk BASIC and mount a writable copy of the blank practice disk in FD0. Keep that disk mounted between runs. The program keeps its travel log in TRIP.LOG.
  2. Replace main.c in your Hello World project with returntrip.c. In Project Settings → Libraries, select vcccompat, then decbfile. Choose Build and Run. On an empty log, the first trip records VISIT 1: EARTH.
  3. For a protected landing, try the save-and-retry exercise below before you fly again. For an ordinary landing, leave the disk writable and choose Run again. The program reads the Earth entry and seeks back to byte zero. Predict where the Mars entry will go. When the program reopens the log, you should see VISIT 1: EARTH followed by VISIT 2: MARS.
  4. Run it a third time. Both visits are already on disk. The program shows them again and adds no further entry.

Look for the "a+" in fopen. On the CoCo it opens the log at byte zero for reading, creating the file if needed. The loop has already read to the end. The deliberate seek below puts the cursor back at byte zero so you can see what append mode does. Look for AT BYTE ZERO and FILING MARS on your second trip.

    /* Move the cursor to the first record. With a+, output still appends. */
    if (fseek(log, 0L, SEEK_SET) != 0)
        return 0;
    planet = visits ? "MARS" : "EARTH";
    printf("AT BYTE ZERO\nFILING %s\n", planet);
    if (fprintf(log, "VISIT %u: %s\n", visits + 1, planet) < 0)
        return 0;

Even with the cursor at the beginning, the write goes to the end. fprintf sends the visit number, planet name and newline straight to the stream. Once the stream has accepted the complete line, the program calls fflush to send its pending bytes to the disk. It also checks the final close.

Which kind of trip? Use a+ to preserve the earlier visits and add a new one. Choose w+ when you intend to start a fresh log and read back what you write. Opening with w+ immediately empties an existing log. To change a particular byte in a file you already have, try r+ in the atlas exercise below.

Recover the Mars entry after a refused save

Catch the second flight between writing a line in guest RAM and saving it to disk. Start just after the first run of Return Trip, with VISIT 1: EARTH saved in TRIP.LOG. If both planets are already in the log, mount a fresh writable practice disk and run the program once to record Earth.

  1. At BASIC’s OK, open Media → Floppy Disks…. In the FD0 row, open Disk options, turn on Write protected, and leave this disk in the drive. Run the C project again.
  2. Look for FILING MARS followed by SAVE FAILED. The stream accepted the Mars line in guest RAM. Its flush encountered the protected disk. With protection still on, click the CoCo display and press R. The retry reaches the same prompt. Earth is still the only visit on disk. You can press Q here to abandon this save, or continue to the next step.
  3. In FD0’s Disk options, turn Write protected off for that same disk. Return to the CoCo display and press R once. Under REOPENED TRIP.LOG, read both lines. You should see VISIT 1: EARTH and exactly one VISIT 2: MARS.
  4. Run once more. BOTH VISITS ALREADY FILED tells you the program found its two visits on disk.
The running CoCo program pauses with the pending Mars save and offers a retry or quit key.

What does R repeat? It calls clearerr on the open stream, then tries fflush again. The cursor stays put and the pending bytes still contain Mars. Calling fprintf a second time would add a second copy of the line to the output. The recovery loop retries only the flush. You can follow the whole loop in the downloaded program. The key is read once each time the disk refuses the flush.

    while (fflush(log) == EOF)
    {
        char key;
        if (ferror(log) != DECB_ERR_IO)
            return 0;
        printf("SAVE FAILED\nKEEP THE SAME DISK IN DRIVE 0\n");
        printf("IF PROTECTED, TURN PROTECT OFF\nR: RETRY   Q: QUIT\n");
        do {
            key = waitkey(0);
        } while (key != 'R' && key != 'r' && key != 'Q' && key != 'q');
        if (key == 'Q' || key == 'q')
            return 0;
        /* Retry just the flush. Printing the observation again could duplicate it. */
        clearerr(log);
        printf("RETRYING SAVE\n");
    }
After protection was removed, the program reopened TRIP.LOG and displayed one visit to Earth and one to Mars.

Send a flight report to the TP-10

The crew needs its next instruction on the CoCo display. Mission Control wants a copy of the observations. You can give each one a different destination. This flight carries two observations in its C source, so you can try it with Run in the Disk BASIC profile.

  1. Create a Hello World C project. Replace main.c with flightreport.c and select vcccompat under Project Settings → Libraries. Choose Build, then Run. The CoCo waits for Space.
  2. Open Media → Printer Output…, or click the TP-10 behind the cassette recorder in System view. Choose Start Capture. Click the CoCo display and press Space once.
  3. Read REPORT SENT TO PRINTER PORT on the CoCo. Find the flight report in Printer Output. Choose Stop Capture. Save Text… keeps a readable copy on your Mac. Print… opens the Mac print dialog.
TP-10 FLIGHT REPORT
01 EARTH  BLUE SEA
02 MARS   RED RIDGE
END OF REPORT
Printer Output retains the four-line flight report after Stop Capture. Use Save Text to keep it.
The CoCo shows the flight’s completion message and returns to BASIC after sending the report to its printer.

Look at the two kinds of printing in the source. Ordinary printf tells the crew when to press Space. vcc_printer_printf formats the observations and hands them to the serial printer. Its newline ends the printed line. The ROM’s printer connection carries characters one way. REPORT SENT TO PRINTER PORT can therefore appear even when capture is off. Turn capture on and run the flight again if you missed it.

The same helper prints both landing rows. %02u gives visit 1 its leading zero. %-5s reserves five columns for the planet and puts its name against the left edge. Earth fills the field. Mars leaves one extra space before the observation. Try a second flight with a different observation and compare your two reports.

static int printLanding(unsigned visit, const char *planet, const char *observation)
{
    /* Two digits for the visit, a five-character field for the planet. */
    return vcc_printer_printf("%02u %-5s  %s\n", visit, planet, observation);
}

For a tour of the capture window, raw byte export, and the corresponding BASIC printer command, see Book 5’s printer receipt.

Exchange a flight recording with BASIC

The TP-10 gave Mission Control a printed report. This time a second program will read the observations. Give each observation one line in a cassette file named FLIGHT. A reader finds Earth first and Mars second. To read Earth again, you rewind the tape.

Record in C, read in BASIC. Use the Disk BASIC profile. Save any current BASIC program and export any cassette recording you want to keep before you begin.

  1. Create a Hello World C project. Replace main.c with Flight Recorder. Select vcccompat under Project Settings → Libraries, then Build and Run. Leave the CoCo waiting at W WRITE R READ.
  2. In Media → Cassette…, choose New Recording → CAS. Click the CoCo display and press W. Wait for FLIGHT SAVED and the BASIC prompt. In the recorder choose Stop, then Export Tape…. Save it as First Flight.cas. The Mac filename identifies the tape image. FLIGHT is the name the two guest programs use to find the data on it.
  3. Choose Rewind, then Play. Open the BASIC reader in BASIC Development and run it. You should see EARTH BLUE SEA, MARS RED RIDGE, then END OF FLIGHT.
10 OPEN "I",#-1,"FLIGHT"
20 IF EOF(-1) THEN 60
30 LINE INPUT #-1,A$
40 PRINT A$
50 GOTO 20
60 CLOSE #-1
70 PRINT "END OF FLIGHT"

BASIC device #-1 is the cassette. Line 20 checks for the end before reading. Line 30 takes a whole observation, including its spaces. Line 50 goes back for the next one. Your C writer can change the number of observations without changing this reader.

Record in BASIC, read in C. The return flight sends different observations so you can tell which tape supplied them.

  1. Open the BASIC writer. Choose New Recording → CAS and run the writer. Wait for FLIGHT SAVED and OK, then stop and export the tape with a second name, such as Return Flight.cas.
  2. Choose Rewind, then Play. In C Development, run Flight Recorder again. Click the CoCo display and press R. Look for EARTH TIDE POOL followed by MARS DUST DEVIL and END OF FLIGHT.
10 OPEN "O",#-1,"FLIGHT"
20 PRINT #-1,"EARTH TIDE POOL"
30 PRINT #-1,"MARS DUST DEVIL"
40 CLOSE #-1
50 PRINT "FLIGHT SAVED"
Flight Recorder in C displays EARTH TIDE POOL and MARS DUST DEVIL from the BASIC recording, reaches END OF FLIGHT and returns to OK.

Opening a file for output records its name. Each line adds a record. Closing the file records its ending. If a writer opens FLIGHT and immediately closes it, the reader should reach END OF FLIGHT without printing an observation. If the recorded ending is missing or a block is damaged, Flight Recorder reports TAPE ERROR. A recording can contain both observations and still be incomplete. On the same cut-short tape, the BASIC reader can sit at the end waiting for another block. A block with a bad checksum can produce ?IO ERROR. For a fresh attempt, use your complete exported recording.

The C reader gives each line a 32-byte array, including space for the final zero. Check the return value before printing that array. Look up the cassette functions, tour the recorder controls in Book 5, or compare tape order with seeking to a planet on disk.

Jump to a planet in the atlas

Imagine keeping the planets on four index cards. If every card takes up the same amount of space, you can jump straight to Mars. In Planet Atlas, each card occupies 24 bytes of a binary disk file. Mercury, Venus, Earth and Mars start at bytes 0, 24, 48 and 72.

  1. Mount a copy of the initialized practice disk in FD0 on the Disk BASIC profile. Leave the disk writable. On a fresh disk Planet Atlas creates ATLAS.DAT and writes the four cards once. On later trips it opens the existing atlas with r+b, so it can read a card and mark your visit.
  2. In Develop → C Development…, create a Hello World project. Replace main.c with atlas.c. Under Project Settings → Libraries, add vcccompat, then decbfile to LIBS. Choose Build, then Run.
  3. Click the CoCo display, type 4 and press Enter. Look for YOUR PICK AT BYTE 72 and MARS: RED RIDGE. The program visits Earth, returns to the bookmarked Mars card and rewinds to Mercury. Look for VISIT SAVED after the first trip to Mars. At OK you are back in BASIC.
The CoCo shows Mars at byte 72, rewinds to Mercury, then reports VISIT SAVED and ATLAS CLOSED before BASIC’s OK prompt.

The first time through, the program writes four records, padding the unused bytes of each with zeros. The first record is number 1 but its first byte is at offset 0. Subtracting one before multiplying by the card size accounts for that difference.

    /* Card numbers begin at 1. Disk offsets begin at 0. */
    long offset = (long)(number - 1) * CARD_SIZE;
    long bookmark;
    if (fseek(atlas, offset, SEEK_SET) != 0)
        return 0;
    bookmark = ftell(atlas);        // Save the start before reading the card.
    if (bookmark < 0)
        return 0;
    printf("YOUR PICK AT BYTE %ld\n", bookmark);

fseek moves to the chosen byte. SEEK_SET measures from the start of the file. ftell gives you a position you can keep in a long, which is 32 bits in CMOC. Reading a card advances the stream by 24 bytes. If you saved the position after reading Mars, where would the bookmark take you? Byte 96 is the end of this atlas. Saving the position before the read lets you find Mars again after the side trip to Earth.

rewind returns to byte 0 so the program can read Mercury.

Binary mode makes these offsets easy to calculate. In a text stream a line ending can occupy more than one byte. When you want to return to a place in text, save a bookmark from ftell and pass it back to fseek with SEEK_SET.

Leave a mark for your next visit

Run the same program again with the same practice disk in drive 0. Choose 4 for Mars. This time look for ALREADY VISITED. Your program just started over, so where did it find that memory?

Each card uses the last of its 24 bytes for the visit mark. On a fresh card that byte is zero. The Mars card starts at byte 72, so its mark lives at byte 95. On the first visit the program reads the card, seeks to the mark and writes the single character V. It calls fflush to publish that byte to the disk. Next time, reading the same card brings the V back. Earth’s card at byte 48 still has its own mark. Showing Earth as home base did not mark Earth as your selected destination.

    // Position the update stream between reading the card and writing its flag.
    if (fseek(atlas, start + CARD_SIZE - 1, SEEK_SET) != 0 ||
        fputc('V', atlas) == EOF || fflush(atlas) == EOF)
        return 0;
    printf("VISIT SAVED\n");

If you edited the atlas on an earlier trip, a full-length description might use that last byte. NO ROOM FOR VISIT MARK means the program kept your card intact.

With an update stream the same file handle reads and writes. The stream remembers one position for both operations. After reading the entire Mars card the position is already 96. Seeking to byte 95 tells the stream where to write and permits the change of direction. After writing, a successful flush or seek permits reading again. Check each result before claiming a visit was saved.

Try refusing a visit. Wait for BASIC’s OK, turn on write protection for your practice disk, and run the atlas again. Choose 2 for Venus if you have only selected Mars so far. Look for CANNOT SAVE VISIT. Choosing Mars still works because its V is already there. Restore the disk to writable for the next exercise.

Which answers reach Venus?

  1. Choose Run again. Type 2X and press Enter. The atlas says EXTRA CHARACTER: X and asks again. Can you see why a program that only checks the numeric result would send you to Venus?
  2. Type 0x2 and press Enter. Look for YOUR PICK AT BYTE 24 and VENUS: CLOUDS. The program reads your answer in hexadecimal.
  3. Run once more. Type 2 and press Enter. This time your answer is decimal. Both spellings select the same card and set the same bookmark.
Planet Atlas identifies the X in 2X and asks for another destination on the guest screen.

Look inside choosePlanet. It asks for a line beginning with a digit. Passing zero for the base tells strtoul to recognize prefixes. Then the function leaves end pointing into the line. For 2X, it points straight to the X. For 0x2, it reaches the zero byte that marks the end of the string.

        errno = 0;
        number = strtoul(line, &end, 0);
        if (*end)
            printf("EXTRA CHARACTER: %c\n", *end);
        else if (errno == ERANGE || number < 1UL || number > 4UL)
            printf("CHOOSE A NUMBER FROM 1 TO 4\n");
        else
            return (int)number;  // Now the value is small enough for an int.

There are two limits here. The conversion must fit in an unsigned 32-bit long. Clearing errno first lets you check for ERANGE on this attempt. The atlas itself has just four cards. It checks both limits before putting the result into a smaller int. For input that can be negative, see the signed companion, strtol.

Rescue an interrupted atlas save

The Mars survey team has a new observation: MARS: DUST STORM. You want the new atlas on disk, but what if the CoCo restarts halfway through replacing the old one? With three directory names, you can leave the next crew enough evidence to recover.

Name on drive 0 What it holds
ATLAS.DAT The atlas readers open.
ATLAS.NEW The proposed new edition. The program closes it, reads it back and compares every byte before moving the original.
ATLAS.BAK The previous complete edition, including the visit marks.
  1. Mount a writable copy of the blank practice disk in FD0 under Disk BASIC. Use automatic saving. You can also use a copy of the disk from the four-card atlas, including its V marks. Save other work in guest RAM before trying the restart.
  2. Create a Hello World C project, replace main.c with atlasbackup.c, and select vcccompat followed by decbfile in Project Settings → Libraries. Build and Run. On a blank disk the program first creates the original four cards. Wait for BACKUP IN PLACE and PRESS A KEY TO INSTALL. Leave the keyboard alone for a moment. Which two filenames would you expect in a directory right now?
  3. Use the emulator toolbar’s Restart → Cold Restart — Clear RAM… and confirm. Keep the same practice disk mounted. At BASIC’s OK, type DIR 0. You should find ATLAS BAK and ATLAS NEW. Both editions exist. At this instant neither has the name ATLAS.DAT.
  4. Run the same project again. Look for ORIGINAL ATLAS RESTORED and MARS: RED RIDGE. Type DIR 0 after the program returns to BASIC. ATLAS.DAT is back. The program removed its verified draft.
  5. For comparison, run it again and this time press Space at PRESS A KEY TO INSTALL. Look for UPDATED ATLAS SAVED and MARS: DUST STORM. DIR 0 now shows ATLAS.DAT and ATLAS.BAK. Running again reports ATLAS ALREADY UPDATED. The backup still holds the old ridge.
Planet Atlas Backup in a freshly started CoCo session reports ORIGINAL ATLAS RESTORED and reads MARS: RED RIDGE from the recovered edition.

Each rename changes one name on the same disk. Here’s the point where you interrupted the pair:

    if (rename(LIVE, BACKUP) != 0)
        return 0;
    printf("BACKUP IN PLACE\nPRESS A KEY TO INSTALL\n");
    waitkey(0);
    if (rename(DRAFT, LIVE) != 0)
        return 0;

When the program starts again, it reads the directory and the cards. Finding the original edition under ATLAS.BAK with ATLAS.DAT absent is its cue to restore that name. Then it calls remove only if ATLAS.NEW contains exactly the revision it would have made, visit marks and all. The code leaves unexpected contents for you to inspect. A custom atlas with extra cards or different descriptions belongs on its own disk.

The promise you tested is precise: restarting between two completed renames leaves a complete atlas to recover. Disk BASIC has no journal to repair a disk damaged during a sector write. Keep the original Mac disk image when experimenting on a copy.

Land on a second disk without leaving your program

You’re flying an expedition from the CoCo SDC profile. Drive 0 holds the flight program. Drive 1 is your destination. Earth and Mars each carry a file named LANDING.TXT. Can the same line of C find two different sets of landing instructions?

  1. Save the Planet Expedition project, expand it, and open PlanetExpedition in Develop → C Development…. Choose Build. Under Build and file actions (…) → Show Build Products, find EXPED. Copy that whole folder to a new location in Finder. The copy is your practice card.
  2. Save work in guest RAM before changing profiles. Load CoCo SDC from Machine → Configuration Profiles…. Under Cartridge → Cartridges…, open the CoCo SDC details. Note your current card folder so you can return to it. Use Choose Folder… to select the copied EXPED folder. You can enable Protect SD card files (read-only) for the entire trip.
  3. At the SDC-DOS prompt, type these commands. The first places the program disk in SDC0. The second loads and starts the program saved on that disk.
DRIVE 0,"/EXPLORE.DSK"
LOADM"EXPLORE:0":EXEC

The chart lists the disk images it finds in your card folder. Press 1 for Earth. Look for SPLASH DOWN BESIDE THE BUOY. Now press 2 for Mars. How did LAND BEYOND THE DUST FIELD. arrive on the same screen?

The running CoCo shows the Mars landing instructions. EXPLORE.DSK is still mounted on SDC0 and the Mars data disk is mounted on SDC1.

Follow the two filenames in expedition.c. At startup, sdc_list_begin and sdc_list_next read the outer directory on the card. When you choose Mars, sdc_mount selects /MARS.DSK for drive 1. The slash names a file at the root of the card. Inside the newly mounted image, LANDING.TXT:1 names a Disk BASIC file. Its :1 tells the guest which drive to read.

static void landingReport(void)
{
    // :1 asks the Disk BASIC ROM for a file inside the mounted planet.
    FILE *file = fopen("LANDING.TXT:1", "r");
    char line[40];
    int ok;

The program reads the landing instructions with fgets and closes the stream before accepting another destination. Keeping a file open across a disk change would leave its directory and sector information pointing into the old image.

Miss a landing. With Mars in drive 1, press 3. The practice card has no MISSING.DSK. Look at the error, the repeated Mars report and the two actual mounted names returned by sdc_mounted. A failed request let you keep flying with the same disks. Press Q to return to BASIC. Type DIR 0 to see EXPLORE BIN, then DIR 1 to see LANDING TXT. Select your original card folder when you finish.

Send your own instructions. Edit assets/mars.txt, rebuild, and take the new EXPED folder to a second practice location. Choose that card and repeat the two SDC-DOS commands. The guest should now print your new words when you select Mars.

Original VCC Plus manuals © 2026 Brian K. Holman. Third-party references retain their authors’ copyrights and licenses. Artwork notices. Edition 3.7.1; source and export identity. Printable edition: PDF source and export identity.

A closer look

Open original