Atari Compendium Errata Pt.1

 "The American government is making nuclear weapons like  there's
no tomorrow."
                                                      Emo Philips

             "THE ATARI COMPENDIUM" BY SCOTT SANDERS
                     Errata Sheet: 11/1/1993
                           Part 1 of 3
                   (Foreword by Michael Noyce)

 When "The Atari Compendium" was released a couple of years ago I
immediately purchased a copy.  Okay,  my parents bought it for me
as a Christmas present <grin>.  Anyway,  it was a real  god-send.
Never  before had all the offical Atari developers  documentation
been gathered into one comprehensive volume.
 However, it soon came apparent there were many mistakes, errors,
and  omissions  that needed correcting,  and that is  what  these
three errata 'sheets' do.

 Originally one file,  I have split it into three distinct parts.
The  first  part (this file) is the original errata  released  by
Scott Sanders. The second part was compiled by Mark S. Baines, of
"Profile"  fame,   from  various  sources  (credited  after  each
correction).  The  third  part  is a  collection  of  corrections
extracted from "ST Applications".

 I   haven't  changed  the  contents  in  any  way   other   than
reformatting the text for the ST NEWS page viewer and tidying  up
the presentation a bit.
 Finally,  I would like to thank Mark S.  Baines for supplying me
with  the  original file and for his permission to  reproduce  it
here.  In  fact  he  says  you  are  encouraged  to  spread  this
information as much as possible.

                              *****

1.3 (The 260/520/1040ST)
The  original  ST  computers  contained  a  320x200x16  mode,   a
640x200x4 mode, and a 640x400x2 mode (not 640x400x1 as stated).

1.5
The MegaSTe has three serial ports,  not two (one is shared  with
the LAN).

The TT has a 1280x960x2 mode (not 1280x960x1).

1.6
The  Falcon030 may have a 2.5" IDE drive installed,  not a  half-
height drive as stated.

2.3 (Overview)
GEMDOS derives its heritage from CPM 68k (not CPM 86k).

2.4 (GEMDOS Directories)
Each  sub-directory contains a directory named '..' which  refers
to its parent directory. In addition, each sub-directory contains
a directory named '.' which refers to itself.  The root directory
contains neither of these files.

2.5 (Disk Transfer Address)
The DTA structure is never defined. It is as follows:

   typedef struct _dta
   {
        BYTE    d_reserved[21];
        UCHAR   d_attrib;
        UWORD   d_time;
        UWORD   d_date;
        ULONG   d_length;
        BYTE    d_fname[14];
   } DTA;

(Actually,  the  DTA structure is defined (as above)  in  section
2.64 - Fgetdat() - MN)

2.17 (Signal Table - SIGABRT)
The  last  sentence  in  this  table  entry  should  be  "It   is
unrecommended that you catch this signal."

2.23 (GEMDOS Time & Date Functions)
TOS 1.02 is incorrectly referred to as 1.2. Any references to TOS
1.2  should be considered references to TOS 1.02,  likewise  with
TOS 1.04 or TOS 1.06.

2.38 (Dcntl() - FS_INSTALL entry)
The structure fs_descr is defined without the portability macros.
'WORD'  should  be substituted for 'short' and 'LONG'  should  be
substituted for 'long'.

2.51 (Fchmod() - table)
The definition 'S_IRUSER' should be 'S_IRUSR'.

2.54-2.58 (Fcntl() - table)
Several  constant  definitions for the cmd parameter  of  Fcntl()
were  omitted.  The  correct constants are  (note:  TIOCSTOP  was
documented, but the constant listed was incorrect):

   Definition               Constant
   F_SETLKW                 0x0007
   TIOCSTOP                 0x5409
   TIOCGXKEY                0x540D
   TIOCSXKEY                0x540E
   PSETFLAGS                0x5404
   PGETFLAGS                0x5405
   PTRACEGFLAGS             0x5007
   PTRACESFLAGS             0x5006
   PTRACEGO                 0x5008
   PTRACESTEP               0x500A
   PLOADINFO                0x500C
   SHMSETBLK                0x4E01
   SHMGETBLK                0x4E00

