═══ 1. DH-Grep-PM Introduction ═══

General information about DH-Grep-PM 

Grep stands for "Get Regular Expression and Print" and is a text searching tool 
that was first developed for unix systems and has been ported to most operating 
systems. 

This PM version of grep is designed as a user friendly application.  It is 
designed for a multitasking environment and the search takes place on a 
separate thread to minimize the time that the wait icon is displayed. It will 
also run in a low priority idle mode to further reduce the impact the search 
has on the other active programs. 

The often cryptic command line options have been replaced with easy to use 
selections on the OS/2 menu bar. The output of the search is sent to a PM 
window and the user has easy access to all of the information that was found by 
the program. 

To reduce the overhead, the results are buffered until the search is completed 
and then written to the results window.  To indicate that the search is still 
active, the small icon at the left of the title bar will change color as an 
activity indicator. The color change depends on the search results, so it does 
not change at a fixed rate. 

This program will try to search binary files as well as text files, but it 
still tries to read "lines" from the binary file.  The program reads from the 
file until a new-line is found or 4096 characters have been read. 

If a new-line is not found and the program reads in 4096 characters there is a 
very good chance that a word will be split.  If that word is what you are 
searching for, the search will fail. 

Binary files can and often do contain null characters. The C/C++ string 
handling functions all use a null character as a string terminator and the 
"line" will be truncated at the first null character by those functions.  This 
means that the program may miss finding the search pattern in a binary file. 

I have added an option to replace null characters with spaces, but using that 
option will increase the search time. This option may be useful when doing a 
search in word processor files.  See BINARY Flag 

This version of grep does not support the full set of "regular expressions" 
that most of the command line versions of grep support.  It does support two 
wild-card characters.  The '*' character represents multiple characters and the 
character '?' represents one character. Thus a search pattern of "h*e"  would 
match both "house" and "horse". A search pattern of "ho?se" would also match 
both words. 


═══ 1.1. Binary Files ═══

This program will try to search binary files as well as text files, but it 
still tries to read "lines" from the binary file.  The program reads from the 
file until a new-line is found or 4096 characters have been read. 

If a new-line is not found and the program reads in 4096 characters there is a 
very good chance that a word will be split.  If that word is what you are 
searching for, the search will fail. 

Binary files can and often do contain null characters. The C/C++ string 
handling functions all use a null character as a string terminator and the 
"line" will be truncated at the first null character by those functions.  This 
means that the program may miss finding the search pattern in a binary file. 

I have added an option to replace null characters with spaces, but using that 
option will increase the search time. This option may be useful when doing a 
search in word processor files.  See BINARY Flag 


═══ 1.2. Regular Expressions ═══

This version of grep does not support the full set of "regular expressions" 
that most of the command line versions of grep support.  It does support two 
wild-card characters.  The '*' character represents multiple characters and the 
character '?' represents one character. Thus a search pattern of "h*e"  would 
match both "house" and "horse". A search pattern of "ho?se" would also match 
both words. 


═══ 1.3. File ═══

This menu selection opens a pull-down menu that contains selections to save, 
reload, or print the results of the search. The external editor is also on this 
menu. 


═══ 1.3.1. Save As ═══

The Save As selection opens a file dialog box that allows the user to enter a 
file name to use for saving the search results. If the user enters the name of 
an existing file, the utility will warn the user and ask for verification 
before writing the file. 


═══ 1.3.2. Load File ═══

The Load File selection opens a file dialog box that allows the user to select 
a file to load into the results window. 


═══ 1.3.3. Print On Default Printer ═══

The Print On Default Printer selection sends the contents of the results window 
to the default system printer. This is a raw dump of the results window to the 
default system printer and no attempt to format the text. 


═══ 1.3.4. Load Marked File In External Editor ═══

To use the external editor option, you must create a CMD file named 
EDIT_CMD.CMD that calls the editor you wish to use.  A minimal CMD file to use 
the OS/2 system editor E would contain the following line. 

e %1 

The CMD file should be located in the working directory. 

To use the external editor, the cursor must be on a line that contains the name 
of a file that was found during the search. After the cursor is on the line, 
either an ALT+W key press or a Right Mouse Button double click will launch the 
CMD file. The cusror can be moved to a specific line by a Left Mouse Button 
click. 

