Rediscovering CONVERTC Practical uses for a little-known tool
From "VS Workshop",  Access to Wang, April 1992
[ Prior Article ]     [ Return to the Catalog of articles ]     [ Next Article ]

Among the most powerful and least-used VS tools is the CONVERTC utility. CONVERTC - located in the USERAIDS or VSAIDS library of your system - is a flexible search tool that will also perform limited text conversions. Its capabilities include the ability to search for the occurrence or absence of text, numbers, or hexadecimal characters and perform conversions to the items found. While primarily designed for source file conversions, recent versions of CONVERTC can also process data files.

CONVERTC uses a parameter file that contains a list of search criteria and the corresponding actions to be taken. It uses this parameter file to review a file or series of files, performing any specified changes and placing the modified files in a new library. In some cases, the only output is a report showing where text items have been found.

Some VS users are reluctant to use CONVERTC due to the limited documentation and occasional inconsistencies in its output; CONVERTC is not perfect and its operation is unfamiliar. CONVERTC does not harm input files; the converted results are always placed in a new file at the location you specify. In spite of this, files created by CONVERTC should always be checked carefully before production use. I recommend that you retain backups of source files and use a source file comparison tool (such as Wang's COMPARE utility with the SRCDIFF option) to verify the results of your conversion.

The examples shown below should give you some idea of the power of CONVERTC and allow you to experiment on your own. I have used COBOL program conventions in the examples, but the process would be similar for any other language.

Getting started

CONVERTC is a USERAID, now supported by the United States Society of Wang Users (USSWU) as a part of their VSAIDS collection. You might already have an older copy on your system in a library named USERAIDS or USERAID; if not, contact USSWU for details on purchasing the VSAIDS collection or a single copy of the program.

The OPTIONS menu screen lists six options: create new list of changes (PF2), modify previously defined list (PF3), use old list of changes (PF4), special conversion options (PF5), run the DISPLAY utility (PF6), and exit. The first two choices allow you to create or change the parameter file mentioned above; a parameter file must be created before a CONVERTC operation can be performed. Press PF4 if you have already created a parameter file and are ready to process files using it. The special conversions item allows you to specify a user exit program, which accommodates special conversion needs by passing the text to a program you specify. Finally, the DISPLAY utility option can be used to conveniently view the results of the program.

The parameter file maintenance screen shows two columns: the Search options (on the left) define what text is to be found, while the Action options (on the right) specifies the actions to be taken. Typical search options might specify a search for combinations of known and unknown text; typical action options include changing text from one form to another or printing the line containing the text. Figure 1 lists the options available for the search and action options. The list of possible options may appear discouraging at first, but there are some very simple choices that can be effective for real-life purposes. Here are a few samples.

Example: Search for file input and output

Many programmers have some documentation of file usage across programs, including information on where records are created, updated, or just read. Many times this documentation has drifted out of date. A simple CONVERTC search can find this information by searching programs for occurrences of text, such as the programming language verbs used for file access.

A possible search to meet this need is shown in Figure 2. In this example, five COBOL verbs have be specified in the search. The action parameter (#) specifies that the occurrence should be printed. Note that two leading spaces have been included in the search specification; this filters out unwanted occurrences of the text (e.g. PERFORM 1000-READ-NEXT-INFIL), concentrating only on the actual text to be found.

Once the parameter file has been created, CONVERTC prompts for the files to be modified. Enter the file, library, and volume if one file is to be searched, or the library and volume if all files in a library are to be processed. Note that only an input file or library is necessary, since this parameter file contains only search and print actions - not conversions. The resulting print file is displayed at the conclusion of the search. The search criteria are also displayed on the last page, along with the number of occurrences of each item.

Example: Remove specific modification codes in source code

Modification codes in source files are often useful in determining the timing of changes to programs. Over time, though, the number of mod codes in a file may grow to the point where it is difficult to see specific changes. At some point it may be necessary to remove early mod codes so that more recent versions are more visible. A sample parameter file to perform this task is shown in Figure 3.

In the example, specific modification codes (DB860131 and DB860315) are being searched in columns between 73 and 80 - the location of COBOL modification codes. The action parameters specify replacement of the text with blanks. The pound sign in the action column tells CONVERTC to print the source line containing the search string after the conversion, recording the event of changing that line.

After specifying the search and action items and saving the parameter file, CONVERTC will prompt for the files to be examined; again, a single file or all files in a library may be processed. This time CONVERTC will request both input and output file locations, since text will be changed. When the conversion is complete, check the results shown in the listing and by reviewing the output file.

Example: List subroutine arguments

Suppose you wanted to find out the variable names used in calls to subroutines. These arguments usually span multiple lines, so conventional search tools such as FINDTEXT will not show all of the text - only the beginning of the call. For example, your source file might have the following text:

CALL "EXTRACT" USING KEY-ID REC-ID KEY-WS REC-WS KEY-DV REC-DV KEY-LN REC-LN.

You are interested in which of the many possible options of the EXTRACT subroutine are being used in your programs, but EXTRACT allows one or many arguments within the same call and the text can span many lines in the input file. To solve this sort of question, CONVERTC offers range limits, allowing you to activate and deactivate functions.

Figure 4 illustrates how range limits can be used to activate and deactivate a function. The first line specifies a search string that includes a call to the Wang SORTCALL subroutine. The related action when this string is found is a 1, indicating the start of a range; as before, the pound sign is used to print the line. Line two will print any lines in this range that do not include an asterisk in column seven - in other words, it will ignore comment lines. (Note that the underline character - not visible in this illustration - must precede the column range specifications.) Finally, line 3 specifies the end of range: a period, closing the subroutine call. (Naturally, the period could actually lie outside the called area.)

Use of the range functions in CONVERTC fools the program into thinking that you are performing a conversion, and an output file location will be requested when this parameter is used. Since the purpose is merely to search and report on text occurrences, specify a work library as the output and scratch the output files that are created.

Advanced uses

CONVERTC also has many more possible uses. These include hex changes to data files (recent versions of CONVERTC only), on-line review and editing of found text, evaluation of numeric information, searches for combinations of known and unknown text, commenting out source lines, and inserting text before the text occurrence. The on-line edit functions require some practice and should be attempted on test files first. If these choices aren't enough, write a user exit program that can perform the changes you need and use CONVERTC to search for the items.

A few sample parameter files may also be found in the library along with CONVERTC. These include specs to exchange COBOL code between the VS and IBM systems (files IBM and TOIBM) and a similar file for Unisys COBOL (BURROUGH). All of these files show advanced use of ranges and conversion of VS-specific numeric field definitions.

If you have a clever use for CONVERTC, drop me a sample so I can share with other readers.

Figure 1: CONVERTC Parameter File Options

Search options (left side)

Description	Value
Search for specific target string	'A'
Search for specific HEX target string	hh...
Search for combination of known and unknown substrings	'A'?'B'?'C'...
Search for a target string within limits   [column/column]   [string/string]   [column/string]   [string/column]	'A'[n1/n2] 'A'['a1'/'a2'] 'A'[n1/'a2'] 'A'['a1'/n2]
Search for non-occurrence of target string within limits	'A'_[n1/n2]
Search for numeric within limits	''9[n1/n2]