2.77-2.78 (Fsfirst() and Fsnext())
The  DTA structure was never defined.  See the note for page  2.5
above.

2.87 (Pexec())
Pexec() mode 6 is available as of GEMDOS version 0.15.

3.4 (System Startup)
The  Fuji  logo  and hard disk spin-up delay occurs  on  all  TOS
versions past 2.06, not just 2.06 and 3.06 as is stated.

3.8 (Searching for a Cookie)
The example code references the cookie structure members 'cookie'
and 'value' as 'c' and 'v' rather than by their full name.

3.11 (_MCH cookie)
The ST Book '_MCH' cookie contains a value of 0x00010008.

3.12 (FSMC cookie)
The  value  field of the 'FSMC' cookie contains a  pointer  to  a
structure  with information about the current version of GDOS  as
follows:

   typedef struct _gdos_info
   {
        ULONG   gdos_type;
        UWORD   gdos_version;
        WORD    gdos_quality;
   } GDOS_INFO;

The structure member gdos_type will be either '_FSM' for FSMGDOS,
'_FNT' for FONTGDOS, or '_SPD' for SpeedoGDOS.

The   structure  member  gdos_version  contains   the   currently
installed version of GDOS with the major version number being  in
the high byte and the minor version being in the low byte.

The  structure  member gdos_quality is initialized to  0xFFFF  to
indicate  that  printouts  will be  processed  at  the  'default'
quality setting.  Applications may change this value to 0x0000 to
force  GDOS  drivers to output in DRAFT mode or 0x0001  to  force
GDOS  drivers  to output in FINAL mode.  The variable  should  be
restored to 0xFFFF after each print.

3.13 (BIOS Devices)
The Mega STe supports devices 6,  7,  and 9 as Modem 1,  Modem 2,
and  Serial 2 respectively.  Reliable use of BIOS serial  devices
other  than the ST compatible device #1 on a  Falcon030  requires
the  use of the TSR program "FPATCH2.PRG" (available  from  Atari
Developer Support) or a TOS version >4.04.

3.31 (Setexc() - table)
The vector number for TRAP #1 (GEMDOS) is 0x21.

4.16 (The Serial Port)
No mention was made of the Mega STe's serial ports. They bear the
same functionality as serial ports on the TT except that there is
no Serial 1 port on a Mega STe.

The Falcon030 contains an MFP chip,  however,  it is not used  to
control any of the serial devices.

4.23 (Bconmap())
The Falcon030 requires "FPATCH2.PRG" or an installed TOS  version
greater than 4.04 for Bconmap() to work as expected.

4.xx (DSP functions)
Most of the DSP functions contain an incorrect function opcode in
the  'Binding'  section of the function  reference.  The  correct
opcode  for all DSP functions is properly listed in the  'Opcode'
section, however.

4.33 (Dosound())
Dosound(-1) returns a pointer to the sound block of the currently
playing sound or NULL if no sound is currently being played. This
feature is broken in MultiTOS 1.00-1.08.

4.58 (EsetGray())
Mode 0 of EsetGray() causes the low 12 bits of a palette entry to
be interpreted as a TT color. Mode 1 causes the low eight bits of
a palette entry to be interpreted as a gray value between 0-255.

4.59 (EsetPalette())
The correct binding for EsetPalette() is:

   pea     palette
   move.w  count,-(sp)
   move.w  start,-(sp)
   move.w  #$54,-(sp)
   trap    #14
   lea     10(sp),sp

4.61 (Flopfmt())
buf should be a word-aligned pointer to a buffer large enough  to
hold one complete track (not sector as stated).

4.74 (Kbrate())
The correct binding for Kbrate() is:

   move.w  rate,-(sp)
   move.w  delay,-(sp)
   move.w  #$23,-(sp)
   trap    #14
   addq.l  #6,sp

4.80 (Offgibit())
Offgibit()  bit  #7 toggles SCC A between the Serial  2  and  LAN
ports on a TT.

