Programmer 7500

home *** CD-ROM | disk | FTP | other *** search

/ Programmer 7500 / MAX_PROGRAMMERS.iso / CLIPPER / MISC / TLDR20.ZIP / NAMECHNG.DOC < prev next >

Wrap

Text File | 1992-10-01 | 16.8 KB | 463 lines

N a m e C h a n g e r Version 2.0 ─────────────────────────────────────── User's Guide ┌───────┐ ┌───────┐ │ (R) ──│ │ │─────────────────── │ ┌───────┐ │ Association of ConVal Software, Inc. │ │ │─┘ Shareware └──│ o │ Professionals ─────│ | │───────────────────── └───┴───┘ MEMBER N a m e C h a n g e r Version 2.0 ─────────────────────────────────────── User's Guide ┌───────┐ ┌───────┐ │ (R) ──│ │ │─────────────────── │ ┌───────┐ │ Association of ConVal Software, Inc. │ │ │─┘ Shareware └──│ o │ Professionals ─────│ | │───────────────────── └───┴───┘ MEMBER Copyright 1991, 1992 ConVal Software, Inc. All rights reserved. This program is produced by a member of the Association of Shareware Professionals (ASP). ASP wants to make sure that the shareware principle works for you. If you are unable to resolve a shareware-related problem with an ASP member by contacting the member directly, ASP may be able to help. The ASP Ombudsman can help you resolve a dispute or problem with an ASP member, but does not provide technical support for members' products. Please write to the ASP Ombudsman at: ASP Ombudsman 545 Grover Road Muskegon, MI 49442-9427 U.S.A. or send a CompuServe message via CompuServe MAIL to ASP Ombudsman 70007,3536. The ombudsman may be contacted by FAX by sending to the ASP FAX number: (616) 788-2765. In communication with the ombudsman please include a telephone number and/or FAX if available. TABLE OF CONTENTS Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 Features of NameChanger . . . . . . . . . . . . . . . . . . . . . . . . 7 Specifying the Files to be Examined. . . . . . . . . . . . . . . . . . . 8 Specifying the Naming Transform. . . . . . . . . . . . . . . . . . . . . 9 Getting Started. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 Notes and Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . 11 Page 6 Introduction ────────────────────────────────────── ConVal Software supports software developers. It provides tools and services to assist throughout the life cycle of a software project. NameChanger is a tool for changing names - ■ to enable the porting of code that would not otherwise run on the target platform (because of naming rules or collisions with existing applications ) ■ to allow easy conversion to one's current naming preference ■ to make source code naming style more compatible with Microsoft Windows conventions ■ to make source code naming style more compatible with IBM's OS/2 PM conventions NameChanger changes filenames and other symbols, throughout an application - source code and documentation files as well. It intelligently scans a variety of languages to incorporate the renaming so you merely need to recompile. The following discussion demonstrates the need for much more than just a global replacement tool to perform these tasks: ■ On one platform long file names using mixed upper and lower case may be OK, while the target platform may require shorter, all-uppercase. Thus filenames themselves may require renaming. ■ The filename "BONUS.COB" probably contains a COBOL subroutine named "BONUS". Other files probably contain references to the subroutine, for example, CALL 'BONUS' USING and also documentation about the "BONUS" subroutine. So internal references must obviously be changed too. ■ If the filename "ART" is to be changed to XXXART then an occurrence of PART-TYPE in a COBOL file could become PXXXART-TYPE. This change is definately not desired! ■ If the filename "ADDIT" is to be changed to XXXADDIT then Start Addit in a SQL file could be missed because of the case mismatch. ■ If the lengths of the source-text and replacement-text are different, then text could be shifted. This matters when we're already at the line length limit or in files with a fixed format. E.G. the "free-form" area of COBOL or FORTRAN and the sequence (or identification) area in columns 73-80. NameChanger meets these needs! Page 7 You may wish to use NameChanger to allow you to change your internal naming conventions to, say, the Hungarian notation, coined by Charles Simonyi of Microsoft. The notation requires a lower case prefix that describes data type, followed by a variable name whose first letter is capitalized. Some prefix examples are: ─────────────────────────────────────────────── b - boolean (0 or 1, usually an int) c - character i - int l - long ─────────────────────────────────────────────── For example: iHeapStatus is an integer variable whose name is HeapStatus. This convention is used widely by MS-Windows and OS/2 programmers. The NameChanger utility will enable you to readily change your naming convention. On mainframes where many applications share a production environment like CICS and IMS, naming collisions must be avoided. Use NameChanger on your product to make it conform to your potential client's needs. It could give you a sale you'd miss otherwise! Features of NameChanger ────────────────────────────────────── NameChanger reads a list of text files and makes a copy of each with its symbols altered according to a symbol rename list. This version has special processing logic for supporting the syntax of the following file types: Table 1: File types automatically supported FILE EXTENSION CATEGORY ────────────────────────────────────── .BAS BASIC .BAT Batch Files .C .CPP C and .H .HPP C++ source .CBL .COB COBOL .FOR FORTRAN .ASM Macro Assembler .MAK Make files .SQL .INP Oracle .PAS Pascal .PLI PL/I .REX REXX .DOC .TXT Text (ASCII) .PRG xBASE ────────────────────────────────────── All other types are processed as if they were ASCII text files. So NameChanger is a language and context-sensitive tool for changing naming conventions. Page 8 You will prepare a control file, called the file specification list, containing a list of files to be processed. Or, you may use a utility, CRE8FSL (see Page 9), to create a list of all files on a directory matching one of the file types in Table 1. You'll prepare a second control file, called the symbol rename list, with each line containing an "old name" a "new name" and a flag to tell whether the search for the old name is to be case sensitive. When you invoke the NameChanger program, you will specify a directory where the files containing the transformed symbols will be written. (Your files will not be changed in place!) Specifying the Files to be Examined ───────────────────────────────────── A File Specification List (FSL) file identifies to NameChanger the files to be read. It is a text file and may be created with any text editor. Each line must start in column one and contain exactly three columns - Line format, Maximum line length, and File specification. Place one or more spaces between the three columns. line format - F "Fixed length lines" Each line of the file is the same length. V "Variable length lines" The length of the lines may be different. Maximum line length - For fixed length lines, this is the actual length of each input line in this file. For variable length lines this is the maximum length to be written for any given input line after transforming symbols. The maximum line length must be <= 256. File specification - A DOS file specification. Examples: V 100 C:\SOURCE\MAINPGM.C V 100 C:\SOURCE\INCLUDE\INFILE.H V 120 D:\SAMPLES\DEMO01.TXT F 80 C:\COBOL\TEST1.COB F 80 C:\FORTRAN\MYPROG.FOR By listing all files in the File Specification List you will insure that the renaming is complete. Page 9 To ease the effort in preparing this file, a utility called CRE8FSL is provided for you. Given a directory, it will read all files in that directory, writing each filename matching a file type in Table 1. Example 1: This causes CRE8FSL to create a list of all files in directory C:\SOURCE with file extensions in Table 1 and write them to NAMEC.FSL. CRE8FSL C:\SOURCE NAMEC.FSL Example 2: This causes CRE8FSL to create a list of files on the C root directory. CRE8FSL C: NAMEC.FSL Example 3: This causes CRE8FSL to create a list of all files on three different directories (and different drives) CRE8FSL C:\BASELINE C.LST CRE8FSL D:\CHANGES1 D1.LST CRE8FSL D:\CHANGES2 D2.LST COPY C.LST+D1.LST+D2.LST NAMEC.FSL Specifying the Naming Transform ────────────────────────────────────── We need to define the renaming rules. This input to NameChanger is a Symbol Rename List (SRL) file. It contains the rules to be followed in changing "old symbols" to "new symbols". Use a text editor to create this file. Start each entry in column one and place exactly three columns on each line - Case code, Old symbol and New symbol. Case code - I when your want NameChanger to look for the Old symbol regardless of the case of each letter. (both comparands are raised to upper case before the comparison) - S when you want NameChanger to have an exact match on the Old symbol before it will replace it with New symbol. Old symbol One to 31 characters. A valid symbol for the language being scanned. For case code I, this may be entered without regard to case. (It doesn't matter how you enter this.) For case code S, enter the old symbol in upper/lower case. The symbol will be replaced only when matched exactly. New symbol One to 31 characters. A valid symbol for the language being examined. The case of this entry is important, since this will be used as-is when making replacements. Page 10 Example: Change "CALCDIST" to "Calculate_distance" regardless of case. (So Calcdist, CaLcDisT, and CALCDIST would all be transformed) Change "Help_A" to "HelpEditError" but perform case-sensitive matching. Change "RNDVAL", to "RandomNumber" performing case-sensitive matching. I CALCDIST Calculate_distance S Help_A HelpEditError S RNDVAL RandomNumber Getting Started ────────────────────────────────────── Prior to running NameChanger, create the list of files to be examined (see Page 8) and the symbol rename list (see Page 9). The program requires CONFIG.SYS to contain FILES=20, or more. The general command line syntax for running NameChanger is: NAMEC [?] /OUTDIR=xxx [fsl srl msg] where ? is used to request help with using NameChanger. xxx is a path identifying where to put the output files after the renaming. Note: The output files from the processing must not already exist in this directory. fsl is a file specification for the input file containing file specifications for each source to be processed. If omitted, this defaults to NAMEC.FSL. srl is a file specification for the input file containing the symbol rename list. If omitted, this defaults to NAMEC.SRL. msg is a file specification for the output file of run statistics. If omitted, this defaults to NAMEC.MSG. Example 1: Take all the defaults. NAMEC /OUTDIR=C:\TEMP The two control files (NAMEC.FSL and NAMEC.SRL) must be in the current directory. This will read file specifications from NAMEC.FSL and will get the symbol rename list from NAMEC.SRL. Messages will be output to NAMEC.MSG. The copies of the renamed files will be generated to the C:\TEMP directory. This directory must already exist and none of the files to be generated must exist (as a safety precaution). Page 11 Example 2: Override the location and naming of the control and message files. NAMEC /OUTDIR=D:\NEWNAMES C:\FILESPEC.LST OLDNEW.CTL MESSAGE.LST Here files will be written to the D: drive in the NEWNAMES directory. Also, the standard file names and locations have been overridden. Although the above is shown as two separate lines, you would type it all in at the DOS prompt and press enter once. NOTE: All parameters are positional. So, to override the last one, you must supply the defaults for the others. That is, none may be omitted prior to the one you wish to override. Notes and Restrictions ────────────────────────────────────── 1. The input files must be text files with each line terminated by a line feed alone or a carriage return and line feed. 2. COBOL, FORTRAN, and PL/I are assumed to be fixed length, 80 character lines. Data in columns 1-7 and 73-80 of CBL and COB, 1-6 and 73-80 of FOR, and 73-80 of PLI file types is copied as is. No symbol translation is used for these ID, sequence and comment columns. 3. If you get the message "Insufficient memory", try reducing the scope of the processing. This may mean limiting the file specification list (FSL) entries to only those files used by your application and/or limiting the symbol rename lists (SRL) entries and making multiple passes to rename all symbols. 4. Only the first 31 characters of a symbol are retained. 5. Filenames and symbols must be consistent with the symbol naming convention for each source file type. So the restriction means that if the following is a fragment from a .C file, a renaming would not be performed for items c and d below, even though these are valid DOS file names. This is because the names are not valid C symbols. a. avg_value = get_avg ( list ); OK b. fp = fopen ( "C:\\TEST.dat", "r" ); OK c. fp = fopen ( "87tax.dat", "w" ); starts with a digit d. strcpy ( fspec, "A:$budget.trn" ); starts with $ Page 12 6. If a filename to be processed is also a language keyword you use (like extern.bat if you use C) then all occurrences of that symbol (extern in this case) will become uppercase in all the C files processed. So exclude files like this from NameChanger processing or rename them first. 7. String literals may contain tokens of no more than 99 characters each. 8. Whenever a symbol is replaced by a longer symbol and there are sufficient trailing blanks on a statement, then the replacement will occur on the same statement. But when no more space is available on the current statement, a new statement will be created. You will be notified of this by a message that "statement number nnn had to be split". Since this process duplicates the sequence number field of the original statement, you may need to make manual changes in these cases. 9. In a single invocation of NameChanger, the filenames in the file specification list (FSL) must be unique. Thus MYPGM.C and MYPGM.TXT cannot be processed in the same run. 10. For variable length file types, trailing blanks on lines are not copied to the output. End of NameChanger Documentation.