Note:  The RMB double click will not move the cursor to the desired line. 


═══ 1.4. Display ═══

This menu selection opens a pull-down menu that contains selections that affect 
how the results are displayed after the search has been completed. 


═══ 1.4.1. Font ═══

The Font selection opens a standard OS/2 Font dialog box that lets the user 
select a new font or change the font size for the displayed results.  This will 
allow the selection of any of the installed fonts. This option only changes the 
font in the main window. 

To change the font for the menubar or the information area below the main 
window, use the OS/2 font palette and drag and drop a new font on either area. 
The font selections are only saved when 'Save Settings' is selected. 

Note:  For the main window, font drag and drop does not always work correctly. 
The displayed font will be correct, but the wrong font size may be saved. 


═══ 1.4.2. Word Wrap ═══

The Word Wrap selection enables or disables the word wrap feature of the 
results window. 

Note:  The Word Wrap is a software word wrap and it does not insert hard 
       carriage return - line feed  pairs. 


═══ 1.4.3. Do not clear past results ═══

This selection disables the clearing of the results window when a new search is 
started.  It is useful if the user wishes to save the search results from 
several related searches. 


═══ 1.4.4. Reset to default colors ═══

The 'Reset to default colors' option restores the system default background and 
foreground colors.  To change the colors on the menubar, main window, or the 
information area use the OS/2 color palette and drag and drop a color 
selection.  When 'Save Settings is selected , the color selections are made the 
default colors. 

Note:  The background and foreground colors of the results window may be set 
       via drag and drop from the OS/2 Color Palette. The other colors may also 
       be changed, but only the background and foreground colors of the results 
       window are saved. 


═══ 1.4.5. Get file names in display ═══

This selection will cause the program to scan all of the results text and 
extract the file names and insert them at the top of the results window.  This 
provides the user with a list of file names that can be imported into another 
document or used by another program. 


═══ 1.4.6. Edit ═══

The results window is an MLE (MultiLine Editor) window and it has the basic 
OS/2 editor functions. This selection brings up a submenu with the available 
edit functions. 


═══ 1.4.7. Open Enter Search Parameters Immediately ═══

This selection will cause the program to open the 'Enter Search Parameters' 
window immediately after the program is loaded.  This is one of the settings 
that are saved when the user selects the "Save option settings in program INI 
file" menu item. 


═══ 1.5. Configure Search ═══

This menu selection opens a pull-down menu that contains selections to 
configure the search and the search parameters. 


═══ 1.5.1. Case Sensitive Search ═══

When this option is checked, the search is case sensitive.  The default is to 
ignore case in the search pattern. 


═══ 1.5.2. Set absolute flag ═══

When this option is checked, the search pattern is absolute. The two wild-card 
characters are treated as characters and not wild-cards. 

Regular Expressions 


═══ 1.5.3. Search Subdirectories ═══

When this option is checked, the program starts the search in the specified 
directory and searches in all subdirectories (recursively) for files that match 
the file mask. The default is to not search in subdirectories. 


═══ 1.5.4. Set NOT Flag ═══

When this option is checked, the search results will contain all the lines that 
do not contain the search pattern. This means that all of the lines in a file 
that does not contain the search pattern would be displayed in the results 
window. 


═══ 1.5.5. Set NAME Flag ═══

When this option is checked, only the names of files that contain the search 
pattern are displayed in the results window. 


═══ 1.5.6. Show Line Numbers ═══

When this option is checked, line numbers are included in the results window. 
This makes it easier to find the search pattern when the file is loaded into an 
editor. 


═══ 1.5.7. Use idle time priority for search thread ═══

When this option is checked, the priority of the thread that does the searching 
is reduced to the lowest priority. This priority only gets processing time when 
there is no other work to do.  This option allows the user to do a search in 
the background without a significant impact on the other active tasks. 


═══ 1.5.8. Files newer than Age Mask ═══

When this option is checked, only files with dates newer or equal to the Age 
Mask value will be evaluated. 

File Age 


═══ 1.5.9. Files older than Age Mask ═══