4.81 (Ongibit())
For each bit of mask that is set, that bit will be toggled.

4.86 (Rsconf())
Rsconf()  with a speed parameter of -2 will return the  last  set
baud rate on TOS 1.06 or TOS 1.04 with "TOS14FX2.PRG".

4.92 (Setscreen())
If  any parameter of Setscreen() is -1,  then the value  is  left
unchanged.

4.94 (Sndstatus())
Sndstatus() is available when bit #2 of the '_SND' cookie is set.

4.96 (Soundcmd() - table)
The  sample  rates generated by using a  TT  compatible  prescale
value  with SETPRESCALE are incorrectly identified in MHz  rather
than KHz.

4.97 (Supexec())
The  function  pointer  taken  by  Supexec()  was  not   properly
prototyped.  Supexec() takes a pointer to a function accepting no
arguments and returning a LONG.

4.99 (VgetRGB())
VgetRGB() is available when the '_VDO' cookie contains a value of
0x00030000 or higher.

4.100 (VsetMask())
The opcode for VsetMask() is 92 (0x5C).

4.101 (VsetMode())
Vsetmode() should be VsetMode().  In addition,  a value of -1 for
the mode parameter will return the current mode setting.

5.10 (The IKBD Controller - Kbdvbase())
The  chain of events that occurs when an IKBD event is  generated
is  incorrectly documented.  When an interrupt occurs  on  either
6850 chip (IKBD or MIDI), the following chain of events happen:

1. The  system interrupt handler installed in MFP #4  is  called.
   This routine determines which 6850 caused the interrupt.

2. If  the MIDI 6850 caused the interrupt,  midisys()  is  called
   immediately.  midisys()  checks the MIDI control register  for
   either  an error condition or a data byte.  If a data byte  is
   available,  it  is  placed in the low byte of d0 and  sent  to
   midivec(). If an error occurred, vmiderr() is called.

3. If  the Keyboard 6850 generated the  interrupt,  ikbdsys()  is
   called immediately.  The ikbdsys() handler checks for an error
   condition  or  the availability of a data byte.  If  an  error
   condition  exists,   vkbderr()  is  called.   Otherwise,   the
   ikbdsys()  handler reads data byte(s) as necessary to  form  a
   complete  'packet' depending on what generated  the  interrupt
   (joystick, mouse, or keyboard).

4. If  the  ikbdsys() handler receives a keyboard make  or  break
   code,   it  handles  the  packet  internally.  Otherwise,  the
   address  of  the packet is passed  to  statvec(),  mousevec(),
   clockvec(), or joyvec().

Handler  vectors may be altered by modifying the structure  whose
address  is  returned  by  Kbdvbase() or  by  using  Mfpint()  as
appropriate.

5.22 (Falcon030 Video Modes)
The  Falcon030  is capable of producing a wide variety  of  video
modes.  The  table represents those accessible from  the  Desktop
only.

6.5 (Applications)
The sample code contains an error. Replace the lines:

   if(_AESglobal[0] == -1)
        menu_register( ap_id, menu_title);

with:

   if(_AESglobal[1] == -1)
        menu_register( ap_id, menu_title);

6.30 (The Desktop Window)
Calling wind_get( 0,  WF_WORKXYWH,  ...) will return the size  of
the  desktop  work area minus the menu bar  (not  WF_PREVXYWH  as
stated).

6.37 (_aes)
The  _aes binding should list the arrays _addrin and _addrout  as
being of type '.ds.l', not '.ds.w'.

6.51 (appl_init())
appl_init() may return a value of -1 which indicates that the AES
failed  to initialize the application.  GEM applications may  not
make any AES or VDI calls unless appl_init() succeeds.

6.53 (appl_search())
The  type  parameter  will  be filled in with  the  value  10  to
indicate the current system shell.

6.53 (appl_tplay()/appl_trecord())
These  functions require a patch (available from Atari)  to  work
under TOS 1.0.

6.59 (evnt_button())
evnt_button( 0x101,  0x03,  0x00,  ...  ) may be used to wait for
either  the left or right mouse button.  This method  works  with
evnt_multi() as well.

