ClearBackup
$200B

GS/OS ProDOS 8
Purpose:

To clear the backup-needed bit in the access code for the file.
Under ProDOS 8, use the SET FILE - INFO command instead.
Parameter table:

GS/OS Input
or

bet Symbolic Name Result
+0to +1 pcount I
+2to +5 pathname I

Descrtptions of parameters:

Description

Number of parameters (1)
Pointer to the pathname string

pcount The number of parameters in the GS/OS parameter table. The min-
imum value is 1; the maximum is 1.

pathname A pointer to a class 1 GS/OS string describing the current pathname
of the file to be used. If the pathname specified is not preceded by a
separator (/ or :), the operating system appends the name to the
default prefix (the 0/ prefix) to create a full pathname.

Common error codes:

$40 The pathname contains invalid characters or a full pathname was not
specified (and no default prefix has been set up). Verify that the
filenames and directory names specified in the pathname adhere to
the naming rules described in Chapter 2 and, if a partial pathname
was specified, that a default prefix has been set up.

$44 A directory in the pathname was not found. Solution: Double-check
the spelling of the pathname, insert the disk containing the correct
directory, or change the default prefix.

$45 The volume directory was not found.
$46 The file was not found.
Other possible error codes are $07, $4A, $52, $58.

Command Descriptions 97

Programming example:

A file-backup program capable of doing incremental backups acts on only those files
that have been modified since the last backup operation. The program checks the state
of a file's backup bit to determine whether it needs to be backed up; it does if the bit
is set to 1. (GS/OS and ProDOS 8 automatically set the bit after any write operation or
any operation that changes the directory entry.) Once the backup copy has been made,
the program should clear the backup bit by calling ClearBackup.
Here is the trivial piece of code for doing this:

_ClearBackup CBB_Parms
RTS

CBB_Parms ANOP
DC I2'1' The number of parameters
DC I4'Pathname' Pointer to pathname

Pathname GSString '/nISK/NEW.FILE' The file to act on

98 GS/OS and ProDOS 8 Commands

Close
$2014

GS/OS ProDOS 8
Purpose:

To close an open file. This causes the operating system to write the contents of the
data portion of the file's I/O buffer to disk (if necessary) and to update the file's
directory entry. Once it does this, the operating system releases the memory used for
the file's I/O buffer to the system and prevents fUrther access to the file (until it is
reopened).

Parameter table:

ProDOS 8 Input

or

bet Symbolic Name Result Description
+0 num~parms I Number of parameters (1)
+ 1 ref num I Reference number for the file

GS/oS Input
or

bet Symbolic Name Result Description
+ 0 to + 1 pcount I Number of parameters (1)
+ 2 to + 3 ref~ num I Reference number for the file

Descriptions of parameters:

num - parms The number of parameters in the ProDOS 8 parameter table (always 1).

pcount The number of parameters in the GS/OS parameter table. The min-
imum value is 1; the maximum is 1.

ref~ num The reference number the operating system assigned to the file

when it was first opened.

If you set refnum to 0, all open files at or above the system file
level are closed. To set the value of the file level under ProDOS 8,
store the value at lLEVEL ($BF94). Under GS/OS, use the SetLevel
command.

Command Descriptions 99

Common error codes:

$2B The disk is write-protected.

$43 The file reference number is invalid. You might be using a reference
number for a file that you've already closed.

Other possible error codes are $04, $07, $27, $5A.
Programming example:

To close all open files at or above level 1, use SetLevel to set the level and use the
Close command with ref~ num set to 0. Here's how to do it if GS/OS is active:

_SetLevel SL_Parms Set system file level to 1
_Close Cl_Parms

BCS
RTS

SL_Parms DC
DC

Cl_Parms DC

DC

Error ;Branch if error occurred
II']'

II']' New file level

II',' Parameter count

lID' reference number = 0 (close all files)

If ProDOS 8 is active, set the system file level by storing the new value at LEVEL
($BF94).

100 GS/OS and ProDOS 8 Commands

Create
$2001

GS/OS ProDOS 8
Purpose:

To create a new disk file. The operating system does this by placing an entry for the
file in the specified directory. You must create every new file, except the volume
directory file, with this command. (GS/OS automatically creates the volume directory
when you use the Format or EraseDisk command. ProDOS 8 formatting programs
create the volume directory by using the WRITE - BLOCK command to write an
image of the four volume directory blocks to disk.)
Parameter table:

ProDOS 8 Input

or

bet Symbolic Name Result
+0 num~parms I
+1 to +2 pathname I
+3 access I
+4 file-type I
+5to +6 auxtype I
+7 storagetype I
+8to +9 createdate I
+10 to +11 createtime I

GS/OS Input
or

bet Symbolic Name Result
+0to +1 pcount I
+2to +5 pathname I
+ 6 to + 7 access I
+8to +9 file-type I

Description

Number of parameters (7)
Pointer to the pathname string
Access code
File type code
Auxiliary type code
Storage type code
Creation date
Creation time

Description

Number of parameters (7)
Pointer to the pathname string
Access code
File type code

Command Descriptions 101

+ 10 to +13 auxtype I Auxiliary type code
+ 14 to + 15 storage - type I Storage type code
+ 16 to + 19 eof I Anticipated size of data fork
+ 20 to + 23 resource - eof I Anticipated size of resource fork

Descriptions of parameters:

num - parms The number of parameters in the ProDOS 8 parameter table (always 7).

pcount The number of parameters in the GS/OS parameter table. The min-
imum value is 1; the maximum is 7.

pathname A pointer to a class 0 (ProDOS 8) or class 1 (GS/OS) string describ-
ing the pathname of the file to be created. If the pathname specified
is not preceded by a separator (/ for ProDOS 8; / or: for GS/OS), the
operating system appends the name to the default prefix (in GS/OS,
this is the 0/ prefix) to create a full pathname.

access This field contains several 1-bit codes defining the access attributes
of the file to be created. (The other bits must set to zero.) See Figure
2-10 for a description of these bits. The backup-needed bit of the
access code is forced to 1 by this command.

file - type A code indicating the type of data the file holds. See Table 2-5 for a

description of the file type codes for the ProDOS file system.
aux - type This is the auxiliary type code. The meaning of the code depends on

the file type code and on the program that created the file in the first
place. For SYS, BIN, BAS, and VAR files, it is a default loading
address; for TXT files, it is a record length; for SRC files, it is an
APW language type code.

storage - type This field indicates how the operating system is to store the file on

the disk:
$00-$03 standard tree-structured data file
$05 extended file

$0D linked-list directory file

If you specifi' a code of $00, $02, or $03, ProDOS 8 or GS/OS
converts it to a code of $01 and returns that value in this field.
Note that you cannot change the storage - type of a file once it has
been created.

create - date This field contains the date (year, month, day) that ProDOS 8 will

save as the file's creation date. Figure 8-1 in Chapter 8 shows the

102 GS/OS and ProDOS 8 Commands

format of these bytes. If these bytes are both zero, the current date
will be used.

create - time This field contains the time (hour, minute) that ProDOS 8 will save

as the file's creation time. Figure 8-1 in Chapter 8 shows the format of
these bytes. If these bytes are both zero, the current time will be used.

eof If the file being created is a standard file (storage - type $01), this
field indicates the anticipated size of the file in bytes. GS/OS preal-
locates enough blocks on disk to hold a file of this size.
If the file is an extended file (storage - type = $05), this field
indicates the anticipated size of the data fork, in bytes. GS/OS
preallocates enough blocks on disk to hold a data fork of this size.
If the file is a subdirectory file (storage - type = $0D), this field indi-
cates the anticipated number of entries in the subdirectory. GS/OS
preallocates enough blocks on disk to hold a subdirectory of this size.
resource - eof If the file being created is an extended file (storage - type = $05), this

field indicates the anticipated size of the resource fork in bytes. GS/OS
preallocates enough blocks on disk to hold a resource fork of this size.
Common error codes:

$2B The disk is write-protected.

$40 The pathname contains invalid characters or a full pathname was not
specified (and no default prefix has been set up). Verify that the
filenames and directory names specified in the pathname adhere to
the naming rules described in Chapter 2 and, if a partial pathname
was specified, that a default prefix has been set up.

$44 A directory in the pathname was not found. Solution: Double-check
the spelling of the pathname, insert the disk containing the correct
directory, or change the default prefix.

$45 The volume directory was not found.

$47 The filename specified already exists. You can't have two files with
the same name in the same subdirectory.

$48 The disk is full.

$49 The volume directory is full. Only 51 files can be stored in the
volume directory.

$4B Invalid storage type code. Solution: Set the storage type code to $0D
for directory files, to $01 for standard data files, or (for GS/OS only)
to $05 for extended files.

Command Descriptions 103

Other possible error codes are $04, $07, $10, $27, $52, $53, $58.
Programming example:

Here is a short GS/OS subroutine you can use to create a standard textfile; the
filename for the textfile is JUPITER, and the full pathname is :PLANETS:JUPITER.

_Create Cr_Parms
BCS Error
RTS

Cr_Parms DC II'S'

DC I4'PathName'

;Branch if error occurred
Only using 5 parameters

DC
DC

DC II'$E3' ;standard access code (unlocked)
DC II'$04' file type = 4 (textfile)
I4'0' auxiliary type (0 = sequential)
II'$0l' ;storage type = I (standard file)

PathName GSString ':PLANETS:JUPITER' ;Pathname (in ASCII)

Note that when you create a file under GS/OS, the date and time of creation is always
set to the current date and time. (Under ProDOS 8 you can specifi' any time you want
in the parameter table for CREATE.) To set a different date and time of creation, use
the SetFileInfo command.

104 GS/OS and Pro DOS 8 Commands

DControl
$202E
GS/OS
Purpose:

To send control commands to a GS/OS device.
There is no equivalent ProDOS 8 command.
Parameter table:

GS/OS Input
or

ProDOS 8

Cllrset Symbolic Name Result
+0to +1 pcount I
+2to +3 devnum I
+4 to +5 controlcode I
+6 to +9 controlh.st I
+ 10 to +13 request-count I
+ 14 to + 17 transfer-count R

Description

Number of parameters (5)
Device reference number
Control request code
Pointer to control list
Size of the control list
Number of bytes transferred

Descriptions of parameters:

pcount The number of parameters in the GS/OS parameter table. The min-
imum value is 5; the maximum is 5.

dev - num The device's reference number.

control - code A code indicating what control operation is to be performed:

$0000 reset device
$0001 format device medium
$0002 eject device medium
$0003 set configuration parameters
$0004 set wait/no-wait mode
$0005 set format options
$0006 assign partition owner
$0007 arm signal
$0008 disarm signal
$0009 set partition map
$000A-$7FFF [reserved]

$8000-$FFFF device-specific operations

Command Descriptions 105

control - list

This is a pointer to a buffer that contains any supplementary data
that GS/OS may need to perform the control operation.

request - count The size of the control list buffer.

transfer - count The number of bytes in the control list buffer that were transferred

to the device is returned here.

Common error codes:

$11 The device reference number is invalid.
$53 The parameter is out of range.
Another possible error code is $07.
Programming example:

The only control command you're ever likely to need for a disk device is the eject
command. Here is a GS/OS subroutine for ejecting the disk medium from a drive:

_DControl DC_Parms
RTS

DC_Parms ANOP
DC II'S'
DC III'
DC II'I'

DC I4'Ctrl List'
DC I4'0'
DS 4

The number of parameters
Device number

;Control code (I = eject)

4 Nothing in control list

Ctrl _List DS

You can determine if the disk medium is removable by doing a DInfo call and
examining bit 2 of the characteristics word; if the bit is 1, the medium is removable.
You will use several device-specific control commands to communicate with the
Console Driver (see chapter 9). For a detailed discussion of the standard control
commands, see GS/OS Reference, Volume 2.

106 GS/OS and ProDOS 8 Commands

none

GS/OS ProDOS 8
Purpose:

To remove the address of an interrnpt-handling subroutine from the internal ProDOS
8 interrupt vector table.

Under GS/OS, use the UnbindInt command instead.
Parameter table:

ProDOS 8

bet Symbolic Name

+0 numparms
+1 int~num

Input
or

Result Description

Descriptions of parameters:

I Number of parameters (1)
I Interrupt handler reference number

num - parms The number of parameters in the ProDOS 8 parameter table (always 1).
int - num The identification number for the interrupt handler. ProDOS 8 assigned

this number when the handler was installed using the ALLOC -
INTERRUPT command.

Important: Do not remove an interrupt-handling subroutine until your application has
first told the source of the interrupts to stop generating interrupts. If you remove the
subroutine first, the system will crash the next time an interrupt occurs.
Common error codes:

$53 The intnum parameter is not valid. Use the number ALLOC
INTERRUPT returned when you installed the interrupt handler.

Another possible error code is $04.
Programming example:

Here's how to remove the interrupt vector table entry for an interrupt-handling
subroutine assigned the code number 1 when it was installed using the ALLOC -
INTERRUPT command:

Command Descriptions 107

JSR MLI

DFB $41 ;DEALLOC_INTERRUPT
DA PARMTBL ;Address of parameter table
BCS ERROR Branch if error occurred
RTS

PARMTBL DFB 1 ;The # of parameters
DFB 1 Interrupt code number

108 GS/OS and Pro DOS 8 Commands

Destroy

$2002 _______________________

GS/OS ProDOS 8
Purpose:

To remove a file from disk. When you destroy a file, the operating system frees up all
the disk blocks the file uses and zeros the length byte in the file's directory entry. You
can destroy any file (except a volume directory file) whose destroy-enabled access
code bit is set to 1; subdirectory files must be empty before you can destroy them,
however.

Parameter table:

ProDOS 8 Input

or

C))rset Symbolic Name Result
+0 numparms I
+1 to +2 pathname I

Description

Number of parameters (1)
Pointer to the pathname string

GS/OS Input
or

Cllrset Symbolic Name Result

+0 to + 1 pcount I
+2to +5 pathname I

Descriptions of parameters:

Description

Number of parameters (1)
Pointer to the pathname string

num - parms The number of parameters in the ProDOS 8 parameter table (always 1).
pcount The number of parameters in the GS/OS parameter table. The min-
imum value is 1; the maximum is 1.

pathname A pointer to a class 0 (ProDOS 8) or class 1 (GS/OS) string describ-
ing the pathname of the file to be destroyed. If the pathname
specified is not preceded by a separator (/ for ProDOS 8; / or : for
GS/OS), the operating system appends the name to the default prefix
(in GS/OS, this is the 0/ prefix) to create a full pathname.
If the pathname describes an extended file (storagetype = $05),
both forks are destroyed.

Command Descriptions 109

Common error codes:

$2B The disk is write-protected.

$40 The pathname contains invalid characters, or a full pathname was not
specified (and no default prefix has been set up). Verify that the
filenames and directory names specified in the pathname adhere to
the naming rnles described in Chapter 2 and, if a partial pathname
was specified, that a default prefix has been set up.

$44 A directory in the pathname was not found. Solution: Double-check
the spelling of the pathname, insert the disk containing the correct
directory, or change the default prefix.

$45 The volume directory was not found. Solution: Double-check the
spelling of the volume directory name, insert the correct disk, or
change the default prefix.

$46 The file was not found.

$4E The file cannot be accessed. Solution: Set the destroy-enabled bit of
the access code to 1 using SETFILEINFO.

$50 The file is open. You can destroy closed files only.
Other possible error codes are $04, $07, $10, $27, $4A, $4B, $52, $58.
Programming example:

Consider a situation in which the 0/prefix is /DEMOS/GAMES. To destroy a file that
has a full pathname of /DEMOS/GAMES/TRIVIA.BLITZ, you could use the follow-
ing GS/OS subroutine.

_Destroy DY_Parms

BCS Error
RTS

