Basic Disk Operating System Functions
FUNCTION 30 SET FILE
ATTRIBUTES
Return
,
AL: Return Code
The Set File Attributes function allows programma'tic manipulation of permanent indicators attached to files. In particular, the R/O, System and Archive attributes (tl', t2', and t3') can be set or reset. The OX pair addresses a FeB containing a file name with .the appropriate attributes set or reset. It is the user's responsibi~ity to insure that an ambiguous file name is not specified. Function 30 searches the default disk drive directory area for directory entries that belong to the current user number and that match the FCB specified name and type fields. All matching directory entries are updated to contain the selected indicators.
Indicators fl' through f4' are not presently used, but may be useful for applications programs, since they are not involved in the matching process during file open and close operations. Indicators f 5' through f8' are reserved for future system expansion. The currently assigned attributes are defined as follows:
tl': The R/O attribute indicates if set that the file is in read/only status. Bnos will not allow write commands to be issued to files in R/O status.
t2': The System attribute is referenced by the CP/M DIR
~ile
CP/M-86 System Guide 4.3 .BriOS Pi l.e OJ?erat ions t3': The Archive attribute is reserved but not a9tually
used bv CP/M-86 If. set it inl'Hcates that the fi l.e has been wri tten to back UP storaqe bv a user writte·n archive program. To implement this facility, the archive ~rogram sets this attrihute when it copi.es a file to back up storage; any programs updating or creating files reset thi.s attribute. Further, the archive program backs up only those files that have the Archive attribute reset. Thus, an automati.c back UP facility restricted to modified files can be easi ly implemented.
Function 30 returns with register AL set to OFFH (255 decimal) if the referenced file cannot be found, otherwise a value of zero is returned.
Entry
CL: IFB FUNCTION 31 GET ADDR (DISK PARMS)
Return
"
RX: DPB Offset 1'.:5: Segment Base
The offset and the seqment base of the BIOS resident disk parameter blorik of the curre~tly selected driv~ ~re returned in BX and ES as a resul t of this funct ion call. 'l'h is control block can be used for either of two ourooses. First, tbe disk oarameter values can be extracted for dis~lay and space computation ~urposes, or transient programs can dynamically change the values of current disk
~arameters when the disk env ironment changes, if required.
Normally, application ~rograrns will not require this faci.lity.
Section 6.3 defines the BIOS disk parameter block.
Entry
CL: 20H OL: OFFH (get)
or User Code
(set)
FUNCTION 32 SET/GBT USER CODE
""
Return AT .. : Current Code
or no value
An application program can change or intertogate the currently active user number by calling function 32. If register DL = OFFH, then the value of the current user number is returned in register AL, where the value is i.n the range 0 to 15. If register DL is not OFFH, then .the current user number is changed to the value of DL
(modulo 16).
CP/M-86 System Guide
Entry CL: 2lH
•
OX: FCB Offset
4.3 BOOS File Operations
Return
~---~, FUNCTION 33 AL: Return Code
.
READ RANDOM ,'---~
The Read Random function is similar to the sequential file read operation of previous releases, except that the read operation takes place at a.particular record number, selected by the 24-bit value constructed from the three byte field following the FCB (byte positions r'O at 33, rl at 34, and r2 at 35). Note that the sequence of 24 bits is stored with least significant byte first (rO), middle byte next (rl), and high byte last (r2). CP/M does not reference byte r2, exce~t in computing the size of a file (function 35). Byte r2 must be zero, however, since a non-zero value indicates overflow past the end of file.
Thus, the rO, rl byte pa ir is treated as a double-byte, or
"word" value, which contains the record .to read. This value ranges from 0 to 65535, providing access to any particular record of any size file. In order to access a file using the Read Random 'function, the base extent (extent 0) must first be opened. Although the base extent mayor may not contain any allocated data, this ensures that the FCB is properly initialized for subsequent random access operations. The selected record number is then stored into the random record field (rO,rl), and the BOOS is called to read the record. Upon return from the call, register AL either contains an error code, as listed below, or the value, 00 indicating the operation was successful. In the latter case, the buffer at the current DMA address contains the randomly accessed record. Note that contrary to the sequential read operation, the record number is not advanced. Thus, subsequent random read operations continue to read the same record.
Upon each random read operation, the logical extent and current record values are automatically set. Thus, the file can be sequentially' read or written, starting from the current randomly accessed position. Note, however, that in this case, the last randomly read record will be re-read as you switch from random mode to sequential read, and the last record will be re-written as you switch to a sequential write operation. You can, of course, simply advance the random record position following each random read or write to obtain the effect of a sequential I/O operation.
CP/M-86 System Guide 4.3 BOOS File Operations
Error codes returned in register AL following a random read are listed in Table 4-4, below.
Table 4-4. Function 33 (Read Random) Error Codes
Code
I
Mea'n i ng01 Reading unwritten data - This error code is returned when a random read operation accesses a data block which has not been previously written.
02 (not returned by the Random Read command)
03 Cannot close current extent - This error code is returned when BOOS cannot close the current extent prior to moving to the new extent containing the record specified by bytes rO,rl of the FCB. This error can be caused by an overwritten FCB or a read random operation on an FCB that has not been opened.
04 Seek to unwritten extent - This error code i~ returned when a random read operation accesses an extent that has not been created. This error situation is equivalent to error 01.
05 (not returned by the Random Read command)
06 Random record number out o~ range - This error code is returned whenever byte r2 of the FCB is non-zero.
Normally, non-zero return codes can be treated as missing data, with zero return codes indicating operation complete.
CP/M-86 System Guide Entry CL: 22H DX: FCB
Offset
4.3 BDOS File Operations Return
FUNCTION 34 AL: Return Code WRITE RANDOM
The Write Random operation is initiated similar to the Read Random call, except that data is written to the disk from the current DMA address. Further, if the disk extent or data block which is the target of the write has not yet been allocated, the allocation is performed before the write operation continues. As in the Read Random operation, the random record numbe~ is not changed as a result of the write. The logical extent number and current record positions of the file control block are set to correspond to the random record which is being written. Sequential read or write operations can commence following a random write, with the note that the currently addressed record is either read or rewritten again as the sequential operation begins. You can also simply advance the random record position following each write to get the effect of. a sequential write operation. In particular, reading or writing the last record of an extent in random mode does not cause an automatic extent switch as it does in sequential mode.
In order to access a file using the Write Random function, the base extent (extent 0) must first be opened. As in the Read Random function, this ensures that the FCB is properly initialized for subsequent random access operations. If the file is empty, a ~ake File function must be issued for the base extent. Although the base extent mayor may not contain any allocated data, this ensures that the file is properly recorded in the directory, and is visible in DIR requests.
Upon return from a Write Random cal', register AL either contains an error code, as listed in Table 4-5 below, or the value 00 indicating the operation was successful.
Table 4-5. Function 34 (WRITE RANDOM) Error Codes
Codel Meaning
01 (not returned by the Random Write command)
02 No available data block - This condition is encountered
CP/M-B6 System Guide 4.3 BOOS File Operations Table 4-5.. (continued)
Code
I
Mean i ng03 Cannot close current extent - This error code is returned when BOOS cannot close the current extent prior to moving to the new extent containing the record specified by bytes rO,rl of the FCB. This error can be caused by an overwritten FCB or a write random operation on an FCB that has not been opened.
04 (not returned by the Random write command)
05 No available directory space - This condi tion occurs when the write command attempts to create a new extent that requires a new directory entry and no available directory entries exist on the selected disk drive.
06 Random record number out of range - This error code is returned whenever byte r2 of the FCB is non-zero.
Entry CL: 23H OX: FCB
Offset
FUNCTION 35