InetMatchName

Returns information about the next file or sub-directory, in the current server handle.

Synopsis

error = InetMatchName(variableName, template, flags)

Args

variableName is the name of some REXX stem variable that you wish to be set to the information about the next file or sub-directory. The name of the file/dir is stored in variableName. The size (in bytes) is stored in variableName.0. (A directory always has a size of 0). The creation date is stored in variableName.1, and the attribute (bits) are stored in variableName.2.

template is the name of some directory you want to list. For example, you could pass "MyDir/MySubDir" if you wish to get a listing of MySubDir within the directory MyDir (which is itself a sub-directory of the server's current directory).

Alternately, you can pass a particular filename if you wish to get information about only that one file. For example, you could pass "MyFilename.txt" to get information upon just that one file. (In this case, you should also specify the ONE option).

InetMatchName also supports using wildcards in template, in order to list only those names that fit a certain pattern (such as only those files whose names end with a .HTM extension). So you could pass "*.txt" to list only those files and directories whose names end with .txt.

If you omit template, then you get a listing of all of the files/sub-directories in the current directory on the server.

flags specifies some options. It may be any of the following, each separated by a | character:

ValueMeaning
RELOAD Force a refresh of the directory listing from the origin server, not from the cache.
RESYNC Refresh the directory listing if it has been modified since the last time it was listed.
LINK Force a refresh if there's no Expires time and no LastModified time returned from the server when determining whether to refresh the listing.
NOWRITECACHE Don't save the listing in the offline cache after downloading information.
USETEMP Cause a temporary file to be created if the listing can't be cached.
ONE Get information about only one file.

If omitted, flags defaults to none of the above.

Returns

An empty string if successfully returned information about the next file or sub-directory, the string DONE if no more matching files or sub-directories, or an error message if a problem.

Notes

You must have first called InetConnect to connect to the FTP server. If you call InetIn before calling InetConnectUrl(), InetConnect() or some other function to set the current server handle, then a REXX SYNTAX condition is raised. CONDITION('E') returns error number 40.1 and CONDITION('D') returns the message DLL function "INETMATCHNAME" reported server handle not open!.

Regardless of how you've set the InetErr variable, no condition is raised if there are no more matching files or sub-directories. So, you need to specifically check for "DONE" being returned.

You can enumerate only one directory at a time. This means that if you need to list the contents of sub-directories too, you'll have to collect those names, and then list each one separately after you've finished the parent directory.

To abort a listing before InetMatchName returns "DONE", then you must call InetMatchName without passing any arguments.