GUI ScreenIO for Windows

ScreenIO.com

FindFile

The FindFile API allows you to find files that match a given name (or pattern) and return the exact file name, date, time, and size of the file.  You can retrieve information about a specific unique file name, or sequentially retrieve information about all files in a directory, or all files that match wildcard DOS characters.

In addition to finding files, it is a quick way to get Date, Time, and Size of any known file.

The API is designed for ease of setup and use, where the first call will set up the parameters for any subsequent calls, such as when finding all files in a specific directory, or any time more than one file will be returned.

Some compilers support Find-File APIs, but those APIs are not Client/Server aware, and are typically more troublesome to set up.

PATTERNS: 

To search for files, you first specify a pattern.

The pattern consists of the a LOCATION element (Drive, Directory) and a NAME  element (file name).  

Location Elements, Drive and Directory, are in the familiar DOS format:  c:\Windows\,  or alternatively in UNC format: \\computer\share\directory\.

The Name Element is either a unique file name, or are partial name with Wildcard Characters (*?).

Searching for multiple files with "Wildcard" characters works similar to DOS wildcard characters.  Asterisk * means any number of any characters, and Question Mark ? means one occurrence of any character.

Examples of Patterns:

• F:\COBOL\*.COB
• \\Server\Software Development\COBOL\ACCT*.c??
• C:\Documents and Settings\All Users.WINNT\Documents\DrWatson\*.* 
• C:\Windows\*

FindFile Sessions

Calls for finding files in Windows typically consist of a Find-First call, optionally followed by a Find-Next call, and finally a Find-Close call. 

This is called a FindFile Session.  The FindFile API implements an entire session, not just one element.   

• A session starts with the first FindFile call.  It persists (remains open) till terminated.
• A session that returns a single unique file (no wildcard characters used) is automatically terminated.
• A session that uses wildcard characters persists until you request the next file, but no more exist.
• You can prematurely terminate a Session by setting FIND-CLOSE to true and making one last call.

Abandoning a FindFile session while FINDFILE-IS-ACTIVE is TRUE will leak one handle.  In the grand scheme of things this is not terribly serious, as these will all be released when your job terminates, but it is poor programming practice which can lead to resource starvation for long running tasks.

This API automates session management so that most of the time you do not have to worry about which type of call you are making.  Your first call will find the first matching file, and set up the arguments so that the next call will do a find-next.  Just remember to make a FIND-CLOSE call when finished if FINDFILE-IS-ACTIVE is True.

Call Arguments

Upon the first call you set FINDFILE-INITIALIZE to true, and load your Pattern.

Do not change the storage on subsequent calls to the same session.  The API will make changes to this area to shift from the Find First, to the Find Next mode.

If you want to use two (or more) different FindFile sessions concurrently, (perhaps to compare the content of different directories), then you must use different FINDFILE-DATA areas for each session.

Client/Server issues

The API may be used to access files on either the client or the server.  It defaults to Client.  To find files on the server:

This should only be done on the FIRST call.  The system will remember the target machine on subsequent Find-Next and Find-Close calls for this session.  

Files

Files available to copy to your system:

• FINDFILE.COB - COBOL copybook with arguments for this function
• WIN32API.COB - COBOL copybook common to all APIs and functions
• FINDFILE.ZIP  - Sample application for demonstrating FindFile API.

Usage

Parameters specific to this function

FINDFILE-INITIALIZE

This is an 88 level that you should set TRUE prior to your first Call.  (Only your first call of the session).

FINDFILE-PATTERN

The Pattern is where you place the complete Drive. Directory and File name (with or without wildcards) for the file you want to find.

See examples above.

FINDFILE-OPERATION

This will be set properly by virtue of the FINDFILE-INITIALIZE (above).  You should not have to directly manipulate it except when you want to terminate a FindFile session that is still active.  In this case set FIND-CLOSE to true.  See code sample above.

FINDFILE-STATUS

This field is output only.  It will be used to indicate whether a FindFile session is active or Not.  88s are supplied for Active and Not Active.

If you use wildcards in your FINDFILE-PATTERN, you will know if there are potentially more matching files because this field will have FINDFILE-IS-ACTIVE set true.  Note that the actual value of FINDFILE-STATUS will be L (Local) C (Client) S (Server) so that you are aware of where the FindFile session is running.  Do Not change this value.

The filler item contains the Windows Handle for this FindFile session, and you must not change it.  It is uses to distinguish one session from another.

FF-FILENAME 

This is the name of the file found.  (It does not include the path or directory).  It may include spaces, and will be terminated by low-values.

FF-DOSFILENAME

This is the DOS name in "8.3" format.  It is supplied only when the FF-FILENAME is a long name.  It will be terminated by a low value.

FF-FILEATTRS

This field is followed by a number of 88s which indicate characteristics of the file found.  The individual 88 names are self explanatory for the most part.  More than one 88 may be true.  Fir instance, a file may be Hidden and ReadOnly.  

FF-FILESIZE

This is the size in bytes of this file.

FF-CREATIONTIME, FF-LASTACCESS, FF-LASTWRITE

These three structures (and the subordinate fields beneath them) indicate the Date and Times for this file.

Of this the most useful is FF-LASTWRITE, which is what the DIR command or Windows Explorer displays.  This is the date/time the file was last changed.

The FF-LASTACCESS is not reliable on FAT file systems.

All Dates and Times are in Universal Coordinated Time (UTC).

You might find the GetSystemTime API useful in evaluating these times, as it will yield the Computer's Time in the same format.

WIN32API-PARMS - Used in all GSWINAPI calls

This argument is standard for all CALLs to GSWINAPI. It is used to select the desired API or function, and to return the status of the operation.

WIN32API-RC

Used to return the status of a call to GSWINAPI.  A value of zero is a failure, any other value indicates success.

Recommended usage is to test the 88-level value WIN32API to see if it worked, then to use the text error message to see why it failed.

WIN32API-ERROR-CODE

Error code that was returned by Windows.  This is not generally useful unless you have the Windows Platform SDK documentation available to you.

WIN32API-ERROR-TEXT

Plain-text error message that describes why the operation failed.

WIN32API-A through WIN32API-F

The number of these used varies depending on how many arguments are required by the desired function.  These are not used, but must be present because this CALL requires seven arguments.