Apple II
Technical Notes
_____________________________________________________________________________
                                                  Developer Technical Support


GS/OS
#13:    GS/OS Reference Update

Revised by:    Matt Deatherage & Dave Lyons                      January 1991
Written by:    Matt Deatherage                                  November 1990

This Technical Note corrects and updates the Addison-Wesley Apple IIgs GS/OS
Reference.  Previous versions from APDA labeled Volume 1 or 2 are obsolete, and
should no longer be used.
Changes since November 1990:  Renamed the note GS/OS Reference Update.  Added
information about the system level, a bug in ChangePath, the new parameter to
the Flush call and the correction to the errors for ChangePath.
_____________________________________________________________________________



Chapter 4, "Accessing GS/OS Files"

Page 72:  The System File Level:  How to Protect an Open File From the
Application

The class 1 SetLevel and GetLevel calls have a special option that allows you to
open a file at an "internal" file level, so that it cannot be closed by an
application making a Close call with reference number zero at any application
level.

GetLevel and SetLevel actually accept two parameters, not just the one parameter
(level) documented in Chapter 7.  The second parameter, level_mode, is a Word
that controls the internal range of the file level.

The steps to open a file at an internal file level are:

  1.  Call GetLevel with pCount=2, level_mode=$0000.  Save the returned level.
  2.  Call SetLevel with pCount=2, level = $0080 and level_mode = $0000.
  3.  Open a file or files with a class 0 or 1 Open call, or with
      OpenResourceFile (OpenResourceFile on System Software 5.0.4 and earlier
      does not try to protect your resource files from being accidentally closed
      by a Close(0)).
  4.  Call SetLevel with pCount=2, level_mode=$0000, and level = saved level.

To close your protected file, simply do a Close with the reference number.
There is no need to fiddle with the file level when closing by reference number.

NDAs should close all their files at or before DeskShutDown time.


Chapter 7, "GS/OS Call Reference"

Pages 98-99:  ChangePath

On page 98, the Reference states that a subdirectory may not be moved into
itself or into a directory the first subdirectory already contains.  For
example, you may not change /v to /v/w or /v/w to /v/w/x.  Although this is
correct, the System Software 5.0.x implementations of the ProDOS FST trash your
disk if you try this with ChangePath.  Do not try it on disks you want to keep.

On page 99, error $4E is described as "file not destroy-enabled."  No,
ChangePath doesn't destroy the file.  The error should read "file not
rename-enabled."

Page 142:  Flush

The Flush call, under System Software 5.0.3 and later (GS/OS version 3.3)
accepts a maximum of two parameters.  If the second parameter is present, it is
the flushType.  The flushType Word specifies the type of flush to be performed.
A flushType of $0000 is the standard flush, where all dirty blocks are written
to disk.  If flushType is $8000, however, only dirty data blocks are written to
disk.  Dirty system blocks (directories, bitmaps, etc.) are not flushed in this
fast flush.


Appendix A, "GS/OS ProDOS 16 Calls"

Page 386:  GetDirEntry buffer description incorrect

On page 386, nameBuffer is described as a pointer to a buffer in which GS/OS
returns a Pascal string containing the name of the file or directory entry (in
GetDirEntry).  This is incorrect; all versions of GetDirEntry return GS/OS
(word-length) strings for the directory entry.


Further Reference
_____________________________________________________________________________
  o     GS/OS Reference
  o     Apple IIgs Technical Note #71, DA Tips and Techniques

