User`s guide

BDOS FUNCTION 17: SEARCH FOR FIRST
Entry Parameters:
Registers C: 11H
DE: FCB Address
Returned Value:
Registers A: Directory Code
H: Physical Error
The Search For First function scans the directory for a match with the FCB addressed
by register pair DE. Two types of searches can be performed. For standard searches,
the calling program initializes bytes 0 through 12 of the referenced FCB, with byte 0
specifying the drive directory to be searched, bytes 1 through 11 specifying the file or
files to be searched for,, and byte 12 specifying the extent. Usually byte 12 is set to
zero. An ASCII question mark, 63 decimal, 3F hex, in any of the bytes 1 through 12
matches all entries on the directory in the corresponding position. This facility, called
ambiguous reference, can be used to search for multiple files on the directory. When
called in the standard mode, the Search function scans for the first file entry in the
specified directory that matches the FCB, and belongs to the current user number.
The Search For First function also initializes the Search For Next function. After
the Search function has located the first directory entry matching the referenced FCB,
the Search For Next function can be called repeatedly to locate all remaining match-
ing entries. In terms of execution sequence, however, the Search For Next call must
either follow a Search For First or Search For Next call with no other intervening
BDOS disk-related function calls.
If byte 0 of the referenced FCB is set to a question mark, the Search function
ignores the remainder of the referenced FCB, and locates the first directory entry
residing on the current default drive. All remaining directory entries can be located
by making multiple Search For Next calls. This type of search operation is not
usually made by application programs, but it does provide complete flexibility to
scan all current directory values. Note that this type of search operation must be
performed to access a drive's directory label (see Section 2.3.6).
3-24
BDOS Function Calls CP/M 3 Programmers Guide