When this option is checked, only files with dates older than the Age Mask 
value will be evaluated.  Do not use this option with a Age Mask of 0, it will 
just increase the search time. 

File Age 


═══ 1.5.10. Skip known binary files ═══

When this option is checked, the utility will skip the following known binary 
file types by looking at the file extent. 

 .exe, .dll, .lib, .ico, .gif, .jpg 

 .zip, .inf, .hlp, .obj, .com, .res 

This utility will try to search for the search pattern in any file. If you know 
the extent of the files you wish to search, you should use that extent in the 
file mask to reduce the number of files that are searched. 

If you are not sure of the file extent and you know that you do not need to 
search any binary files, then this option should be selected. 

Binary Files 


═══ 1.5.11. Search for files only, no pattern search ═══

When this option is checked, the utility will just search for files that match 
the file mask and the other search parameters. The contents of the file will 
not be checked. 


═══ 1.5.12. BINARY Flag ═══

When this option is checked, the program will replace any null characters that 
are read with spaces. The file being searched is not modified, only the data 
that is read from the file. 

This option is intended for searching word processor files that have embedded 
null characters - such as DeScribe.  Using this option will increase the search 
time, so it should only be used when needed. 

Searches in binary files often fail. Many compilers will compress or condense 
text strings and a search will not find the altered text.  Many word processors 
also modify text so that addional information about formatting can be stored 
with the text. 

Binary Files 


═══ 1.5.13. Enter Search Parameters ═══

This selection opens a dialog box that has 4 entry fields. 

Search Path 

File Mask 

Search Pattern 

File Age 

All the fields except 'File Age' must be filled in or the search cannot be 
started. 

The 'Search Path' is checked to see if a valid path has been entered when the 
user clicks on the 'Ok' or 'Start' buttons. 


═══ 1.5.13.1. Search Path ═══

The search path consists of the Drive letter and the path without the file 
name. 

For Example:  C:\OS2\APPS\ 

The ending '\' is not required 

The searching of subdirectories is controled by another option setting under 
'Configure Search' on the menubar. 

Search Subdirectories 


═══ 1.5.13.2. Browse ═══

The Browse button opens a dialog box that will allow the user to select a 
search path.  This dialog box is similar to the normal File Dialog box , except 
that there is no way to select a file name.  The file names are still displayed 
to aid the user in finding the correct directory. 

File Mask 


═══ 1.5.13.3. File Mask ═══

The file mask represents the file or files to be searched without any path 
information. Wild cards are allowed. 

For Example: 
*.txt 
*.msg 
a?bc.txt 

Note:  In OS/2  "*" as a search pattern (not "*.*") means search ALL files. 


═══ 1.5.13.4. Search Pattern ═══

The search pattern can contain up to 512 characters. This version of grep does 
not support the full set of "regular expressions" that most of the command line 
versions of grep support.  It does support two wild-card characters.  The '*' 
character represents multiple characters and the character '?' represents one 
character. Thus a search pattern of "h*e"  would match both "house" and 
"horse". A search pattern of "ho?se" would also match both words. 

The use of the wild-card characters depends on the setting of the Set absolute 
flag 


═══ 1.5.13.5. File Age ═══

The File Age entry is used when one of the age limit options is used. The 
number can be in the range 0 to 999 days.  The lower range of zero is used to 
indicate today when the 'newer than' search option is checked. 

Files newer than Age Mask 

Files older than Age Mask 


═══ 1.5.14. Save option settings in program INI file ═══

When option is selected, the current configuration information, the size and 
location of the application window, the background and foreground colors, the 
current font and font size are saved in the file named DHGREPPM.INI. 


═══ 1.6. Start ═══

This selection on the menu bar is used to start the search.  The selection is 
inactive until the search parameters have been entered and while the search is 
in progress.  The 'Start' button on the 'Enter Search Parameters' dialog box 
performs the same action as the selection on the menu bar. * 


═══ 1.7. Stop ═══

This selection on the menu bar is used to stop the search.  The selection is 
inactive until the search is in progress and becomes inactive when the search 
has been completed or stopped.  A dialog box is displayed when 'Stop' is 
selected and the user is asked to verify that he wants to stop the search. *