The first arg is the name of a REXX variable where you want information stored about the file or sub-directory.
The second arg 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. (ie, InetMatchName will return information about the first file or sub-directory inside of MySubDir, and then you continue calling InetMatchName to get information on each additional file/sub-directory).
Or you could 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.
InetMatchName also supports using wildcards in the name, 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 the second arg, then you get a listing of all of the files/sub-directories in the current directory on the server.
The third arg is some options. If you omit this arg, the default behavior is to get the listing from the local cache, if it is up-to-date, and then cache the listing if it needs to be fetched from the server.
If InetMatchName finds a matching file or sub-directory, it stores the information (about that file/dir) in your REXX variable, and also returns an empty string. If it fails because there are no more matches, then it returns the string DONE. If it fails for any other reason, then it either returns some other message, or it raises some condition if you've set InetErr to do that.
Assume you ask InetMatchName to return information in your REXX variable named "Info". Here is the information that is returned:
Variable | Stores |
---|---|
Info | The file's name. |
Info.0 | The file's size. Directories have a 0 size. |
Info.1 | The file's creation date. Some FTP servers will not fill this in correctly. |
Info.2 | The file's attributes. Each bit of this value represents a different attribute. Use Reginald's BIT function to test each bit. |
Here is a complete example that list files and sub-directories in the current directory, printing the returned information about each.
/* Raise ERROR condition for any problem. */ InetErr = "ERROR" /* Get the next file/dir, and store information in the variable * "Info". Note: If there are no more matching files, then * "DONE" is returned. NOTE: A condition is not raised in * that event, even if we've set InetErr to raise a * condition for a problem. */ DO WHILE InetMatchName("Info") == "" /* Display the name. */ CHAROUT(, dirInfo) /* If it's a directory, display <DIR>. */ flag = BIT(dirInfo.2, 4) IF flag THEN SAY " <DIR>" ELSE SAY /* We have a real error here. */ CATCH ERROR CONDITION('M') END