DY_Parms DC II']'

DC I4'PathName'

;Branch if error occurred

1 parameter

PathName GSString 'TRIVIA.BLITZ' ;Pathname (in ASCII)

Notice that it was not necessary to specify the fUll pathname in this program. GS/OS
automatically appends the name specified to the 01 prefix to create the fUll pathname
that it acts on.

The ProDOS file system does several things when it destroys a file. First, it zeros the
name - length byte in the file's directory entry. (This is the first byte in the entry.)
Then it frees up the disk blocks the file uses by setting the appropriate bits in the
volume bit map. Finally, it reads in the file's index blocks from disk, reverses the two
256-byte halves of each block (meaning the low-order block number appears in the

110 GS/OS and Pro DOS 8 Commands

upper half and the high-order block number appears in the lower half), and then
writes the blocks back to disk. (Versions of ProDOS 8 numbered 1.2 or lower actually
zeroed the index blocks, making it impossible for a utility program to recover a
deleted file.)

Note that you cannot destroy an extended file (storage ~ type = $05) with the
ProDOS 8 version of the DESTROY command. It can be destroyed only with the
GS/OS Destroy command.

Command Descriptions 111

none

GS/OS ProDOS 8
Purpose:

To determine information about a device connected to the system.
There is no equivalent ProDOS 8 command.
Parameter table:

GS/OS Input
or

Cl)'set Symbolic Name Result
+0to +1 pcount I
+2 to +3 devnum I
+4to +7 devname R
+ 8 to + 9 characteristics R
+ 10 to +13 totalblocks R
+14 to +15 slotnum R
+16 to +17 umtnum R
+ 18 to + 19 version R
+20 to +21 deviceIDnum R
+22 to +23 headh.nk R
+24 to +25 forwardhnk R

Descriptions of parameters:

Description

Number of parameters (10)
Device reference number
Pointer to the device name string
Device characteristics
Capacity of volume, in blocks
Slot number for device
Unit number for device
Device driver version number
Device ID number
First related device
Next related device

pcount The number of parameters in the GS/OS parameter table. The min-
imum value is 2; the maximum is 10.

dev - num The device's reference number.

dev - name A pointer to a class 1 output buffer in which GS/OS returns the

device name. A device name may be up to 31 characters long, so set
the buffer size word in the class 1 output buffer to 35 bytes.

characteristics The bits in this word reflect the characteristics of the device:

112 GS/OS and ProDOS 8 Commands

bit 15 1 = device is a RAMdisk or ROMdisk
bit 14 1 = device driver was generated
bit 13 [reserved]
bit II 1 = device is busy
bit]] [reserved]
bit 10 [reserved]
bit 9 device speed (high)
bit 8 device speed (low)
bit 7 1 = device is a block device
bit 6 1 = write is allowed
bit 5 1 = read is allowed
bit 4 [reserved]

bit 3 1 = format is allowed
bit I 1 = device contains removable media
bit] [reserved]
bit 0 [reserved]

Bits 9 and 8, the device speed bits, indicate the speed at which the
device can operate:

00 1 MHz device
01 1.6 MHz device
10 >1.6 MHz device
11 not speed dependent

total-blocks For a block device, the capacity of the volume in blocks. For a
character device, this field is zero.

slot - num The slot number of the firmware driver for the device.
unit - num The SmartPort unit number for the device.
version The version number of the device driver:

bits 15-II major version number
bits 11- primary minor version number
bits 7-4 secondary minor version number
bits 3-0 version type:

$0 = released final

$A = alpha
$B = beta

$E = experimental
$F = unreleased final

For example, version 2.12 beta would be represented by the version
word $212B.

device - ID - num This is a code number that identifies the device type:

$0000
$0001
$0002
$0003
$0004

5.25-inch disk drive
ProFile hard disk (5Mb)
ProFile hard disk (10Mb)
3.5-inch disk drive
generic SCSI device

Command Descriptions 113

$0005 SCSI hard disk
$0006 SCSI tape drive
$0007 SCSI CD-ROM drive
$0008 SCSI printer
$0009 serial modem
$000A console
$000B serial printer
$000C serial LaserWriter
$000D AppleTalk LaserWriter
$000E RAM Disk
$000F ROM Disk
$0010 file server
$0011 IBX telephone
$0012 Apple desktop bus device
$0013 generic hard disk drive
$0014 generic floppy disk drive
$0015 generic tape drive
$0016 generic character device
$0017 MFM-style floppy disk drive
$0018 generic AppleTalk network device
$0019 SCSI sequential access device
$001A SCSI scanner
$001B non-SCSI scanner
$001C SCSI LaserWriter
$001D AppleTalk main driver
$001E AppleTalk file service driver
$001F AppleTalk RPM driver

head - link This is a device number that is the first entry in a linked list of

device numbers. The devices in the list are related in that they each
have a distinct partition on the same disk medium. If head - link is
zero, there is no link.

forward - link This is a device number that is the next entry in a linked list of

device numbers. The devices in the list are related in that they each
have a distinct partition on the same disk medium. If forward - link
is zero, there is no link.

Common error codes:

$11 Invalid device reference number.
Another possible error code is $07.
Programming example:

You can use DInfo to determine the names of all the devices connected to the system.
To do this, make a series of calls to DInfo, incrementing dev - num by 1 after each
call, until DInfo returns an error code of $11 ("invalid device reference number"). The
first dev - num you pass to DInfo should be 1 since this is the device number GS/OS
assigns to the first device it finds when it boots up.

114 GS/OS and ProDOS 8 Commands

Keep in mind, however, that the number of active devices in the system may change
during program execution. For example, server volumes may come on line or go off
line at almost any time. As a result, if you're designing a program which has a "list
volumes" command, you should form the list each time the user requests it. It is not
good enough to form the list once at the beginning of the program.
Here is a GS/OS code fragment that shows how you might do this in an application:

LDA #1
STA DevNum

Get_Name _DInfo DI_Parms
BCS Exit

LDA DevName ;Get length word
XBA ;(Put low-order byte at
STA DevName beginning of string)
PushPtr DevName+1 (point to length byte)
_DrawString Display name in window
JSR CRLF ;(CRLF moves cursor to next line)
BRA Get_Name

Exit RTS
DI_Parms ANOP
DC II' 10' ;The number of parameters

DevNum DC II' 1' ;Device number
DC I4'DevSpace' ;Pointer to device name buffer

DevSpace DC II'35' Size of buffer

DevName

DS 33 Name stored here

Call this subroutine after positioning the cursor with the Move or - MoveTo macro.
- DrawString is the macro for a QuickDraw II tool set fUnction that displays a
Pascal-like string (one preceded by a length byte) in the current window.

Command Descriptions 115

none

GS/OS ProDOS 8
Purpose:

To perform low-level read operations on a GS/OS device.
Under ProDOS 8, use the READ BLOCK command instead.
Parameter table:

GS/OS Input
or

O[Cset Symbolic Name Result
+0to +1 pcount I
+2 to +3 devnum I
+4 to +7 buffer R
+8to +11 requestcount I
+ 12 to + 15 startingblock I
+16 to +17 blocksize I
+ 18 to +21 transfrr~count R

Descriptions of parameters:

Description

Number of parameters (6)
Device reference number
Data buffer

Number of bytes to read
First block to read from
Number of bytes per block
Number of bytes actually read

pcount The number of parameters in the GS/OS parameter table. The min-
imum value is 6; the maximum is 6.

dev - num The device's reference number.

buffer A pointer to a class 0 output buffer into which the data is to be read.
request - count The number of bytes to read.

starting - block If the device is a block device, this is the number of the block to start

reading from. For character devices, this field is not used.
block size The size of a block in bytes.

transfer - count The number of bytes actually read from the device.
Common error codes:

$11 The device reference number is invalid.
$53 Parameter out of range.

116 GS/OS and Pro DOS 8 Commands

Another possible error code is $07.
Programming example:

For block-structured devices, DRead is most often used to read the contents of data
blocks on the disk volume. Here is a GS/OS subroutine you could use to read blocks 6
and 7 on a disk volume containing 512-byte blocks:

_DRead DR_Parms
RTS

DR_Parms DC II '6' ;The number of parameters
DC II'I' ;Device number
DC I4'Buffer'

DC I4' 1024' Read 1024 bytes

DC I4'100'
DC II'512'
DS 4

Buffer DS 1024

starting with block 100

512 bytes per block
;transfer_count result

Note that after DRead reads the 512 bytes in block 100, it proceeds to the next
higher-numbered block, 101, to read the next 512 bytes.

Command Descriptions 117

none

ProDOS 8

GS/OS
Purpose:

To determine the status of a GS/OS device.
There is no equivalent ProDOS 8 command.
Parameter table:

GS/OS Input
or

bet Symbolic Name Result
+0to +1 pcount I
+2to +3 devnum I
+4to +5 statuscode I
+6to +9 statush.st R
+ 10 to + 13 requestcount I
+ 14 to + 17 transfercount R

Descriptions of parameters:

Description

Number of parameters (5)
Device reference number
Control request code
Pointer to control list
Size of the control list
Number of bytes transferred

pcount The number of parameters in the GS/OS parameter table. The min-
imum value is 5; the maximum is 5.

dev - num The device's reference number.
status - code A code indicating what status request is to be made:

$0000 get device status
$0001 get configuration parameters
$0002 get wait/no-wait status
$0003 get format options
$0004 get partition status
$0005-$7FFF [reserved]

$8000-$FFFF device-specific status calls

status list This is a pointer to a class 0 buffer that holds any status data that the

status call may return.

request - count The number of status bytes to be returned in the status list.
transfer - count The actual number of bytes returned in the status list is returned here.

118 GS/OS and ProDOS 8 Commands

error codes:

I The device reference number is invalid.
Parameter out of range.
.1 possible error code is $07.

application should rarely have to use the DStatus command unless it is commu-
with the Console Driver (see Chapter 9). For a discussion of the standard
status commands, see GS/OS Reference Volume 2.

Command Descriptions 119

none

GS/OS ProDOS 8
Purpose:

To perform low-level write operations on a GS/OS device.
Under ProDOS 8, use the WRITE - BLOCK command instead.
Parameter table:

GS/OS Input
or

O)l'set Symbolic Name Result
+0to +1 pcount I
+2 to +3 devnum I
+4to +7 buffer I
+8 to + 11 request-count I
+ 12 to + 15 startingblock I
+ 16 to +17 blocksize I
+ 18 to +21 transfercount R

Descriptions of parameters:

Description

Number of parameters (6)
Device reference number
Data buffer

Number of bytes to write
First block to write to
Number of bytes per block
Number of bytes actually written

pcount The number of parameters in the GS/OS parameter table. The min-
imum value is 6; the maximum is 6.

dev - num
buffer

The device's reference number.

A pointer to a buffer in which the data to be written is stored.

requestcount The number of bytes to write.

starting - block
block size

If the device is a block device, this is the number of the block to start
writing to. For character devices, this field is not used.
The size of a block, in bytes.

transfer count The number of bytes actually written to the device.
Common error codes:

$11 The device reference number is invalid.
$53 Parameter out of range.

120 GS/OS and ProDOS 8 Commands

Another possible error code is $07.
Comments:

This command is for low-level transfer of data to a character or block device. The file
system on the block device is not relevant.

Command Descriptions 121

none

GS/OS ProDOS 8
Purpose:

To perform all disk block write operations that have not been made because a
write-deferral session is in progress. EndSession also terminates the current write-
deferral session.

There is no equivalent ProDOS 8 command.
Parameter table:

GS/OS Input
or

Offset Symbolic Name Result
+0to +1 pcount I
Descriptions of parameters:

Description

Number of parameters (0)

pcount The number of parameters in the GS/OS parameter table. The min-
imum value is 0; the maximum is 0.

Common error codes:
[none]

Comments:

You must call EndSession if your application began a disk-deferral session by calling
BeginSession and wants to close the session.

122 GS/OS and ProDOS 8 Commands

EraseDisk
$2025

GS/OS ProDOS 8
Purpose:

To write to disk the boot record, volume bit map, and empty root directory for the
specified file system. Unlike Format, EraseDisk does not initialize the disk first, so
you can use it only with previously initialized disks.

There is no equivalent ProDOS 8 command. Under ProDOS 8, you must use
WRITE - BLOCK to perform the required disk-write operations needed to erase a
disk.

Parameter table:

GS/OS Input
or

Offset Symbolic Name Result
+0to +1 pcount I
+2to +5 devname I
+6to +9 volname I
+10 to +11 Msysid R
+12 to +13 requestedfsys I

Description

Number of parameters (4)
Pointer to the device name string
Pointer to the volume name string
ID code for selected file system
ID code for requested file system

Descriptions of parameters:

pcount The number of parameters in the GS/OS parameter table. The min-
imum value is 3; the maximum is 4.

dev - name A pointer to a class 1 device name string.
vol - name A pointer to a class 1 disk volume name string. The name must be

preceded by a slash.

file - sys - id If the requested - fsys field is zero, GS/OS displays a dialog box that

lets the user pick the file system to be used on the disk volume. On
return, the file - sys - id field indicates which file system was selected:

$01 = ProDOS/SOS
$02 = DOS 3.3
$03 = DOS 3.2/3.1
$04 = Apple II Pascal
$05 = Macintosh MFS

Command Descriptions 123

$06 = Macintosh HFS
$07 = Macintosh XL (LISA)
$08 = Apple CP/M
$09 = [never used]
$0A = MS-DOS

$0B = High Sierra (CD-ROM)
$0C = 1509660 (CD-ROM)

If GS/OS returns a zero in this field, the user canceled the operation.
requested - fsys This field contains the ID code for the file system to be written to

the disk volume. (The codes are the same as those described for
file - sys - id.) If the field is zero, GS/OS displays a dialog box that
lets the user pick his or her own file system; GS/OS returns the
selected ID in the file - sys - id field.
Common error codes:

$10 The specified device name does not exist.
$40 The volume name specified contains invalid characters or does not
start with a valid separator (1 or:).

$5D The specified file system is not supported.
Other possible error codes are $07, $11, $27.
Programming example:

Suppose you want to erase a disk whose device name is .APPLEDISK3.5A and give it
the name :BLANK. Here is the GS/OS subroutine to use:

EraseIt _EraseDisk ED_Parms
RTS

ED_Parms ANOP
DC II '4'

DC I4'DevName'
DC I4'VolName'
DS I

DC II'O'

The number of parameters
;Pointer to device name
Pointer to volume name
file_sys_id

0 = let user pick

DevName GSString '.APPLEDISK3.5A'
'i-~w~ ~c+,'.,~ '.Dl

124 GS/OS and ProDOS 8 CommandsExpandPath
$200E

GS/OS ProDOS 8
Purpose:

To convert a filename, partial pathname, or full pathname into a full pathname with
colon separators.

There is no equivalent ProDOS 8 command.
Parameter table:

GS/oS Input
or

