Subject: Re: gs/os calls
From: [email-masked] (David Empson)
Date: Sat, 22 Oct 1994 23:31:39 GMT
Newsgroups: comp.sys.apple2.programmer

In article <[email-masked]>,
Alexander Eddy <[email-masked]> wrote:
> David Empson ([email-masked]) wrote:
> : What language are you using?  ORCA/Pascal and ORCA/C header files
> : include most of the information you need for the actual operating
> : system calls and parameter block formats.
>
> Ah, I am using Merlin 16+. There is info about the parameters passed
> for each class0/1 call, but nothing about the data formats...

OK.  In general, you should use Class 1 calls in all new programs,
unless you need the program to work with System 3.2 or earlier.

They are much more flexible.

The most important sturctures you need to know about are the Class 1
pathname formats. 

A "GS/OS Input String" is a string preceded by a length word (in the
usual low-byte-first order).  e.g. the pathname '*:System:Start' would
be stored as:

StartPath  da   StartPathEnd-StartPath-2
           asc  "*:System:Start"
StartPathEnd

(You can easily set up a macro to declare constant GS/OS class 1 input
strings, which would then look similar to the 'str' directive).

A "GS/OS Result Buffer" is the same as a GS/OS Input String, with the
addition of an extra word before the string.  This word specifies the
length of the whole buffer, including both length words.  For example,
to declare a result buffer that will fit a 255 character string, use:

Result     da   ResultEnd-Result
ResultLen  ds   2
ResultStr  ds   255
ResultEnd

The string can be any length from zero up to the size of the buffer
minus four.

When passing a result buffer to a GS/OS function, you need to
initialize the buffer length word, but the string length and contents
can contain garbage.

This type of buffer is used in calls that return strings, such as
GetDirEntryGS.  Most other calls only require an input string.

A closely related data structure is the 'option list'.  This contains
data about a file which is specific to a file system.  The same
strucutre is used for ProDOS, HFS and AppleShare - it contains the
Macintosh file information, such a the Type and Creator.

Even when passed as an input parameter, the option list is in the form
of a result buffer, i.e. buffer length word, data length word, data.

If you don't want to deal with the option list, make sure that
parameter is not included in the parameter count, or the pointer to
the option list is NULL (0).

> : Byte Works might have some.  They were out of stock when they
> : inherited the APDA products from Resource Central, and the GS/OS
> : Reference and Toolbox References are not listed in the price list in
> : the last issue of GS+.
> Okay, phone # for Byte Works? Unfortunately I am no longer subscribed
> to GS+... The easiest thing to do is just buy the GS/OS reference...

If they have it.  I'm concerned that Apple may not be printing any
more.  This has already happened with the HyperCard IIgs Script
Language Guide - Apple took back all the copies Addison-Wesley had and
shredded them!

Byte Works, Inc.
8000 Wagon Mound Drive N.W.
Albuquerque, NM 87120
U.S.A.

Phone   (505)898-8183
E-Mail  [email-masked]
-- 
David Empson
[email-masked]
Snail mail: P.O. Box 27-103, Wellington, New Zealand