19. The Wildcard Handler

The wildcard calls can be used to supplement the calls described in "File Input/Output". You can use the wildcard handler to gain control over the match selected, or indeed get all possible matches. The wildcard system recognizes the following character sequences:

*           match any number of characters, or none
?           match a single character
//          matches any number of directories, or none

Normal use of the wildcard handler involves specifying a wildcard string and then getting, one by one, the possible explicit filenames that match it, if any actually do, which may then be used or discarded as required. The calls available are as follows:

GN_Opw

Open wildcard handler. This is given a pointer to a wildcard string and returns a wildcard handle in register IX associated with it. You can specify whether directories or files come first in the search and if directories and device paths are returned with each name.

This gives the explicit filename of the next file which matches the string supplied to GN_Opw. It also returns the length and number of segments of the name it finds. If no more matches are available, the routine returns with Fc = 1 and A = RC_EOF.

Close the wildcard handler. You simply supply the wildcard handle.A detailed description of the call parameters of these calls may be found in the "System Calls Reference" section.

Example

The following program demonstrates the use of the above sequence in providing a complete catalogue of the RAM filing system, by matching to the wildcard string ":RAM.*//*". Note that this program does not include a "Page Wait" mechanism so output will simply be scrolled - you can hold down <SHIFT> and <DIAMOND> to freeze scrolling temporarily.

include "#fileio.def"               ; get definitions for wildcard calls
include "#stdio.def"                ; get standard I/O definitions

.main       ld   b, 0               ; local pointer to wildcard string
            ld   hl, wildstring
            xor  a                  ; directories returned first, do
                                    ; not return parents
            call_oz(GN_Opw)         ; open wildcard handler
.nextname   ld   de, (scratch)      ; pointer to buffer for returned filenames
            ld   c, 40              ; max. extent of buffer
            call_oz(GN_Wfn)         ; get next (or first) match
            jr   c, exit            ; is it the last entry?
            ld   hl, (scratch)      ; point at found filename match
            call_oz(GN_Sop)         ; write filename to std. output
            call_oz(GN_Nln)         ; print a newline

.exit       call_oz(GN_Wcl)         ; close wildcard handler
            ret

.wildstring DEFM ":RAM.*//*" & 0    ; change this if you like!