SetMark
$2016
GS/OS
Parpose:
SET-MARK
$CE
ProDOS 8
To change the current position-in-file pointer (Mark) of an open file. You can set Mark
to any position within the file; subsequent read or write operations take place at that
position.
Parameter table:
ProDOS 8 Input
or
O(fret 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 I The new mark position
GS/OS Input
or
O(fret Symbolic Name Result Description
+ 0 to + 1 pcount I Number of parameters (3)
+ 2 to + 3 ref num 1 Reference number for the file
+ 4 to + 5 base I Code for determining new mark
+ 6 to + 9 displacement I The new mark position
Descriptions of parameters:
num - parms The number of parameters in the ProDOS 8 parameter table (always 2).
ref num The reference number ProDOS 8 or GS/OS assigned to the file when
it was first opened.
position This field holds the new Mark position. This position must not
exceed the EOF position for the file.
pcount The number of parameters in the GS/OS parameter table. The min-
imum value is 3; the maximum is 3.
Command Descriptions 203
base This code tells GS/OS how to determine the new value for the M~
pointer:
$0000 new Mark = displacement
$0001 new Mark = EOF - displacement
$0002 new Mark = old Mark + displacement
$0003 new Mark = old Mark - displacement
displacement GS/OS uses this value in conjunction with the base code to deter-
mine the new value for the Mark pointer.
Common error codes:
$43 The file reference number is invalid. You might be using 'a referen~
number for a file that you've already closed.
$4D The Mark position is larger than the EOF position.
Other possible error codes are $04, $07, $27.
Programming example:
Suppose you have created a large textfile in which information is arranged in 98-byte
records, and you want to directly access the 23rd such record. The easiest way to do
this is to move the Mark pointer directly to the start of this record, and then use the
Read or Write command.
You can determine the proper value fur Mark by multiplying the record length (98) by the
record number (23); the result is 2254 (or $08CE). Here's how to move Mark to this
position (assume that the file is open and has a reference number of 1) under GS/OS:
PARMTBL
New_Mark
LDA #$08CE
STA NewMark
LDA #$00OO
STA NewMark+2 ;(high-order word is zero)
_SetMark SM_Parms
BCS Error ;Branch if error occurred
RTS
DC I2'3' The # of parameters
DC 12' 1' ;File reference number
DC 12'0' New Mark = displacement
DS 4 ;New Mark position
Remember that the Mark position cannot exceed the EOF position.
204 GS/OS and ProDOS 8 Commands
SetPrefix
$2009
GS/OS ProDOS 8
Parpose:
To set the default prefix to a specified directory path. When you pass a filename or partial
pathname to an MLI command, ProDOS 8 or GS/OS automatically converts it into a full
pathname by appending it to the current value of the prefix you're trying to set.
Parameter table:
ProDOS 8 Input
or
bet Symbolic Name Result
+0 num~parms I
+1to +2 prefix I
Description
Number of parameters (1)
Pointer to the new prefix string
GS/OS Input
or
O(rset Symbolic Name Result
+0 to + 1 pcount I
+2 to +3 prefixnum I
+4to +7 prefix I
Descriptions of parameters:
Description
Number of parameters (2)
Prefix number (0 to 31)
Pointer to the new prefix string
num_parms The number of parameters in the ProDOS 8 parameter table (always 1).
pathname A pointer to a class 0 (ProDOS 8) or class 1 (GS/OS) string describ-
ing the pathname of the prefix. If the pathname specified is not
preceded by a separator (/for ProDOS 8; / or: for GS/OS), ProDOS
8 appends the name to the default prefix and GS/OS appends it to
the prefix string for the prefix you're trying to set, thus creating a full
pathname. An optional separator may be placed at the end of the
prefix pathname.
pcount The number of parameters in the GS/OS parameter table. The min-
imum value is 2; the maximum is 2.
Command Descriptions 205
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:
$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.
$4B A nondirectory name was specified in the prefix string. Solution: Try
again with a prefix string that contains only directory names.
Other possible error codes are $04, $07, $27, $53.
Programming example:
It is often convenient to be able to set the ProDOS 8 default prefix to the name of the
volume directory on a disk in a specific disk drive. If this is done, all files in the
volume directory can be referred to by filename alone, rather than by full pathname.
This can be done in two simple steps: First, use the ON - LINE command to
determine the volume name for that disk, and second, use SET - PREFIX to assign
that name to the default prefix. One complication does arise, however: The name
returned by ON - LINE is not quite in the format required by SET PREFIX.
Fortunately, we can easily overcome this discrepancy.
JSR MLI
DFB $CS
DA PARMTBL
BCS ERROR
LDA BUFFER
AND #$OF
STA PFXNAME
INC PFXNAME
LDA #'/'
STA BUFFER
ON_LINE
;Address of parameter table
Branch if error occurred
;Get length byte
;Strip off slot/drive bits
;Store length for SET_PREFIX
;(add 1 for leading slash)
;Put slash in front of volume name
206 GS/OS and ProDOS 8 Commands
JSR MLI
DFB $C6 SET_PREFIX
DA PARMTBL1
BCS ERR0R1 ;Branch if error occurred
RTS
PARMTBL DFB 2 ;The # of parameters
DFB $E0 unit number = slot 6, drive 2
DA BUFFER ;Pointer to 16-byte buffer
PARMTBL1
PFXNAME
BUFFER
DFB 1 The # of parameters
DA PFXNAME ;Pointer to volume name
DS 1 Length of name for SET_PREFIX
DS 1 Slot/drive (bits 4-7) and length
of volume name (bits 0-3)
DS 15 ;Volume name (in ASCII)
The ON - LINE command returns a volume name that is not preceded by the slash
required by SET PREFIX. This problem is fixed by reading the name length by
SET_PREFIX, storing it at the previous memory location (PFXNAME), and then
overwriting the name length byte with the slash. After this has been done, the data
structure beginning with PFXNAME is in the format required by SET PREFIX.
Command Descriptions 207
GS/OS
Purpose:
To set the GS/OS global system preferences.
There is no equivalent ProDOS 8 command.
Parameter table:
GS/OS Input
or
Symbolic Name Result
+0to +1 pcount I
+ 2 to + 3 preferences I
Descriptions of parameters:
ProDOS 8
Description
Number of parameters (1)
System preferences
pcount The number of parameters in the GS/OS parameter table. The
imum value is 1; the maximum is 1.
preferences Use bit 15 of this value to indicate whether GS/OS should display a
mount volume dialog box if a disk volume can't be found during
execution of certain GS/OS commands:
bit 15 1 = display mount volume dialog box
0 = don't display the dialog box
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 may need to complete. If the application wants to handle
"volume not found" errors itself it can use SetSysPrefs to clear bit 15 of the prefer-
ences word.
208 GS/OS and ProDOS 8 Commands
UnbindInt
$2032
GS/OS ProDOS 8
Purpose:
To remove a GS/OS interrupt handling subroutine.
Under ProDOS 8, use the DEALLOC - INT command instead.
Parameter table:
GS/OS Input
or
O(rset Symbolic Name Result
+0to +1 pcount I
+2 to +3 int~num I
Descriptions of parameters:
Description
Number of parameters (1)
Interrupt handler reference number
pcount The number of parameters in the GS/OS parameter table. The min-
imum value is 1; the maximum is 1.
int - num
The identification number for the interrupt handler. GS/OS assigned
this number when the handler was installed using the BindInt com-
mand.
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 int - num parameter is not valid. Use the number BindInt
returned when you installed the interrupt handler.
Other possible error codes are $04, $07.
Comments:
See Chapter 6 for a discussion of how to handle interrupts in a GS/OS environment.
Command Descriptions 209
GS/OS ProDOS 8
Purpose:
To return status information about a disk volume.
Under ProDOS 8, use the ON - LINE command instead.
Parameter table:
GS/OS Input
or
Offset Symbolic Name Result
+0to +1 pcount I
+2to +5 devname I
+6to +9 volname R
+ 10 to +13 totalblocks R
+14 to +17 freeblocks R
+18 to +19 filesysid R
+20 to +21 blocksize R
Meanings of parameters:
Description
Number of parameters (6)
Pointer to the device name string
Pointer to the volume name string
Size of the volume in blocks
Number of unused blocks
Operating system ID code
Number of bytes in a block
pcount The number of parameters in the GS/OS parameter table. The min-
imum value is 2; the maximum is 6.
dev - name A pointer to a class 1 string containing the device name. (Use DInfo
to get a list of active device names.)
vol - name A pointer to a class 1 output buffer where GS/OS returns the disk
volume name string. The buffer should be 35 bytes long.
total - blocks The total number of blocks on the disk volume.
free - blocks The number of unused blocks on the disk volume. For the High
Sierra FST, this value is always zero.
file - sys - id The identification code for the file system on the disk volume. The
currently defined values are:
210 GS/OS and Pro DOS 8 Commands
$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
$0B = High Sierra (CD-ROM)
$0C = 1509660 (CD-ROM)
block size The size of a disk block in bytes.
Common error codes:
$10 The specified device name does not exist.
$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. This error is returned if you do not have a
second 5.25-inch drive connected to the drive controller, but you try
to access it.
$2F Device not on line. This error is returned if no disk is in a 3.5-inch
drive.
Other possible error codes are $07, $11, $2E, $40, $45, $4A, $52, $55, $57, $58.
Programming example:
You can use the DInfo command to determine the GS/OS device names for disks
attached to the system. It is these names that Volume requires as inputs.
To get the status for a particular device, say .APPLEDISK3.5A, so that you can
determine the number of blocks in use on the disk, use a subroutine like this:
_Volume Vol _Parms
SEC ;Used blocks = total blocks
LDA total _blk minus free blocks
SBC free_blk
STA used_blk
LDA total _blk+2
SBC free_blk+2
STA used_blk+2
RTS
Command Descriptions 211
Vol Parms AN0P
DC 12 '6' ;The number of parameters
DC I4'DevName' Pointer to device name
DC I4'VolSpace' ;Pointer to volume name
total blk DS 4 ;total blocks
free_blk DS 4 free blocks
sys_id DS 2 ;file system ID
block sz DS 2 ;bytes per block
DevName GSString '.APPLEDISK3.5A'
VolSpace DC I2'35' Size of class 1 buffer
VolName DS 33 Space for volume name
used blk DS 4
212 GS/OS and ProDOS 8 CommandsWrite
$2013
GS/OS ProDOS 8
Purpose:
To write bytes of data to an open file. Writing begins at the current Mark position.
After you write the data to the file, the operating system increases the Mark position
by the number of bytes written. If the new Mark position is greater than EOF, EOF
is set equal to Mark.
Parameter table:
ProDOS 8 Input
or
O(fret Symbolic Name Result Description
+0 num - parms I Number of parameters (4)
+1 refnum I Reference number for the file
+2 to +3 databufler I Pointer to start of data buffer
+4to +5 requestcount I Number of bytes to write
+ 6 to + 7 transfer - count R Number of bytes actually written
CS/OS Input
or
Offset Symbolic Name Result Description
+ 0 to + 1 pcount I Number of parameters (5)
+ 2 to + 3 ref num I Reference number for the file
+4 to +7 databufler I Pointer to start of data buffer
+8 to + 11 requestcount I Number of bytes to write
+ 12 to + 15 transfer - count R Number of bytes actually written
+ 16 to + 17 cache priority I Block-caching priority code
Descriptions of parameters:
num - parms The number of parameters in the ProDOS 8 parameter table (always 4).
Command Descriptions 213
ref num
data - buffer
The reference number ProDOS 8 or GS/OS assigned to the file when
it was first opened.
A pointer to the beginning of a block of memory that contains the
data to be written to the file.
request - count The number of characters to be written to the file from the buffer
pointed to by data - buffer.
transfer - count This result contains the number of characters actually written to the
file and usually equals request - count. However, it will be less the
request - count if the disk becomes full part way through a write
operation or if some other disk error occurs that prevents the file
from being written to.
pcount The number of parameters in the GS/OS parameter table. The min-
imum value is 4; the maximum is 5 (or 4 for a character device file).
cache - priority This code indicates how GS/OS is to handle the caching of disk
blocks related to the write operation:
$0000 do not cache blocks
$0001 cache blocks
This field is not used for character devices.
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.
$48 The disk is full.
$4E The file cannot be accessed. Solution: Set the write-enabled bit of
the file's access code to 1 using SET - FILE - INFO.
$56 The pathname buffer address is invalid because it has been marked
as in use in the ProDOS 8 system bit map. Specifi' a buffer address
that does not conflict with areas already used by ProDOS 8 or its file
buffers. Examine the system bit map to determine the free and
protected areas.
Other possible error codes are $04, $07, $27.
Programming example:
This GS/OS subroutine writes 256 bytes to file 2; the data buffer begins at location
Buffer.
214 GS/OS and ProDOS 8 Commands
_Write WR_Parms
BCS Error ;Branch if error occurred
RTS
WR_Parms DC 12 '4' ;Parameter count
DC 12 '2' ;File reference number (assume #2)
DC 14'Buffer' ;Pointer to data buffer
DC 14'256'
TransCnt DS 4
Buffer DS 256
Number of bytes to write
;# of bytes actually written
;Data buffer
If no error occurred, the number stored at TransCnt should be equal to 256, the
request count. But if the disk becomes full during the write, TransCnt will be less
than 256.
If you want to append data to the end of an open file, use GetEOF to determine the
file size, and then use SetMark to set the Mark pointer to the EOF value. Subsequent
Write operations will begin at the end of the file.
Command Descriptions 215
GS/OS ProDOS 8
Purpose:
To transfer the contents of a 512-byte buffer from memory to a block on an At -
formatted disk.
Under GS/OS, use the DWrite command instead.
Parameter table:
ProDOS 8 Input
or
Offset Symbolic Name Result Description
+ 0 num - parms I Number of parameters (3)
+1 unitnum I Unit number
+ 2 to + 3 data - buffer I Pointer to the data output buffer
+4to +5 Mcknum I Number of block to be written to
Warning: Do not use WRITE - BLOCK if you want your application to work with ~
AppleShare file server volume over AppleTalk.
Descriptions of parameters:
num - parms The number of parameters in the ProDOS 8 parameter table (always 3).
unit - num The slot and drive number for the disk drive to be accessed. The
format of this byte is as follows:
7 6 $ 4 3 2 1 0
ProDOS 8 assigns a drive number of 1 or 2 to each drive in the
system. DR = 0 for drive 1, and DR = 1 for drive 2. SLOT is
usually the actual slot number for the disk controller card (1-7
decimal; 001-111 binary) but may be the number of a phantom, or
logical, slot.
The unit - num value for the /RAM volume is $B0, meaning it is the
logical slot 3, drive 2 device.
databufler A pointer to the beginning of a 512-byte block of memory that is to
be written to the disk.
216 GS/OS and Pro DOS 8 Commands
block - num The number of the block to be accessed. The permitted values for
block num depend on the disk device:
z 0-279 for 5.25-inch drives
z 0-1599 for 3.5-inch drives
z 0-127 for the ProDOS 8 /RAM volume
You can determine the volume size for a device using the GET
- FILE - INFO command and speci~ing the name of the volume
directory for the disk in the device. The size (in blocks) is returned at
relative positions $5 and $6 in the parameter table.
Common error codes:
$27 The disk is unwriteable probably because a portion of the disk
medium is permanently damaged. This error also occurs if the drive
door on a 5.25-inch drive is open or no disk is in the drive.
$28 No device connected. This error is returned if you do not have a
second 5.25-inch drive connected to the drive controller, but you try
to access it.
$2B The disk is write-protected.
Other possible error codes are $04, $07, $11, $2F, $53, $56.
Programming example:
WRITE - BLOCK is perhaps the most dangerous of all the ProDOS 8 commands since it
lets you overwrite any block on the disk with any data you want. It is very useful,
however, for trying to recover damaged files and malcing backup copies of disks.
It is also possible to use WRITE - BLOCK to write to any sector on a DOS 3.3-
formatted disk. See Appendix II for suggestions on how to do this.
Here's an interesting ProDOS 8 program that allows you to rename the volume
directory of a disk in slot 6, drive 1 to AREA:
JSR ML1
DFB $80
DA PARMTBL
BCS ERROR
LDX #0
LDY #5
M0VENAME LDA NEWNAME,X
BEQ SETLEN
STA BLKBUFF,Y
INX
INY
BNE MOVENAME
;READ_BLOCK
Address of parameter table
Branch if error occurred
Offset for volume name
Branch if at end
Move new name into place
;(Always taken)
Command Descriptions 217
SETLEN TXA
0RA #$FO
LDY #4
STA BLKBUFF,Y
JSR MLI
DFB $81
DA PARMTBL
BCS ERROR
RTS
PARMTBL DFB 3
DFB $60
DA BLKBUFF
DW 2
BLKBUFF DS 512
NEWNAME ASC 'AREA'
DFB 0
Get new name length
;Merge directory ID bits
Save new name length
;WRITE_BLOCK
;Address of parameter table
Branch if error occurred
The # of parameters
;unit number code (slot 6, drive 1)
Pointer to 512-byte buffer
Block number for volume directory
;This is the block buffer
;New volume name (<15 chars)
(Terminate with 0)
We saw in Chapter 2 that the volume directory of a disk always begins in block 2
that the volume name is the first entry in that directory block (beginning at offset
This program simply reads in block 2 (using READ - BLOCK), changes the vc
name, and then writes the block back to disk. The chore is simplified because
parameter tables for READ - BLOCK and WRITE - BLOCK are identical.
Of course, the preferred way to rename a volume directory is to use the RENAME
command.
218 GS/OS and Pro DOS 8 Commands