Author: Matt Deatherage
Year: 1990
... 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.
Apple II
Technical Notes
_____________________________________________________________________________
Developer Technical Support
GS/OS
#13: GS/OS Reference Update
Revised by: Matt Deatherage March 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 January 1991: Added a correction to the character device
status word diagram.
_____________________________________________________________________________
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 ReferenceJstates 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
tokeep.
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 129: The Character Device Status Word
The diagram on the top of page 129 says that if bit 5 is set, the device isin
no-wait mode. This is incorrect. To determine if a device is in
no-waitmode, make the GetWaitStatus subcall described on page 130.
Bit 5 of the character device status word is set if there are one or more
characters waiting to be read from the device. This is an assistance for
developers, since generated character drivers don't support no-wait mode.
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,
itis the flushType. The flushType Word specifies the type of flush to
beperformed. A flushType of $0000 is the standard flush, where all dirty
blocks arewritten to disk. If flushType is $8000, however, only dirty data
blocks are writtento disk. Dirty system blocks (directories, bitmaps, etc.)
are not flushed inthis 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