Programming on the Apple IIgs

with APW and Related Products

A Survey of APW products
By Mike Westerfield

Like myself, many of you have been programming on the Apple II since it really was the Apple II – no plus, e, c, or GS. The first assembler I used on the Apple II was actually tape based. I break out in hives every time I remember that. As the Apple II grew, so did the languages that were available for it. First, better assemblers appeared, starting with Lisa, and continuing to Big Mac (or Merlin), and ORCA/M. The UCSD P system provided implementations of Pascal, Fortran and Cobol that were really quite respectable for a small machine like the Apple II. But we all really wanted high quality native code compilers, and they just never seemed to arrive. Those of us who were developing languages for the Apple 11 found that the machine was just too small for a full implementation of Pascal or C, and barely large enough for a good Applesoft BASIC compiler.

Finally, the Apple IIGS arrived. The Apple IIGS is, in every respect, an Apple II that grew up. With a faster 16-bit processor and up to eight megabytes of RAM, the Apple IIGS is powerful enough for good native code compilers. Sure enough, they have started to arrive, and more are due out shortly

In this series of articles, I would like to provide a programming forum for those of us who enjoy programming on the Apple IIGS. This will not be a column of programs, although we will often present programs. Rather, it is a column for programmers who are using APW and its related products. In this article, we will look at APW, surveying the various APW related products that are available. As new products are introduced, I will continue to spotlight them in this column. Next time, we will take a close look at the anatomy of APW, discovering how to set it up to take advantages of various types of hardware. I have a list of ideas for articles after that, but I will leave it open ended. I would like to hear your suggestions. The direction the series takes will depend, to a great extent, on what you want

Basic Anatomy
APW stands for Apple IIGS Programmer’s Workshop. There is a product called APW, but when I refer to APW, I generally mean the development environment, not the product. The development environment is all of those parts of APW needed to support a compiler or assembler.

You see, APW is really just a (very) supped up version of BASIC.SYSTEM. Like BASIC.SYSTEM, it gives you the ability to catalog disks, edit files, create directories, and so on. It goes much farther, though. It also lets you write complex script files, compile programs using more than one language, link programs with libraries, and much more

One of the nicest things about APW is that it is a very open system, in the sense that any piece can easily be replaced. You can add or replace compilers, use either of two linkers, or change the editor without affecting the system as a whole. In fact, there are now two completely separate
development environments that support APW languages – one is APW itself, which is a traditional text-based development environment, and one is a desktop development environment. The unfortunate thing about all of this is that, with all of the choices available, you may not know exactly what you need to program in C, for example.

To program with APW, you need two things. First, you need the development environment, which comes with several of the languages. In its simplest form, the development environment is the program that lets you enter programs, see what files are on your disk, and so on. Secondly, you need a language that runs in the APW development environment. Four are currently available: assembly language, C, and two implementations of Pascal. At least one, and possibly two, BASICS are on the way, and other languages are sure to follow. In some cases, the language comes with a development environment – we will refer to these as stand-alone systems. In other cases, you must purchase a product that has an APW compatible development environment before you can use the compiler.

APW is a stand-alone assembly language development package. It includes the APW shell, a full screen text editor, a linker, an assembler, and macro libraries. If you would like to program in assembly language, this is all you need.

ORCA/M is also a stand-alone assembly language development package. It includes the same shell, called the ORCA shell in this product, the same full screen editor and text editor, and a linker and macro libraries.

How did this happen? Why is one product available from two sources?
APW is actually an extended version of a development environment and assembler available for eight-bit Apple II computers. Apple contracted with the Byte Works to translate and extend ORCA/M as the basis of a family of language products for the Apple IIGS.

The agreement, however, is non-exclusive, so the Byte Works also has the right to publish the program. This allows Apple to sell the product through its channels, which are designed for professional and advanced amateur programmers. APW is currently sold through APDATM For a variety of reasons; Apple cannot sell APW through normal retail channels, like software stores and bookstores. The Byte Works can. ORCA/M is intended primarily for those retail channels. Table I gives a detailed comparison of the commands and utilities available in each version of the shell. It also compares the shells included with ORCA/M and APW with the one in ORCA/Pascal.

Besides the shell, there are three areas where the two systems differ. The first is the linker. ORCA/M comes with a linker that will be familiar to anyone who has used one before. It is used from the command line. You type in a list of flags, object modules (the output from a compiler or assembler) and libraries, and the linker combines these to produce an executable program. The linker supplied with APW can do all of this, too, but it also has a script-driven mode. With script files, you “program” the linker, writing a text file that tells the linker what object modules and libraries to use. The script driven mode isn’t there just to be different. It adds a great deal of flexibility in the way you can segment programs

