💾 Archived View for mirrors.apple2.org.za › archive › apple.cabi.net › System › GSOS.P8.Anatomy › CO… captured on 2023-01-29 at 08:32:07.
-=-=-=-=-=-=-
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