"LISMAK"   D. MC CUNE 11 AUG 1981  X2731  PPPL

THIS INTERACTIVE PROGRAM GENERATES ALPHABETIC LISTS OF "SYMBOL
NAMES" FROM FORTRAN SOURCE CODE.  A SYMBOL NAME IS THE NAME OF
A USER-DEFINED VARIABLE, ARRAY, SUBROUTINE, FUNCTION OR PARAMETER
IN THE FORTRAN SOURCE (FORTRAN-DEFINED NAMES SUCH AS "WRITE", "DO",
AND "CLOSE" ARE NOT INCLUDED).
     THESE LISTS ARE ALPHABETIZED AND MAY BE WRITTEN OUT TO 
SPECIAL OUTPUT FILES KNOWN AS "SYMBOL LIST FILES".  THESE FILES
HAVE THE FORM:

; FROM SYMBOL           TO SYMBOL            
; --------------------  --------------------
  <SYMBOL NAME #1>      <SYMBOL NAME #1>
  <SYMBOL NAME #2>      <SYMBOL NAME #2>
      ...
  <SYMBOL NAME #N>      <SYMBOL NAME #N>
; <USER REMARKS>

WHERE:   LINES BEGINNING WITH ";" ARE COMMENTS.
   <SYMBOL NAME #J> DENOTES THE JTH SYMBOL NAME; EACH SYMBOL NAME 
IS A 1 TO 20 CHARACTER NAME CONTAINING NO IMBEDDED DELIMITER 
CHARACTERS.  DELIMITER CHARACTERS ARE CHARACTERS WHICH SEPERATE
VARIABLE NAMES IN FORTRAN (AND INCLUDE ARITHMETIC OPERATORS).
THE FOLLOWING CHARACTERS ARE DELIMITERS: BLANK, TAB, ",", "=",
"+", "-", "*", "/", "(", ")", "'", DBL. QUOTE, ".", "<",">",
":",";", AND "!".  NORMALLY SYMBOL NAMES WILL CONSIST OF 
ALPHANUMERIC CHARACTERS ONLY.
   <USER REMARKS> ARE TYPED IN BY THE USER AT THE END OF THE
SYMBOL LIST OUTPUT FILE.

ONCE A SYMBOL LIST FILE HAS BEEN CREATED ON DISK IT MAY BE READ
BACK IN BY LISMAK OR APPENDED (EACH ENTRY INSERTED IN ALPHABETIC 
ORDER) TO A LIST ALREADY STORED IN LISMAK MEMORY.  MOREOVER, THE 
SYMBOL NAMES FROM SEVERAL FORTRAN SOURCE FILES MAY ALSO BE AMALGAMATED
INTO A SINGLE LIST IN LISMAK CORE MEMORY.  EACH NAME <SYMBOL NAME>
WILL OCCUR ONLY ONCE IN THE SYMBOL NAME LIST;  IF THE SAME NAME
IS ENCOUNTERED IN A FORTRAN SOURCE OR SYMBOL LIST INPUT FILE IT
WILL BE IGNORED:  MULTIPLE ENTRIES OF THE NAME WILL NOT BE MADE.

THE SYMBOL LIST FILES GENERATED BY LISMAK HAVE A NUMBER OF 
APPLICATIONS.  FOR EXAMPLE THEY CAN BE USED TO EASE THE TASK
OF CHECKING FOR NAME CONFLICTS IN TWO "INCLUDE" COMMON BLOCKS
ABOUT TO BE INCLUDED IN THE SAME SUBROUTINE.

HOWEVER, THE TASK FOR WHICH THEY WERE DESIGNED WAS NOT MERELY
TO AID PASSIVELY IN CHECKING FOR NAME CONFLICTS BUT TO BE 
USED ACTIVELY AS A TOOL FOR EDITTING FORTRAN SOURCE CODE.  WHEN
A SYMBOL LIST FILE IS FIRST CREATED, IT WILL HAVE BEEN OBSERVED
THAT THE ENTRIES IN THE "TO SYMBOL" COLUMN ARE IDENTICAL TO THE
ENTRIES IN THE "FROM SYMBOL" COLUMN.  BY EXITTING LISMAK AND USING
A SYSTEM EDITOR (SOS OR TEDI) THE ENTRIES IN THE "TO SYMBOL"
COLUMN MAY BE CHANGED.  THIS DEFINES FOR LISMAK A LIST OF SYMBOL
NAME **CHANGES** WHICH MAY THEN BE APPLIED TO ONE OR MANY FORTRAN
SOURCE FILES.
<*=*>
A SYMBOL LIST FILE WHICH HAS BEEN SO EDITTED MIGHT LOOK LIKE
THIS:

