This is a cache of https://vccplus.brianholman.com/manuals/programming-in-c/shipment/. It is a snapshot of the page as it appeared on 2026-11-21T00:01:12.098+0000.
Hand a function one shipment · 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 4 of 9

Hand a function one shipment

The cook handed the pilot a single number, 360. How could you tell which shipment the program was counting before a number appeared on screen? Stop the running program while its helper is working, then look back at the row that called it.

Stop before the first count

Use the CargoCount project from the previous chapter with the original two rows. If you are starting here, get the complete cargo source and follow the project setup. Select Debug, save and build. The debugger needs the source and compiled binary from the same build.

  1. At the bottom of C Development, open Source breakpoint. Pick Line 33, the assignment that calls mealsFor(&manifest[row]) in the supplied file. Use the statement to find it if you've added your own comments.
  2. Click Run to Breakpoint and confirm. That command targets the line you selected. Clicking an ordinary Run with no added breakpoints lets the program finish immediately.
  3. At the pause choose Into. You may first stop on the function header at line 20. Press Over once if necessary to reach its multiplication at line 22. A stop on the function header can be too early for CMOC to describe its parameters. Wait until the highlighted source and pause message both name the line you want to inspect.
/* A pointer lets us read one row without copying the whole structure. */
static word mealsFor(const struct Shipment *shipment)
{
    return (word) shipment->crates * shipment->mealsPerCrate;
}

The ampersand at the call site means “the address of.” On the first pass &manifest[row] gives the address of the Earth shipment. The star in const struct Shipment *shipment declares a pointer that the function can use to read that shipment. The arrow in shipment->crates follows the pointer and selects its crates member. The cast (word) makes the first factor explicitly an unsigned 16-bit integer for this calculation.

Open the pointed-to shipment

Select Variables in the lower pane. In Inspect frame, choose 0: mealsFor if necessary. Expand shipment. Expand the Pointee underneath it to inspect the structure at that address. Look for crates = 12 and mealsPerCrate = 20. The hexadecimal address beside a pointer may differ between builds. Its members tell you which delivery it describes.

In the paused C Development window, line 22 multiplies the two members. Variables shows shipment expanded through Pointee to crates 12 and mealsPerCrate 20.

To keep one value in sight, select Watches, enter shipment->crates in the expression field and press Return. In this frame on the first delivery it should read 12. Watching an expression reads paused memory. You can inspect a member safely without running a second copy of the function. A watch written with a parameter name belongs to the frame where that name has meaning.

Look back at the pilot’s row

Select Call Stack. Frame 0 is the function currently executing. Frame 1 is main at the call that brought you here. Select frame 1, then Variables. The source moves back to the assignment in main. You should now find row = 0 and total = 0. Execution still waits inside mealsFor.

Call Stack shows mealsFor stopped at line 22 and its caller main at line 33.
Selecting frame 1 shows main at its call site. The caller's row and total are both zero. Its local meals has not yet received the answer.

There may already be a number beside the caller's meals. The right-hand side of the assignment is still running. Until the helper returns, that storage can hold a leftover value. Select frame 0 again. Out finishes the helper and returns to its caller. If the assignment is still highlighted, step Over to the following line before reading meals. Its first assigned value is 240. Continue to see the Earth line, or inspect the next visit at the call site. During the Mars call the caller's row is 1 and its accumulated total is 240. Finish with Continue, resuming again if the same source stop is encountered.

How long does an address last?

The manifest has static storage. Its two rows remain in memory throughout the program, so a helper can read the selected row whenever it is called. const on the pointed-to shipment prevents the helper from modifying that row through this pointer. The local row and total belong to this invocation of main. The local meals belongs to the block inside the loop. When the block ends, another use of that storage is free to overwrite it.

C lets you form a pointer without attaching an element count. The loop protects the access by checking the row before handing off the address. Valid indices for this manifest are 0 and 1. Reading manifest[2] would step outside the array, even if the debugger could show bytes at that address. Keep the bounds check and the lifetime of the object in view whenever a pointer crosses a function boundary.

You've now examined source on the Mac and data in the CoCo's RAM. In the next project, you'll follow the program into a data file on the floppy in FD0.

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