C(rset Symbolic Name Result
+Oto +1 pcount I
+2to +5 inputpath I
+6to +9 output-path It
+10 to +11 flags I

Descriptions of parameters:

Description

Number of parameters (3)
Pathname to be expanded
Pointer to expanded pathname
Uppercase conversion flag

pcount The number of parameters in the GS/OS parameter table. The min-
imum value is 2; the maximum is 3.

input - path Pointer to a class 1 pathname string that is to be expanded.
output - path Pointer to a class 1 output buffer where GS/OS returns the expanded

pathname.

flags Bit 15 of this flag indicates whether lowercase characters are to be
converted to uppercase:

bit IS 1 = convert to uppercase characters

0 = don't convert characters

bits 14-0 must be zero
Common error codes:

$40 The pathname syntax is invalid.
$4F The class 1 output buffer is too small to hold the result.

Comments:

The input - path parameter does not have to represent an existing filename on disk.

Command Descriptions 125

FLUSH

$CD

GS/OS ProDOS 8
Purpose:

To force the operating system to write the contents of the data portion of a file's 110
buffer to disk and to update the file's directory entry. The operating system does this
without closing the file.

Parameter table:

ProDOS 8 Input

or
Cll'set Symbolic Name Result Description

+0 numparms I Number of parameters (1)
+ 1 ref num I Reference number for the file

GSIoS Input
or

bet Symbolic Name Result

+0 to + 1 pcount I
+2 to +3 refnum I

Descriptions of parameters:

Description

Number of parameters (1)
Reference number for the file

num - parms The number of parameters in the ProDOS 8 parameter table (always 1).
pcount The number of parameters in the GS/0S parameter table. The min-
imum value is 1; the maximum is 1.

ref num The reference number ProDOS 8 or GS/OS assigned to the file when

it was first opened.

If refnum is 0, all open files at or above the system file level are
flushed. To set the value of the file level under ProDOS 8, store the
value at LEVEL ($BF94). Under CSlOS, use the SetLevel command.
Common error codes:

$2B The disk is write-protected.

126 CS/OS and ProDOS 8 Commands

$43 The file reference number is invalid. You might be using a reference
number for a file that you've already closed.

Other possible error codes are $04, $07, $27, $48.
Programming example:

To flush all open ProDOS 8 files at or above file level 2, use the FLUSH command
with ref num equal to 0 and LEVEL ($BF94) equal to 2. Here's the code:

LDA #2

STA LEVEL
JSR MLI
nFB $CD

PA PARMTBL
BCS ERROR
RTS

PARMTBL BFB 1
0FB 0

Set LEVEL to 2
FLUSH

Address of parameter table
;Branch if error occurred

The # of parameters

reference number = 0 (close all files)

Command Descriptions 127

none

GS/OS ProDOS 8
Purpose:

To format a disk and write out the boot record, volume bit map, and empty root
directory for the specified disk operating system.

There is no equivalent ProDOS 8 command. Under ProDOS 8, You must use a utility
program like System Utilities to format a disk.
Parameter table:

GSlOS Input
or

bet Symbolic Name Result
+0to +1 pcount I
+2to +5 devname I
+6 to +9 volname I
+10 to +11 file~sys~id It
+ 12 to + 13 requestedfi;ys I

Descriptions of parameters:

Description

Number of parameters (4)

Pointer to the device name string
Pointer to the volume name string
ID code for selected file system
ID code for requested file system

pcount The number of parameters in the GS/OS parameter table. The min-
imum value is 3; the maximum is 4.

dev - name A pointer to a class 1 device name string.

vol - name A pointer to a class 1 disk volume name string. The name must be

preceded by a slash.

file - sys - id If the requested - fsys field is zero, GS/OS displays a dialog box that

lets the user pick the file system to be used on the disk volume. On
return, the file - sys - id field indicates which file system was selected:

$01 = ProDOS/SOS

$02 = DOS 3.3
$03 = DOS 3.2/3.1

$04 = Apple II Pascal
$05 = Macintosh MFS
$06 = Macintosh HFS
$07 = Macintosh XL (LISA)

128 GS/OS and ProDOS 8 Commands

$08 = Apple CP/M
$09 = [never used]
$0A = MS-DOS

$0B = High Sierra (CD-ROM)
$0C = 1509660 (CD-ROM)

If CS/OS returns a zero in this field, the user canceled the operation.
requested - fsys This field contains the ID code for the file system to be written to

the disk volume. (The codes are the same as those described for
file - sys - id.) If the field is zero, CS/OS displays a dialog box that
lets the user pick his or her own file system; GS/OS returns the
selected ID in the file - sys - id field.

Common error codes:

$10 The specified device name does not exist.
$40 The volume name specified contains invalid characters or does not
start with a valid separator (/ or :).

$5D The specified file system is not supported.
Other possible error codes are $07, $11, $27.
Programming example:

See the example given for the EraseDisk command. The only change to make is to
replace the ~ EraseDisk macro with the Format macro.

Command Descriptions 129

none

GS/OS ProDOS 8
Purpose:

To perform operations which are unique to a particular file system translator.
There is no equivalent ProDOS 8 command. ProDOS 8 does not use file system
translators.

Parameter table:

GS/OS Input
or

C))cset Symbolic Name Result
+0to +1 pcount I
+2 to +3 file~sysid I
+4 to +5 commandnum I
+6to +7/9 command~parm I/It

Description

Number of parameters (3)
File system ID code

FST-specific command number
Command parameter or result

Descriptions of parameters:

pcount The number of parameters in the GS/OS parameter table. The min-
imum value is 3; the maximum is 3.

file - sys - id This field indicates the file system that the FST implements:

$01 = ProDOS/SOS

$02 = DOS 3.3
$03 = DOS 3.2/3.1
$04 = Apple II Pascal
$05 = Macintosh MFS
$06 = Macintosh HFS
$07 = Macintosh XL (LISA)
$08 = Apple CP/M
$09 = Character FST
$0A = MS-DOS

$0B = High Sierra z(CD-ROM)
$0C = 1509660 (CD-ROM)

This field contains an FST-specific command code.

130 GS/0S and ProDOS 8 Commands

command - parm This can be either an Input or a Result field, depending on com-
mand - num. Its meaning depends on which FST you are communi-
cating with.

Common error codes:

$53 Invalid parameter.
Other possible error codes are $04, $54.
Comments:

This command is for performing operations unique to a particular file system. The
nature of these operations varies from one FST to another. Consult the technical
description of the FST you want to deal with for an explanation of the FSTSpecific
calls it supports.

Command Descriptions 131

none

GS/OS ProDOS 8
Purpose:

To determine the name of the disk volume from which the GS/OS operating system
was booted.

There is no equivalent ProDOS 8 command. ProDOS 8 does not keep track of the
name of the disk it was booted from.
Parameter table:

GS/OS Input
or

O(rset Symbolic Name Result
+0to +1 pcount I
+2 to +5 vol~name It

Description

Number of parameters (1)
Pointer to the volume name string

Note: The volume name CetBootVol returns is the same as the name GS/OS assigns to
the ~/ prefix when it first boots up.

Descriptions of parameters:

pcount The number of parameters in the GS/OS parameter table. The min-
imum value is 1; the maximum is 1.

vol - name A pointer to a class 1 output buffer in which CS/OS returns the disk

volume name (preceded and followed by a pathname separator). The
output buffer should be 35 bytes long.
Common error codes:
[none]

Another possible error code is $07.
Programming example:

An application never really needs to know the actual name of the GS/OS boot volume.
If it needs to define a pathname on the boot volume, it should use the */ shorthand
notation to identify the root directory.

It may be convenient, however, to display the name for information or when debug-
ging. Here is a GS/OS subroutine that shows how to use GetBootVol:
Get_Boot _GetBootVol GBV_Farms
RTS

132 CS/OS and ProDOS 8 Commands

Parms AH0P
PC I2'1' The number of parameters
PC I4'BootSpace' Pointer to output buffer

~tSpace PC I2'35'

~tName PS 33 Space for name

exit from the subroutine, the name is stored at BootName, preceded by a length word.

Command Descriptions 133

GETBUF

$D3

GS/OS ProDOS 8
Purpose:
To determine the starting address of the 1024-byte 1/0 buffer an open file uses.
There is no equivalent GS/OS command. CS/OS takes care of all buffer-management
operations internally.
Parameter table:

Pro DOS 8

bet Symbolic Name

+0 num~parms
+ 1 ref~num
+2to +3 io~bufler

Input
or

Result Description

Descriptions of parameters:

I Number of parameters (2)
I Reference number for the file
It Pointer to 1/0 buffer

num - parms The number of parameters in the ProDOS 8 parameter table (always 2).
ref~ num The reference number ProDOS 8 assigned to the file when it was

first opened.

io - buffer A pointer to the 1024-byte file buffer used by the open file. The

low-order byte of this pointer is always $00. (That is, the buffer
begins on a page boundary.)
Common error codes:

$43 The file reference number is invalid. You might be using a reference
number for a file that you've already closed.

Another possible error code is $04.
Programming example:

You can use the following program to determine the address ~f the file buffer for file 2.
After the GETS BUF command executes, the address will be stored at BUFFPTR.

JSR MLI
PFB $P3

PA PARMTBL
BCS ERROR
RTS

;GET_BUF

;Address of parameter table
Branch if error occurred

134 GS/OS and ProDOS 8 Commands

PARMTBL PFB 2 The # of parameters
PFB 2 File reference number

BUFFPTR PS 2 Buffer address is returned here

Command Descriptions 135

GetDe"Number
$2020

GS/OS ProDOS 8
Purpose:

To determine the device reference number corresponding to a specified device name
or volume name.

There is no equivalent ProDOS 8 command.
Parameter table:

GS/OS Input
or

bet Symbolic Name Result
+0to +1 pcount I
+2to +5 dev~name I

+6 to +7 dev~num It

Description

Number of parameters (2)
Pointer to device/volume name
string

Device reference number

Descriptions of parameters:

pcount The number of parameters in the GS/OS parameter table. The min-
imum value is 1; the maximum is 2.

dev - name A pointer to a class 1 device name string or the class 1 volume name

string. A volume name must be preceded by a pathname separator.

dev - nun'

The device's reference number.

Note: If dev - name points to a volume name, the dev - num GS/OS returns repre-
sents the current device reference number for the volume. The volume's dev - num
will change if the disk is removed and placed in another disk drive.

Common error codes:

$10 The specified device name does not exist.

$40 The volume name specified contains invalid characters or does not
start with a valid separator (/or :).

$45 The disk with the specified volume name can't be found, or the
name, although preceded by a separator, is otherwise invalid.
Other possible error codes are $07, $11.

136 GS/OS and ProDOS 8 Commands

Programming example:

Here is a GS/OS code fragment you can use to determine the device reference
number for a disk whose name is /APPLEWOItKS.GS:

GetPevNumber GPN_Parms
RTS

GPN_Parms AN0P
PC I2'2' The number of parameters
PC I4'VolName'

PS 2 ;Pevice ref number returned here

VolName GSString '/APPLEW0RKS.GS'

Don't forget to include a leading slash (or colon) in the volume name.

Command Descriptions 137

none

GS/OS ProDOS 8
Purpose:

To read an open directory file. GS/OS returns entries that contain informatiop about
the files in a directory.

There is no equivalent ProDOS 8 command. Under ProDOS 8, you must open the
directory file, read it into memory, and interpret the data yourself. This requires an
understanding of the structure of a directory file. See Chapter 2.
Parameter table:

GS/OS Input
or

Olfset Symbolic Name Result
+0to +1 pcount I
+2to +3 ref~num I
+4 to +5 flags It
+6to +7 base I
+8to +9 displacement I
+ 10 to +13 namebufler I
+ 14 to + 15 entry~num It
+16 to +17 file-type It
+18 to +21 eof It
+22 to +25 block-count It
+26 to +33 create~td It
+34 to +41 modify~td It
+42 to +43 access It
+44 to +47 auxtype It
+48 to +49 file~sys~id It
+50 to +53 option-list It
+54 to +57 res~eof It
+58 to +61 res~block~count It

Description

Number of parameters (17)
Reference number for the file
Extended file flag

Base code
Displacement code
Pointer to name buffer
Absolute directory entry number
File type code
Size of the file

Number of blocks file uses

Time and date of creation
Time and date of modification
Access code

Auxiliary type code
Operating system ID code
Pointer to option list
Size of the resource fork
Number of blocks resource fork uses

138 GS/OS and ProDOS 8 CommandsDescriptions of parameters:

pcount The number of parameters in the GS/OS parameter table. The min-
imum value is 5; the maximum is 15.

ref~ num The reference number GS/OS assigned to the directory file when it

was first opened.

Bags Bit 15 of this word indicates whether the file represented by the current
directory entry is an extended file (bit 15 = 1) or not (bit 15 = 0).

base This code tells GS/OS how to calculate the number of the next
directory entry to read. If base = 0, displacement is an absolute
directory entry; if base = 1, GS/OS adds displacement to the current
entry number to get the next entry number; if base = 2, GS/OS
subtracts displacement from the current entry number to get the
next entry number. Note that GS/OS sets the current entry number
to 0 when it first opens a file and updates it each time the application
calls GetDirEntry.

If base = 0, this represents the absolute number of the directory
entry to be returned. Otherwise, it represents the displacement to
the next directory entry to be returned, which can be positive or
negative, depending on the value of base.

Note that if base and displacement are both zero, GS/OS returns in
the entry - num field the total number of active entries in the subdi-
rectory. It also sets the current entry number to the first entry in the
subdirectory.

To step through the directory one entry at a time, set both base and
displacement to 1 and keep calling GetDirEntry until error $61 (end
of directory) occurs.

bufler A pointer to a class 1 output buffer in which GS/OS stores the
filename it finds in the directory entry. For volumes formatted for
the ProDOS file system, the buffer size should be 19 bytes (15 for
the name bytes, 2 for the length word, and 2 for the buffer size
word). Since GetDirEntry could also be used to read directories of
foreign operating systems that use longer filenames (such as Macin-
tosh HFS or CD-ItOM High Sierra), you might want to make the
buffer even larger.

If the output buffer you provide is too small, GetDirEntry returns as
much of the name as will fit in the buffer, but returns the actual length.

- num The absolute directory entry number of the current entry.
file - type A code indicating the type of data the file holds. See Table 2-5 for a

description of the ProDOS file type codes.

Command Descriptions 139

eof A value that holds the current EOF position. This value is equal to
the size of the file (in bytes). If the file is an extended file, this field
relates to the data lork of the file only.

block - count This field contains the total number of blocks used by the file for data

storage and index blocks. If the file is an extended file, this field
relates to the data fork of the file only.

create - td The time and date of creation. These 8 bytes represent the following

parameters in the following order:

seconds
minutes

hour in 24-hour military format
year year minus 1900
day day of month minus 1
month 0 = January, 1 = February, and so on
[not used]

weekday 1 = Sunday, 2 = Monday, and so on

Note: This format is the same as the one used by the ReadTimeHex
function in the IIcs's Miscellaneous Tool Set but is different from
the one used in a standard file entry for the ProDOS file system.

modify - td The time and date of last modification. The ordering of these 8 bytes

is the same as for create - time.

access This field contains several 1-bit codes defining the access attributes
of the file. See Figure 2-10 for a description of these bits.

aux - type This is the auxiliary type code. The meaning of the code depends on

the file type code and on the program that created the file in the first
place. For SYS, BIN, BAS, and VAIt files, it is a default loading
address; for TXT files, it is a record length; for SItC files, it is an
APW language type code.

file - sys - id The file system identification code. The currently defined values are

$00 = [reserved]

$01 = ProDOS/SOS
$02 = DOS 3.3
$03 = DOS 3.2/3.1
$04 = Apple II Pascal
$05 = Macintosh MFS
$06 = Macintosh HFS
$07 = Macintosh XL (LISA)
$08 = Apple CP/M
$09 = [reserved]
$0A = MS-DOS

140 GS/OS and ProDOS 8 Commands

$0B = High Sierra (CD-ROM)
$0C = 1509660 (CD-ItOM)

All other values are reserved.

n - list A pointer to a class 1 output buffer where GS/OS returns file infor-
mation unique to the file system translator used to access the file.
- eof A value that holds the current EOF position of the resource fork of

an extended file. This value is equal to the size of the resource fork of
the file (in bytes).

block-count This field contains the total number of blocks used by the resource
fork of an extended file for data storage and for index blocks.
error codes:

The name buffer is too small to hold the filename.
End of directory. When you receive this error, close the subdirectory
file you opened before calling GetDirEntry.

possible error codes are $07, $27, $43, $4A, $41a, $52, $53, $58.

example:

is a GS/OS subroutine that displays the names of all the files in a given

by repeatedly calling GetDirEntry. On entry to the subroutine, the
'pointer to the subdirectory pathname must be in the A (high word) and X
word) registers.
- START
STX Name_Ptr Set up pointer to pathname
STA Name_Ptr+2