The command line linker is definitely easier to use. With care, you can do anything with the command line linker that you can do with the script driven linker. While you can segment programs from the source level, and thus use the command line linker for any job, the extra control provided by the script driven linker makes it the linker of choice for programs over 64K, or for any program that is split into multiple segments. Also, note that the linker is the reason for the differing memory requirements between the two systems. ORCA/M requires a minimum of 5 1 2K, while APW requires at least 768K (not 1.25M, as Apple claims). Stay tuned next month!

The second major difference is the macros that come with each system. Both provide macros that interface with the Apple IIGS toolkits. Both also provide other kinds of macros, but here they differ. APW comes with a set of macros that generate in-line code or call the toolkits. ORCA/M comes with a larger set of macros, which include functions that call library subroutines, much like the runtime libraries of compilers. Many of the functions provided by these macros are identical, but unfortunately, the parties could not get together on names. Thus, for example, you can push a four-byte value onto the stack with either set of macros, but with APW this function is called PUSHLONG, while it is called PH4 with ORCA/M. When we present programs that use assembly language in this column, we will always include the macros. That way, it won’t matter which system you are using.

Finally, the documentation is considerably different. The documentation for APW is split into two volumes, one covering the programming environment, and the other covering the assembler. The ORCA/M documentation combines these into a single volume. It also adds several introductory chapters designed to teach you how to use the programming environment, as well as chapters covering the macro libraries and an index.

APW C is a full implementation of Kerninghan & Ritchie C, with some extensions. This product comes with the C compiler, the run-time libraries needed to support the compiler, and interface files that provide access to the Apple IIGS toolkit.

APW C does not come with a development environment. To use it, you must also buy one of the four products that provide a development environment. If you prefer to work in a traditional, text based environment, you can purchase APW or ORCA/M, both of which come with an assembler, or ORCA/Pascal, which includes a Pascal compiler. The ORCA Desktop Development System also supports C. If you want to program in a desktop environment, you can use that product.

ORCA/Pascal is a stand-alone implementation of Pascal. It comes with a subset of the full APW development environment; commands and utilities related to shell programming and assembly language programming have been removed.

While you do not need anything else to use ORCA/Pascal, it will work with the ORCA/M or APW shells, or under the ORCA Desktop Development System.

ORCA/Pascal conforms to the ISO Pascal standard, which basically means that it is a full implementation of the Jensen & Wirth Pascal standard. There are also many extensions, including UCSD style strings, C style strings, units, type casting, and bit manipulations functions. All string operations work on either string format.

The compiler comes with several extras. There is a complete set of sample programs, most notably a full implementation of the popular Reversi game, running in a desktop environment. Complete instructions on using assembly language subroutines, including macros to make the task easier, are also included. Finally, the source code for the run time libraries is on the disk.

TML Pascal
There are two versions of the TML Pascal compiler available. One is a standalone system that uses a proprietary desktop development environment. That version does not work with any other APW product, so we won’t deal with it here. Another version is designed to work with APW. That version comes with a compiler, run-time libraries, interface files for the Apple IIGS toolkit, and a few short sample programs. More complete samples are available separately.

The language is a subset of the original Jensen & Wirth Pascal standard, with extensions. The extensions include UCSD style strings (up to 255 characters), units, type casting, and bit manipulation functions.
Like APW C, the APW version of TML Pascal does not come with a development environment. If you would like to program in a text environment with this compiler, you can use the development environment in APW, ORCA/M, or ORCA/Pascal. If you would like to program in a desktop environment, you can use the ORCA Desktop Development

The ORCA Desktop Development System
The ORCA Desktop Development System is both a replacement and supplement for the text-based shell that comes with APW, ORCA/M and ORCA/Pascal. It supports any APW based compiler or assembler. The environment supports multiple windows: with enough disk space and memory, you could have programs from all of the languages you have installed open simultaneously on the desktop. Files can be copied and deleted from the desktop, so you do not have to go back to the finder for basic file operations.

Three important aspects are worth noting about this development system. The first, mentioned already, is that it is an open-architecture system capable of supporting all language that run under APW. Next, this desktop environment can actually use the ORCA/M shell, running it in a window on the desktop. This means that you can still use all of the power of a text based programmable shell, without giving up the simplicity of a desktop environment. Finally, for languages that support it, the desktop environment also includes a high-level language debugger, which supports step, trace, real-time execution, break points, and the ability to look at variables.

If you want to use a shell in the desktop environment, be sure to get the right version. To use the ORCA/Pascal shell, you must have version 1.2 or later. For ORCA/M, version 1.1 or later will do the job. This environment is fairly new, so Apple has not yet had time to decide if they will update APW to support the desktop environment. As a result, it is not clear yet what version of APW will be needed.

