💾 Archived View for mirrors.apple2.org.za › archive › apple.cabi.net › System › GSOS.P8.Anatomy › CO… captured on 2024-02-05 at 14:49:04.
⬅️ Previous capture (2023-01-29)
-=-=-=-=-=-=-
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