6.65 (evnt_mesag() - table)
The  AC_OPEN  message contains the menu  identifier  returned  by
menu_register() in msg[4]. msg[3] is unused.

6.73 (form_alert())
Each  line of an alert may be as many as 30 characters long  (not
40 as is stated).

6.99 (menu_attach())
If you remove a menu with menu_bar(), all attachments are cleared
and must be reset upon reenabling the menu.

The MENU structure is missing a member.  It should be defined  as
follows:

   typedef struct _menu
   {
        OBJECT  *mn_tree;
        WORD    mn_menu;
        WORD    mn_item;
        WORD    mn_scroll;
        WORD    mn_keystate;
   } MENU;

mn_keystate  is unused with menu_attach() but is used  to  return
the current keyboard state in menu_popup().

6.124 (rsrc_rcfix())
rsrc_rcfix() is available as of AES version 4.0 and higher.

6.136 (shel_read())
The  last sentence of the 'Parameters' section  should  be:  "The
first BYTE of the command line indicates the length of the string
which actually begins at &tail[1]."

6.138 (shel_write() - table)
shel_write() mode 1 should have a wisgr paramater of 0 to  launch
a  TOS  application  or a wisgr parameter of 1 to  launch  a  GEM
application.

6.145 (wind_create() - table)
The  SMALLER  attribute shows the correct mask but  an  incorrect
bit. The correct bit is 14.

6.156 (wind_update())
The first sentence of page 6.156 should read:

As of AES version 4.0,  you may logically OR a mask of 0x0100  to
either BEG_UPDATE or BEG_MCTRL.

7.4 (VDI Device Identification Numbers - table)
The "MEMORY.SYS" driver should always be assigned to device #61.

7.35 (v_clswk())
v_clswk() closes a physical workstation.

7.60 (v_opnvwk())
v_opnvwk() opens a virtual workstation.

7.113 (vqt_name())
As  of  SpeedoGDOS  version 4.20,  this call will  return  the  a
modified  font index for GDOS bitmap fonts to  avoid  conflicting
with  outline font indexes.  The index will be added to 5000  for
bitmap fonts.

11.13 (Illustration)
The version of Pagestream shown is actually 2.2, not 2.1.

11.15 (The File Menu)
If  a menu item 'Recall' appears,  it should appear  between  the
'Open' command(s) and 'Save' command(s).

11.23 (Application Software)
The '_IDT' cookie does not contain any information that could  be
used  to  determine a nation's currency symbol.  Use  the  '_AKP'
cookie  if  present  (or the OSHEADER if not)  to  determine  the
country for which this version of TOS was compiled (and thus  the
correct symbol).

Applications  (like  entertainment  software)  should  place  any
data/configuration  files in a sub-directory of  the  application
folder.  Only directly reveal those files which the user may have
to launch or manipulate.

B.6 (Memory Map)
The SCC vectors are present on a Mega STe.

B.7 (System Variables)
The availability of system variables depends on the installed TOS
version,  not  the computer as might be implied by the layout  of
the table. The columns next to system variables were shaded based
upon the release of TOS which is most often associated with  that
computer as follows:

   Computer            TOS Version
   ST                  1.00 or 1.04
   Mega ST             1.02
   STe                 1.06
   Mega STe            2.0x
   TT030               3.0x
   Falcon030           4.0x

B.15 (_longframe)
This  system variable is valid on an ST as well (it  will  simply
contain 0).

B.15 (kcl_hook)
This  vector is jumped through with the keycode contained in  the
low byte of d0.

B.16 (0x00E00000)
The operating system ROM's moved to this address as of TOS 1.06.

B.16 (0x00FC0000)
This  block of memory extends to  0x00FEFFFF,  not  FF7FFFF.  The
memory  between  0x00FF0000  and 0xFF7FFF  is  reserved  for  the
operating system.

B.30 (MFP)
The MFP is present on a Falcon, however it is not used for serial
communications.

C.6 (Image Compression)
.IMG files do not always contain a vertical replication count  at
the beginning of every scanline.