mirror of
https://github.com/SEPPDROID/Digital-Research-Source-Code.git
synced 2025-10-23 08:24:18 +00:00
476 lines
16 KiB
TeX
476 lines
16 KiB
TeX
.bp
|
|
.pn 31
|
|
.cs 5
|
|
.mt 5
|
|
.mb 6
|
|
.pl 66
|
|
.ll 65
|
|
.po 10
|
|
.hm 2
|
|
.fm 2
|
|
.ft All Information Presented Here is Proprietary to Digital Research
|
|
.tc 4.2.3 Open File Function
|
|
.sh
|
|
4.2.3 Open File Function
|
|
.qs
|
|
.sp
|
|
.ix open file function
|
|
.nf
|
|
.sp 3
|
|
FUNCTION 15: OPEN FILE
|
|
|
|
Entry Parameters:
|
|
Register R5: 0FH
|
|
Register RR6: FCB Address
|
|
|
|
Returned Values:
|
|
Register R7: Return Code
|
|
|
|
success: 00H - 03G
|
|
error: FFH
|
|
.sp 2
|
|
.fi
|
|
.pp 5
|
|
The Open File Function matches the filename and filetype fields of the FCB
|
|
specified in register RR6 with these fields of a directory entry for an
|
|
existing file on the disk. When a match occurs, the BDOS sets the FCB
|
|
extent (ex) field and the second system (S2) field to zero before the BDOS
|
|
opens the file. Setting these one-byte fields to zero opens the file at the
|
|
base extent, the first extent in the file. In CP/M-8000, files can be opened
|
|
only at the base extent. In addition, the physical I/O mapping information,
|
|
which allows access to the disk file through subsequent read and write
|
|
operations, is copied to fields d0 through dn of the FCB. A file cannot be
|
|
accessed until it has been opened successfully. The open function returns
|
|
an integer value ranging from 00H through 03H in R7 when the open
|
|
operation is successful. The value FFH is returned in register R7 when
|
|
the file cannot be found.
|
|
.ix wildcard
|
|
.pp
|
|
The question mark (?) wildcard can be specified
|
|
for the filename and filetype fields of the FCB referenced by
|
|
register RR6. The ? wildcard has the value 3FH. For each position
|
|
containing a ? wildcard, any character constitutes a match. For
|
|
example, if the filename and filetype fields of the FCB
|
|
referenced by RR6 contain only ? wildcards, the BDOS accesses the
|
|
first directory entry. However, you should not create a FCB of all wildcards
|
|
for this function because you cannot ensure which file this function
|
|
opens.
|
|
.pp
|
|
Note that the current record field (cr) in the FCB must be set to
|
|
zero by the program for the first record in the file to be
|
|
accessed by subsequent sequential I/O functions. However, setting the
|
|
current record field to zero is not required to open the file.
|
|
.ix wildcard
|
|
.ix open file
|
|
.bp
|
|
.tc 4.2.4 Close File Function
|
|
.sh
|
|
4.2.4 Close File Function
|
|
.qs
|
|
.ix close file function
|
|
.sp
|
|
.nf
|
|
.sp 3
|
|
FUNCTION 16: CLOSE FILE
|
|
|
|
Entry Parameters:
|
|
Register R5: 10H
|
|
Register RR6: FCB Address
|
|
|
|
Returned Values:
|
|
Register R7: Return Code
|
|
|
|
success: 00H - 03H
|
|
error: FFH
|
|
.sp 2
|
|
.fi
|
|
.pp
|
|
The Close File Function performs the inverse of the Open File
|
|
Function. When the FCB passed in RR6 was opened previously by either
|
|
an Open File (15) or Make File (22) Function, the close function
|
|
updates the FCB in the disk directory. The
|
|
process used to match the FCB with the directory entry is
|
|
identical to the Open File Function (15). An integer value
|
|
ranging from 00H though 03H is returned in R7 for a successful
|
|
close operation. The value FFH is returned in R7 when the file
|
|
cannot be found in the directory. When only read functions access
|
|
a file, closing the file is not required. However, a file must be
|
|
closed to update its disk directory entry when write functions access the
|
|
file.
|
|
.ix close file
|
|
.bp
|
|
.tc 4.2.5 Search For First Function
|
|
.sh
|
|
4.2.5 Search For First Function
|
|
.qs
|
|
.sp 3
|
|
.ix search for first function
|
|
.nf
|
|
FUNCTION 17: SEARCH FOR FIRST
|
|
|
|
Entry Parameters:
|
|
Register R5: 11H
|
|
Register RR6: FCB Address
|
|
|
|
Returned Values:
|
|
Register R7: Return Code
|
|
|
|
success: 00H - 03H
|
|
error: FFH
|
|
.sp 2
|
|
.fi
|
|
.pp
|
|
The Search For First Function scans the disk directory allocated
|
|
to the current user number to match the filename and filetype of
|
|
the FCB addressed in register RR6 with the filename and filetype
|
|
of a directory entry. The value FFH is returned in register R7
|
|
when a matching directory entry cannot be found. An
|
|
integer value ranging from 00H through 03H is returned in
|
|
register R7 when a matching directory entry is found.
|
|
.ix disk directory
|
|
.pp
|
|
The directory record containing the matching entry is copied to
|
|
the buffer at the current DMA address. Each directory record
|
|
contains four directory entries of 32 bytes each. The integer value returned in
|
|
R7 indexes the relative location of the matching directory
|
|
entry within the directory record. For example, the value 01H
|
|
indicates that the matching directory entry is the second one in the directory
|
|
record in the buffer. The relative starting position of the directory
|
|
entry within the buffer is computed by multiplying the value
|
|
in R7 by 32 (decimal), which is equivalent to shifting the
|
|
binary value of R7 left 5 bits.
|
|
.ix search for first
|
|
.pp
|
|
When the drive (dr) field contains a ? wildcard, the auto disk
|
|
select function is disabled and the default disk is searched. All
|
|
entries including empty entries for all user numbers in the
|
|
directory are searched. The search function returns any matching
|
|
entry, allocated or free, that belongs to any user number. An
|
|
allocated directory entry contains the filename and filetype of
|
|
an existing file. A free entry is not assigned to an existing
|
|
file. If the first byte of the directory entry is E5H, the entry
|
|
is free. A free entry is not always empty. It can contain the
|
|
filename and filetype of a deleted file because the directory
|
|
entry for a deleted file is not zeroed.
|
|
.bp
|
|
.tc 4.2.6 Search For Next Function
|
|
.sh
|
|
4.2.6 Search For Next Function
|
|
.qs
|
|
.sp
|
|
.ix search for next function
|
|
.nf
|
|
.sp 3
|
|
FUNCTION 18: SEARCH FOR NEXT
|
|
|
|
Entry Parameters:
|
|
Register R5: 12H
|
|
|
|
Returned Values:
|
|
Register R7: Return Code
|
|
|
|
success: 00H - 03H
|
|
error: FFH
|
|
.fi
|
|
.sp 2
|
|
.pp
|
|
The Search For Next Function scans the disk directory for an
|
|
entry that matches the FCB and follows the last matched entry, found
|
|
with this or the Search For First Function (17).
|
|
.pp
|
|
A program must invoke a Search For First Function before invoking
|
|
this function for the first time. Subsequent Search For Next
|
|
Functions can follow, but they must be specified
|
|
without other disk related BDOS functions intervening. Therefore,
|
|
a Search For Next Function must follow either itself or a Search
|
|
For First Function.
|
|
.pp
|
|
The Search For Next
|
|
Function returns the
|
|
value FFH in R7 when no more directory entries match.
|
|
.ix search for next
|
|
.bp
|
|
.tc 4.2.7 Delete File Function
|
|
.sh
|
|
4.2.7 Delete File Function
|
|
.qs
|
|
.ix delete file function
|
|
.sp 3
|
|
.nf
|
|
FUNCTION 19: DELETE FILE
|
|
|
|
Entry Parameters:
|
|
Register R5: 13H
|
|
Register RR6: FCB Address
|
|
|
|
Returned Values:
|
|
Register R7: Return Code
|
|
|
|
success: 00H
|
|
error: FFH
|
|
.fi
|
|
.sp 2
|
|
.pp
|
|
The Delete File Function removes files and deallocates the
|
|
directory entries for and space allocated to files that match the
|
|
filename in the FCB pointed to by the address passed in RR6. The
|
|
filename and filetype can contain wildcards, but the drive select
|
|
code cannot be a wildcard as in the Search For First (17) and
|
|
Search For Next (18) Functions. The value FFH is returned in
|
|
register R7 when the referenced file cannot be found. The
|
|
value 00H is returned in R7 when the file is found.
|
|
.ix delete file
|
|
.bp
|
|
.tc 4.2.8 Read Sequential Function
|
|
.sh
|
|
4.2.8 Read Sequential Function
|
|
.qs
|
|
.sp 3
|
|
.ix read sequential function
|
|
.nf
|
|
FUNCTION 20: READ SEQUENTIAL
|
|
|
|
Entry Parameters:
|
|
Register R5: 14H
|
|
Register RR6: FCB Address
|
|
|
|
Returned Values:
|
|
Register R7: Return Code
|
|
|
|
success: 00H
|
|
error: 01H
|
|
.sp 2
|
|
.fi
|
|
.pp
|
|
The Read Sequential Function reads the next 128-byte record in a
|
|
file. The FCB passed in register RR6 must have been opened by
|
|
an Open File (15) or the Make File Function (22) before this
|
|
function is invoked. The program must set the current record
|
|
field to zero following the open or make function to ensure the
|
|
file is read from the first record in the file. After the file
|
|
is opened, the Read
|
|
Sequential Function reads the 128-byte record specified by the
|
|
current record field from the disk
|
|
file to the current DMA buffer. The FCB current record (cr) and
|
|
extent (ex) fields indicate the location of the record
|
|
that is read. The current record field is automatically
|
|
incremented to the next record in the extent after a read
|
|
operation.
|
|
.pp
|
|
When the current record field overflows, the next
|
|
logical extent is automatically opened and the current record
|
|
field is reset to zero before the read operation is performed. After
|
|
the first record in the new extent is read, the current record field
|
|
contains the value 01H.
|
|
.pp
|
|
The value 00H is returned in register R7 when the read
|
|
operation is successful. The value of 01H is returned in R7
|
|
when the record being read contains no data. Normally, the no data
|
|
situation is encountered at the end of a file. However, it can
|
|
also occur when this function tries to read either a previously
|
|
unwritten data block or a nonexistent extent. These situations
|
|
usually occur with files created or appended with the BDOS
|
|
Write Random Function (34).
|
|
.ix read sequential
|
|
.bp
|
|
.tc 4.2.9 Write Sequential Function
|
|
.sh
|
|
4.2.9 Write Sequential Function
|
|
.qs
|
|
.ix write sequential function
|
|
.sp 3
|
|
.nf
|
|
FUNCTION 21: WRITE SEQUENTIAL
|
|
|
|
Entry Parameters:
|
|
Register R5: 15H
|
|
Register RR6: FCB Address
|
|
|
|
Returned Values:
|
|
Register R7: Return Code
|
|
|
|
success: 00H
|
|
error: 01H or 02H
|
|
.sp 2
|
|
.fi
|
|
.pp
|
|
The Write Sequential Function writes a 128-byte record from the
|
|
DMA buffer to the disk file whose FCB address is passed in
|
|
register RR6. The FCB must be opened by either an Open File (15)
|
|
or Make File (22) Function before your program invokes
|
|
the Write Sequential Function. The record is written
|
|
to the current record, specified in the FCB current record (cr)
|
|
field.
|
|
.pp
|
|
The current record field is automatically incremented to the next record.
|
|
When the current record field overflows, the next logical extent of the
|
|
file is automatically opened and the current record field is reset to zero
|
|
before the write operation. After the write operation, the current record
|
|
field in the newly opened extent is set to 01H.
|
|
.pp
|
|
Records can be written to an existing file. However, newly
|
|
written records can overlay existing records in the file because the
|
|
current record field usually is set to zero after a file is
|
|
opened or created to ensure a subsequent sequential I/O function accesses
|
|
the first record in the file.
|
|
.pp
|
|
The value 00H is returned in register R7 when the
|
|
write operation is successful. A nonzero value in register
|
|
R7 indicates the write operation is unsuccessful
|
|
due to one of the conditions described below.
|
|
.bp
|
|
.ce
|
|
.sh
|
|
Table 4-6. Unsuccessful Write Operation Return Codes
|
|
.qs
|
|
.sp
|
|
.in 5
|
|
.ll 60
|
|
.nf
|
|
Value Meaning
|
|
.fi
|
|
.sp
|
|
.in 13
|
|
.ti -7
|
|
01 No available directory space - This condition 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.
|
|
.sp
|
|
.ti -7
|
|
02 No available data block - This condition is encountered when
|
|
the write command attempts to allocate a new data block to the
|
|
file and no unallocated data blocks exist on the selected disk drive.
|
|
.ix write sequential
|
|
.in 0
|
|
.ll 65
|
|
.bp
|
|
.tc 4.2.10 Make File Function
|
|
.sh
|
|
4.2.10 Make File Function
|
|
.qs
|
|
.sp 3
|
|
.ix make file function
|
|
.nf
|
|
FUNCTION 22: MAKE FILE
|
|
|
|
Entry Parameters:
|
|
Register R5: 16H
|
|
Register RR6: FCB Address
|
|
|
|
Returned Values:
|
|
Register R7: Return Code
|
|
|
|
success: 00H - 03H
|
|
error: FFH
|
|
.sp 2
|
|
.fi
|
|
.pp
|
|
The Make File Function creates and opens a new file on a
|
|
specified disk or the default disk. The address of the FCB for the
|
|
file is passed in register RR6. You must ensure the FCB contains
|
|
a filename that does not already exist in the
|
|
referenced disk directory. The drive field (dr) in the FCB
|
|
indicates the drive on which the directory resides. The disk
|
|
directory is on the default drive when the FCB drive field
|
|
contains a zero.
|
|
.pp
|
|
The BDOS creates the file and initializes the directory and
|
|
the FCB in memory to indicate an empty file. The program must ensure that no
|
|
duplicate filenames occur. Invoking the Delete File Function
|
|
(19) prior to the Make File Function excludes the possibility of
|
|
duplicate filenames.
|
|
.pp
|
|
Register R7 contains an integer value in the range 00H through
|
|
03H when the function is successful. Register R7 contains the
|
|
value FFH when a file cannot be created due to insufficient directory
|
|
space.
|
|
.ix make file
|
|
.bp
|
|
.tc 4.2.11 Rename File Function
|
|
.sh
|
|
4.2.11 Rename File Function
|
|
.qs
|
|
.ix rename file function
|
|
.sp 3
|
|
.nf
|
|
FUNCTION 23: RENAME FILE
|
|
|
|
Entry Parameters:
|
|
Register R5: 17H
|
|
Register RR6: FCB Address
|
|
|
|
Returned Values:
|
|
Register R7: Return Code
|
|
success: 00H
|
|
error: FFH
|
|
.sp 2
|
|
.fi
|
|
.pp
|
|
The Rename File Function uses the FCB specified in register RR6
|
|
to change the filename and filetype of all directory entries for
|
|
a file. The first 12 bytes of the FCB contains the file
|
|
specification for the file to be renamed as shown in Figure 4-1.
|
|
Bytes 16 through 27 (d0 through d12) contain the new name of the
|
|
file. The filenames and filetypes specified must be valid for
|
|
CP/M. Wildcards cannot be specified in the filename and filetype
|
|
fields. The FCB drive field (dr) at byte position 0 selects the
|
|
drive. This function ignores the drive field at byte position 16,
|
|
if it is specified for the new filename. Register R7 contains the value
|
|
zero when the rename function is successful. It contains the
|
|
value FFH when the first filename in the FCB cannot be found
|
|
during the directory scan.
|
|
.ix rename
|
|
.sp 3
|
|
.nf
|
|
FCB byte position
|
|
.sp
|
|
0 1 2 3 4 5 6 7 8 9 10 11...16 17 18 19 20 21 22 23...27...
|
|
.sp
|
|
dr f1 f2 f3 f4 f5 f6 f7 f8 t1 t2 t3...d0 d1 d2 d3 d4 d5 d6 d7...d12...
|
|
|
|
old file specification new file specification
|
|
.fi
|
|
.sp 2
|
|
.sh
|
|
.ce
|
|
Figure 4-1. FCB Format for Rename Function
|
|
.qs
|
|
.sp 2
|
|
.pp
|
|
In the above figure, horizontal ellipses indicate FCB fields that are not
|
|
required for this function. Refer to Section 4.1.2 for a description of
|
|
all FCB fields.
|
|
.bp
|
|
.tc 4.2.12 Set Direct Memory Access (DMA) Address
|
|
.sh
|
|
4.2.12 Set Direct Memory Access (DMA) Address Function
|
|
.ix set direct memory access (DMA address function
|
|
.sp 3
|
|
FUNCTION 26: SET DMA ADDRESS
|
|
|
|
Entry Parameters:
|
|
Register R5: 1AH
|
|
Register RR6: DMA Address
|
|
|
|
Returned Values:
|
|
Register R7: 00H
|
|
.sp 2
|
|
.fi
|
|
.pp
|
|
The Set DMA Address Function sets the starting address of the
|
|
128-byte DMA buffer. DMA is an acronym for Direct Memory Access,
|
|
which often refers to disk controllers that directly access
|
|
memory to transfer data to and from the disk subsystem. Many
|
|
computer systems use nonDMA access in which the data is
|
|
transferred through programmed I/O operations. In CP/M the
|
|
term DMA is used differently. The DMA address in
|
|
CP/M-8000 is the beginning address of a 128-byte data buffer,
|
|
called the DMA buffer. The DMA buffer is the area in memory
|
|
where a data record resides before a disk write operation and after a
|
|
disk read operation. The DMA buffer can begin on
|
|
an even or odd address.
|
|
.ix set DMA address
|
|
.ix DMA buffer
|
|
.nx fourc
|