VS Search Utilities Assessing four public domain USERAIDS
From "VS Workshop",  Access 87, November 1987
[ Prior Article ]     [ Return to the Catalog of articles ]     [ Next Article ]

In the life of nearly every VS administrator, there comes a time to search. Perhaps you need to find a particular phrase in a entire volume of COBOL files, or simply locate all occurrences of a phrase within a document. If you're a cheapskate like me, you'll appreciate knowing that there are Useraids that can perform most search needs; this month, we'll cover four of them.

Why Search?

If you don't do your own development, search utilities may be of little need to you. Most shops, however, write procedures to make packaged software meet their individual needs or to control logons. At some time, it might be necessary to find all occurrences of a volume name (shame on you for hard-coding it!) and change that name to fit new requirements. Perhaps you wish to know what programs in your canned Accounting system use the EXTRACT subroutine because you suspect that the vendor hasn't revised them since 1979. In all of these cases, search utilities can be of great benefit.

Rating search utilities

Before we begin, we should review some of the ways that search utilities can be categorized. Relevant parameters include:

1. FILE TYPE: Some utilities allow only certain types of files to be searched, such as 80-character consecutive source files, object files, or Word Processing files. Some recent utilities can select by file type or ignore invalid files.

2. CASE SENSITIVITY: Most public-domain utilities are case-sensitive; that is, they search for items exactly as you specify rather than ignoring whether the text is upper or lower case. In contrast, most of the purchased search utilities - such as SCANNER and SCANLIB - offer case sensitivity options. This can be important in many text searches, such as when Procedure files have been inconsistently capitalized. It may not be important, however, in a library of COBOL programs where all active program text must be capitalized.

3. SEARCH RANGE SELECTION: Some utilities offer means to limit the search to specific files. This can be accomplished through table selection, file name masking, or other means.

4. DISPLAY OF RESULTS: Most utilities offer a printed report of search strings found. Some also offer screen display or allow either or both.

5. STRING SPECIFICATION: Some utilities will search for several strings at the same time, saving time when several items must be found. Some also offer search string masking, similar in concept to file name masking explained in the December column (see ACCESS, December 1986, page 12); this might find a search string when it is "buried" between other items.

6. SEARCH POSITION: Some utilities allow specification of the limits of the search within the record area.

Searching source files: SCANSRC

The first utility we'll cover is SCANSRC, which searches for strings in source files, such as Procedure files or libraries of COBOL source files. SCANSRC accepts up to 12 search strings and searches files whose names meet the masking requirements specified, producing an abbreviated print file of the results of the search. SCANSRC uses GETPARM screens, so its operation can be controlled by a procedure; however, it must be run in foreground (e.g. on a terminal rather than submitted to the background queue) since it writes the name of the file being searched on the screen.

The first screen you encounter when running SCANSRC is the STRINGS screen. In addition to the 12 40-character search strings, you will also have to specify the length of the string area to be considered in the search, since SCANSRC is too dumb to figure this out and won't accept quotation marks.

After completing the STRINGS screen, you will be prompted for the range of files to be searched by the INPUT screen. Standard FILEDISP masking conventions work here, and you can enter as many masked names as you dare. Note that the file name must be specified as '?' if you wish to search the entire library. Press PF'16 when you have specified the last masked entry and the search will begin.

If you have specified a search range that includes files that are not 80-character consecutive files, SCANSRC will get confused and tell you so with a CORRECTION GETPARM to the INPUT screen. Your only recourse at this point is to specify a file of correct organization (I use a dummy file) and continue searching. A particularly annoying situation develops when you attempt to search a library that contains procedures and program files mixed together, since you must specify the file names exactly or suffer through all the invalid file specification. Hey, no complaining; you didn't pay for this turkey, did you?

When the search is complete, the NOFILES screen will tell you how many eligible files were found. You may then return to the STRINGS screen or exit the program. A modest print file awaits you, showing the file name and string found. Upon closer examination you will discover that SCANSRC searches until ONE of the search strings is located, then moves on to the next file. Again, what do you want for free?

Obviously, SCANSRC is of limited use in most shops. Its value lies in use in extremely limited circumstances, possibly where the print file will be reduced to a data file and processed in some automated manner. Fortunately, there are better tools available for more extensive searches.

Search for subroutine use: SCANOBJ

The SCANOBJ utility is similar in operation to SCANSRC, except its purpose is to search for section names in object files (programs). It is most typically used to identify subroutine usage in program files that you don't have source for, as in the case when you have purchased a packaged software application and did not get the source for that application. Before discussing SCANOBJ, however, let's review how programs are executed on the VS.

Most programming on the VS is done using high-level languages like C, COBOL, RPGII, or BASIC. There is often need when developing applications to perform a process many times and in many programs; for example, it is often necessary to EXTRACT the user's name and ID from the system. These processes are usually handled by subroutines - small program segments that perform specific functions and can be incorporated into the master program during the development process. Sometimes it is necessary to know what subroutines have been used in a program library; this is the purpose of SCANOBJ.

To use SCANOBJ, you must know the sections (subroutines) that you need to find. The SECTIONS screen is the first to appear, and it will accept up to 36 eight-character section names. The next screen to appear is the INPUT screen, where the masked file names may be specified. This screen is identical in operation to the INPUT screen in SCANSRC. Finally, the OBJCOUNT screen informs you how many occurrences were noted and allows you to search again or exit.

SCANOBJ has proved very helpful in locating subroutine usage in canned applications when operating system changes made some subroutines obsolete. Beyond such use, however, it is unlikely that most users will find much of interest in this program.

Search and modification: CONVERTC