Open Open_Prms Open the subdirectory file
LPA ref num
STA ref_num1
STA ref_num2

Pir _GetPirEntry GPE_Parms
BCS Exit

LPA NameBuff+2
XBA

STA NameBuff+2

PushPtr NameBuff+3
_PrawString

JSR CRLF

Put length in high byte
so it's just before the
filename

Point to length byte
;Pisplay filename

Move to start of next line

Command Descriptions 141

BRA Read Pir

Exit _Close Close_Prms Close subdirectory file
RTS

Open_Prms ANOP
PC 12'2' The number of parameters

ref_num PS 2 ;Reference number
Name_Ptr PS 4 ;Pointer to subdir pathname

Close_Prms ANOP
PC 12' 1'

ref num1 PS 2

GPE Parms ANOP

PC 12'S'

ref_num2 PS 2 ;reference number
PS 2 ;flags
PC 12' 1' Base = "increment"
PC 12' 1' ;displacement = +1
PC 14' NameBuff' Pointer to name buffer

NameBuff PC 12' 19' ;Buffer size
PS 2 ;Length
PS 15 ;Filename

ENP

Notice that the values for base and displacement are both set to 1 in the GetDirEntry
parameter table so that all active entries in the directory will be returned as Get-
DirEntry is called again and again. The read loop ends when GetDirEntry returns an
error. (This will normally be error code $61 - "end of directory.")
Also notice the trickery used to set up a standard Pascal-type string for - DrawString
to act on. Pascal strings are preceded by a single length byte, but the length in the
GetDirEntry name buffer occupies 2 bytes. The low-order length byte is stored at
Name - Buff+ 3 to set up the Pascal-type string. The subroutine assumes that the file
name will not exceed 255 characters.

142 CS/OS and ProDOS 8 Commands

GetEOF
$2019

GS/OS ProDOS 8
Purpose:

To determine the value of the current end-of-file pointer (EOF) of an open file. This
value represents the size of the file.

Parameter table:

Pro DOS 8 Input

or

