Subject: DRAFT FAQ: csa2.programmer (d1)
From: [email-masked] (Bryan K. Ogawa)
Date: 4 Oct 1995 20:36:02 -0000
Newsgroups: comp.sys.apple2.programmer

Draft FAQ:  Apple II Programming Frequently Asked Questions
Draft 1
Last Revised 04 October 1995
Author: Bryan K. Ogawa <[email-masked]>
 
This is a draft version of the FAQ (frequently asked questions) list for
comp.sys.apple2.programmer.  Comments, suggestions, corrections, and other
information (such as suggested topics) are welcomed, either in the
newsgroup comp.sys.apple2.programmer, or via email to
<[email-masked]>. 

FYI:  stuff in {curly braces} are comments to myself to remember, look 
for, or otherwise do things.
 
--
 
This is a list of frequently asked questions (FAQs) concerning programming
the Apple II series of computers, both 8-bit (the Apple II, II+, IIe, IIc,
and IIc+, as well as clones, such as the Franklin Ace and Laser 128 series
of computers) and 16-bit (the Apple IIgs). 
 
This FAQ does NOT directly cover questions concerning the following topics:
 
--Apple II emulators for non-Apple II machines (e.g. STM or a2em)
--General Apple II questions
 
Separate FAQs are available on these topics, and are available in similar 
locations as this FAQ.
 
This FAQ is posted monthly to news.answers, comp.answers, comp.sys.apple2,
and comp.sys.apple2.programmer.  The most recent version of the FAQ can be
obtained in the following manner{Insert information on how to obtain this
FAQ via the rtfm.mit.edu sites, mirrors, and mail server} {Insert
information about html WWW versions, e.g. the Ohio State archive.}
 
This FAQ is maintained by Bryan K. Ogawa, <[email-masked]>. 
Corrections, suggestions, and additional information, and other criticism
(hopefully constructive) are welcomed.  To ease mail handling, please put
the word "[FAQ]" into the subject line of email.  I haven't begun
filtering my email, but this may change at some point. 
 
{Special thanks section goes here}

---
 
Questions
 
------------------------------
 
Subject: Programming 8-bit Apple IIs and Compatibles
 
Q01)  What assemblers are available for the Apple II?
Q02)
 
------------------------------
 
Subject: Programming the Apple IIgs

------------------------------
 
Subject: General Programming Information and Source Code
 
Q01)  What programming languages have been available for the Apple II?
 
A list of known Apple II programming languages is maintained by Larry
Virden <[email-masked]>, and is available from the compiler information
site,
 
<URL:ftp://idiom.berkeley.ca.us/pub/compilers-list/AppleIICatalogV.L>
 
where V is the version number, and L is the revision number.
 
Q02)  I am interested in choosing a language to learn on my Apple II.  
What are my options?
 
There are a number of languages currently available for 8-bit Apple IIs. 
A few of these options are briefly discussed here. 
 
  Applesoft
  ---------
 
Applesoft is the name of the implementation of Microsoft BASIC for the
Apple II series of computers.  It is a floating point interpreted BASIC,
built into all Apple II series computers (excepting certain original Apple
II machines).  It has not changed significantly since its release with the
Apple II+, and it does not include built-in commands to handle "advanced"
operations for more recent models, including double-high resolution
graphics, extra memory beyond 48K, or any GS-specific features. 
 
Many add-ons were, and are, available for Applesoft.  Current tools for
the serious Applesoft developer include RADE, a real-time debugger for
Applesoft (which requires a GS), and <insert Morgan Davis's other
tool--the one that adds structured programming elements to
Applesoft--here>. 
 
  Assembly Language
  -----------------
 
The Apple II computers are also programmable in 6502, 65C02, or 65816
machine language.  This can be accomplished in one of two ways:  by typing
in machine code (in the form of hexadecimal numbers) into the monitor, or
via an assembler. 
 
The monitor is a program, built into all Apple II computers, which gives
the user access to information stored in the computer.  It can be accessed
from Applesoft by typing
 
]CALL -151 <RETURN>
 
