Programming the Apple IIGS in Assembly Language by Ron Lichty and David Eyes APW C and ORCA/C Code by Cecil Fretwell You can reproduce this document by using the APW or ORCA/C command TYPE READ.ME.FIRST >.PRINTER The C code on the disk accompanying this documentation is based on the book Programming the Apple IIGS in Assembly Language by Ron Lichty and David Eyes. The book was published by Brady, part of the Simon & Schuster Reference Division, copyright 1989. As of the summer of 1991, this book is no longer in print. However, it is felt the C code presented here is sufficiently commented to assist you in learning how to write a desktop application using C. Although the book uses assembly language, most of it can be a valuable source for C programming efforts. If you wish to learn C using the IIGS, use the book as an outline for generating code, from a few lines in the first example to a full-fledged Apple IIGS desktop application in the final example. If you are an experienced C programmer, the skeleton developed on the disk can be a solid starting point for building your own application. The C author, Ron Lichty, David Eyes, and Brady make no warranty of any kind, expressed or implied, with regard to the C code and all forms thereof. These same people shall not be liable in any event for incidental or consequential damages in connection with or arising out of the furnishing, performance, or use of the C code in any form. The C version is copyrighted by Cecil Fretwell to an extent which does not violate the copyrights of Ron Lichty, David Eyes, or Brady. The disk contains a file called CREF.9.23. Use the command TYPE CREF.9.23 >.PRINTER to print approximately thirty five pages of source code with numbered lines and a cross reference showing all variables, function names, etc. and the lines in which they occur. This listing came from Fragment 9.23 in Chapter 9 and the include files in the root of the disk. The source file for this fragment has a few comments which are shorter than those in previous fragments. This was done to limit the listing to 80 characters per line. You will note that all source code is extensively documented. Very few lines do not contain a comment. These comments are taken from Ron's and David's original assembly code, and expanded where appropriate to explain how it's done in C. The combination of the extensive comments and a hard copy of the file CREF.9.23 should help you to avoid many common mistakes when working with C code. If you try to convert the assembly code, this documentation will save hours of frustration trying to find an error which often results in a crash to the monitor or a system lock-up. In the C code, you will find two nearly identically named functions, one called main and the other Main. The Hello label in the assembly version is equivalent to the main function in the C code. C always begins execution of a program starting with the function called main, which must be all lower-case. It would undoubtedly have been less confusing to use something other than Main, for the other function; however, Main is what Ron and David called the label that this function parallels, so it seemed most consistent to retain the names. If you try to parallel the book and its assembly language disk, Chapter 5 may be confusing with respect to the C disk. Listing 5.2 for the assembly version is a slight variation of Listing 5.1. For the C disk, only Listing 5.1 was converted. The assembly module called AT.FRAG.5.2 parallels the C code in the files called FRAG.5.2.CODE and FRAG.5.2.DATA. The assembly module is missing a call to Main, the C code corrects this omission. MAKE A WORKING COPY OF THE ORIGINAL DISK AND WORK ALWAYS WITH A COPY. If you use a 3.5" disk to compile and link modules, delete the file CREF.9.23. Failure to do will result in running out of disk room when you compile and link the code for the final chapters. If you are using APW C, the disk as shipped is ready for use. If you are using ORCA/C, execute BUILD.ORCA.C. Given an ORCA/C based disk, execute BUILD.APW to convert the disk back for use with APW C. If you desire to compile and link a particular module for a chapter, first copy the proper chapter .CODE file to HELLO.CODE in the root of the disk. Then copy the proper chapter .DATA file to HELLO.DATA in the root of the disk. With the root set as the prefix, execute the file BUILD.HELLO to produce the S16 module called HELLO in the root. Take some time to examine the disk catalog at the end of these notes and then the following discussion regarding details for the disk. Those files marked with an asterisk (*) are unique to APW C. Those files marked with a pound sign (#) are unique to ORCA/C. The disk is ready for use with APW C. ABOUT.H. One of many header files on the disk. Each header file very closely resembles a data segment in the assembly version. BANNER.H. When the disk is in APW C form, all compiled and linked programs contain material from the APW C Run-Time Libraries, copyright 1987 - 1990 by Apple Computer, Inc. and used with the permission of Apple Computer. The "About" dialog in the S16 module HELLO.CHAPTER.8 also reflects this acknowledgment. In this case, BANNER.H and BANNER.APW are equal. When the disk is in ORCA/C form, all compiled and linked programs contain material from the ORCA/C Run-Time Libraries, copyright 1987-1990 by ByteWorks, Inc. and used with the permission of Byte Works. The "About" dialog in the S16 module HELLO.CHAPTER.9 also reflects this acknowledgment. In this case, BANNER.H and BANNER.ORC are equal. BUILD.APW. Execute this file to create a disk for APW C. BUILD.ORCA.C. Execute this file to create a disk for ORCA/C. BUILD.HELLO. Same as BUILD.HELLO.APW if the disk is in APW C form. Same as BUILD.HELLO.ORC if the disk is in ORCA/C form. Execute this file to compile and link modules to produce the S16 file called HELLO. CHAPTERc. Directories for code in Chapters 5, 6, 7, 8, and 9. FRAG.c.f.CODE. Source code for Fragment f in Chapter c. All fragments are located at the same points as given in the book and on the assembly disk. LIST instead of FRAG is used for Listing 5.1. FRAG.c.f.DATA. Header code for Fragment f in Chapter c. This code uses #include to copy in the necessary .H header files for a fragment. LIST instead of FRAG is used for Listing 5.1. COMPILE.UP.DOWN. Unique to the APW C form of the disk. Used to compile the module called UP.DOWN.CC and produce UP.DOWN.ROOT. CREF.9.23. Source code listing and cross reference for Fragment 9.23. Parallels the code in Appendix D of the book. HELLO. S16 file resulting from compiling HELLO.CC and, for APW C only, linking this with UP.DOWN.ROOT (APW C only). HELLO.CC. Same as HELLO.CC.APW if the disk is in APW C form. Same as HELLO.CC.ORC if the disk is in ORCA/C form. This C code file combines HELLO.CODE and HELLO.DATA and other code to produce the proper source code for the appropriate language. HELLO.CHAPTER.c. Executable code developed from the last fragment in Chapters 5, 6, 7, 8, or 9. Established by the command COPY HELLO HELLO.CHAPTER.c To save disk space, after the files were copied, the APW COMPACT command was used to reduce the size of these executable modules. HELLO.CODE. Produced by a command of the form COPY CHAPTERc/FRAG(or LIST).c.f.CODE HELLO.CODE Used by BUILD.HELLO to produce an executable module. HELLO.DATA. Produced by a command of the form COPY CHAPTERc/FRAG(or LIST).c.f.DATA HELLO.DATA Used by BUILD.HELLO to produce an executable module. UP.DOWN.CC. This source module is unique to the APW C form. It contains the startup and shutdown code for the toolbox. The detailed code is used to parallel the book and to support older System Disk versions. For the ORCA/C form, the abbreviated startup(640) and shutdown() functions unique to ORCA/C are used. UP.DOWN.ROOT. Unique to the APW C form. Results from using COMPILE.UP.DOWN and is used in the link step of BUILD.HELLO. About the C code author. Cecil Fretwell has been a computer professional for almost 32 years, has programmed microcomputers for over 16 years, and started working with Apple II computers in 1982. He has written more than 30 articles about the Apple II and other personal computers and has reviewed in excess of 25 books. As one of three technical reviewers of Programming the Apple IIgs in Assembly Language, he found himself addicted to typing in the program listings, assembling them, and running the result, and he happily marked up Lichty's and Eyes' work with deep layers of red ink. They later thanked him for it! He was, for its final two years, Technical Editor of Call -A.P.P.L.E. He currently does the Apple Clinic column for inCider/A+. Learning to program in C has been one of his recent challenges. Disk Catalog READ.ME.FIRST (This file, TXT form) CHAPTER8 ABOUT.H FRAG.8.2.CODE BANNER.H FRAG.8.2.DATA *BANNER.APW FRAG.8.5.CODE #BANNER.ORC FRAG.8.5.DATA *BUILD.APW FRAG.8.7.CODE #BUILD.ORCA.C FRAG.8.7.DATA BUILD.HELLO FRAG.8.10.CODE *BUILD.HELLO.APW FRAG.8.10.DATA #BUILD.HELLO.ORC CHAPTER9 CHAPTER5 FRAG.9.9.CODE LIST.5.1.CODE FRAG.9.9.DATA LIST.5.1.DATA FRAG.9.13.CODE FRAG.5.2.CODE FRAG.9.13.DATA FRAG.5.2.DATA FRAG.9.18.CODE FRAG.5.16.CODE FRAG.9.18.DATA FRAG.5.16.DATA FRAG.9.23.CODE CHAPTER6 FRAG.9.23.DATA FRAG.6.2.CODE COMPILE.UP.DOWN FRAG.6.2.DATA CREF.9.23 FRAG.6.4.CODE HELLO FRAG.6.4.DATA HELLO.CC FRAG.6.10.CODE *HELLO.CC.APW FRAG.6.10.DATA #HELLO.CC.ORC FRAG.6.14.CODE HELLO.CHAPTER.5 FRAG.6.14.DATA HELLO.CHAPTER.6 FRAG.6.16.CODE HELLO.CHAPTER.7 FRAG.6.16.DATA HELLO.CHAPTER.8 CHAPTER7 HELLO.CHAPTER.9 FRAG.7.3.CODE HELLO.CODE FRAG.7.3.DATA HELLO.DATA FRAG.7.6.CODE MENUDEFS.H FRAG.7.6.DATA MENUDEFSN.H FRAG.7.13.CODE MENUDEFSO.H FRAG.7.13.DATA MYCURSOR.H FRAG.7.23.CODE *UP.DOWN.CC FRAG.7.23.DATA *UP.DOWN.ROOT FRAG.7.29.CODE WDWGLOBE.H FRAG.7.29.DATA WDWWORLD.H FRAG.7.30.CODE WORLDICON.H FRAG.7.30.DATA The C disk is Shareware for $20 from: Cecil Fretwell 2605 Highview Ave. Waterloo, IA 50702 Note to ORCA/C users. If you obtain error messages like compiler error, the system hangs during compile..., reboot your system. Early versions of ORCA/C had some problems.