O(rset Symbolic Name Result Description

+ 0 num - parms I Number of parameters (2)
+ 1 ref~num I Reference number for the file
+ 2 to + 4 eof It The end-of-file position

GS/OS Input
or

bet Symbolic Name Result Description

+ 0 to + 1 pcount I Number of parameters (2)
+ 2 to + 3 ref~ num I Reference number for the file
+ 4 to + 7 eof It The end-of-file position

Descriptions of parameters:

num - parms The number of parameters in the ProDOS 8 parameter table (always 2).

pcount The number of parameters in the GS/OS parameter table. The min-
imum value is 2; the maximum is 2.

ref~num The reference number ProDOS 8 or GS/OS assigned to the file when
it was first opened.

eof A value that holds the current EOF position. This value is equal to
the size of the file (in bytes).

Command Descriptions 143

Common error codes:

$43 The file reference number is invalid. You might be using a reference
number for a file that you've already closed.

Other possible error codes are $04, $07.
Programming example:

Use the GetEOF command to quickly determine how big an open file is. For example,
after you call this GS/OS subroutine, the size of open file #1 is stored at Position
(low-order bytes first):
GetEOF GE Parms

BCS Error
RTS

GE_Parms PC 12'2'
PC I2'1'

Position PS 4

;Branch if error occurred
The # of parameters
File reference number
;Current EOF position

144 GS/OS and ProDOS 8 Commands

GS/OS

retrieve the information stored in a file's directory entry. This includes the access

file type code, auxiliary type code, storage type code, the number of blocks the
uses, and the date and time the file was created and last modified.

table:

Input
or

Symbolic Name Result
num~parms I

to +2 pathname I

access It
file-type It

to +6 aux~type It

storage-type It

to +9 blocks-used It
to +11 modify-date It
to +13 modifytime It
to +15 createdate It
to +17 create-time It

Description

Number of parameters (10)
Pointer to the pathname string
Access code
File type code
Auxiliary type codea
Storage type code
Blocks used by the filea
Modification date
Modification time
Creation date
Creation time

pathname points to the name of a volume directory rather than the name of a standard file, the
size (in hlocks) is returned in the aux - type field, and the uumher of hlocks currently in use hy all
the volume is returned in the blocks - used field.

Command Descriptions 145

GS/OS Input
or

-set Symbolic Name Result Description
+0 to + 1 pcount I Number of parameters (12)
+ 2 to + 5 pathname I Pointer to the pathname string
+ 6 to + 7 access It Access code
+8to +9 filetype It File type code
+ 10 to + 13 auxtype It Auxiliary type code
+ 14 to + 15 storage - type It Storage type code
+ 16 to + 23 create - td It Creation time and date
+ 24 to + 31 modify - td It Modification time and date
+ 32 to + 35 option - list It Pointer to option list
+36 to +39 eof It Size of the file
+40 to +43 blocksused It Blocks used by the file
+ 44 to + 47 resource - eof It Size of resource fork
+ 48 to + 51 resource blocks It Blocks used by resource fork

Descriptions of parameters:
num - parms The number of parameters in the ProDOS 8 parameter table (always

10).

pcount The number of parameters in the GS/OS parameter table. The min-
imum value is 1; the maximum is 12.

pathname A pointer to a class 0 (ProDOS 8) or class 1 (GS/OS) string describ-
ing the pathname of the file to be used. If the pathname specified is
not preceded by a separator (/for ProDOS 8; / or : for GS/OS), the
operating system appends the name to the default prefix (in GS/OS,
this is the 0/ prefix) to create a full pathname.

access This field contains several 1-bit codes that define the access at-
tributes of the file. See Figure 2-10 for a description of these bits.

file-type This code indicates the type of data the file holds. See Table 2-5 for
a description of the ProDOS file type codes.

aux - type This is the auxiliary type code. The meaning of the code depends on

the file type code and on the program that created the file in the first

146 GS/OS and ProDOS 8 Commands

place. For 5Y5, BIN, BAS, and VAR files, it is a default loading
address; for TXT files, it is a record length; for SRC files, it is an
APW language type code.

Exception: Under ProDOS 8, if the pathuame is a volume direc-
tory name, aux - type holds the volume size (in blocks).
storage - type This code describes the physical organization of the file on the

disk:

$01 = seedling file
$02 = sapling file
$03 = tree file

$04 = Pascal region on a partitioned disk
$05 = extended file

$0D = directory file (linked list)
$0F = volume directory file (linked list)

block5 - used This field contains the total number of blocks used by the file for

data storage and index blocks. (Use GetEOF to determine the
number of bytes in a file.) If the file is an extended file, this is the
number of blocks used by the data fork only. This field is unde-
fined for a GS/OS subdirectory file.

Exception: Under ProDOS 8, if the pathname field points to a
volume directory name, blocks - used contains the number of
blocks in use on the disk by all files.

modify - date This field contains the date (year, month, day) the file was last

modified. Figure 8-1 in Chapter 8 shows the format of these
bytes.

modify - time This field contains the time (hour, minute) the file was last modi-
fied. Figure 8-1 in Chapter 8 shows the format of these bytes.

ereate~date This field contains the date (year, month, day) the file was created.
Figure 8-1 in Chapter 8 shows the format of these bytes.
create - time This field contains the time (hour, minute) the file was created.

Figure 8-1 in Chapter 8 shows the format of these bytes.

create - td The time and date of creation. These eight bytes represent the

following parameters in the following order:

seconds
minutes

hour in 24-hour military format
year year minus 1900
day day of month minus 1
month 0 = January, 1 = February, and so on
[not used]

weekday 1 = Sunday, 2 = Monday, and so on

Command Descriptions 147

Note: This format is the same as the one used by the ReadTimeHex
function in the IIcs's Miscellaneous Tool Set, but is different from
the one used in a standard directory entry for the ProDOS file
system.

modify~td The time and date of last modification. The ordering of these eight
bytes is the same as for create - td.

option - list A pointer to a class 1 output buffer where GS/OS returns file infor-
mation unique to the file system translator used to access the file.

eof The size of the file in bytes. If the file is an extended file, this is the size
of the data fork only. This field has no meaning for a subdirectory file.
resource - eof If the file is an extended file, this is the size of the resource fork.
resource-blocks If the file is an extended file, this is the number of blocks the
resource fork uses on disk.

Common error codes:

$40 The pathname contains invalid characters, or a full pathname was not
specified (and no default prefix has been set up). Verify that the
filenames and directory names specified in the pathname adhere to
the naming rules described in Chapter 2 and, if a partial pathname
was specified, that a default prefix has been set up.

$44 A directory in the pathname was not found. Solution: Double-check
the spelling of the pathname, insert the disk containing the correct
directory, or change the default prefix.

$45 The volume directory was not found. Solution: Double-check the
spelling of the volume directory name, insert the correct disk, or
change the default prefix.

$46 The file was not found.

Other possible error codes are $04, $07, $27, $4A, $4B, $52, $53, $58.
Programming example:

See the example given for the SetFileInfo command.

148 GS/OS and ProDOS 8 Commands

GetFSTInfo
$202B

GS/OS

ProDOS 8

Purpose:

To get general information about the characteristics of a GS/OS file system translator.
There is no equivalent ProDOS 8 command.

Parameter table:

GS/OS Input
or

Olfset Symbolic Name Result
+0 to + 1 pcount I
+2 to +3 FST~num I
+4 to +5 M~sys~id It
+6 to +9 FST~name It
+10 to +11 version It
+ 12 to + 13 attributes It
+ 14 to + 15 block-size It
+16 to +19 max~volsize It
+20 to +23 max~filesize It

Descriptions of parameters:

Description

Number of parameters (8)
FST reference number
File system ID
Pointer to FST name
FST version number
FST attributes
FST block size
FST volume size
FST file size

pcount The number of parameters in the GS/OS parameter table. The min-
imum value is 1; the maximum is 8.

FST - num The FST reference number. GS/OS assigns consecutive reference

numbers, beginning with 1, to the FSTs it finds in the system.
file - sys - id The identification code for the file system that the FST supports:

$01 = ProDOS/SOS
$02 = DOS 3.3
$03 = DOS 3.2/3.1
$04 = Apple II Pascal
$05 = Macintosh MFS
$06 = Macintosh HFS
$07 = Macintosh XL (LISA)

Command Descriptions 149

$08 Apple CP/M
$09 = Character FST
$0A = MS-DOS

$0B = High Sierra (CD-ROM)
$0C = 1509660 (CD-ROM)

FST~name A pointer to class 1 output buffer where GS/OS returns the name of
the file system translator.

version The version number of the file system translator:

bit 15 1 = prototype version

0 = final version

bits 14-8 major version number
bits 7-0 minor version number

attributes The attributes of the file system translator:

bit IS 1 = FST wants filenames in uppercase
bit 14 1 = character FST; 0 = block FST
bit 12 1 = FST wants the characters in

filenames to have the high-order
bit clear

block-size The size (in bytes) of the blocks the FST handles.
max~vol~size The maximum size (in blocks) of the disk volumes the FST handles.
max - file - size The maximum size (in bytes) of the files the FST handles.
Common error codes:

$53 Parameter out of range. GS/OS returns this error if the FST refer-
ence number does not exist.

Another possible error code is $07.
Comments:

GS/OS provides no simple way to determine how many FSTs are active. To get
information on all FSTs, keep calling GetFSTInfo with successively higher FST -
num values (beginning at 1) until GS/OS returns an error code of $53.

150 CS/OS and ProDOS 8 CommandsGetLevel
$201B

GS/OS ProDOS 8
Purpose:

To determine the value of the system file level.

z There is no equivalent ProDOS 8 command. The system file level is stored at LEVEL
($BF94) in the ProDOS 8 system global page.
Parameter table:

GS/OS Input
or

O)(ket Symbolic Name Result
+0to +1 pcount I
+2 to +3 level It

Descriptions of parameters:

Description

Number of parameters (1)
The system file level

pcount The number of parameters in the GS/OS parameter table. The min-
imum value is 1; the maximum is 1.

level The value of the system file level. The values that can be returned
range from $0000 to $00FF.
Common error codes:
[none]

Another possible error code is $07.
Programming example:

Here is a GS/OS subroutine for returning the system file level number:

_Get Level GL_Parms
RTS

GL_Parms ANOP
PC 12' 1' The number of parameters

theLevel PS 2 ;System file level returned here

Command Descriptions 151

GetMark GET-MARK
$2017 $CF
GS/OS ProDOS 8
Purpose:

To determine the value of the current position-in-file pointer (Mark) of an open file.
Subsequent read or write operations take place at this position.
Parameter table:

ProDOS 8 Input

or

bet Symbolic Name Result Description

+ 0 num - parms I Number of parameters (2)
+ 1 ref~num I Reference number for the file
+ 2 to + 4 position It The current Mark position

GS/OS Input
or

bet Symbolic Name Result

+0to +1 pcount I
+2to +3 ref~num I
+4to +7 position It

Descriptions of parameters:

Description

Number of parameters (2)
Reference number for the file
The current Mark position

num - parms The number of parameters in the ProDOS 8 parameter table (always 2).
pcount The number of parameters in the GS/OS parameter table. The min-
imum value is 2; the maximum is 2.

ref num The reference number ProDOS 8 or GS/OS assigned to the file when

it was first opened.

position The current Mark position in bytes.
Common error codes:

$43 The file reference number is invalid. You might be using a reference
number for a file that you've already closed.

152 GS/OS and ProDOS 8 Commands

Other possible error codes are $04, $07.
Programming example:

Here is a ProDOS 8 subroutine that reads and displays the current Mark position of
an open file:

JSR MLI
PFB $CF

PA PARMTBL
BCS ERROR

LPA POSITION+2

JSR PRBYTE Print high part (PRBYTE=$FPPA)
LPA POSITION+1

JSR PRBYTE Print mid part
LPA POSITION

JSR PRBYTE ;Print low part
LPA #$8P

JSR COUT ;Followed by CR (COUT=$FPEP)
RTS

PARMTBL PFB 2 ;The # of parameters

;GET_MARK

Address of parameter table
Branch if error occurred

~ITION

PFB 1 ;File reference number
PS 3 ;Current Mark position

The system Monitor subroutine called PRBYTE ($FDDA) prints the byte in the
~umulator as two hexadecimal digits.

Command Descriptions 153

none

GS/OS ProDOS 8
Purpose:

To determine the name of the application currently running.
There is no equivalent ProDOS 8 command. Under ProDOS 8, you can deduce the
name by examining the pathname or partial pathname stored at $280 when the
application starts up.
Parameter table:

GS/OS Input
or

O(rset Symbolic Name Result
+0to +1 pcount I
+2to +5 data~bufler It

Descriptions of parameters:

Description

Number of parameters (1)

Pointer to application name string

pcount The number of parameters in the GS/OS parameter table. The min-
imum value is 1; the maximum is 1.

data - buffer A pointer to a class 1 output buffer where the name of the curren

application is to be returned. The name is an ASCII string preceded
by a length word. The output buffer should be 35 bytes long to
accommodate the longest filename you might encounter. (Macintosh
filenames can be up to 31 characters long.)
Common error codes:
[none]

Other possible error codes are $07, $4F.
Programming example:

A running application sometimes needs to be able to determine what its name is. It
would need to know this, for example, if it had to transfer a copy of itself to a RAM disk
when it was started up. The application shouldn't assume a specific name because the
user may have renamed the application.
Here is how to determine the name of the application:

GetName GN_Parms
RTS

154 GS/OS and ProDOS 8 Commands

GM_Parms ANOP
PC II' 1' The number of parameters
PC 14' NameSpace' Pointer to class I buffer

NameSpace PC I2'35' Size of buffer

TheName PS

33 ,Space for class I name string

GetName returns the filename only, preceded by a length word. The subdirectory it
resides in is given by the 1/ prefix, provided the application, or a desk accessory,
hasn't changed it since the application was launched. Use GetPrefix to determine the
specific value of this prefix.

Command Descriptions 155

GetPrefix
$200A
GS/OS
Purpose:

GET-PREFIX

$C7

ProDOS 8

To determine the name of the default prefix (ProDOS 8) or any of the 32 GS/OS
prefixes (0/ through 31/).
Parameter table:

ProDOS 8 Input

or

bet Symbolic Name Result
+0 num~parms 1
+1to +2 prefix R

Description

Number of parameters (1)
Pointer to prefix name string

GS/OS Input
or

bet Symbolic Name Result

+0to +1 pcount I
+2to +3 prefix~num I
+4to +7 prefix R

Description

Number of parameters (2)
Prefix number (0 to 31)

Pointer to prefix name string

Note: The GS/OS GetPrefix command uses the colon as a separator character in the
prefix strings which it returns. In addition, if the prefix name used with SetPrefix
contained lowercase characters, GetPrefix does not convert them to uppercase (but the
ProDOS 8 GETS PREFIX command does).

Descriptions of parameters:

num - parms The number of parameters in the ProDOS 8 parameter table (always 1).

prefix A pointer to a class 0 (ProDOS 8) or class 1 (GS/OS) output buffer in
which the operating system returns the prefix name. The name is in
ASCII and is preceded and followed by a pathname separator char-
acter (/for ProDOS 8; / or : for GS/OS).

For ProDOS 8, the buffer must be 67 bytes long to accommodate the
longest possible prefix that might be active (64 characters) plus the
preceding length byte and the two separator characters.

156 GS/OS and Pro DOS 8 Commands

For GS/OS, a pathname can be up to 8K in size, but it is rare to
encounter any longer than 67 characters. You should set the class 1
buffer length word to 69 when you call GetPrefix; if the buffer isn't
big enough, GS/OS returns error code $4F, and you can call the
command again using the length word returned after the buffer size
length word.

pcount The number of parameters in the GS/OS parameter table. The min-
imum value is 2; the maximum is 2.

prefix - num

The GS/OS prefix number (0 to 31). This is a binary number, not an
ASCII number string followed by a slash.

Common error codes:

$56 The pathname buffer address is invalid because it has been marked
as in use in the ProDOS 8 system bit map. Specify a buffer address
that does not conflict with areas already used by ProDOS 8 or its file
buffers. Examine the system bit map to determine the free and
protected areas.

Other possible error codes are $04, $07, $4F, $53.
Programming example:

This GS/OS subroutine gets the 7/ prefix and stores it in the buffer beginning at
PathName (preceded by a length word):

_GetPrefix GP_Parms

BCS Error Branch if error occurred
RTS

GP Parms PC I2'2'

PC I2'7' Get prefix 71
PC I4'PathBuff'

PathBuff PC 12'69' Size of buffer
PathNamePS 67

Note that if a 7/prefix has not yet been set up (with SetPrefix), the prefix length word
returned by GetPrefix will be zero.

Command Descriptions 157

none

GS/OS ProDOS 8
Purpose:

To determine the state of the system preferences status word.
There is no equivalent ProDOS 8 command.
Parameter table:

GS/OS Input
or

O(rset Symbolic Name Result
+0to +1 pcount I
+2 to +3 preferences I

Descriptions of parameters:

Description

Number of parameters (1)
System preferences

pcount The number of parameters in the GS/OS parameter table. The min-
imum value is 1; the maximum is 1.

preferences The system preferences status word:

bit IS I = display mount volume dialog

0 = don't display the dialog

Common error codes:
[none]

Comments:

GS/OS commands that have pathnames as input parameters normally display a mount
volume dialog box (to ask the user to insert a specified disk volume) if the commands
can t find the volume they are expecting. If the application wants to handle "volume
not found" errors itself it can use SetSysPrefs to clear bit 15 of the preferences word.

158 GS/OS and ProDOS 8 Commands

none

GS/OS ProDOS 8
Purpose:

To read the date and time from the system clock into the ProDOS 8 system global
page at DATE ($BF90-$BF91) and TIME ($BF92-$BF93).
There is no equivalent GS/OS command. Use the ReadAsciiTime and ReadTimeHex
functions in the IIcs's Miscellaneous Tool Set instead. Sec Chapter 8.
Parameter table:

[no parameter table, but the caller must point to a dummy table]
Common error codes:
[none]

Programming example:

When you use this command, the current date (year, month, day) and time (hour,
minute) are stored in a reserved area of the ProDOS 8 system global page from $BF90
to $BF93. The date is stored in the DATE locations ($BF90 and $BF91), and the time
is stored in the TIME locations ($BF92 and $BF93) in the special packed format
described in Figure 8-1 of Chapter 8.

Note, however, that GET-TIME returns the time only if a ProDOS-compatible
clock, like the built-in II&s clock, Thunderware Thunderclock, Prometheus Versacard,
or Applied Engineering Timemaster H.O., is installed. When ProDOS 8 first starts up,
it installs a special clock driver for reading these types of cards. (We see how to install
custom clock drivers in Chapter 8.)

The subroutine to use to read the current date and time is very simple since no
parameter table is required and no errors can occur. Here it is:

JSR MLI

PFB $82 GET_TIME

PA $0000 Dummy parameter table
RTS

Notice the use of a dummy parameter table pointer of $0000.

Command Descriptions 159

none

GS/OS ProDOS 8
Purpose:

To return the GS/OS version number.

There is no equivalent ProDOS 8 command. Under ProDOS 8, the minor release
number is stored at $BFFF in the ProDOS 8 system global page. The major release
number is always 1.
Parameter table:

GS/OS Input
or

bet Symbolic Name Result
+0 to +1 pcount I
+2 to +3 version R

Descriptions of parameters:

Description

Number of parameters (1)
GS/OS version number

pcount The number of parameters in the GS/OS parameter table. The min-
imum value is 1; the maximum is 1.

version The version of the GS/OS operating system currently in use. The
low-order byte contains the minor release number, and the high-
order byte contains the major release number. (This means, for
example, that version 2.1 would be represented by $0201.) Bit 7 of
the high-order byte is 1 if the release is a prototype (beta) version.

Common error codes:
[none]

Another possible error code is $07.
Programming example:

Here is a subroutine that will print out the GS/OS version number in ASCII in the
current desktop window:

Show_Vers START

GetVersion GV_Parms
LPA Version

RHA

Get version word

;(Save two copies on stack)

160 GS/OS and ProDOS 8 Commands

PHA
XBA

AND #$OO7F
ORA ,'$0O30
PHA

_DrawChar
PushWord ,'$2E
_PrawChar
PLA

AND ,'$OOFF
ORA #$0030
PHA
_PrawChar

PLA
BPL Exit

PushWord ,i'$7O
_PrawChar

Exit RTS
GV_Parms ANOP
DC II' I'

Version PS 2
END

Swap high/low

Isolate major version
Convert to ASCII

Period

Get version word back
Isolate minor version
;Convert to ASCII

;Get version word back
;Branch if prototype bit not I

;'p' for prototype

The number of parameters
;Version word returned here

This subroutine works only if the major and minor version numbers are less than 10.

Command Descriptions 161

NEWLINE

$C9

GS/OS ProDOS 8
Purpose:

To enable or disable newline read mode. When you enable newline read mode,
subsequent read operations automatically terminate once the specified character (the
newline character) has been read. When you disable newline read mode, read opera-
tions terminate when the end-of-file position is reached or the requested number of
characters has been read.

Parameter table:
ProDOS 8

bet Symbolic Name

+0 numparms
+1 ref~num
+2 enable-mask
+3 neMne~char

Input
or

Result Description

I Number of parameters (3)
I Reference number for the file
I Newline enable mask
I Newline character

GS/OS

Input
or

bet Symbolic Name

+ 0 to + 1 pcount
+2 to +3 ref~num
+4 to +5 enaM~mask
+6to +7 num~chars
+8to +11 newline~table

Result Description

Descriptions of parameters:

I Number of parameters (4)
I Reference number for the file
I Newline enable mask
I Number of characters in table
I Pointer to newline character table

num~parms The number of parameters in the ProDOS 8 parameter table (always 3).
ref~ num The reference number ProDOS 8 or GS/OS assigned to the file when

it was first opened.

162 CS/OS and ProDOS 8 Commandsenable - mask This value is logically ANDed with each byte subsequently read from

the file. If the result of the AND operation is the same as newline - char
(or, for CS/OS, any of the characters in newline - table), the read
request terminates; otherwise, the read continues normally.
Exception: If enable - mask is zero, newline read mode is disabled, and
read operations are not affected.

newline - char The value of the newline character. Read requests automatically

terminate if the logical AND of enable - mask and the character
being read equals newline - char.

pcount The number of parameters in the GS/OS parameter table. The min-
imum value is 3; the maximum is 3.

num - chars The number of characters in the newline character table. If enable -

mask is not zero num_chars cannot be zero.

newlinetable A pointer to a table of active GS/OS newline characters. Each character
occupies one byte in the table and the table can be up to 256 bytes long.
Common error codes:

$43 The file reference number is invalid. You might be using a reference
number for a file that you've already closed.

Other possible error codes are $04, $07.
Programming example:

A common situation is one where you want to read one line at a time from a textfile.
Since each line in a standard ProDOS textfile is terminated by $0D, the ASCII code
for the carriage return character, you could simply set enable - mask equal to $~F and
the newline character to $0D before executing the Newline command. But some
applications may use the negative ASCII code for the carriage return character ($8D)
for an end-of-line character. If you want to terminate a read operation for either $0D
or $8D, use a newline character of $0D and set the enable - mask to $7F.
Here is a GS/OS subroutine that sets the $0D/$8D newline read mode for you:

NewLine NL_Parms
BCS Error
RTL

PARMTBL DC 12 '4' ;4 parameters
DC I2'1' File reference number (#1 assumed)
DC I2'$7F' enable_mask

DC 12' 1' Number of newline characters

NL_Table

DC 14'NL_Table' Pointer to table
DC I1'$OD' Carriage return

Command Descriptions 163

none

GS/OS ProDOS 8
Purpose:

To execute pending events in the GS/OS signal queue and the Schedulers task queue.
There is no equivalent ProDOS 8 command.
Parameter table:

GS/oS

bet Symbolic Name

+ 0 to + 1 pcount

Input
or

Result Description

Meanings of parameters:

I Number of parameters (0)

pcount The number of parameters in the GS/OS parameter table. The min-
imum value is 0; the maximum is 0.

Common error codes:
[none]

Comments:

As explained in Chapter 6, some interrupt handlers place events in the GS/OS signal
queue to ensure that they are dealt with when the system isn't busy. They can also
place tasks into the Scheduler tool set's task queue if they wish.
The events in the signal and task queues are normally processed when a GS/OS
command ends or, if no GS/OS commands are being used, every sixtieth of a second,
in response to a task triggered by a vertical blanking interrupt.
If your application isn't making CS/OS commands for extended periods, and inter-
rupts are disabled, it should call the Null command periodically so that signal queue
and task queue events may be processed.

164 GS/OS and ProDOS 8 Commands

none

GS/OS ProDOS 8
Purpose:

To determine the volume directory name of a specific disk or the names of all active
ProDOS 8 volumes.

Under CS/OS, use the Volume command instead.
Parameter table:

ProDOS 8 Input

or

O(fret Symbolic Name Result Description

+ 0 num - parms I Number of parameters (2)
+ 1 umtnum I Unit number
+2 to +3 data~bufier 1 Pointer to data buffer

Descriptions of parameters:

num - parms The number of parameters in the ProDOS 8 parameter table (always 2).
unit - num The slot and drive number for the disk drive to be accessed. The

format of this byte is as follows:

ProDOS 8 assigns a drive number of1 or 2 to each drive in the system.
DR 0 for drive 1, and DR = 1 for drive 2. SLOT is usually the actual
slot number for the disk controller card (1-7 decimal; 001-111 binary)
but may be the number of a phantom, or logical, slot.
The unit - num value for the ~M volume is $B0, meaning it is the
logical slot 3, drive 2 device.
Exception: If unit - num is 0, the volume names of all drives are re-
turned.

data - buffer A pointer to a buffer containing the volume name information for the

specified drive. If unit - num is 0, the volume names of all drives are
returned. Each volume name entry is 16 bytes long.
The first byte of each 16-byte record contains the drive and slot
number for the disk volume and the length of its volume name in the
following format:

Command Descriptions 165

7 6 $ 4 3 2 1 0
DR SLOT [name length]

DR and SLOT are defined in the same way as unitnum. Name
length contains the length of the volume name for the device defined
by DR and SLOT. (If name length is zero, an error occurred; in
this case, the error code is stored in the next byte. If the error code is
$57 ("duplicate volume"), the third byte of the record contains the
unit - num for the duplicate.)

The next 15 bytes of the record contain the volume name (in stan-
dard ASCII). This name is not preceded by a slash (I).
If unit - num is 0, the record after the last valid 16-byte record
begins with a $00 byte. You must reserve a 256-byte buffer area if
you call ONLINE with umtnum set toO.
Common error codes:

$27 The disk is unreadable probably because a portion of the disk me-
dium is permanently damaged. This error also occurs if the drive
door on a 5.25-inch drive is open or no disk is in the drive.

$28 No device connected. ProDOS 8 returns this error if you do not have
a second 5.25-inch drive connected to the drive controller, but you
try to access it.

$2E A disk with an open file was removed from its drive before executing
the command. Solution: Close all files on the disk to be removed
before executing the ON - LINE command.

$2F Device not on line. ProDOS 8 returns this error if no disk is in a
3.5-inch drive.

$52 The disk in the drive specified by unit - num is not a ProDOS-
formatted disk. Solution: Use only ProDOS-formatted disks with
ProDOS 8!

$56 The pathname buffer address is invalid because it has been marked
as in use in the ProDOS 8 system bit map. Specily a buffer address
that does not conflict with areas already used by ProDOS 8 or its file
buffers. Examine the system bit map to determine the free and
protected areas.

Other possible error codes are $04, $55.

ON - LINE handles error conditions quite differently from how the other MLI
commands do. Generally, if an error occurs, name length is set to 0, and the error code
is stored in the second byte of the corresponding 16-byte record. ""he error code is not
stored in the accumulator, and the carry flag is not set. Errors are handled in the

166 GS/OS and ProDOS 8 Commands

way, however, when errors $55 ("Volume Control Block full"), $56 ("buffer
- invalid"), and $04 ("incorrect number of parameters") occur.

amming example:

ProDOS 8 program reads the volume directory name of a disk that is in the slot
drive 2 disk device.
JSR MLI

DFB $CS ;ONL1NE

DA PARMTBL Address of parameter table
BCS ERROR Branch if error occurred
RTS

z DFB 2
DFB $EO
0A BUFFER

OFFER DS 1
DS 15

The # of parameters is stored here
unit_num = slot 6, drive 2
Pointer to 16-byte buffer

Slot/drive (bits 4-7) and length
of volume name (bits 0-3)
Volume name (in ASCII)

If the volume directory name was ASM.FILES, the byte stored at BUFFER would be
1E9, and the bytes stored beginning at BUFFER + 1 would be

41 $3 40 2E 46 49 4C 45 $3

These are the ASCII codes for the characters in ASM.FILES.

Command Descriptions 167

OPEN

$C8

GS/OS ProDOS 8
Purpose:

To prepare a file for subsequent read and write operations. When you open a file, the
position-in-file pointer (Mark) points to the start of the file (that is, Mark = 0), and its
file level is set equal to the system file level. Under GS/OS open also returns all the
file's directory attributes.
Parameter table:

Pro DOS 8 Input

or

bet Symbolic Name Result
+0 numparms 1
+1 to +2 pathname I
+3to +4 iobufier R
+5 refnum R

Description

Number of parameters (3)
Pointer to the pathname string
Pointer to 1/0 buffer
Reference number for the file

GS/OS Input
or

O(rset Symbolic Name Result

+0to +1 pcount I
+2 to +3 refnum R
+4to +7 pathname I
+8to +9 requestaccess I
+ 10 to +11 resource~num I
+12 to +13 access R
+14 to +15 filetype R
+16 to +19 aux~type R
+20 to +21 storagetype R

Description

Number of parameters (15)
Reference number for the file
Pointer to the pathname string
Access permissions requested
Fork designator

Access code
File type code
Auxiliary type code
Storage type code

168 65/05 and ProDOS 8 Commands

+22 to +29 createtd R Creation time and date
+ 30 to + 37 modif' - td R Modification time and date
+ 38 to + 41 option - list R Pointer to option list
+42 to +45 eof R Size of the file
+46 to +49 blocksused R Blocks used by the file
+ 50 to + 53 resource - eof R Size of resource fork

+ 54 to + 57 resource - blocks R

Blocks used by resource fork

Important: You can usually open a closed file only. But, if a file is open, and its
write-enabled access code bit is not set (that is, you aren't allowed to write to it), it
may be opened more than once simultaneously.
Descriptions of parameters:

num parms The number of parameters in the ProDOS 8 parameter table (always 3).
pathname A pointer to a class 0 (ProDOS 8) or class 1 (65/05) string describ-
ing the pathname of the file to be used. If the pathname specified is
not preceded by a separator (/for ProDOS 8; / or : for 65/05), the
operating system appends the name to the default prefix (in 65/05,
this is the 0/ prefix) to create a full pathname.

io - buffer A pointer to a 1024-byte file buffer that the open file can use. The

low-order byte of this pointer must be $00. (That is, the buffer must
begin on a page boundary.)

The first half of the file buffer for a standard file contains a copy of
the current file data block being accessed; the second half contains
the current file index block. Only the first half of the buffer is used
for a directory file; it contains the current directory file block.

z ref_num The reference number ProDOS 8 or 65/05 assigns to the file. All file

operations on open files use this reference number (instead of a path-
name) to identi~ the file. The file level is set to the value of the system
file level. (For ProDOS 8, this value is stored at $BF94. For 65/05, use
GetLevel and SetLevel to read and set the system file level.)

pcount The number of parameters in the 65/05 parameter table. The min-
imum value is 2; the maximum is 15. If the file is for a character
device, the maximum value is only 3.

request - access This word describes the requested access permission:

bit 1 1 = request write access
bit 0 1 = request read access
bit 0 == request ~~8 ~CC~~~

Command Descriptions 169

You cannot request write access for files on a CD-ROM drive.
If this word is $0000, the access granted is the same as allowed

resource - num

the access - code word.

If the file is an extended file, this word tells 65/05 which fork
open:

$0000 open data fork
$0001 open resource fork

Note: The rest of the parameters in the 65/05 parameter list are the same as
returned by the GetFileInfo command.

Common error codes:

$40 The pathname contains invalid characters, or a full pathname was
specified (and no default prefix has been set up). Verify that
filenames and directory names specified in the pathname adhere
the naming rules described in Chapter 2 and, if a partial
was specified, that a default prefix has been set up.

$42 An attempt was made to open a ninth file. ProDOS 8 allows only
eight open files.

$44 A directory in the pathname was not found. Solution: Double-check
the spelling of the pathname, insert the disk containing the correct
directory, or change the default prefix.

$45 The volume directory was not found. Solution: Double-check the
spelling of the volutne directory name, insert the correct disk, or
change the default prefix.

$46 The file was not found.

$50 The file is open. You can open only files that are closed unless the
file is not write-enabled.

$56 The pathname buffer address is invalid because it has been marked
as in use in the ProDOS 8 system bit map. Speciiy a buffer address
that does not conflict with areas already used by ProDOS 8 or its file
buffers. Examine the system bit map to determine the free and
protected areas.

Other possible error codes are $04, $07, $27, $4A, $4B, $52.
Programming example:

The following 65/05 subroutine opens a file called SESAME that resides in the
subdirectory identified by 0/:

170 65/05 and ProDOS 8 Commands

_Open OP_Parms

BCS Error ;Branch if error occurred
RTS

OP_Parms DC 12 '2' Only need 2 parameters
05 2 ;ref_num returned here
DC 14' PathName' Pointer to pathname

PathName GSString 'SESAME' ;Filename

GS/OS returns an error code of $46 if the file you try to open does not yet exist.
Once you open a file, you should take the reference number Open returns and store it
in the parameter tables of other GS/OS commands which you might use to access the
file while it is open.

Command Descriptions 171

GS/OS ProDOS 8
Purpose:

To shut down GS/OS prior to a cold reboot or power down operation.
There is no equivalent ProDOS 8 command.
Parameter table:

CS/OS Input
or

O(rset Symbolic Name Result
+0 to + 1 pcount I
+2to +5 shutdown-flag I

Description

Number of parameters (1)
Pointer to next pathname

Descriptions of parameters:

pcount The number of parameters in the GS/OS parameter table. The min-
imum value is 1; the maximum is 1.

shutdown - flag The two low-order bits in this flag control the mechanics of the

shutdown operation:

bit 0 : 1 = GS/OS shuts down and system is rebooted

0 = 65/05 shuts down and the user is asked

to either reboot or power down

bit 1 1 = RAM disk is left intact upon reboot

0 = RAM disk is initialized upon reboot

Common error codes:
[none]

Comments:

When GS/OS shuts down it writes to disk any blocks in the disk cache, closes all new

z desk accessories, shuts down the Desk Manager, then disposes of all device drivers
and file system translators. The OSShutdown command should be used by program
selectors like the Finder, not applications.

172 GS/OS and ProDOS 8 Commands

Quit
$2029

GS/OS
Purpose:

To terminate the current application. Under ProDOS 8, control passes to the ProDOS
8 selector program or, if GS/OS was the boot operating system, to a system program
(ProDOS 8 or GS/OS) the application specifies. (The standard selector program asks
the user to enter the prefix and pathname of the next ProDOS 8 system program to run.)
Under GS/OS, the application can pass control to another system program (ProDOS 8 or
GS/OS) or return control to the application that called it (typically the Finder).
Parameter table:

ProDOS 8 Input

or

bet Symbolic Name Result Description

+ 0 num - parms I Number of parameters (4)
+1 qmttype I Quit type code
+ 2 to + 3 pathname I Pointer to next pathname

+ 4 [reserved] I
+5 to +6 [reserved] I

CS/OS Input
or

Oll'set Symbolic Name Result

+0to +1 pcount I
+2 to +5 pathname I
+6to +7 flags I

Descriptions of parameters:

Reserved area
Reserved area

Description

Number of parameters (2)
Pointer to next pathname
Return/Restart flags

numparms The number of parameters in the ProDOS 8 parameter table (always 4).
quit - type The ProDOS 8 quit type code. The only quit types currently defined

are $00 (standard quit) and $EE (quit to system program). Type $EE
may be used only if the system was first booted up under GS/OS.

Command Descriptions 173

pathname A pointer to the class 0 (ProDOS 8) or class 1 (GS/OS) pathname of
the next system program to run. The file type code of the program
must be $FF (ProDOS 8 system) or $B3 (GS/OS system). Note: The
pathname cannot reside in page 2 of memory since the QUIT com-
mand handler uses this area. For ProDOS 8, this field must be zero if
quittype is $00.

pcount The number of parameters in the GS/OS parameter table. The min-
imum value is 0; the maximum is 2.

flags The Quit option flags; only bits 15 and 14 are significant. If bit 15 is
1, the program's UserID is to be placed on the Quit Return Stack so
that the program can be restarted later. If bit 14 is 1, the program is
capable of being restarted from memory.

Note: The reserved areas in the ProDOS 8 parameter table must be zeroed before
calling the QUIT command.
Common error codes:

$46 The file with the specified pathname was not found.
$5C The file with the specified pathname is not an executable program.
The pathname must be a ProDOS 8 system program (file type $FF)
or a GS/OS system program (file type $B3).

$5D The specified pathname represents a ProDOS 8 system program, but
the P8 system file (which contains the ProDOS 8 operating system)
is not present in the SYSTEM/ subdirectory of the GS/OS boot disk.

$5F The Quit Return Stack has overflowed. This stack can hold only 16
entries.

Other possible error codes are $04, $07, $40, $5E.
Programming example:

All well-designed system programs use QUIT to exit so that control can pass to
another system program. Here is the usual calling sequence from a ProDOS 8

application:

JSR ML1
DFB $6$

DA PARMTBL
BCS ERROR
RTS

PARMTBL DFB 4
DFB 0

QUIT

;Address of parameter table
Branch if error occurred

The number of parameters
Quit type code

174 GS/OS and Pro DOS 8 Commands

DA $0000
DFB 0

DA $0000

When you execute a QUIT command with a quit type of $00, ProDOS 8 moVes the
code residing at $D100-$D3FF in the second 4K bank of bank-switched RAM (called
the selector code or dispatcher code) to location $1000 in main memory and then
executes a JMP $1000 instruction.

When the standard ProDOS 8 selector (the one defined inside the PRODOS file)
takes over, it performs the iollowing steps:

z It asks you to enter the prefix and name of the next system program to be
executed.

z It stores the length of the name of the system program at $280, followed by the
ASCII-encoded name itself.

z It closes all open files.

z It clears the ProDOS 8 system bit map and marks as in use zero page, the stack
(page 1), the video RAM area (pages 4-7), and the ProDOS 8 global page (page
$BF).

z It enables the 4O-column screen and connects the standard input (keyboard) and
output (video) subroutines. (You can do this in your own selector program by
executing the following group of instructions:

LDA $C082 Read-enable monitor ROM
STA $C000 ;Turn off 8OSTORE
STA $CO0E ;Turn off alternate char. set
STA $COOC Turn off 80 columns
JSR SETNORM ;$FE84: normal-video characters
JSR INIT ;$FB2F: full-screen text mode
JSR SETKBD ;$FE89: connect keyboard
JSR SETVID ;$FE93: connect 40-column video

The writes to the $C000, $C00E, and $C00C soft switches don't do anything on
an Apple II Plus but are required for a lIe, tIc, or tIcs to ensure the system
switches to standard 4O-column mode. Note that the Monitor ROM must be
read-enabled before calling the SETNORM, INIT, SETKBD, and SETVID sub-
routines because it will have been disabled when the selector first takes over.)

z It loads the specified system program at $2000 and starts executing it by jumping
to that location.

You can also install your own ProDOS 8 selector code if you wish. If you do, it must
:~ with a CLD instruction and it must perform the steps indicated above.
4-5 shows an alternative selector program that follows the above steps. To
the new selector at $D100 (bank2), BRUN the program file from disk. This
is not interactive since it always passes control to the same system program:

Command Descriptions 175

Table 4-5 A ProDOs 8 selector program

2 ******~~~*~~~~~~~~~~~~~~~~~~~~~~~~~~~~

3
4
$
6
7
8
9

10
11
12
13
14
1$
16
17
18
19
20
21
22

23 _
24
2$
26
27
28
29

30 11STORE80 EQU
31 COL8O0FF EQU
32 XALTCHAR EQU
33

SSPACE EQU

INIT EQU
HOME EQU
SETNORM EQU
SETKBD EQU
SETVID EQU
0RG

$C0O0 ;Enable normal page2 switching
$COOC ;Turn off 80-column hardware
$CO0E Disable MouseText characters

$0100 Selector space (in bank2)
$FB2F Set full-screen text mode
$FC$8 Clear the screen
$FE84 Set normal video
$FE89 ;Connect keyboard driver
$FE93 ;Connect video driver

$2000

* Store selector code at $0100 in bank2 of
* bank-switched RAM:

LDA $CO81

LDA $C081 ;Write-enable bank2 BSR

176 GS/OS and Pro DOS 8 Commands

Table 4-5 Continued

2006: A2 00 $0 LDX
2008: BD 1$ 20 $1 MOVEC0DE LDA
20OB: 9D 00 01 $2 STA
200E: E8 $3 INX
200F: DO F7 $4 BNE

2011: AD 82 CO $6 LDA

$7

2014:60 $8 RTS
$9

60 SELECTOR EQU

#0

SELECTOR,X Move the new code
SSPACE,X to its proper place

M0VEC0DE

$C082 Write-protect BSR

61

62 * Here is the actual selector code:
63

64 ORG $1000
6$

1000: 08 66 CLD (Required by ProDOS)

67

68 Get into plain vanilla 40-column mode:
69

1001: AD 82 CO 70 LDA $CO82 Read-enable monitor ROM

71

1004: 8D 0C CO 72 STA COL8O0FF 40-column screen
1007: 80 OE CO 73 STA XALTCHAR No MouseText
100A: 80 00 CO 74 STA XSTORE80 Normal page2 switching

7$

1000: 20 84 FE 76 JSR SETNORM ;Normal video
1010: 20 2F FB 77 JSR INIT Full text window
1013: 20 93 FE 78 JSR SETVID Standard video output
1016: 20 89 FE 79 JSR SETKB0 Standard keyboard input
1019: 20 $8 FC 80 JSR HOME Clear the screen

81
101C: 20 00 BF 82 JSR MLI

z 101F: C6 83 0F8 $C6 Set a null prefix
1020: BE 10 84 0A PFX_PRMS

8$

1022: 20 00 BF 86 JSR MLI

z 102$: C$ 87 DFB $C$ ;ONLINE for the boot volume
1026: 9A 10 88 0A 0L PARMS
1028: B0 38 89 BCS ERROR

90

102A: AD 9E 10 91 L0A NAMELEN Get returned length
1020: 29 OF 92 AND #$0F Strip slot, drive bits
102F: F0 31 93 BEQ ERROR If zero, then error

1031: 80 9E 10 94 STA NAMELEN

9$

96 Put prefix at $281:
97

1034: A9 2F 98 LDA

Store length

;Start prefix with slash
Command Descriptions 177

Table 4-5 Continued

1036: 8D 81 02 99 STA PATHNAME+1

100

1039: A2 00 101 LDX #0
103B: BD 9F 10 102 PUTNAME LDA V0L_NAME,X
103E: 9D 82 02 103 STA PATHNAME*2,X
1041: E8 104 INX
1042: EC 9E 10 10$ CPX NAME_LEN
104$: DO F4 106 BNE PUTNAME

107

1047: A9 2F 108 LDA #'/ ;End prefix with slash
1049: 9D 82 02 109 STA PATHNAME+2,X
104C: E8 110 INX

111

112 * ... and then tack on the BASIC.SYSTEM filename:
113

1O4D: AO 00 114 LDY #0
104F: B9 C3 10 11$ PUTSYS LDA SYS_NAME,Y
10$2: FO 07 116 BEQ SAVELEN ;Done if zero
1O$4: 90 82 02 117 STA PATHNAME+2,X
10$7: E8 118 INX
1O$8: C8 119 INY

10$9: DO F4 120 BNE PUTSYS (Al ways taken)

121

10$B: E8 122 SAVELEN INX ;Add 1 for initial slash
1O$C: 8E 80 02 123 STX PATHNAME Store length before pathname

124

10$F: 4C 6$ 10 12$ JMP RUN_SYS

126

1062: 4C 62 10 127 ERROR JMP ERROR

128

106$: 20 00 BF 129 RUN_SYS JSR MLI

1068: C8 130 DFB $C8 Open system file
1069: AE 10 131 DA OP_PARMS
106B: BO F$ 132 BCS ERROR

133

1060: AD B3 10 134 LDA REFNUM

1070: 80 B$ 10 13$ STA REFNUM1 Store ref # in READ table

136

1073: 20 00 BF 137 JSR MLI

1076: CA 138 DFB $CA ;Read system file
1077: B4 10 139 0A RD_PARMS
1079: BO E7 140 BCS ERROR

141

107B: 20 00 BF 142 JSR MLI

1O7E: CC 143 DFB $CC ;Close system file
107F: BC 10 144 0A CL_PARMS
1081: BO OF 14$ BCS ERROR

146

147 Initialize the system bit map:

178 GS/OS and ProDOS 8 CommandsTable 4-5 Continued

148

1083: A9 CF 149 LDA #$CF ;Pages 0,1,4. .7 in use
108$: 8D $8 BF 1$0 STA BITMAP

1$1

1088: A9 00 1$2 LDA #0
108A: A2 16 1$3 LDX #22
108C: 9D $8 BF 1$4 INITMAP STA BITMAP,X ;Pages 8. .$BE free
1O8F: CA 1$$ DEX
1090: DO FA 1$6 BNE INITMAP

1$7

1092: A9 01 1$8 LDA #1 Page $BF in use
1094: 8D 6F BF 1$9 STA BITMAP+23

160

1097: 4C 00 20 161 JMP

162

SYS_LOAD Execute system file

164

109A: 02 16$ OL_PARMS DFB 2

109B: 60 166 DFB SLOT*16 ;Boot slot 16

163 0NLINE parameter table:

1O9C: 9E 10 167 DA

168

1O9E: 00 169 NAME_LEN DS
1O9F: 00 00 00 170 VOL_NAME DS
1OA2: 00 00 00 00 00 00 00 00
10AA: 00 00 00 00

171
172
173

10AE: 03 174 _
lOAF: 80 02 17$
10B1: 00 11 176
10B3: 00 177

178
179
180

10B4: 04 181 _
1OB$: 00 182
1OB6: 00 20 183
10B8: FF FF 184
1OBA: 00 00 18$

186
187
188

10BC: 01 189 _
10BD: 00 190

191

10BE: 01 192 _
10BF: C1 10 193

194

NAME_LEN Pointer to len+name

_ 1 ;Length (bits 0. .3)
_ 1$ Volume name

* OPEN parameter table:
OP_PARMS DFB 3

DA PATHNAME
DA FILEBUFF
DS 1

REFNUM

* READ parameter table:
RD_PARMS DFB 4
REFNUM1 DS 1
DA SYS_LOAD
OW $FFFF
OW $0000

CLOSE parameter table:
CL_PARMS DFB 1
DFB 0

PFX_PRMS DFB 1
0A PFXNAME

;Pointer to pathname
File reference number

Start of load buffer
;(Enough for entire file)

;All files

Command Descriptions 179

Table 4-5 Continued

10C1: 01 19$ PFX_NAME DFB 1
10C2: 2F 196 ASC '/'

197

10C3: 42 41 $3 198 SYS_NAME ASC 'BASIC.SYSTEM' ;Name of system program

10C6: 49 43 2E $3 $9 $3 $4 4$
10CE: 40

10CF: 00 199 DFB

0 ,... followed by zero

BAStC.SYSTEM in the volume directory of the slot 6, drive 1 disk device. However,
this is the program that many users of ProDOS 8 will always want to select after
leaving other system programs. From BAStC.SYSTEM, you can use the - (dash)
command to execute any other system program.

In certain situations, your selector code may be permitted to pass the name of a file to the
system program it selects so that the system program can work with it when it first starts
up. For example, you can pass the name of an Applesofi program to BAStC.SYSTEM, and
BAS1C.SYSTEM will run it as soon as its starts up. (If the selector does not pass a name,
BAStC.SYSTEM runs the STARTUP program.) For the system program to accept a
filename, it must adhere to a special anto-rvn protocol that we look at in Chapter 5.
If you are using a ttcs and you ran the ProDOS 8 application after booting GS/OS,
you can take advantage of quit - type $EE to pass control from a ProDOS 8 applica-
tion directly to a ProDOS 8 or GS/OS system program without going through the
selector code. All you have to do is place a pointer to the program's pathname in the
QUIT parameter list. These programs have file type codes of $FF (SYS) and $B3
(516), respectively. GS/OS was the bootup operating system if value at location
$E100BD is $01.

CS/OS considerations:

Under GS/OS, an application can use the Quit command to either pass control to a
specific system program (ProDOS 8 or GS/OS) or return control to the system
program whose UserID is on the top of a Quit Return Stack. (GS/OS assigns a unique
UserID to a system program when it starts up the program.)

The Quit Return Stack is where an application places its UserID if it wishes to regain
control the next time an application quits without speciiying the pathname of the next
application to run. The availability of a Quit Return Stack makes it easy for a
supervisory program to execute subsidiary programs so that control always eventually
returns to the original program. tn fact, the tIcs Launcher or Finder always pushes its
UserID on the Quit Return Stack before launching an application. If it did not, you
would not return to it when an application ended.

180 GS/OS and ProDOS 8 Commands

If the pathname pointer is 0, and the Quit Return Stack is not empty, GS/OS pulls a
UserID from the Quit Return Stack and executes the program with that ID. If the
Quit Return Stack is empty, GS/OS executes the program launched when the system
was booted.

Only the two high-order bits of the flags parameter are significant. If bit 15 is 1,
GS/OS places the current application's UserID on the Quit Return Stack before
passing control to the application described by the pathname pointer. This means
eontrol eventually will return to the current application as later programs quit with a
0 pathname parameter. If bit 15 is 0, nothing is placed on the Quit Return Stack.
If bit 14 of the flags is 1, the calling program is capable of being restarted without
being reloaded from disk. (Programs that initialize all their data areas when they start
up should be restartable.) If control returns to the calling program, the program will
not be loaded from disk unless it has been purged from memory by the tIcs Memory
Manager.

Command Descriptions 181

READ

$CA

GS/OS ProDOS 8
Purpose:

To read bytes of data from an open file beginning at the current Mark position. After
the read operation, the operating system increases Mark by the number of bytes read
from the file. The read operation ends when the specified number of bytes have been
transferred, when a newline character is encountered, or when the end of the file has
been reached.

Parameter table:

ProDOS 8 Input

or

O]fret Symbolic Name Result Description

+ 0 num - parms I Number of parameters (4)

+ 1 ref num I
+2 to +3 data~bufler I
+4to +5 request-count I
+6to +7 transfercount R

Reference number for file

Pointer to start of data buffer
Number of bytes to read
Number of bytes actually read

GS/OS
O(fret

+ 0 to + 1
+ 2 to + 3
+4 to +7
+8to +11
+ 12 to + 15
+ 16 to + 17

Input
or

Symbolic Name Result

pcount I
refnum I
databufler I
request count I
transfer count R
cache priority I

182 GS/OS and ProDOS 8 Commands'

Description

Number of parameters (5)
Reference number for file
Pointer to start of data buffer
Number of bytes to read

Number of bytes actually read
Block caching priority level

Descriptions of parameter5;

num - parms The number ofparameter5 in the ProDOS 8 parameter table (always 4).
ref_num The reference number ProDOS 8 or GS/OS assigned to the file when
it was first opened.

data - buffer A pointer to the beginning of a block of memory into which file data is

to be read. The size of the buffer must be request - count characters.
request - count The number of characters to be read from the file and placed in the

buffer pointed to by data buffer.

transler count The number of characters actually read from the file. It usually equals

request - count, but it will be less if the operating system reaches the
end of the file or if newline read mode is active and a newline character
is read. See the discussion of the NewLine command.

pcount The number of paramete~5 in the GS/OS parameter table. The min-
imum value is 4; the maximum is 5 (or 4 if the file is a character file).
cache priority This code indicates how GS/OS is to handle the caching of disk

blocks related to the read operations

$0000 do not cache blocks
$Oooj cache blocks

This field is not used for character devices.
Common error codes:

$43 The file reference number is invalid. You might be using a reference
number for a file that you've already closed.

$4C The end-of-file position has been reached. Solution: Stop reading
from the file. Note that ProDOS 8 or GS/OS flags this error only if
no bytes were read from the file. (That is, transier count is 0.)

$4E The file cannot be accessed. Solution: Set the read-enabled bit of the
file's access code to 1 using SET FILE - INFO.

$56 The pathname buffer address is invalid because it has been marked
as in use in the ProDOS 8 system bit map. Specily a buffer address
that does not conflict with areas already used by ProDOS 8 or its file
buffers. Examine the system bit map to determine the free and
protected areas.

Other possible error codes are $04, $07, $27.

Programming example:

The following GS/OS subroutine reads up to $1000 bytes from open file #1 into the
block of memory beginning at Buffer. As usual, the reading operation begins at the
current Mark position in the file. By making repeated calls to the program, further
$1O00-byte blocks of the file can be read.

Command Description5 183

Read RDParns

BCS Error Branch if error occurred
RT5

RDParms DC 12 '4' ;Parameter count
DC 12']' ;File reference number
DC 14' Buffer' ;Pointer to data buffer
DC 14' $1000' ;Number of bytes to read

TransCnt 05 4 ;# of bytes actually read

Buffer 05 $1000 ;Data buffer

After every call to this subroutine, you must examine the 4-byte number at TransCnt
to determine how many bytes were actually read. This number may be less than $1000
if GS/OS reaches the end-of-file position part way through the reading operation or il
it encounters a newline character. (See the discussion of the NewLine command for
information on newline characters.)

If the Read command returns error code $4C ("end of file"), no bytes were read, and
you can close the file.

184 GS/OS and Pro DOS 8 Commands

none
GS/OS

Purpose:

To transfer one block (512 bytes) of information from an Apple-formatted disk device
to a buffer in memory.

Under GS/OS, use the DRead command instead.
Parameter table:

ProDOS 8 Input

or

Ol'set Symbolic Name Result Description

+0 num - parms I Number of parameters (3)
+1 unitnum I Unit number

+2 to + 3 data - buffer R
+4to +5 blocknum I

Pointer to the data input buffer
Number of block to be read from

Warning: Do not use READ - BLOCK if you want your application to work with an
AppleShare file server volume over AppleTalk.

Descriptions of parameters:

numparms The number of parameters in the ProDOS 8 parameter table (always 3).

unit - num

databufler

The slot and drive number for the disk drive to be accessed. The
format of this byte is as follows:

ProDOS 8 assigns a drive number of 1 or 2 to each drive in the
system. DR = 0 for drive 1, and DR = 1 for drive 2. SLOT is
usually the actual slot number for the disk controller card (1-7
decimal; 001-111 binary) but may be the number of a phantom, or
logical, slot.

The unit - num value for the /RAM volume is $B0, meaning it is the
logical slot 3, drive 2 device.

A pointer to the beginning of a 512-byte block of memory that is to
hold the contents of the specified block when READ - BLOCK
successfully completes.

Command Descriptions 185

block - num The number of the block to be read. The permitted values for

block - num depend on the disk device:

z 0-279 for 5.25-inch drives
z 0-1599 for 3.5-inch drives
z 0-127 for the ProDOS 8 /RAM volume

You can determine the volume size for a device using the GET -
FILE - INFO command and specifying the name of the volume
directory for the disk in the device. The size (in blocks) is returned at
relative positions $5 and $6 in the parameter table.

Common error codes:

$27 The disk is unreadable, probably because a portion of the disk
medium is permanently damaged. This error also occurs if the drive
door on a 5.25-inch drive is open or no disk is in the drive.

$28 No device connected. This error comes back if you do not have a
second 5.25-inch drive connected to the drive controller, but you try
to access it.

Other possible error codes are $04, $07, $11, $2F, $53, $56.
Programming example:

READBLOCK is one of two low-level disk-access commands ProDOS 8 provides.
(WRITE - BLOCK is the other.) Use it to read any block on a ProDOS-formatted disk,
whether it be a file data block, index block, directory block, or a boot record block.
You can also use READ - BLOCK to read any sector on a DOS 3.3-formatted disk.
See Appendix II for suggestions on how to do this.

Here's a short ProDOS 8 program that reads into memory the volume bit map block
(block 6) on a 5.25-inch disk in slot 6, drive 1 and then calculates the number of free
blocks on the disk:

JSR MLI
DFB $80

DA PARMTBL
BCS ERROR

LDA #0

STA COUNTER
STA COUNTER+1

LDY #34

NEXTBYTE LDA BLKBUFF,v
LDX #8

TESTBIT LSR
BCC NEXTBIT

;READ_BLOCK

;Address of parameter table
Branch if error occurred

Zero the counter

;Bit map bytes from 0 to 34
Get next bit in volume bit map

8 bits to test

Put next bit into carry
;Branch if block not free

186 GS/OS and ProDOS 8 Commands

INC COUNTER

BNE NEXTBIT ;Branch if not past 2$$
INC COUNTER+1 ... else bump high part

flEXTBIT DEX ;Decrement bit counter
BNE TESTBIT Branch if not done

DEY

BPL NEXTBYTE
RTS

PARMTBL DFB 3
DFB $60

DA BLKBUFF
DW 6

BLKBUFF DS $12
COUNTER DS 2

;Move to next byte
;Branch if not done

;The # of parameters

;unit number code (slot 6, drive 1)
;Pointer to $12-byte buffer
Block number for volume bit map

;This is the block buffer

of free blocks stored here

Recall from Chapter 2 that the first 280 bits (35 bytes) in the volume bit map act as

usage flags for the 280 blocks on a standard disk. If the bit is 1, the block is not in use;
if it is 0, it is. This program simply scans through these 35 bytes and counts the
number of 1 bits. The 2-byte result is stored in COUNTER and COUNTER + 1.

Command Descriptions 187

RENAME

$C2

GS/OS ProDOS 8
Purpose:

To change the name of a file on disk.
Under GS/OS, use the ChangePath command instead.
Parameter table:

ProDOS 8 Input

or

O(fret Symbolic Name Result
+0 numparms I
+1to +2 currname I
+3to +4 newname I

Descriptions of parameters:

Description

Number of parameters (2)
Pointer to current pathname
Pointer to new pathname

num - parms The number of parameters in the ProDOS 8 parameter table (always 2).
currname A pointer to a class 0 ProDOS 8 string describing the current
pathname of the file to be renamed. If the pathname specified is not
preceded by a separator (/), the operating system appends the name
to the default prefix to create a full pathname.

new name A pointer to a class 0 ProDOS 8 string describing the new pathname

for the file. If the pathname specified is not preceded by a separator
(/), the operating system appends the name to the default prefix to
create a full pathname. The new - name must be the same as curr
- name except for the filename itself. (That is, it must describe a file
in the same directory.) For example, you can rename a file called
/FOOTBALL/CANADA/BC.LIONS

/FOOTBALL/CANADANANCOUVER.LIONS but not as
/FOOTBALL/USA/DETROIT.LIONS.
Common error codes:

$2B The disk is write-protected.

$40 The pathname contains invalid characters, or a full pathname was not
specified (and no default prefix has been set up). Verif' that the
filenames and directory names specified in the pathname adhere to

188 GS/OS and ProDOS 8 Commands

the naming rules described in Chapter 2 and, if a partial pathname
was specified, that a default prefix has been set up.

$44 A directory in the pathname was not found. Solution: Double-check
the spelling of the pathname, insert the disk containing the correct
directory, or change the default prefix.

$45 The volume directory was not found. Solution: Double-check the
spelling of the volume directory name, insert the correct disk, or
change the default prefix.

$46 The file was not found.
$47 The new filename specified already exists.
$4E The file cannot be accessed. Solution: Set the rename-enabled bit of
the file's access code to 1 using SETH FILE - INFO.

$50 The file is open. You can rename only closed files.
Other possible error codes are $04, $27, $4A.
Programming example:

Here is a subroutine that will change the name of a file called BATMAN in the
/SUPER.HEROES volume directory to a file called BRUCE.WAYNE in the same
directory.

JSR MLI

DFB $C2
DA PARMS
BCs ERROR
RTS

PARMS DFB 2
DA PATH]
DA PATH2

RENAME code

;Address of parameter table
,;Rra.nr,h f ,,"- ~',,,r:v'

2 parameters

Pointer to current pathname
Pointer to new pathname

PATH] STR '/SUPER.HEROES/BATMAN' Old pathname
PATH2 STR '/SUPER.HEROES/BRUCE.WAYNE' ;New pathname

Note that you cannot rename /SUPER.HEROES/BATMAN as /IDENTITIES/BRUCE.
WAYNE because this would violate the rule that the two pathnames must identifi' files in
the same directory.

Command Descriptions 189

none

GS/OS ProDOS 8
Purpose:

To force an immediate resizing of the GS/OS disk cache using the size value stored in
Battery RAM. (Battery RAM holds system configuration and preferences information
even when the Apple IIcs has been turned off.)

There is no equivalent ProDOS 8 command.
Parameter table:

GS/OS Input
or

O(fret Symbolic Name Result
+0to +1 pcount I
Descriptions of parameters:

Description

Number of parameters (0)

pcount The number of parameters in the GS/OS parameter table. The min-
imum value is 0; the maximum is 0.

Common error codes:
[none]

Comments:

A program can use the Miscellaneous Tool Set's WriteBParam function to change the
size of the GS/OS disk cache, as follows:
PushWord #newCacheSize

PushWord #$OO81 ;Parameter reference number

LDX #$0B03 ;WriteBParam
JSL $E10000

The newCacheSize value represents the size of the cache (in K units) divided by 32.
This means, for example, that you would use a value of4 to set up a 128K cache. You
can only set the cache size to a multiple of 32K.

The new cache size setting usually doesn't take effect until the system is rebooted. If the
program calls ResetCache, however, the change takes effect immediately. Utility pro--
grams like the Disk Cache desk accessory on the GS/OS system disk use ResetCache.

190 CS/OS and ProDOS 8 CommandsSessionStatus

$201F ___________________

GS/OS ProDOS 8
Purpose:

To determine whether a write-deferral session (initiated with a BeginSession com-
mand) is in progress.

There is no equivalent ProDOS 8 command.
Parameter table:

GS/OS Input
or

Descriptions of parameters:

O(fret Symbolic Name Result
+0to +1 pcount I
+2to +3 status R

Description

Number of parameters (1)
Status code

pcount The number of parameters in the GS/OS parameter table. The min

imum value is 0; the maximum is 1.

status This code indicates whether a write-deferral session is in progress:

$0000 write-deferral session not in progress
$0001 write-deferral session in progress

Common error codes:
[none]

Comments:

Write-deferral sessions are useful for accelerating file transfer operations. You can

begin such a session with BeginSession and end it with EndSession. SessionStatus
tells you whether a session is currently in progress.

Command Descriptions 191

SET BUT
$D2

GS/OS ProDOS 8
Purpose:

To move the ProDOS 8 file buffer for an open file from its current position to another
1024-byte area in memory.

There is no equivalent GS/OS command. GS/OS takes care of all buffer-management

operations internally.
Parameter table:
ProDOS 8

bet Symbolic Name
+0 num~parms
+1 refnum
+2 to +3 iobufler

Descriptions of parameters:

Input
or

Result Description

I Number of parameters (2)
I Reference number for the file
I Pointer to 1/0 buffer

num - parms The number of parameters in the ProDOS 8 parameter table (always 2).
ref num The reference number ProDOS 8 assigned to the file when it was

first opened.

io - buffer

A pointer to the new 1024-byte area to which the file's current buffer
is to be transferred. The low-order byte of this pointer must be $00
(that is, the buffer must begin on a page boundary).

Common error codes:

$43 The file reference number is invalid. You might be using a reference
number for a file that you've already closed.

$56 The pathname buffer address is invalid because it has been marked
as in use in the ProDOS 8 system bit map. Speciiy a buffer address
that does not conflict with areas already used by ProDOS 8 or its file
buffers. Examine the system bit map to determine the free and
protected areas.

Another possible error code is $04.

192 GS/OS and ProDOS 8 Commands

Programming example:

The following ProDOS 8 program will move the file buffer for file 1 from its current
position to $2000. You are responsible for ensuring that the area $200~$23FF will
not be used for any other purpose.

JSR MLI

DFB $D2
DA PARMTBL
BCS ERROR
RTS

PARMTBL DFB 2
DFB 1

DA $2000

;SET_BUF

;Address of parameter table
;Branch if error occurred

The # of parameters
;File reference number
Pointer to new buffer

Command Descriptions 193

SET~EOF

$D0

GS/OS ProDOS 8
Purpose:

To change the current end-of-file pointer (EOF) of an open file. If you reduce EOF,
all data blocks past the end of the new EOF are freed up; if you increase EOF,
however, ProDOS 8 and GS/OS do not allocate new blocks for the file until you
actually write data to the new part of the file. If the new EOF is less than Mark, Mark
is set equal to the new EOF. You can change the EOF of any file whose write-enabled
access code bit is set to 1.

Parameter table:
Pro DOS 8

O(fret Symbolic Name

+0 numparms
+ 1 refnum
+2 to +4 eof

Input
or

Result Description

I Number of parameters (2)
I Reference number for the file
I The new end-of-file position

GS/OS

Input
or

bet Symbolic Name

+ 0 to + 1 pcount
+2 to +3 refnum
+4to +5 base
+6to +9 displacement

Result Description

I Number of parameters (3)
I Reference number for the file
I

Code for determining new eof

I The new end-offile position

Descriptions of parameters:

num - parms The number of parameters in the ProDOS 8 parameter table (always 2).
ref num The reference number ProDOS 8 or GS/OS assigned to the file when

it was first opened.

eof The new EOF position.

194 GS/OS and ProDOS 8 Commands

pcount The number of parameters in the GS/OS parameter table. The min-
imum value is 3; the maximum is 3.

base This code tells GS/OS how to determine the new value for the
end-of-file pointer:

$0000 new E0F = displacement
$0001 new EOF = old EOF + displacement
$0002 new E0F = Mark + displacement
$0003 new EOF = Mark - displacement

displacement GS/OS uses this value in conjunction with the base code to deter-
mine the new value for the end-of-file pointer.
Common error codes:

$2B The disk is write-protected.

$43 The file reference number is invalid. You might be using a reference
number for a file that you've already closed.

$4D The position is out of range.
$4E

The file cannot be accessed. Solution: Set the write-enabled bit of

the file's access code to 1 using SET FILE - INFO.
Other possible error codes are $04, $07, $27, $4E.
Programming example:

Consider a situation in which you must read an entire file into memory, modifi' it, and
then write it back to the same file. If you are not careful, and the new file is smaller
than the original, the tail end of the old file (the part not overwritten) will unexpect-
edly remain as part of the new file.

To avoid this, you can do one of two things: Delete the file before rewriting it, or write
to the file and then use the SetEOF command to fix the new EOF position. The
second method is faster and more convenient because it is not necessary to go to the
trouble of first deleting, and then re-creating, a file.

Suppose the new file length is $1534 bytes. To set the EOF fur this file, you would
call a GS/OS subroutine like this:

LDA

STA _
LDA
STA

_SetE0F EOF_Parms
BCS Error
RTS

#$1$34 Set up new EOF value
New_E0F
#$0OO0
New EOF+2

;Branch if error occurred

Command Descriptions 195

E0F_Parms DC 12'3' ;The # of parameters
DC 12']' File reference number
DC 12'O' ;E0F = displacement

New_EOF DS 4 ;New E0F position

196 CS/OS and ProDOS 8 Commands

SetFileInfo
$2005

GS/OS ProDOS 8
Purpose:

To modifi' the information stored in a file's directory entry. This includes the access code,
file type code, auxiliary type code, and the date and time the file was last modified.

Parameter table:

ProDOS 8 Input

or

O[fret Symbolic Name Result
+0 num~parms I
+1 to +2 pathname I
+3 access I
+4 file-type I
+5to +6 anxtype I
+7 [not used] I
+8to +9 [not used] I
+10 to +11 modifi'date I
+ 12 to +13 modi~~time I

Description

Number of parameters (10)
Pointer to the pathname string
Access code
File type code
Auxiliary type code

Modification date
Modification time

GS/OS

O(rset Symbolic Name
+0to +1 pcount
+2to +5 pathname
+ 6 to + 7 access
+8to +9 file-type
+10 to +13 anxtype
+ 14 to + 15 [not used]

Input
or

Result

I
I
I
I
I
I

Description

Number of parameters (12)
Pointer to the pathname string
Access code
File type code
Auxiliary type code

Command Descriptions 197

+ 16 to +23 createdt I Creation date and time
+24 to +31 modiiydt I Modification date and time
+ 32 to + 35 option - list I Pointer to option list
+36 to +39 [not used] I
+40 to +43 [not used] I
+44 to +47 [not used] I
+48 to +51 [not used] I

Descriptions of parameters:

num - parms The number of parameters in the ProDOS 8 parameter table (always fl.

pathname A pointer to a class 0 (ProDOS 8) or class 1 (GS/OS) string describ-
ing the pathname of the file to be used. If the pathname specified is
not preceded by a separator (/fur ProDOS 8; / or : for GS/OS), the
operating system appends the name to the default prefix (in GS/OS,
this is the 0/ prefix) to create a full pathname.

access This field contains several 1-bit codes that define the access at-
tributes of the file. See Figure 2-10 for a description of these bits.
Note, however, that under GS/OS you cannot clear the backup-
needed attribute with SetFileInfo; use the ClearBackup command
instead. Under ProDOS 8, you can clear the bit but only if you first
store $FF at BUBIT ($BF95) in the ProDOS 8 system global page.
Backup programs should clear this attribute to indicate that the file
has been backed up.

filetype This code indicates the type of data the file holds. See Table 2-5 for
a description of ProDOS file type codes. Under the ProDOS FST, 1
only the low-order byte of file - type is significant.

aux - type This is the auxiliary type code. The meaning of the code depends on

the file type code and on the program that created the file in the first
place. For SYS, BIN, BAS, and VAR files, it is a default loading
address; for TXT files, it is a record length; for SRC files, it is an
APW language type code. Under the ProDOS FST, only the low--
order word is significant.

[Not Used] These bytes are not used. They act as padding to preserve symmetry be-
tween this parameter list and the GET FILE - INFO parameter list.

198 GS/OS and ProDOS 8 Commands

modify - date This field contains the date (year, month, day) the file was last modified.

The current date should be stored here before executing the command.
Figure 8-1 in Chapter 8 shows the format of these bytes.

modify - time This field contains the time (hour, minute) the file was last modified.

The current time should be stored here before executing the com-
mand. Figure 8-1 in Chapter 8 shows the format of these bytes.
create - date This field contains the date (year, month, day) the file was created.

Figure 8-1 in Chapter 8 shows the format of these bytes.
create - time This field contains the time (hour, minute) the file was created.

Figure 8-1 in Chapter 8 shows the format of these bytes.

pcount The number of parameters in the GS/OS parameter table. The min-
imum value is 2; the maximum is 12.

create - td The time and date of creation. These eight bytes represent the

following parameters in the following order:

seconds
minutes

hour in 24-hour military format
year year minus ]90O
day day of month minus
month 0 = January, ] = February, and so on
[not used]

weekday ] = Sunday, 2 = Monday, and so on

Note: This format is the same as the one used by the ReadTimeHex function in the
IIcs's Miscellaneous Tool Set but is different from the one used in a standard file
entry for the ProDOS file system.

modify - td The time and date of last modification. The ordering of these 8 bytes

is the same as for create - time.

option - list A pointer to a class 1 input buffer containing information unique to

the file system translator used to access the file. The ProDOS FST
does not require any such information.

Note: The parameters marked by [not used] must be set to zero.
Common error codes:

$2B The disk is write-protected.

$40 The pathname contains invalid characters, or a full pathname was not
specified (and no default prefix has been set up). Veri(y that the
filenames and directory names specified in the pathname adhere to
the naming rules described in Chapter 2 and, if a partial pathname
was specified, that a default prefix has been set up.

Corntnand Descriptions 199

$44 A directory in the pathname was not fuund. Solution: Double. -
the spelling of the pathname, insert the disk containing the
directory, or change the default prefix.

$45 The volume directory was not found. Solution: Double-check
spelling of the volume directory name, insert the correct disk
change the default prefix.

$46 The file was not found.

$4E The access code specified for the file is not permitted. Sc
Ensure that the reserved bits of the access code are all zero.

Other possible error codes are $04, $07, $27, $4A, $4B, $52, $53, $58.
Programming example:

The following ProDOS 8 program will lock a file called PRISONER by changing *L
value of its access code byte. It is assumed that PRISONER is located in the cur
active directory (the one specified by the default prefix).

LDA #10

STA PARMTBL
JSR MLI
DFB $C4

DA PARMTBL
BCS ERROR

LDA PARMTBL+3
AND #$3D

STA PARMTBL+3
LDA #7

STA PARMTBL
JSR MLI
DFB $C3

DA PARMTBL
BCS ERROR
RTS

PARMTBL DS 1
DA PATHNAME
DS 1
DS 1
DS 2
DS 1
DS 2
DS 2
DS 2
DS 2

Store # of parms for GET_FILE_INFO
;GET_FILE_INFO

;Address of parameter table
Branch if error occurred

Get current access code
;Clear bits 1, 6, and 7 (write,

rename, and destroy bits)
Store new access code

Store # of parms for SET_FILE_INFO
Save new access code to disk
;SET_FILE_INFO

Address of parameter table
;Branch if error occurred

;The # of parameters is stored here
;access code
;file type code

auxiliary type code
;storage type code
;blocks used

;date of modification
;time of modification
;date of creation

200 GS/OS and Pro DOS 8 Commands

DS 2 ;time of creation

PATHNAME STR 'PRISONER'

;Pathname (in ASCII)

There are two interesting things to note about this program. First, it uses the
GET - FILE - INFO command to read the file's current access code and other
directory information. Since the parameter table fur this command and the SET -
FILE - INFO command are symmetric, there is no need to create two tables; all that
has to be done is store the proper parameter number at the head of the table before
calling each command.

Second, notice how the file is locked. The existing access code is logically ANDed
with $3D (binary 00111101) to clear bits 1, 6, and 7 to zero while leaving the others
unaffected. As Figure 2-10 in Chapter 2 indicates, clearing these bits will disable
write, rename, and destroy operations, respectively.

Command Descriptions 201

none

GS/OS ProDOS 8
Prroose:

To set the system file level.

There is no equivalent ProDOS 8 command. To change the value of the system file
level, store the new value at LEVEL ($BF94) in the system global page.
Parameter table:

GS/OS Input
or

OgCset Symbolic Name Result
+0 to + 1 pcount I
+2to +3 level I

Meanings of parameters:

Description

Number of parameters (1)
The new system file level

pcount The number of parameters in the GS/OS parameter table. The min-
imum value is 1; the maximum is 1.

level The value of the system file level. Legal values range from $0000 to
$00FF.

Common error codes:

$59 Invalid file level. The file level must be a number between $0000
and $00FF.

Another possible error code is $07.
Programming example:

Here is how to set the system file level to 2:

SetLevel SL_Parms
RTS

SLParms ANOP

DC 12' 1'
DC I2'2'

The number of parameters
;New system file level

The system file level affects the performance of subsequent Open, Close, and Flush
operalions.

202 GS/OS and Pro DOS 8 Commands