The next line will appear with the monitor prompt, a * :
 
*
 
From this point, commands for the monitor may be entered.
 
{Ed. note: do you guys think a listing of monitor commands would be useful
here?}
 
An assembler is a program which simplifies programming by allowing the
programmer to use mnemonic names for machine language instructions, as
well as symbolic labels.  Use of an assembler is highly recommended if you
are interested in programming in machine language. 
 
{Editor's note:  I'm not sure if I have the facts correct here about the 
mini-assembler, specifically--do the enhanced IIe, IIc, and IIc+ have the 
mini-assembler in ROM?}
 
A number of assemblers are available for the Apple II series.  A simple
assembler, called the mini-assembler, which was originally part of the
Integer BASIC (an alternative BASIC which, as its name suggests, cannot
handle floating point arithmetic) ROMs, and can be found in Apple IIs with
the Integer ROMs.  In addition, the mini-assembler reappeared (without
Integer BASIC) in the ROMs of the enhanced IIe, IIc, IIc+, and IIgs.  To
invoke the mini-assembler, type !  <RETURN> at the monitor prompt, like
so: 
 
* !
 
At this point, the prompt will change to an !, indicating that the 
mini-assembler is active:
 
!
 
{Ed. note:  syntax of mini-assembler?}
 
While the mini-assembler is good for writing and testing short routines,
it lacks many features available in "real" assemblers.  A number of "real" 
assemblers are available, both via anonymous ftp and commercially. 
 
Freely Available (including shareware)
 
Lisa, an assembler from HAL Labs, has been released as shareware. 
Versions for both the 6502 and 65C02 and for the 65816 are avaiable via
anonymous ftp from <URL:...>
 
The Hyper-C system (see section on C, below) contains an 8-bit assembly 
package.
 
Two commercial companies continue to sell assemblers for the Apple II
series.  The first of these is ORCA/M, published by The Byte Works. 
ORCA/M comes in two different versions: ORCA/M for 8-bit machines,
(currently version 4.0.1 {?}), and ORCA/M GS (currently version 2.0.3
{?}). 
 
The other company is Southwest Data Systems, distributed by Roger Wagner
Publishing {?}, which offers the Merlin series of assemblers.  Merlin
comes with both 6502/65C02 and 65816 assemblers in one package, and
includes a 65816-compatible package which will run on 8-bit machines
fitted with a 65802 processor (the 65802 is a chip pin-compatible with the
65C02, which runs the 65816 instruction set).  The assemblers in the
Merlin package are Merlin Pro (which runs under DOS 3.3, and is a
6502/65C02 {?} assembler), Merlin 8 (runs under ProDOS 8, 6502/65C02
assembler), Merlin 16 (runs under ProDOS 8, 6502/65C02/65816 assembler),
and Merlin 16+ (runs under GS/OS, 6502/65C02/65816 assembler). {version
#s?}

  C
  -
 
A number of C compilers have historically been available for the Apple II 
series; however, only two compilers remain available, one 8-bit, one 
GS-specific.
 
The 8-bit compiler is Hyper-C, and is available via anonymous FTP at the 
following URLs:
 
{ed. note: put directories here}
 
Officially, the distribution status of Hyper-C is shareware; however, I do
not know if the address for it is currently working. 
 
The GS-specific compiler available is ORCA/C, currently version 2.0.4. 
ORCA/C is commercial software, and is available from The Byte Works (see
section on contacting companies for more information). 
 
  Pascal
  ------
 
The only Pascal currently available is ORCA Object/Pascal, which runs on
the Apple IIgs only.  It is available from The Byte Works. 
 
  Modula/2
  --------
 
Two Modula/2 packages are available for the IIgs.  The first is ORCA
Modula/2, available from The Byte Works. 
 
The second is {?} Modula/2, and is available via anonymous ftp from
 
<URL:ftp://ftp.cco.caltech.edu/...>
 
This package requires an ORCA-compatible language (or linker), and is
labelled as shareware. 
 
Q03)  My C program appears to compile correctly under ORCA/C v2.0.x, but 
it doesn't work.  Is there a listing of known bugs in ORCA/C?
 