; FROM SYMBOL           TO SYMBOL
; --------------------  --------------------
  LUN1                  LUNIN
  LUN2                  LUNOUT
  XVAR                  TIMEA
; NAME CHANGES FOR "ZTEST.FOR"

THE OLD SYMBOL NAMES ARE IN CHARACTER COLUMNS 3 -- 22, AND THE
NEW NAMES ARE IN COLUMNS 25 -- 44.  THE NAMES MUST NOT CONTAIN
IMBEDDED DELIMITER CHARACTERS BUT THEY NEED NOT BE LEFT-
JUSTIFIED IN THEIR RESPECTIVE FIELDS.

AFTER A COMPLETE LIST OF SYMBOL NAME CHANGES HAS BEEN CREATED,
LISMAK MAY BE RUN AND THE FILE CONTAINING THE NAME CHANGES MAY
BE READ IN.  THEN, THE NAME CHANGES MAY BE APPLIED TO ONE OR
MORE FORTRAN SOURCE FILES.  THE USER WILL BE PROMPTED FOR THE
NAME OF BOTH THE INPUT FILE AND THE OUTPUT FILE.  IF THE SAME
NAME IS SPECIFIED FOR BOTH THE OUTPUT FILE WILL HAVE A HIGHER
VERSION NUMBER THAN THE INPUT FILE, THUS THE INPUT FILE WILL
NOT BE DESTROYED.

EVERY OCCURANCE OF A SYMBOL NAME IN THE "FROM SYMBOL" COLUMN
IN THE INPUT FILE WILL BE REPLACED BY THE CORRESPONDING ENTRY
IN THE "TO SYMBOL" COLUMN IN THE OUTPUT FILE.  NOTE THAT FOR
A CHARACTER SUBSTRING TO TO BE RECOGNIZED AS A SYMBOL NAME IT
MUST BE DELIMITTED BY DELIMITER CHARACTERS (OR BEGINNING OR END
OF LINE), SO THAT A CHANGE IN THE SYMBOL "LUN1" WILL NOT RESULT
IN THE CHANGING OF SYMBOL "LUN12" BECAUSE "2" IS NOT A DELIMITER
CHARACTER.  THUS THERE IS A CLEAR DISTINCTION BETWEEN THE CONCEPT
OF "SYMBOL NAME" AND OF "SUBSTRING".

WHEN CREATING A LIST OF SYMBOL NAMES LISMAK IGNORES EVERYTHING
THAT IS A FORTRAN COMMENT.  WHEN PERFORMING A SYMBOL NAME-CHANGE,
HOWEVER, COMMENT LINES ARE SEARCHED FOR THE SYMBOL-NAMES AND
WILL BE MODIFIED IF CHANGELING NAMES ARE FOUND.  THUS CAUTION
IS ADVISED IF VARIABLE NAMES THAT ARE ALSO VALID ENGLISH ARE
TO BE CHANGED.  IT HAS BEEN ASSUMED THAT MOST VARIABLE NAMES 
ARE NOT ENGLISH WORDS AND THAT THERE OCCURANCE IN COMMENTS IS
A REFERENCE TO THE FORTRAN VARIABLE WHOSE NAME IS BEING CHANGED.
A WARNING IS PRINTED OUT WHEN A COMMENT IS MODIFIED.

CERTAIN FORTRAN CONSTRUCTS ARE NEVER CHANGED, NAMELY:  QUOTE
STRINGS, HOLLERITH STRINGS, AND FORMAT SPECIFIERS IN FORMAT 
STATEMENTS (UNLESS THEY ARE OF THE "<VARIABLE NAME>" TYPE).

THUS IF A DEBUGGING TECHNIQUE WHICH INVOLVES THE PASSING OF A
NAME AND VALUE OF A FORTRAN VARIABLE TO A SUBROUTINE HAS BEEN
USED, AND THE NAME IS PASSED AS A QUOTE- OR HOLLERITH- STRING,
THE PASSED NAME **WILL NOT** BE CHANGED AND MAY BECOME OBSOLETE,
THOUGH THE PASSED VARIABLE ITSELF MAY HAVE ITS NAME CHANGED.
THUS THE FORTRAN LINE "      CALL PRIVAL(6HLUN1  ,LUN1)" WILL
BE CHANGED TO "      CALL PRIVAL(6HLUN1  ,LUNIN)" UNDER THE 
SAMPLE NAME-CHANGE FILE SHOWN ABOVE
--- WARNINGS ---