As I mentioned, the desktop development environment is still fairly new. While TML Pascal and APW C will both run under the desktop development system, ORCA/Pascal is the only language to date that can use the debugging capabilities. If the other languages are updated to take advantage of the debugger, I will let you know in this column.

Add-On Products
Apple lIGS Debugger
This is the Apple IIGS Version of the popular BugByter debugger. It is a machine language debugger, not generally suited for high-level languages. It is excellent for debugging assembly language programs. It can be used with either ORCA/M or APW. Unfortunately, it cannot be used from the ORCA Desktop Development System.

Apple IIGS Demo Sampler Source Code
The sampler disk has a number of programs written by programmers at Apple Computer to show off the Apple IIGS. All samples are written in assembly language. They can be assembled from either ORCA/M or APW.
Merlin to ORCA/M Source Code Translator
This program runs under the ORCA/M or APW shell. It does most of the work of translating assembly language programs written with Merlin into ORCA format, helping translate old programs for use in the APW environment. For diehard Merlin programmers, it can also be used as a preprocessor, translating your original Merlin source for assembly under ORCA/M or APW.

ORCA/M Library Source Code
The ORCA/M assembler (but not APW) comes with a macro library that, for some complicated functions not included in the toolkit, calls subroutine libraries. This product gives the source code for the libraries. These include two, four and eight byte integer math, as well as formatted input and output of those integer sizes and strings. It is not suitable for use with APW, since the macros and their documentation are not included.

ORCA/M Utility Package #1
This utility package provides twelve utilities that can be used from APW, ORCA/M, or ORCA/Pascal. You can use them with C or TML Pascal, if you are using one of these environments. All of the utilities are written in assembly language, and the source code is provided. While you need either ORCA/M or APW to modify the programs, you do not need the assembler to use them.

The utilities range in complexity from LOWER, which converts files to lowercase letters, through SORT, which can sort files. A brief description is given below.

Prints a calendar for any month or year.

Check a disk for bad blocks.

Compare two files for differences. This is a byte-by-byte compare.

Converts all uppercase letters in an ASCII file to lowercase letters.

Sorts an ASCII file. Options allow you to reverse the order of the sort, ignore leading blanks or differences in case, and ignore differences in spacing.

Removes any control characters from an ASCII file.

Removes trailing blanks and tabs from lines in an ASCII file.

This compare program compares ASCII files, line by line. If one line is different, the program can resynchronize itself, and continue scanning for other differences. It can also recognize when lines have been added to one of the files.

Splits a stream into two parts. Input comes from standard in, and is sent to both standard out and error out.

Finds all lines in a file that occur only once. It can print either the unique lines, or those that appeared multiple times. It can also remove duplicate entries or print how many times an entry occurs.

Converts all lowercase letters in an ASCII file to uppercase letters.
Counts the number of characters, words and lines in a file.

TML Source Code Library
This product provides extensive examples showing how to use the Apple IIGS toolkits. It is designed for use with TML Pascal. Differences in the libraries and some language differences make it unsuitable for use with ORCA/Pascal.

TML Speech Toolkit
The TML Speech Toolkit is centered around the SmoothTalker speech synthesizer. It comes with toolkit interfaces for TML Pascal. Since the speech synthesis program is a toolkit, it is possible to use this product with the assembler, APW C or ORCA/Pascal, providing you write your own toolkit interface file.

Closing Comments
Further updates will be available as information about these systems comes to light. We will be attempting to confirm the availability of all packages through their respective owners.

APW 1.0
APW C 1.0
Company: APDA™
APDA™ was turned over to Apple Computer Inc. by A.P.P.L.E. in 1990. Current Availability of these products is not known. Syndicomm was distributing the APDA materials, however, according to Apple’s legal department, no current contract exists to distribute the materials. You may find them on one of the archival websites.

Package Components:
Apple lIGS Debugger
Apple lIGS Demo Sampler
Source Code

Company: Byte Works, Inc.
8000 Wagon Mound Drive NW
Suite 207
Albuquerque, NM 871 14
(505) 898-81 83
Although Byte Works, Inc is still operated by Mike Westerfield, he has turned over the distribution of these products to Juiced.GS on CD.
You can contact them by going to their web site at

The ORCA Desktop Development System
Merlin to ORCA/M Source Code
ORCA/M Utility Package #1
ORCA/M Library Source
All prices are available at:

Product: TML Pascal
Company: TML Systems
Price: TML Pascal (APW Version) $125.00
TML Source Code Library
TML Speech Toolkit

  • Current availability of this package is not known. You can contact Tom Leonard at BlackFin, Inc. at (404) 521-2199
  • Current availability of this package is not known. You can contact Tom Leonard at BlackFin, Inc. at (404) 521-2199
Please follow and like us:

About the Author