A listing of known bugs in ORCA/C v2.0.4 is posted periodically by Soenke
Behrens, <>, and is available via the World Wide Web at 

<URL:http:// ...>. 
 
Q06)  What's GNO/ME?
 
GNO/ME is a programming shell (a command line environment) for the Apple
IIgs.  Designed as a replacement for the ORCA Shell, GNO/ME works in a
manner similar to the Unix operating system, providing preemptive
multitasking of multiple text programs, as well as many Unix commands and
library functions.  It is commercial software, and produced by Procyon,
Inc.  Contact Jawaid Bazyar <[email-masked]> for information on
purchasing GNO/ME.  The current version of GNO/ME is 2.0.4. 
 
It is available from EGO Systems:
 
EGO Systems
....
 
Price: $89 (?)

Q07)  What books do I need to do toolbox programming on the GS?
 
A07)  To do toolbox programming, the following manuals are REQUIRED:
 
Toolbox, vol. 1
Toolbox, vol. 2
Toolbox, vol. 3 (System 5 and later)
System 6 (System 6 calls)
System 6.0.1 (System 6.0.1 calls)
 
Prodos 16 Reference (for making P16 calls)
  or
GS/OS Reference (for making GS/OS calls)
 
recommended:
 
Programmer's Introduction
 
Hardware Reference
Firmware Reference

Q07a) Where can I get GS Programming books?
 
Unfortunately, some of the books {put book list here} are no longer in
print, and must be purchased used.  Check the newsgroup
comp.sys.apple2.marketplace for information from people selling used Apple
II hardware--the books are sometimes sold there. 
 
Some of the Apple books are available from The Byte Works, {insert Byte
Works contact info}
 
Q08)  Where are Apple's Technical Notes available on the Internet?
 
The technical notes are available from several sources.  The offical
location for them is via FTP from ftp.apple.com, Apple's offical location. 
They may be found at the following URL:
	ftp://ftp.apple.com/dts/ {finish address}
 
In addition, the Apple II technotes are also available via the WWW from
Jay Krell:
	http://www.cornell.edu/~jkrell/ {finish address}
 
Q09)  What happened to APDA?
 
The Apple II duties of APDA have been taken over by The Byte Works, with
the exception that filetypes are now handled by someone on GEnie {get
information about filetypes}. {contact information?}
 
Q04)  What are the opcodes for the 6502/65C02/65816?
 
A listing of the 6502, 65C02, and 65816 opcodes are available 
 
Q05)  Do you have a routine for doing {x} on the Apple II?
 
Routines for performing a variety of tasks have been occasionally posted
to comp.sys.apple2.programmer.  Some of this code will be made available
via the World Wide Web, from Bryan Ogawa's Apple II site, at
	<URL:http://www.netvoyage.net/~bkogawa/apple2/>
 
Currently, I have code that does the following:
 
6502 code to multiply two 16-bit numbers, producing a 32-bit result
(authors:  David Empson, in the style of Lichty and Eyes)
 
65816 code to multiply two 16-bit numbers, producing a 32-bit result
(authors:  David Empson, in the style of Lichty and Eyes)
 
65C02 code to activate and deactivate (as well as lock and unlock) the
IIc+ acceleration to and from 4MHz (author: David Empson)
 
65C02 code--VBL interrupt handler (requires a IIe w/ mouse card, IIc,
IIc+, or IIgs w/ a mouse card or mouse firmware enabled) (author: David
Empson, in the public domain)
 
------

Well, there is a little bit of it.  It's obviously NOT going to be done 
anytime soon, but I'd like to get a running small version up soon.

Comments?  Corrections?  Clarifications?  comp.sys.apple2.programmer or 
[email-masked] .

-- 
NEW ADDRESS!  Bryan K. Ogawa <[email-masked]>  II Infinitum  <><