Power-Programmierung/CD2.mdf/tools/tooldrv/namechng.doc

Text File | 1992-09-30 | 17KB | 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:
[phone]. 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.