LISMAK IS A POWERFUL TOOL WHICH HAS BEEN SUCCESSFULLY EMPLOYED
A NUMBER OF TIMES IN MAJOR NAME-CHANGE OPERATIONS SUCH AS ARE
OFTEN REQUIRED WHEN COMBINING TWO LARGE FORTRAN SYSTEMS INTO
A SINGLE PROGRAM.  **BUT** CARELESS USE OF LISMAK CAN UTTERLY
DESTROY YOUR SOURCE PROGRAMS !!!  IT IS ADVISABLE TO THINK CAREFULLY
AHEAD AND WORK OUT A PLAN OF ATTACK BEFORE YOU MAKE ANY NAME-CHANGE
LISTS AND MODIFY ANY SOURCE FILES.  DO VARIABLES WITH THE SAME NAMES
IN DIFFERENT PROGRAMS HAVE THE SAME FUNCTION?  IT MAY BE ADVISABLE
TO CARRY OUT NAME-CHANGES IN MULTIPLE STAGES TO ASSURE FIRST THAT
THERE ARE NO NAME CONFLICTS AMONG VARIABLES WITH DISTINCT FUNCTION
**BEFORE** MAKING CHANGES WHICH GIVE VARIABLES WITH THE SAME FUNCTION
THE SAME NAMES.  AND, OF COURSE, IN MANY CASES MERELY CHANGING
A NAME WILL NOT RESOLVE A DEEPER CONFLICT OF USAGE.

HOWEVER, IN AN ATTEMPT TO MAKE USE OF LISMAK SAFER, A VARIETY 
OF WARNING AND ERROR MESSAGES ARE PROVIDED TO CHECK AGAINST THE
FOLLOWING POSSIBILITIES:
  (1) THAT A SYMBOL NAME CHANGE FILE CONTAINS DUPLICATE ENTRIES
  IN THE "FROM" COLUMN-- A WARNING IS GENERATED, THE 2ND AND
  SUBSEQUENT ENTRIES ARE IGNORED.
  (2) THAT ENTRIES IN A SYMBOL NAME CHANGE FILE DO NOT SPECIFY
  NAME CHANGES-- WARNINGS ARE GENERATED AND USER CONFIRMATION
  IS REQUIRED BEFORE THE NAME CHANGE LIST IS EMPLOYED ON A
  FORTRAN SOURCE FILE.
  (3) THAT THERE OCCURS IN THE "TO" COLUMN OF A SYMBOL NAME CHANGE
  LIST A NAME WHICH IS ALREADY IN THE "FROM" COLUMN-- WARNINGS ARE
  GENERATED AND USER CONFIRMATION REQUIRED BEFORE THE NAME CHANGES
  MAY BE APPLIED TO A FORTRAN SOURCE FILE.
  (4) THAT A NAME CHANGE LIST SPECIFIES MORE THAN ONE NAMES TO BE
  CHANGED TO A SINGLE NAME.  THIS IS NOT PERMITTED.  IF IT MUST
  BE DONE IT MAY BE DONE BY CREATING TWO NAME CHANGE FILES AND
  APPLYING THEM TO THE SAME FORTRAN SOURCE IN SUCCESSION.
  (5) AS A NAME CHANGE OPERATION IS APPLIED TO A FORTRAN SOURCE
  FILE THE FILE IS CHECKED FOR THE PRESENCE OF SYMBOL NAMES WHICH
  CONFLICT WITH ENTRIES OF THE "TO" COLUMN OF THE NAME CHANGE LIST.
  (I.E. THE LIST SPECIFIES CHANGING AN OLD NAME TO A NEW NAME BUT
  THAT NEW NAME IS ALREADY IN USE).  AN ERROR MESSAGE IS GENERATED
  AND USER CONFIRMATION IS REQUIRED TO PROCEED WITH THE NAME
  CHANGING OPERATION (FAILING CONFIRMATION THE OUTPUT FILE IS
  DELETED).
  (6) SINCE IN GENERAL THE NAME-CHANGE OPERATION RESULTS IN
  A CHANGE OF THE LENGTH OF LINES IN THE FORTRAN SOURCE OUTPUT
  FILE, A WARNING IS PRINTED WHEN A LINE LONGER THAN 72 CHARACTERS
  IS GENERATED.

IT IS PROBABLY A GOOD IDEA TO USE LISMAK FIRST JUST TO GENERATE
ALPHABETIC LISTS OF VARIABLE NAMES IN FORTRAN FILES WHICH ARE TO
UNDERGO NAME-CHANGE OPERATIONS, AND USE THAT INFORMATION IN 
PLANNING THE NAME-CHANGE SCHEME.

FOR FURTHER INFORMATION, OR COMMENTS, SUGGESTIONS, ETC. CONTACT
D. MC CUNE  X 2731.

TO GET YOUR OLD PROGRAMS BACK SEE THE OPERATORS...
