Documentation for
PIKFILE.TPU
A Turbo Pascal Version 4.0 Unit
to Display a Directory and Allow
the User to Select a File for Processing

(c) Stephen C. McGough 1988
Madison, Wisconsin


Header information:
==============================================================================
{$R-,S+,I+,D-,T-,F-,V+,B-,N-,L+ }
Unit PikFile;

INTERFACE

Uses
Crt,
Dos,
Turbo3;

type
FilenameType = string[64];
FileArray = array[1..255] of FilenameType;

Var
Template : FilenameType;
Result : byte;

Procedure PickFile(Var Template: FilenameType; Attribute: byte; Var Result:
byte);

IMPLEMENTATION
=============================================================================

PikFile.TPU is intended to be used in programs which need to have the user
specify a file to be used for input. The procedure "PickFile" is called, with
two parameters passed to it: Template and Attribute.

(1) Template: this is the directory mask to be used to find the files from
which to choose, e.g. 'c:\tp\*.pas'. Its use is that same as for the "Dir"
DOS command.

(2) Attribute: this is a byte to specify which types of files, in addition
to the normal files, to include in the listing. Their use is explained in
the section on the "FindFirst" procedure in the Turbo Pascal V4.0 Owners
Handbook, page 408. You should "use" the DOS unit in your program and then
use the constants listed on page 408, which are declared in the DOS unit.
You may add or subtract the constants by name to get just the files you
want. For example, "Anyfile-Directory-VolumeID" would get all files except
those which are subdirectories, and the volume ID of the drive would not be
listed.


When it is called, PickFile saves the current screen and displays a sorted list
of all of the files which match Template's directory mask. If the directory
contains more than 60 files, the user may elect to see another screen full of
filenames, and so on until the correct file is found. The user may restart the
display at the beginning using the key, if he/she missed the desired file
when it was first shown and went on to another screen. After the user has made
a selection using the cursor arrow keys and the key, the original
screen is restored. If the user does not find the desired file in the chosen
directory, a press of the key will exit the procedure and set the Return
code to indicate this to the calling program, so that the program may take
appropriate action.

PickFile returns the complete path and filename in Template and a return code
in Return. Thus, Template may be used in an assignment statement in order to
open a file. Specific points about what to expect for each variable follow:

Template:

(1) The path which is returned is exactly as it was passed to the PickFile
procedure. Therefore, if no path was specified--for example, "*.*"--
indicating to use the current directory, no path will be returned, just
the file name.

(2) Some peculiarities arise with incomplete path specifications. For
example, "C:*" would return any file in the current directory which has
no file name extension. Two other examples of possible problems: "C:"
will return the code for a bad path specification, and "C:\" will
return the code indicating that there is no matching file.

Return:

The return codes are:

0 Normal execution and at least one file was found.
1 No file was found matching the directory mask.
2 The path in the directory mask was bad.
3 The user elected to not choose a file, using the key.
4 The disk drive door was open or no diskette in the drive.



CREDITS

Some of the routines used by PickFile are based upon the AllFiles library
developed by Neil J. Rubenking.