The CONVERTC utility is intended to seek out text occurrences in procedures and program source files and change them, producing a new file. This process is typically necessary when you have hard-coded system-specific information in a number of procedures or programs and changes have occurred in the system. While it really doesn't belong with search utilities, text searching is CONVERTC's most powerful by-product.

Before using CONVERTC, you must create or modify a PARAMETER FILE, a file unique to this utility. The parameter file consists of two columns: the SEARCH column on the left, which specifies the search parameters; and the ACTION column on the right, which tells the system what to do with the item when it's found. Since CONVERTC is designed to change large amounts of program or procedure source files, the action column items are largely based on text processing requirements; however, a '#' in the action column will list the occurrence on a report.

To use CONVERTC for search purposes, run the program and press PF'02 at the OPTIONS screen to create a new parameter file ("list of changes"). You will then be presented with a screen consisting of two columns 38 characters wide and 22 rows deep. The required syntax for this screen can be shown by pressing PF'14. Note that search string must be enclosed in SINGLE quotes and that the search will be case-sensitive; if you suspect that alternate capitalizations have been used, you should prepare additional search column entries.

When the search has been defined, press (RETURN) and the PARMFILE screen will prompt you for the location of the output file. You may place the file anywhere you wish. The next screen to appear is the FILES screen. Here you may indicate a single file to be searched or leave the file name blank and search all files in a library. You may also note the OVERRIDE option at the bottom of the screen; this selects the language that the utility will select for. The OVERRIDE option would be used if we were converting a source library; here, we can leave it alone and search all files regardless of format.

The search begins when you press (RETURN) from the FILES screen. CONVERTC shows the number of files to be processed and the file currently in use. If any files do not appear to be source text files (80-character consecutive files), they will be bypassed. The results of the search are written to a report and the DISPLAY utility is invoked after the search to show this report.

The primary strength of CONVERTC as a search tool lies in its "wild card" search parameters. Sophisticated searches can be constructed that will find the occurrence or non-occurrence of text in specific areas, possibly ignoring unknown string information between known parameters. Unfortunately, these benefits are tempered by the restrictive file types handled, the poor quality of the report, the lack of GETPARM screens in key areas, and the case sensitivity of the search. Thus, the best use of CONVERTC is as it was designed: searching for and modifying program source and procedures that have been consistently structured.

Find it anywhere: FINDTEXT

As usual, I've saved the best for last. FINDTEXT is unquestionably the best search utility available in the public domain. With FINDTEXT, you may: search rapidly through a file, a library, or selected files in a library; search with or without case sensitivity; produce a print file, a screen display, or both; search in foreground or background; search in any type of file.

The INPUT screen is the first one seen. From here you specify a text string of up to 66 characters, the file or library to be searched, the display or print mode, and whether you wish a case-insensitive search or wish to select files within the library. If you have opted for file selection within a library, you will next see a list of the files in the library and must indicate the files to be searched by entering a non-blank element. CAUTION: all files are assumed to be skipped and pressing (RETURN) at this point begins the search - perhaps before you're ready. Note well that this file selection screen is NOT a GETPARM (grumble!).

When all selections have been made, FINDTEXT happily gobbles away. If you have a recent version (I'm looking at version 2.04.00), any type of file will be searched. In fact, about the only way you can get stopped is if you don't have rights to the file or the file is in SHARED or I/O mode.

In DISPLAY mode, you will be prompted each time the text string is found in a record. You may press (RETURN) to continue searching in the same file, or PF'01 to skip to the next file. If you have selected the PRINT option, all occurrences will be listed. In either case, the search will end with the EOJ screen, where the number of occurrences found will be shown. At this point you may return to the INPUT screen to search again or press PF'16 to exit the program. The return code of the program will be set to the number of occurrences found.

Note that this is the only utility we have discussed that can be run as a background job. This is because it has the necessary GETPARM screens to be completely proceduralized and also suppresses the screen displays if run as a background task.

The only complaint I have with FINDTEXT is that only one search string can be specified. This is not particularly important with a few items, but becomes more important when several searches are contemplated. The "wild card" elements of CONVERTC would be a nice addition, too. (Is anyone out there listening?)

Summary

Table 1 compares the four utilities we've discussed. You may use it to evaluate your own search needs or to analyze any search utilities you are considering purchasing.

That's all for this month. I hope your searches yield gold.

Items mentioned in this article:

• SCANSRC, SCANOBJ, CONVERTC, and FINDTEXT: All are Useraids, 'free' software contributed by users. Available through the International Society of Wang Users. Write to: ISWU Software Library, Wang Laboratories, Inc., One Industrial Drive, Mail Stop 019-350, Lowell, MA 01851-9971. (ISWU membership required.)

• SCANNER: A purchased scanning utility. For information contact Grossman Development Co., P.O. Box 85732, Seattle, WA 98155.

• SCANLIB: Another purchased scanning utility. For information contact Software Extraordinaire, 1419 8th Ave. W., Seattle, WA 98119.

• Other utilities: Undoubtably there are many more fine search products available. Please drop me a line with any information you have on such products.

Figure 1: Summary of Search Utilities

Attribute	SCANSRC	SCANOBJ	CONVERTC	FINDTEXT
File types allowed	80-char consec.	object (program)	80-char consec.	any
Case sensitivity selection	No	n/a	No (1)	Yes
Range selection	File or library name masking	File or library name masking	Individ. files Entire library	Table of files Entire library
Display of search results	Print only	Print only	Print or display (2)	Print, display, or both
String count	12	36	22 (3)	1 only
Limits to search area	No	No	Yes	No