Home

EDITOR USER MANUAL Version 2.2

Contents

1. SCRIPT FILE TO CREATE THE EDITOR EXECUTABLE f A gt Select FORTRAN compiler 4 5 Supported compilers include 6 cf77 Cray 90 Sun g95 Gnu gfortran Gnu ifort Intel 7 pgf77 Portland Group xlf IBM 8 9 setenv FCOMP gfortran 10 fe gt Get files from home directory 11 if e libnmlst a cp nmlst libnmlst a 12 Hfo gt If necessary create the directory editor2 2 13 if e editor2 2 mkdir editor2 2 14 o gt Create the change deck 15 rm f chgedit 16 cat lt lt EDF gt chgedit 17 define FCOMP 18 delete par 10 11 19 parameter k1 1000 k2 100000 k3 2000 k4 2000 k5 2000 20 1 k6 128 k7 1000 k8 1000 k9 4000 21 EOF 22 Create the input deck for EDITOR and execute 23 rm f inedit 24 cat lt lt EOF gt inedit 25 editpar inname edit22 chgdk chgedit safety 0 4 26 idump 1 job 3 ipre 1 inmlst 1 iupdate 1 iutask 0 27 ext f branch editor2 2 xeq xedit22 INSTALLING EDITOR 48 28 compiler FCOMP makename makeedit 29 c coptions debug 30 coptions optimise 31 Llibs libnmlst a 32 EOF 33 chmod 755 xedit22 34 xedit22 36 make f makeedit 38 rm f inedit output editlp chgedit chgedit m libnmlst a On line 9 of the first segment t
2. If necessary create the directory DIRECTORY 12 if e DIRECTORY mkdir DIRECTORY 13 a ag a a gt Create change deck 14 rm f changes 15 cat lt lt EOF gt changes 16 ident changes 17 delete par 3 18 parameter idim 100 jdim 100 kdim 100 19 read CHANGEDECK 20 EOF Zl 22 SS gt Create the input deck for EDITOR and execute 22 rm f inedit 23 cat lt lt EOF gt inedit 24 editpar inname SOURCECODE chgdk changes 25 gt ibanner 1 job 3 idump 1 inum 0 ipre 1 26 inmlst 1 iutask 0 iupdate 1 ext f 27 branch DIRECTORY makename MAKEFILE xeq EXECUTABLE 28 compiler COMPILER coptions debug 29 Libs LIBRARIES 30 EOF 31 chmod 755 xedit22 32 xedit22 33 i gt Tidy up directory 34 rm f editlp inedit output xedit22 changes changes m A softcopy of merge_precom s may be found in the file edit22 tar downloaded from the EDITOR website http www ap smu ca dclarke editor There are a three differences of note between merge s and merge_precom s First the second segment creates the directory DIRECTORY in anticipation of precompiled subroutines 2 5 Second in the now third segment lines 17 and 18 have been added which replace line 3 of a deck named par with a parameter statement setting idim etc to 100 This illustrates a st
3. Expecting a Boolean and or or If an EDITOR if define statement lists more than one macro these macros must be separated by an and or an or INOREX ERROR 17 Expecting a Boolean eq or ne An if alias statement must have either an eq or a ne in the fourth field INOREX ERROR 18 Dangling endif statement More endif statements than the number of pending if statements have been discovered All endifs must have a corresponding if statement appearing before it in the deck INOREX ERROR 19 Too few endif statements in previous deck At least one if statement was not closed by an endif statement by the time the previous deck was closed All if statements must be closed by an endif statement before the next deck begins This message is placed immediately after the deck statement of the deck immediately following the deck with the unbalanced if statement s ERROR MESSAGES 56 LIST ERROR 20 Unbalanced parentheses A FORTRAN statement with an argument list if computed goto etc has unbalanced parentheses This FORTRAN syntax error is only reported when it interferes with the desired preprocessing e g looking for targets at the end of an if statement MERGE ERROR 21 Expecting a character expression See ERROR 3 MERGE ERROR 22 Reference made to an undefined deck A MERGE edit insert delete or replace has been issued which re
4. 3 4 User sets DIRECTORY SOURCECODE 5 7 if e xedit22 cp dclarke editor version2 2 xedit22 8 fe gt Tf necessary create the directory DIRECTORY 9 if e DIRECTORY mkdir DIRECTORY LQ RASS Aaa Keane tees a gt Create the input deck for EDITOR and execute 11 rm f inedit 12 cat lt lt EOF gt inedit 13 editpar inname SOURCECODE ibanner 1 job 6 idump 1 ext f 14 branch DIRECTORY 15 EOF 16 chmod 755 xedit22 17 xedit22 18 Tidy up directory 19 xm f editlp inedit output xedit22 A softcopy of split s may be found in the file edit22 tar downloaded from the EDITOR website http www ap smu ca dclarke editor The first segment retrieves xedit22 from the user s home directory if needed The second segment prepares the input deck for EDITOR appropriate for splitting a source listing In addition to the general namelist parameters described in 32 5 two of the namelist parameters used to control PRECOM are also used by SPLIT These are described below parameter description default SPLIT job 6 branch character 32 string indicating directory in which blank separate files are written ext desired extension for files character 8 gt src 43 8 CONCAT Concatenating files EDITOR s CONCAT goes beyond the UNICOS utility cat by bringing together all files with the same specified extension located in the speci
5. 44K 9 akak k ak ak ak ak ak AAAI 3K 3K K K K RRR ACI ACA ACA I I A A KK 21 21 21 21 KKK KK K K K K K 10 cx x Char operations prevented parallel directives from being issued 11 cx I O prevented parallel directives from being issued 12 ck ak ak ak ak ak ak ak ak aK aK aK AAAI III I I CCCI K KKK K K 2k 2k 2k 2k 25 Example 3 Occasionally the EDITOR autotasker needs some help auto scoping a nested loop On line 7 in the example below the variable ar is indexed by mm rather than the outer loop index ny and is assigned a value which depends on some other element of ar Thus ar would be scoped as private and since line 7 is then a reduction on a private variable EDITOR declares the loop non parallelisable 1 do 40 ny 1 nyz 2 mi m0 2 ny 1 nxz 3 ni n0 2 ny 1 nxz 4 do 30 nx 1 nxz 5 mm m1 nx 6 nn n nx 1 7 ar mm ar nn 8 30 continue 9 40 continue However for every value of ny there is a unique value of mm and thus mm is really a ghost of ny Hence ar should actually be scoped as a shared variable and since a reduction on a shared variable does not inhibit parallelism this loop is parallelisable EDITOR is not sophisticated enough to determine this on its own We can help EDITOR by scoping such variables manually using the c shared and c private commands new to Version 2 2 inserted immediately before the loop to be scoped Thus the previous example can be scoped properly by inserting
6. and their corresponding origins to regain the order that the writer may have originally intended Examples of origin and target statements are as follows 1 do 10 i 1 imax 2 sate 3 go to 20 4 Laa 5 20 continue 6 eae 7 10 continue Lines 1 and 3 are origins while lines 7 and 5 are their respective targets TARGET can recognise virtually all FORTRAN structures in which origins and targets may lurk These include 1 nested do loops with numbered targets do 100 i 1 imax do 100 j 1 jmax 100 sae 2 go to statements go to 20 20 kss 3 computed go to statements go to 10 20 30 i 10 RF 20 30 4 if statements if j eq 1 go to 10 20 i 10 20 5 computed if statements if 10 20 30 x 32 FORTRAN TIDY UP 33 6 i o statements write print encode read decode open write 6 1000 x 1000 format f 5 2 read lu end 20 err 100 x 20 100 gi open unit lu file infile status old err 10 form unformatted 10 As mentioned TARGET may be instructed to convert all do enddo structures into targeted do loops TARGET will scan each program module i e deck program function subroutine for origin and targets and reassign the numerical values of the labels so that the targets not the origins appear sequentially with a specified increment between each consecutive target Three levels of targets are identified and are resequenced independently All do loop and goto targets includin
7. c shared ar immediately before line 1 Once ar is classified as shared the reduction in line 7 no longer inhibits parallelism and EDITOR inserts the directives PRECOMPILING SOURCE CODE 17 cmic do all private ny m1 n1 nx mm nn cmic 1 shared ar nyz m0 nxz n0 cmic 1 autoscope immediately before line 1 If more than one variable is to be scoped manually they can be put in the same argument list separated by commas cxshared x y z with spaces optional If there are too many variables to fit on a single line close the list with a close parenthesis then begin a new line immediately following As many c shared and c private lines may be inserted above the loop as needed but there should be no FOR TRAN statements including comments among the c shared and c private statements nor between the last c shared or c private statement and the opening line of the loop Example 4 The EDITOR auto scoper can fail if a goto statement appears within the nested do loop structure If a goto statement redirects execution to somewhere else within the loop parallelism is not affected and multi tasking is desirable However if execution is taken outside the nested loop structure parallelism is destroyed and the loop should not be multi tasked The EDITOR auto scoper has not been endowed with the ability to distinguish where execution is redirected and so blindly scopes the loop In this way the EDITOR auto scoper is per
8. be shared since its first appearance on line 6 is not to the left of an equals sign If vp is in fact shared there is no need to intervene Conversely if vp is private line 1 in the example below assures that it is scoped as such 1 c private vp 2 do 60 j j1 j2 3 do 20 i i1 i2 4 vtmp i v2 i j vg2 j 5 20 continue 6 call x3zc1d vtmp vp 7 do 30 i i1 i2 8 v2star i j vp i qty i 9 30 continue 10 60 continue There is still a potential trap however Normally local variables within a subroutine are considered private for the purpose of multitasking loops that contain calls to that subroutine This is as it should be However if any of the subroutine s local variables are placed in common or equivalenced to variables in common this will cause those variables to act as though they were shared and this invariably leads to incorrect and irreproducible results that are notoriously difficult to dig out with a debugger Unless you know such constructs will not cause conflicts it is best to avoid calls to routines that use common blocks inside a loop you wish to micro task or avoid micro tasking such a loop altogether 2 4 Splitting a source code generating a makefile For code developers who prefer to work with a single master file containing all the program modules UNIX often poses a dilemma Two useful UNIX facilities MAKE and DBX work best if the source code is split into individual files one for each pro
9. indicate segments of the script file which will probably have to be altered every time the script file is used After the header listing the various compiler options the first segment of precom s copies the necessary files in this case just the edit22 EDITOR Version 2 2 executable to the present working directory Note that the UNIX phrase if e on line 21 ensures that the named file will not be retrieved if it already exists in the pwd The second segment creates a directory on disc into which all source files split from the master code during precompilation 2 4 and all corresponding object and listing files are placed should this option be used The third segment is where the input parameters for EDITOR are specified Input parameters are read in by a namelist as discussed in 32 2 Specifying the parameters in the namelist editpar is how EDITOR is controlled In the example DIRECTORY SOURCECODE and all words in allcaps have to be specified by the user Note that the sentinel is preceded by a backslash 1 This prevents the script file from interpreting the as a control character and instead treats it as an ASCII character to be passed without the leading backslash to the text file inedit There are 46 valid namelist parameters in editpar but only 21 are relevant for precom piling source code These include six general parameters which all or most EDITOR jobs use and 15 additional parameters peculiar to P
10. 67 c oto ME e 8 2 2 69 c 10 implicit none 16 character 24 tod 21 common com tod 71 6c T2 CR EEE T3 Cc 74 write 6 2000 tod 79 2000 format Time of day according to Portland Group s PGF77 is a 85 return 86 end 87 c 89 c 4 1 4 2 4 3 4 40 4 4 6 90 c 91 subroutine write2 106 return 107 end In this example the EDITOR definitions are used to account for the differences in system calls for different compilers e g lines 12 20 in the master code They may also be used to tailor a code so that the compiler will generate a binary code optimised for the problem to be solved For example if the master source code is one which computes self gravitating hydrodynamical flows and it has been determined that self gravity is irrelevant PRECOMPILING SOURCE CODE 9 to the problem at hand one does not want to waste memory by declaring gravitational variables nor does one want to perform the computations necessary to evolve the unwanted gravitational potential EDITOR definitions may be used to eliminate those portions of the code peculiar to the self gravity feature thereby streamlining the code for a non self gravitating problem Note the two uses for alias macros illustrated in this example Aliases can be used to select the module to which execution is passed without having to change the body of the source
11. The last thing a curator of a large code wants is to have multiple versions of the same code to upgrade for every change The precompiler in EDITOR will allow these disparate versions to be merged into a single master code and thus upgrades need be implemented only once EDITOR considers a source code as being made up of separate decks a throw back from the days when computer programs consisted of decks of cards which may or may not be grouped into designated groups There are two types of decks that EDITOR recognises Ordinary decks normally consist of individual program modules such as subroutines functions and the main program Common decks are pieces of code which are to appear verbatim in one or more ordinary deck s Common decks can be thought of as EDITOR s answer to include statements which is a common though not ANSI standard extension of many FORTRAN compilers Normally common decks consist of common block definitions which are required by more than one program module Common decks could also be used as a way of in lining a segment of code into more than one place throughout the master code The first thing a user should do in preparing a source code for EDITOR is to insert deck and cdeck statements at the beginning of all source code modules The syntax is as follows cdeck deckname xcd deckname PRECOMPILING SOURCE CODE 4 deck deckname dk deckname where deckname is a user designated n
12. claimer on page iii Version 2 1 is available as part of the ZEUS 3D tar file zeus35 tar gz available at http www ica smu ca zeus3d including a user manual with instructions to install and use EDITOR on the user s home platform EDITOR is designed for source code written in FORTRAN although some of its func tionality is independent of the contents of the ASCII text it manipulates It was born in part out of the author s frustration in porting software from CTSS to UNICOS in 1988 when the NCSA switched the operating system on its Cray machines For those familiar with the CTSS environment EDITOR was initially designed to mimic the CTSS precompiler HIS TORIAN much of whose functionality was not carried into MPPL the first precompiler under UNICOS Since then EDITOR has blossomed into a rather sophisticated package in excess of 13 000 lines of FORTRAN capable of a variety of text manipulations Each of these functionalities shall be referred to as a job of which there are seven in this release These include 1 precompiling source code including inserting modules e g common block declara tions into source code selecting source code to be compiled replacing namelist statements and their associated reads writes with calls to subroutines in a portable library micro tasking nested do loops and splitting up the source code into modules PRECOM 2 2 generating a multi columned source code listing complete with a tabl
13. gt Create the input deck for EDITOR and execute 15 rm f inedit 16 cat lt lt EOF gt inedit 17 editpar inname SOURCECODE outname OUTNAME 18 ibanner 1 job 3 idump 1 inum 0 ipre 0 chgdk changes 19 EOF 20 chmod 755 xedit22 21 xedit22 22 fe gt Tidy up directory 23 rm f editlp inedit output xedit22 changes changes m A softcopy of merge s may be found in the file edit22 tar downloaded from the EDITOR website http www ap smu ca dclarke editor The first segment retrieves xedit22 from the user s home directory if needed You could add lines here to retrieve the source code and change deck from their home directory as well The second segment generates the change deck to be merged with the master file The script file will create a disc file called changes after it has removed any such disc file which may already exist Thus don t run this script file verbatim within a directory in which there is a file called changes that you can t live without The file changes contains the inert ident command followed by a read command which copies the contents of the user supplied file CHANGEDECK with the changes required to the master file onto the file changes Finally the third segment creates the input deck for EDITOR appropriate for the merge being performed and then executes EDITOR In addition to the general namelist parameter
14. The number of variables to be scoped in the nested do loop structure being micro tasked is more than can be accommodated by EDITOR as compiled Either reduce the number of variables being used in the offending do loop or recompile EDITOR with a larger value for k9 MERGE ERROR 48 Too many nested reads Like the call statement as many as 10 read statements may be nested Since it is unlikely that more than 10 nested reads would ever be deliberate this is probably caused by a closed loop That is change deck 1 reads change deck 2 which reads change deck 3 which reads change deck 1 or something to that effect ERRMSG ERROR 999 Unspecified error No guidance other than to say this message should never come up A 3 Warnings In this release there is only one warning message per se and this is completely harmless It is echoed to the user s CRT and is not placed into any of the output files TARGET WARNING Increment for deck deckname reduced from 211 to 22 If the number of targets found in the current module exceeds ienddo ibegdo inc where ienddo ibegdo and inc are namelist input parameters chosen by the user see 5 1 then the user supplied value for inc is reduced until the number of targets is less than ienddo ibegdo inc If choosing inc 1 still doesn t do it then error message 43 or 44 or 45 will result Note that the reduction of the value of inc applies to the current mod
15. in another Without deleting any lines in edit22 add your system dependent changes to edit22 Make sure each addition is bracketed with INSTALLING EDITOR 47 if def FCOMP endif FCOMP using the other compiler options CF77 GFORTRAN etc as a template It may be that some of the compiler dependent calls in edit22 GFORTRAN f worked just fine for your compiler Find these by searching for if def GFORTRAN and add your compiler name to the list of compilers in the if def statements surrounding the seg ments of code that work for your compiler Thus change if def GFORTRAN for if def GFORTRAN or FCOMP etc Step 5 From the directory editor open edit22 s described in 9 2 and for compilers other than gfortran replace gfortran in line 9 with the desired compiler Then type csh v edit22 s which creates your final working version of xedit22 replacing the temporary executable created in step 1 and leaves it in the directory editor You are now ready to go 9 2 The script file edit22 s The script file edit22 s used in the previous section to install EDITOR serves as a good example of how the author uses EDITOR in practise For the purposes of this discussion the file is reproduced below with an electronic copy of the same file in the directory editor of edit22 tar downloaded from http www ap smu ca dclarke editor 1 H 1 4 2 p P P 4 2 gt p 2
16. inmlst 1 gt 1000 0 gt no microtasking attempted 0 1 gt insert Cray microtasking directives cmic in front of parallelisable nested do loops 2 gt insert OpenMP parallelisation directives c omp in front of parallelisable nested do loops 1 2 gt same as 1 2 except directives are inserted before single non nested loops too 0 gt PRECOMpiled source code is dumped to one file 0 1 gt PRECOMpiled subroutines stored to separate files Subroutine is written only if different from version on disc or if it doesn t exist on disc character 32 string indicating default directory in blank which to write subroutine files desired extension for files character 8 AE name of makefile to be created character 16 If blank blank no makefile is created The files compiled by MAKE are those in the directory branch overrides default compiler used by MAKE to compile see chart inname character 16 The default compiler depends on how EDITOR itself was compiled which depends on which EDITOR compiler macro was defined in edit22 s There is no requirement that EDITOR create the makefile for inname with the same compiler with which it was compiled The compiler that compiled EDITOR just serves as a reasonable default macro default compiler origin none gfortran GNU CF77 ct 77 Cray F90 90 f 77 SUN G95 g95 GNU GFORTRAN gfortran GNU IFORT ifort Intel PGF77 pgf77 Portland Group XLF x1f
17. y array iret real x in y jn array in jn go to 40 10 iret 10 continue do 30 j 1 jn do 20 i 1 in array i j x i x x 2 1 2 0 x i y j 2 y j 2 20 continue 30 continue if imax le 100 then imax 100 else imax 200 endif 40 continue return end Indentation is applied to both nested do loops and if else endif structures as illustrated above Note that applying uniform indentation forces the source code to begin in column 8 rather than column 7 the minimum allowed by FORTRAN syntax Starting in column 8 means that there will always be at least one space between a continuation character in column 6 and the first character in the statement thus improving readability Note also that applying uniform indentation will preserve any vertical structure imposed by the user Thus in the example above the s remain under the If the application of uniform indentation or resequencing origins causes the line to extend beyond the 72nd column TARGET will break the line at the 72nd column without regard to word breaks and generate a continuation statement with an ampersand amp in column 6 This will not affect the logic of the source code but may offend the user s notion of aesthetics Thus after TARGET has finished with the source code one merely needs to search the tidied version for an amp in column 6 and then make the desired changes manually Resequencing continuation characters will cause continua
18. 0 gt no resequence indent 0 gt no uniform indentation is imposed 2 gt 0 gt impose uniform indentation of indent spaces ialpha 0 gt no alphabetisation of decks 1 1 gt modulo specification of first etc common decks and ordinary decks are arranged FORTRAN TIDY UP 36 first secnd firstcd firstdk alphabetically Common decks are listed before ordinary decks name of deck common or ordinary to be listed before all others character 16 name of deck common or ordinary to be listed right after first character 16 name of common deck to be listed before all other common decks but after secnd character 16 name of ordinary deck to be listed before all other ordinary decks but after secnd character 16 It should be noted that TARGET is particularly sensitive to tab characters EDITOR is known to make mistakes and even crash if it encounters a tab character during a TARGET ses sion and so as mentioned in 82 5 all tab characters should be replaced with the appropriate number of blanks 6 COMPARE Comparing similar ASCII files 6 1 Comparing entire files EDITOR may be instructed to compare two ASCII files character for character and report the differences found in the two files The locations of where the files diverge and reconverge are reported Obviously for two totally dissimilar files such a report may become unwieldy as chance alignments of the two files are di
19. 1 13 EOF 14 chmod 755 xedit22 15 xedit22 16 H gt Tidy up directory 17 xm f editlp inedit output xedit22 OONDOFWNE 23 GENERATING A NUMBERED LISTING 24 A softcopy of number s may be found in the file edit22 tar downloaded from the EDITOR website http www ap smu ca dclarke editor The first segment gets xedit22 from the user s home directory if needed The second segment prepares the input deck for EDITOR appropriate for reformatting a source listing In addition to the general namelist parameters described in 2 5 there are three namelist parameters which may be used specifically to control NUMBER parameter description default NUMBER job 1 inumber 1 gt sequential numbering of source code only 3 2 gt sequential statement and by subroutine 3 gt sequential statement and by deck itable 1 gt creates a table of contents inumber 3 only 1 0 gt no table of contents ixclude 1 gt won t label line with statement number if excluded 1 by if else endif logic inumber 3 only 0 gt labels all executable statements Some notes 1 Selecting inumber 3 specifies that line numbering in the fifth column will be done relative to deck and cdeck statements rather than FORTRAN module statements such as program subroutine function etc inumber 2 2 Setting ixclude 1 will exclude dormant parts of the source c
20. IBM compiler options character 128 For convenience optimise two generic compiler options debug and optimise are supported where compiler debug gt optimise gt cf77 g 04 f90 f77 g C ftrap common 04 g95 g fbounds check ftrace full 02 gfortran g fbounds check ffpe trap i z o 02 ifort g debug parameters check fpe1 02 m32 traceback m32 diag disable remark pgt77 g 02 x1f g C qextchk qflttrap qsigtrap 04 PRECOMPILING SOURCE CODE 22 These are in addition to c o 0 or equivalent that suppress the link step and give the object file the same name as the module and which are included automatically in PRECOM for each default compiler If a different compiler is used the equivalent of c o 0 should be included with coptions speccopt specifies compiler options for special decks named in blank spe array specdk Occasionally one needs to compile a few routines with special compiler options in order for the computations to be done correctly character 128 cdk those decks to be compiled with compiler options blank speccopt character 16 k4 loader specifies loader to be used by MAKE character 16 blank blank gt compiler segldr if compiler cf77 loptions specifies loader options other than o These are blank lib xeq appended to o EXE which is needed for the makefile character 128 s are the libraries to
21. and replaces it with the text immediately following the delete command if any Note that m must be greater than n If m is missing altogether then m n will be assumed 3 ident changedeckname identifies the name of the change deck to the code developer It has no internal to EDITOR function and is included for the sole purpose of preserving backward compatibility with HISTORIAN In practise it never needs to be used 4 read filename replaces the statement with the contents of the named file This is how more than one change deck may be merged with a source file at the same time The line numbers m and n are relative to the most recent c deck statement where the c deck statement itself is line 1 The line numbers may be attained most easily from the fifth column of a listing of the source code reformatted by NUMBER 83 Note that i xd xid and r are valid abbreviations of insert delete ident and read respectively For those who don t like the fact that the delete command can actually be used to replace text the command replace or rp for short is a recognised synonym for delete Use the two interchangeably Together delete insert and replace commands shall be referred to as MERGE edits EDITOR s MERGE may be given one master source file and one change deck containing an arbitrary number of reads to other change decks if desired and creates a new merged file whose name by default is the same
22. arrays for k2 100000 the default is 51 2 Mbytes It turns out that the size of the EDITOR executable with k2 100000 is 52 4 Mbytes so it is clear that the k2 arrays are the dominant sink of memory Use these numbers to guide your selection for k2 and choose as large a value as may be conveniently handled by your machine 3 The number of lines read by EDITOR at a time will be at most safety k2 The variable safety may be set in the namelist input data file inedit 82 5 and 89 2 and reflects the fact that the source code is apt to expand during preprocessing For NUMBER the expansion is minimal table of contents only and so safety 0 9 is probably OK For TARGET the same However for MERGE the amount of expansion depends on how much extra coding is being merged with the original file For PRECOM the call statements can result in substantial expansion of the source file Thus setting safety 0 4 or smaller may be appropriate If safety is set too high and an overflow results execution will be aborted and the user will be asked to use a smaller value for safety see A 1 Since EDITOR reads only complete decks and in general a deck won t happen to end after exactly safety k2 lines EDITOR will usually read less than safety k2 lines at a time If there are individual decks with more than safety k2 lines this will create an overflow condition and execution will abort A 1 The user must then do one or more of the following resubmit the EDITO
23. as the input master source file with the extension m appended The merger also generates an amalgamated change deck with all the read commands if any carried out This change deck has the same name as the user specified 25 MERGING SOURCE CODE change deck with the extension m appended and is where error messages if any are inserted The original files are not changed An example might be appropriate at this point Following is another version of the time of day program used in 82 a change deck and the result of having the two merged by EDITOR Master source file named for example tod OONDOAEWNE deck tod program tod c PURPOSE This program returns the time of day on various systems implicit none if define CF77 characterx 8 tod endif CF77 if define XLF character 26 tod endif XLF c Get time of day tod c xif define CF77 call date tod xendif CF77 xif define XLF call fdate_ tod xendif XLF Cc c Write result to CRT a write 6 2000 tod 2000 format Time of day is a stop end Change deck named for example chgtod E COAONDORWNEHE define XLF delete tod 32 if define CF77 2000 format Time of day according to Cray s CF77 is a endif CF77 if define XLF 2000 format Time of day according to IBM s XLF is a endif XLF insert tod 6 Cc Supported compilers include Cray s CF77 and IBM s XLF MERGING SOURCE CODE
24. cases assume that all variables including scalars have been specifically declared as real integer etc at the beginning of the program module Note that the line numbers in the first 5 columns are included for reference and are not modifications made by the EDITOR precompiler to the source code Example 1 A straight forward nested loop EDITOR has scoped the nested loop and has inserted the appropriate cmic directives Only the outer loop is micro tasked On a vector PRECOMPILING SOURCE CODE 15 machine such as a Cray the inner loop will be vectorised 1 cmic do all private k kp1 j jpi i ip1 blav b2av b3av 2 cmic 1 shared kmax jmax imax b1 b2 b3 btot 3 cmic 1 autoscope 4 do 30 k 1 kmax 5 kpi k 1 6 do 20 j 1 jmax 7 jpl j i 8 do 10 i 1 imax 9 ipl i 1 10 blav b1 1 j k bi ipi j k 11 b2av b2 1 j k b2 1 jp1 k 12 b3av b3 i j k b3 i j kp1 13 btot i j k 0 25 blav 2 b2av 2 b3av 2 14 btot i j k amax1 sqrt btot i j k tiny 15 10 continue 16 20 continue 17 30 continue The variable tiny line 14 was not scoped i e EDITOR did not include it in either the private or the shared lists in lines 1 and 2 because in the program from which this example was extracted tiny is a parameter and not a variable Parameters are not scoped since the compiler replaces parameters with their assigned numerical values Functions and subroutines should not be scoped Note
25. code itself line 56 They can also be used to prevent an unwanted segment of the code from being compiled line 92 While the latter function may be performed by the definition macros the former may not and thus the alias feature represents a real extension of the functionality of HISTORIAN Common decks such as implicit common and declare beginning on lines 9 11 22 respectively appear in the precompiled version of the code only if they are inserted in the code by a call statement e g line 34 Common decks not referred to by a call statement will not appear in the precompiled version of the code and in particular the common decks themselves are not echoed to the precompiled version as separate modules Common decks may call other common decks e g lines 23 and 24 but they may not call themselves Calls to common decks may be nested i e common deck 1 calls common deck 2 which calls common deck 3 etc as many as 10 deep so long as none of the common decks in the nest are the same no closed loops 2 2 The NAMELIST extension Namelists first appeared at the Lawrence Livermore Labs around 1980 and were incorporated as a CTSS FORTRAN extension Since then most operating systems offer FORTRAN 77 compilers with namelist extensions and namelist has become a standard feature of FOR TRAN 90 90 However until the arrival of 90 sometime in 1994 there was no namelist standard and this caused great headaches for the ZEUS d
26. last parameter k9 depends on the EDITOR function When compar ing declaration lists of two files 86 2 COMPARE will only allow as many k9 variables of each type real integer etc The namelist replacement feature 92 2 will allow as many as k9 variables to be defined in each namelist Finally the micro tasking feature 2 3 will scope as many as k9 variables in each nested loop structure it encounters The default values listed above should be more than adequate for most purposes The parameter k2 sets the maximum number of lines read at a time from the user s source file being processed A source file of any arbitrary size may be read However if the source code is too long the file will be read in pieces rather than all at once in order to avoid surpassing the memory available on your machine Thus EDITOR is built with an effort made toward memory management and this should be entirely transparent to the user A 100 000 line source code may be read in and processed all at once with k2 set as high as need be or in various pieces The end result will be identical There are a few factors to be considered in choosing the appropriate value of k2 1 EDITOR is slightly faster if k2 is large enough to read the entire input file at once but only slightly 2 The amount of memory required by EDITOR is largely dictated by k2 There are four character 128 arrays dimensioned with k2 Thus the memory required by these INSTALLING EDITOR 50
27. quotes If a character string is too long to fit within the 72 column constraint one may type all the way to the 72nd column and resume the string in the third column on the following line Note that even with the character string so split only one opening and one closing quote should be used e g lines 6 and 7 This wrap around feature is supported by the EDITOR namelist for character variable assignments only Hollerith strings are not supported by the EDITOR namelist Use true character variables Setting values for vectors may be done in a number of ways as illustrated on lines 3 and 4 Thus ivector 3 1 2 3 will set ivector 1 1 ivector 2 1 ivector 3 1 ivector 4 2 and ivector 5 3 ivector 20 30 2 will set inclusively the 20th through 30th elements of ivector to 2 and ivector 40 4 3 will set the 40th through 43rd elements of ivector to 3 Note that line 4 which is commented out would perform the identical assignments Note that ivector 3 1 2 3 is by convention identical to ivector 1 3 1 2 3 The redundancy in notation for assigning vector values is so that namelist input data files prepared for the CTSS namelist may be read by the EDITOR namelist Setting values for rank 2 arrays may be done only by using the full colon notation line 5 This notation is peculiar to the EDITOR namelist and so far as is known by the author is not supported by 90 namelist Setting values for arrays of greater rank than 2 is not supp
28. that EDITOR was trying to read was not found or was found to be corrupted All fatal error messages indicate which EDITOR subroutine found the problem of no real use except possibly to EDITOR programmers and what the problem is followed by the unwelcome message ABORTS Internally the ABORTS message is always followed by a stop statement so this message really means what it says These messages are listed here alphabetically with some descriptive text interleaved where necessary The first set of messages come from COMPARE 86 and in particular when the declarations of two files are being compared These all require that EDITOR be recompiled with a larger value of k9 89 3 Note that n indicates the current value of K9 as already compiled COMPARE Number of character variables exceeded n Increase parameter k9 COMPARE ABORTS COMPARE Number of data assignments exceeded n Increase parameter k9 COMPARE ABORTS COMPARE Number of equivalences exceeded n Increase parameter k9 COMPARE ABORTS COMPARE Number of externals declared exceeded n Increase parameter k9 COMPARE ABORTS COMPARE Number of integer variables exceeded n Increase parameter k9 COMPARE ABORTS COMPARE Number of logical variables exceeded n Increase parameter k9 COMPARE ABORTS COMPARE Number of parameters exceeded n Increase parameter k9 COMPARE ABORTS 51 ERROR MESSAGES 52 COMPARE Number of real variables exceede
29. values it is still necessary to include a minimal entry in the namelist input data file of the form data2 Failure to do so will generate an error message and abort execution Should any of these rules be broken namelist error messages are generated at run time These are discussed in 8A 4 2 3 Inserting micro tasking directives While single processor speed is still increasing with each new technology released most of the progress in raw compute power over the past decade has been through parallelisation Two paradigms for parallel computing have emerged The Beowulf is an example of a distributed multi processing environment in which memory is distributed over the constituent processors A great deal of thought must be given to how the processors communicate with each other and for many applications this can be a very time consuming task Shared multi processing SMP is the second and more expensive parallel environment but can simplify enormously the task of parallelising a code On an SMP all processors have access to the same memory and communication among the processors is greatly reduced The auto parallelisation feature of EDITOR is designed for applications on SMP architectures There are two basic strategies to multi tasking 7 e parallelising a source code One may macro task a code by arranging for the individual processors to work on individual calls to one or more subroutine s whose results are
30. 1990 13 ibegwr 2010 iendwr 2990 14 inc 10 irepl 1 ireseq 1 indent 2 ialpha 1 15 first FIRST secnd SECOND firstcd FIRSTCD 16 firstdk FIRSTDK 17 EOF 18 chmod 755 xedit22 19 xedit22 20 i gt Tidy up directory 21 rm f editlp inedit output xedit22 A softcopy of target s may be found in the file edit22 tar downloaded from the EDITOR website http www ap smu ca dclarke editor The first segment retrieves xedit22 from the user s home directory if needed The second segment prepares the input deck for EDITOR appropriate for tidying up a source listing In addition to the general namelist parameters described in 82 5 there are 15 namelist parameters peculiar to TARGET These are described below parameter description default TARGET job 2 ibegdo lowest target value for goto and do stmnts 10 ienddo highest target value for goto and do stmnts 990 ibegre lowest target value for read and decode stmnts 1010 iendre highest target value for read and decode stmnts 1990 ibegwr lowest target value for write and encode stmnts 2010 iendwr highest target value for write and encode stmnts 2990 inc increment between successive targets 10 irepl 1 gt replace do enddo s with targeted do s 1 0 gt do not replace do enddo s ireseq 1 gt resequence 6th character in continuation stmnts il
31. 22 Prepare input deck inedit rm f inedit cat lt lt EOF gt inedit editpar inname tod job 4 EOF Retrieve xedit22 and execute if e xedit22 cp dclarke editor version2 2 xedit22 chmod 755 xedit22 xedit22 rm editlp inedit xedit22 3 NUMBER Generating a numbered listing 3 1 Reformatting a file The NUMBER feature of EDITOR will take as input any ordinary ASCII source code and reformat it so that each line of the source code appears with various labels By default a separate file whose name is the same as the input file with the extension n appended is created containing the reformatted source listing The original file is left as is Each line is labelled with as many as 6 labels The first and third columns of the reformatted file is the line number since the beginning of the file with the source code itself 72 characters wide in the second column The fourth column is the number of executable statements i e not including comments and continuation lines since the beginning of the current module The statement number takes into account the number of statements implied by each call statement 82 1 This is useful for example if compiler and or debugger diagnostics refer to the executable statement number within a module rather than the ASCII line number as more modern compilers and debuggers do The fifth column is the number of lines since the b
32. 27 Master source file tod merged with change deck chgtod to form new master source file tod m 1 deck tod 2 ca s 1 2 4 J 4 42 4 H 4 f 4 3 4 program tod 5 c 6 c PURPOSE This program returns the time of day on various systems 7 c Supported compilers include Cray s CF77 and IBM s XLF 8 c a a a aan 2 aaa 10 c 11 implicit none 12 x if define CF77 13 character 8 tod 14 endif CF77 15 x if define XLF 16 character 26 tod 17 endif XLF 18 c 19 GSS 8338555585558 ss SS 20 c 21 c Get time of day tod 22 c 23 if define CF77 24 call date tod 25 endif CF77 26 if define XLF 27 call fdate_ tod 28 endif XLF 29 c 30 c Write result to CRT 31 c 32 write 6 2000 tod 33 if define CF77 34 2000 format Time of day according to Cray s CF77 is a 35 endif CF77 36 xif define XLF 37 2000 format Time of day according to IBM s XLF is a 38 endif XLF 39 stop 40 end 41 x define XLF Some notes 1 MERGE commands may not appear in the master file only in the change deck 2 Anything before the first MERGE edit will be placed at the end of the merged file e g line 41 of tod m 3 An asterisk is placed in the 74th column of every line put into the merged master source file by the change deck This asterisk is only to aid the user to see at a glance which lines ar
33. E same 8 24 COMPARE COMPARE Number of differences reported 4 COMPARE The first difference reports that the first two lines of each file are different tod2 begins with a comment tod1 begins with the program statement and that the two files reconverge again at line 1 of tod1 and line 3 of tod2 Still there is chaff amongst the wheat if one is not interested in the differences generated by comment statements Finally the third report which follows was generated with differences in comments and blanks overlooked COMPARE COMPARE diff todi tod2 l COMPARE line context line context COMPARE 0 gt COMPARE 1 diff 3 character 8 9 implicit COMPARE same 3 10 A COMPARE 2 diff 5 call date t 12 external COMPARE same 5 18 COMPARE 3 diff 6 write 6 10 tod 22 rite 6 2000 tod COMPARE same 8 24 COMPARE COMPARE Number of differences reported 3 COMPARE In this case COMPARE reports that tod2 has an implicit statement and an external statement whereas tod1 does not and that the target for the write statement differs in the two versions 10 in tod1 2000 in tod2 This is perhaps the most useful of all reports and illustrates the power of being able to ignore selectively various types of differences 6 2 Comparing declaration contents The second way EDITOR may compare two files is by comparing the con
34. EDITOR USER MANUAL Version 2 2 David A Clarke Institute for Computational Astrophysics Saint Mary s University Halifax NS Canada B3H 3C3 http www ap smu ca dclarke editor June 2004 revised 10 07 6 11 Copyright David A Clarke 2004 2007 2011 Contents Disclaimer ili 1 Introduction 1 Jl VERGION ZT oeart Se th Be OS a ee ee ee 1 L VERSIONES 64 24 eee g eima poi aa pe aaa 2 2 PRECOM Precompiling source code 3 21 Basic ree lt se siis ee e e i a a o a 33 5 3 Ze The WAMELIGT extension 2c Gaye ee a ee SS wwe A Oe e 9 2 3 Inserting micro tasking directives 4 24 425524054 805548 5 13 2 4 Splitting a source code generating a makefile 18 2 5 The precom s Gripe fl o cc c bd dee eR eR tk iaa akoa riren 19 3 NUMBER Generating a numbered listing 23 Sd o le ice eee eee eee Due Saw ORS e eS 23 3 2 The RIBES script fil cis lt e oa ea caor Ae e a a baw ee 23 4 MERGE Merging source code 25 4 1 Change decko e s er be ESS Rw EH em OE a a 25 4 2 The merge s and merge_precom s script files 28 5 TARGET FORTRAN tidy up 32 al Ihe tarpet e Gript ale 2962444 22444 eRe ee ace Pa a ee 35 6 COMPARE Comparing similar ASCII files 37 6 1 Comparing entire files 2 54 bee ee wee eee de eee by bee ds 37 6 2 Comparing declaration contents lt lt reos eX 39 6 3 The compare s script files s s sa caa ee radarada ideda 41 7 SPLIT Splitting source code 43 Tal DOUE AE os e o ee o ESS
35. R job with a larger value of safety at the risk of generating overflows when the new files expand rewrite the source code with smaller decks or recompile EDITOR with a larger value of k2 If none of these can be done EDITOR may not be used for the desired task on the chosen machine A Error messages Error messages come in four flavours The most serious cause EDITOR to abort execution and usually require it to be recompiled with higher values for one or more parameters The second type consist of error messages caused by incorrect EDITOR syntax in the files being processed These are not fatal to EDITOR itself but will mean that the files processed by EDITOR will be unusable for their intended purpose EDITOR will insert these error messages directly below the offending line in the output file Note that original input files supplied by the user are never altered by EDITOR The third type are warning messages which are echoed on the terminal screen In this release there is only one warning and it is completely innocuous Finally if the user s program is preprocessed with the namelist replacement feature 2 2 syntax errors in the user s namelist input data file will generate fatal error messages at run time A 1 Fatal errors Fatal error messages which abort EDITOR arise under two conditions Either an overflow has occurred in which case EDITOR may have to be recompiled with one of its parameters set to a higher value or the file
36. RAMETERS 2 A e ee a a integer idim jdim parameter idim 100 jdim 100 E A REE Ree ope E eee ee Nee ae ee ee sal a VARTABLES 2 95S2953 355 A ELERI TEETER IOE E E E EET nee tS SE ene Ss integer i is ie 1 P gt js gt je real si S2 83 S4 sd 1 86 gt ST S8 3 89 S10 2 sii S12 c real vi idim v2 idim v3 idim 1 wi jdim w2 jdim w3 jdim c real al idim jdim a2 idim jdim a OS E E Ce EQUIVALENCE STATEMENTS Epa oie E sae ae ee epi ee integer ieqs 10 equivalence 1 ieqs 1 i Geqs 2 is Cieqs 3 ie 2 iegs 4 j ieqs 5 js ieqs 6 je c real reqs 20 equivalence 1 reqs 1 s1 reqs 2 82 regs 2 83 2 reqs 4 s4 reqs 5 s5 reqs 6 s6 3 reqs 7 s7 reqs 8 s8 Greqs 9 59 4 reqs 10 s10 regs 11 s11 regs 12 s12 real reqv 3x idim 3x jdim equivalence reqv dy VL 1 1 reqv idim 1 v2 1 2 reqv 2xidim 1 v3 1 3 reqv 3xidim 1 wi 1 4 reqv jdim 3 idim 1 w1 1 40 COMPARING SIMILAR ASCII FILES Al 5 reqv 2xjdim 3x xidim 1 w3 1 Ciara iii o o o o e ooo ooo oo ooo soso 2 282 COMMON BLOCKS EE sa a a A oe ee ee ee eee common comi ieqs common comr reqs gt reqv al a2 Upon comparing these two declaration modules EDITOR would is
37. RECOM parameter description default GENERAL inname name of source code to be edited character 64 ibanner 1 gt print banner to screen at beginning of execution 0 0 gt no banner job 1 gt number lines in source code 1 2 gt tidy source code retarget indent alphabetise 3 gt update source code with change decks 4 gt prepare source code for compilation 5 gt compares two files and reports location of first ndiff differences 6 gt splits master file into module files 7 gt concatenates module files to master file idump 1 gt diagnostic dumps are written to output 0 0 gt no diagnostic dumps safety Memory management parameter k2 safety lines of 0 0 inname are read at a time 0 0 gt 0 9 job 1 2 5 6 7 0 4 job 3 4 outname name of outfile If unspecified outfile will be named according to internal naming convention character 64 PRECOM job 4 swcase 0 gt Switches but not aliases are case insensitive 0 def MHD and def mhd are identical 1 gt Switches are case sensitive def MHD and def mhd PRECOMPILING SOURCE CODE 21 inmlst iutask iupdate branch ext makename compiler coptions are different 0 gt leave NAMELIST and associated 1 0 alone 0 gt 0 gt substitute all occurrences of NAMELIST and associated I O for calls to subroutines in D NAMELIST A A maximum of inmlst assignments can be made in the input deck per NAMELIST
38. S OVERFLOW In ERRMSG attempt to insert error message causes a file overflow OVERFLOW Overflowed text file written to file OVERFLOW TXT OVERFLOW ABORTS Finally the subroutine which reads text once a text file is opened RFILE can fall into traps EDITOR will always attempt to read entire decks or modules of a source code 89 3 If it cannot that is if safety k2 is less than the number of lines in the largest deck then execution will abort In addition if the file being read is corrupted or smaller than anticipated a fatal error message will be generated RFILE A module in file filename is longer than i lines RFILE Increase parameter k2 RFILE ABORTS RFILE Array bounds exceeded while reading file filename RFILE Increase parameter k2 RFILE ABORTS RFILE Problem reading line i in file filename RFILE ABORTS A 2 Non fatal errors There are a variety of error messages that EDITOR inserts into the output files should it uncover any EDITOR syntax errors or some selected FORTRAN syntax errors These errors do not abort execution EDITOR simply notes the error leaves the errant line in the output file as opposed to syntactically correct EDITOR statements which once carried out are expunged from the output file and moves on Every effort has been made to ensure that the error message will appear immediately after the offending line in the output file This requires a rather elaborate accounting scheme
39. SES EES 43 Ta Tie Seti ipt iles ce Bo IIA IO O A 43 8 CONCAT Concatenating files 44 SL The Gino serip E coses Swe ee ro e a a 44 9 Installing EDITOR 45 91 Tastallation aio mis ados a ee bee ee hee de es 45 D2 Thegernip BIE UE e bw a e a a a 47 93 EDITOR parameters i 2 2 44 2 pa paos es rs Ga te daye Sdad 49 A Error messages 51 AL Fatal Emor socia a Ra AA ole Sok eG 51 A2 Non fatal errors e e s e es e a o 6 od eS 53 AS WAVES 3 Ge ERE e a dd SS E ORS 59 CONTENTS A 4 NAMELIST errors Disclaimer NOTICE This software was developed by the author at the National Center for Supercomputing Applications NCSA at the University of Illinois in Urbana Champaign between 1988 and 1990 and is currently maintained by the author at the Institute for Computational Astrophysics at Saint Mary s University in Halifax NS It and this manual are offered as is by the author to anyone for non profit educational use with no expressed or implied warranty or suitability It is requested that the author s name and this disclaimer remain associated with this manual and software as well as any descendents of this software that may be developed by a third party ill EDITOR USER MANUAL Version 2 2 David A Clarke ICA June 2011 1 Introduction 1 1 VERSION 2 1 EDITOR is a highly portable text manipulator written in FORTRAN77 designed to manage and compile large computer codes and placed in the public domain by the author see Dis
40. ame for the deck unique from all other decknames cdeck or equivalently cd for short tells EDITOR that everything that follows up to but not including the next cdeck cd deck or dk statement belongs to the common deck so named Similarly deck dk indicates an ordinary deck One is free for example to give an ordinary deck the same name as the module i e program subroutine or function name it contains Optionally the user may designate groups of decks with the group or gp for short statement group groupname gp groupname where groupname is a user designated name for the group not necessarily unique from those named in other group statements All ordinary decks will then be considered part of the group named in the most recent group statement The group command is designed for user convenience it has no effect on how the program is compiled They allow for example the FORTRAN tidy up routine TARGET see 85 to re alphabetise all decks within a certain group then arrange the groups themselves alphabetically In some sense one can think of groups as analogous to directories aiding the user to locate a particular module within a large source code Having designated the decks and perhaps groups one may now insert the various precompiler commands which will be carried out during the first two passes the precompiler makes through the code The first pass establishes which decks the user has defined their
41. and tailored for the named compiler The following instructions are written assuming Gnu s gfortran is being used For other compilers make the appropriate substitutions STEP 1 Create a preliminary edit22 executable xedit22 Since edit22 manages itself in principle one needs the edit22 executable in order to compile it Thus a bit of a boot strap process is required to complete the compilation Go to directory editor 1 1 If using one of the supported compilers e g gfortran type gfortran o xedit22 edit22 GFORTRAN f 45 INSTALLING EDITOR 46 This creates the preliminary xedit22 executable Move on to step 2 1 2 If using a compiler not supported by edit22 let s call it FCOMP you will have to modify edit22 GFORTRAN f as follows Type cp edit22 GFORTRAN f edit22 FCOMP f FCOMP o xedit22 edit22 FCOMP f If this fails and it may not it will likely do so by citing calls to unknown subroutines such as cpu_time date_and_time and system For many compilers these subroutines do the following cpu_time returns the cpu time since the beginning of the run in seconds date_and_time returns eight integers giving the year month day etc Search for date_and_time in edit22 for details system executes a systems call such as removing a disc file at run time You will have to find the equivalents to these functionalities for your compiler Once determined open up edit22 FCOMP f in a text editor find the of
42. ata As many namelists as desired may be so defined and read throughout the program and for every namelist defined there should be a corresponding entry in the namelist input data file indata as described below PRECOMPILING SOURCE CODE 11 Line 51 writes a summary of the namelist settings to unit 52 This is not a necessary part of the namelist structure and many users may not want to bother with this feature Indeed many implementations of namelist don t even offer the option to write a summary of the namelist settings The EDITOR namelist does however support the write or equivalently print statement While it is not necessary it may be useful to assign all the namelist parameters default values before the read statement lines 26 through 43 This is so that in case the user does not assign values to all the parameters in the namelist input data file by no means a requirement all parameters will be initialised to something and hopefully to a useful default value To use the EDITOR namelist one must abide by the following rules 1 Do not use namelist as a variable name in any module that reads data from namelists 2 Do not name any subroutines nlsdacnn where nn varies from 01 to 24 3 Link the library namelist a for single precision applications and dnamelist a for double precision applications to your code during the link step The namelist f and dnamelist f source codes and the script files to build the libraries are in th
43. ate auto scoping feature was incorporated into EDITOR After scoping the variables in a nested loop EDITOR inserts the appropriate cmic auto tasking directives recognised by Cray s CF77 and Sun s 90 compilers or c omp for OpenMP at the beginning of the scoped loop Should the code then be passed through the compiler s auto tasker the presence of these cmic or c omp statements will tell the auto tasker that these loops have already been scoped and parallelised and can be passed over For all other parallelisation opportunities the vendor s auto tasking tools should be used Indeed the auto scoping features of most vendors compilers may by now be superior to EDITOR s and it may be better to use the vendor s auto parallelisation features exclusively Note that the EDITOR auto scoper will only scope those variables declared at the begin ning of the program module Undeclared scalars allowed when implicit none is not used will probably be scoped correctly by the compiler s auto tasker by virtue of the autoscope default __auto directive included in all EDITOR supplied cmic c omp statements but in the author s experience not necessarily Below are some examples using Cray s cmic syntax to illustrate the use of the EDITOR auto scoper There is a one to one correspondence between all cmic and c omp commands which can be gleaned from the code edit22 or from any OpenMP manual if the reader is interested In all
44. be linked by the loader As many blank libraries can be specified as will fit in character 512 name of executable to be created by MAKE character 64 blank to allow for directory specification as well blank gt inname with extension x Some notes Pe 1 2 FOWOONDOPWNEF Default name for precompiled disc file outname is inname with extension f EDITOR is unable to interpret tab characters For programmers who habitually use tabs in their source code these should all be replaced manually with the appropriate number of blanks before attempting to preprocess it with EDITOR Should the EDITOR precompiler detect any EDITOR syntax errors EDITOR will in sert an error message immediately following the offending statement in the precompiled file with the f extension Detection of error message will render the precompiled file unusable for compilation purposes and may prevent additional passes through the code requested by the user replacing namelists for example The user will be told that errors were detected and how to find them in the precompiled disc file Once the errors are corrected in the master file the user can attempt to precompile the file again See A for a description of the error messages generated by EDITOR Incidentally the following and very simplified script file csh v tod s precompiles the program tod in 82 1 to create tod f SCRIPT FILE TO PRECOMPILE TOD USING XEDIT
45. be lower than 999 Obviously a 32 bit word machine will have even more stringent limits NAMELIST ERROR 15 gt no more than 15 digits in single precision The tone of this message is a fossil of the days when EDITOR ran only under UNICOS and where single precision was 15 significant digits double precision on most other platforms The EDITOR namelist will only allow as many as 15 significant figures to be specified in a real variable assignment
46. cit none 10 character 8 tod 11 c 12 external date 13 c l4 Cr rene 15 c 37 COMPARING SIMILAR ASCII FILES 38 16 c Get time of day tod 17 c 18 call date tod 19 c 20 c Write result to CRT 21 c 22 write 6 2000 tod 23 2000 format Time of day is a 24 stop 25 end These two versions of presumably the same program show different programming styles The task is to find all important differences between these two files if any In the report that follows no superficial differences were ignored and COMPARE behaves much like diff COMPARE COMPARE diff todi od2 f COMPARE line context line context COMPARE sSSSsSss gt so saarae cnt ne no ee a See eee ES COMPARE 1 diff 1 progra 1 c 4 1 COMPARE same 4 j 2 j COMPARE 2 diff 5 call date t 3 program tod COMPARE COMPARE Number of differences reported 2 COMPARE First the anatomy of this report The first column headed by diff labels the differences sequentially The second column headed by tod1 the name of the first file gives the line number and a segment of the indicated line in which the difference was discovered for the first file The third column headed by tod2 the name of the second file gives similar information for the second file Each difference report consists of two lines where the files diverge diff and where the files reconverge same The diff line gives the context of the fil
47. common deck Misspelling a common deck name in a call statement is the most probable cause for this error COLLECT ERROR 3 Expecting a character expression If a call statement appears without a common deck named or if any other EDITOR command is incomplete this error message will result Check syntax COLLECT ERROR 4 Too many switches defined This indicates that the user has specified more switches definitions than allowed by the array bounds One either needs to define fewer macros or to recompile EDITOR with a larger value of k7 COLLECT ERROR 5 Too many aliases defined This indicates that the user has specified more aliases than allowed by the array bounds One either needs to set fewer aliases or to recompile EDITOR with a larger value of k8 COLLECT ERROR 6 Too many common decks defined This indicates that the user has specified more common decks than allowed by the array bounds One either needs to define fewer common decks or to recompile EDITOR with a larger value of k4 COPY ERROR 7 Syntax First character is illegal This message is a combined EDITOR FORTRAN syntax error message and indicates that the only allowed characters in the first column of legal FORTRAN EDITOR statements is a blank a digit 0 through 9 c C or COPY ERROR 8 x Syntax EDITOR sentinel not in column 1 This message indicates that the EDITOR command does not begin in t
48. cro task it update only those modules that were affected by whatever change you might have made to the change deck and generate the new makefile all with one execu tion of EDITOR It is in this mode that the author uses EDITOR to manage the ZEUS 3D code http www ica smu ca zeus3d and therefore the mode which is probably the most debugged and robust The second sample script file in 84 2 is a template for using EDITOR in just this way Curators of large codes should be warned that change decks can become too cumber some and numerous to make this strategy practical As a first guide one might consider permanently merging a change deck with the master code once it has grown to 25 the size of the master code Then a new change deck may be started with references to line numbers in the new version of the master source file 4 2 The merge s and merge_precom s script files A merged source listing may be generated by issuing the following command csh v merge s where merge s is as follows oI Se an aca ca Va cma ogc a E 2 SCRIPT FILE TO MERGE A CHANGE DECK INTO A SOURCE CODE 3 4 User sets CHANGEDECK SOURCECODE OUTNAME 5 de 7 if e xedit22 cp dclarke editor version2 2 xedit22 8 Hess ooo gt Create change deck 9 rm f changes 10 cat lt lt EOF gt changes 11 ident changes MERGING SOURCE CODE 29 12 read CHANGEDECK 13 EOF 14 f e
49. d n Increase parameter k9 COMPARE ABORTS COMPARE Number of variables in common exceeded n Increase parameter k9 COMPARE ABORTS CONCAT 88 has one trap which will abort execution should it have trouble reading a particular line in a named file filename This indicates that the file may be corrupted or is shorter than EDITOR anticipated Check the contents of the file particularly around the indicated line CONCAT Problem reading line i in file filename CONCAT ABORTS If a user specified input file isn t actually there the following message will be issued Check that filename was spelled correctly or that the file is in the proper directory OFILE Problem opening file filename OFILE ABORTS While EDITOR has been designed with considerable effort toward memory management 89 3 it is still possible for overflows to occur There are two types of overflow One can be corrected only by recompiling EDITOR with a larger value for the parameter k2 89 3 The other may be corrected by resetting the parameter safety in the namelist input data file indata 2 5 and 9 2 to a lower value then executing EDITOR again Note that the latter case does not require recompiling EDITOR The overflowed text is not written to the intended file but to an emergency file called OVERFLOW TXT that the subroutine OVERFLOW opens writes to and closes before it aborts execution It may help to examine the contents of this f
50. des its scan EDITOR generates this message NMLST ERROR 33 Blank nlsdac suffix Check declarations This error stems usually from some syntax error such as a missing comma in the dec laration list that wasn t detected while the declaration list was being scanned and left the variable attribute undetermined In this event EDITOR is unable to determine which of the namelist lib subroutines named nlsdacnn where nn ranges from 01 to 24 to call Check which variable is involved with the statement to which this error message refers and examine how that variable is declared in that program module PRECOM ERROR 34 Call made to an unknown common deck See ERROR 2 TARGET ERROR 35 Unrecognised character in first five columns TARGET errors refer always to incorrect FORTRAN syntax which impedes the tidy up process This particular error is generated if there is anything other than a digit 0 to 9 in the first 5 columns of any statement that is not a comment blank or EDITOR statement TARGET ERROR 36 Too many targets Going on to next deck Too many targeted statements in the program module The tidy up process cannot continue with current module so execution continues with the next module Either break the module up into smaller modules or recompile EDITOR with a larger value of k5 89 3 ERROR MESSAGES 58 TARGET ERROR 37 Unrecognised syntax The statement does not conf
51. e directory nmlst of dzeus35 tar downloaded from www ica smu ca zeus3d Otherwise use namelists as indicated above and prepare your namelist input data file as in the following example 1 c 1 4 4 3J 4 4 4 p 4 f 4 2 datal rscalar 1 0 iscalar 1 lscalar true cscalar abcdefg 3 ivector 3 1 2 3 ivector 20 30 2 ivector 40 4x 3 4 c ivector 1 1 1 1 2 3 ivector 20 11 2 ivector 40 3 3 3 3 5 larray 1 100 1 100 1 iarray 1 10 91 100 2 6 cvector 3 abcdef ghijklmnopqrstuvwxyz01234567890ABCDEFGHI JKL 7 MNOPQRSTUVWXYZ lvector 98 t false f Various aspects of this data file warrant discussion Again line numbers are not part of the data file they are included for reference only 1 Each line in a namelist input data file may be at most 72 characters wide Anything beyond the 72nd column will be ignored Thus one might consider including a number line such as line 1 which will allow one to see at a glance whether the data extend beyond the 72nd column 2 Only one of three characters are allowed in column 1 c C for commenting out lines as in lines 1 and 4 or a blank Anything else will cause an error message to be generated and execution to abort Note that all lines commented out will be echoed to the CRT at execution time 3 Only one of two characters are allowed in column 2 the sentinel for opening a namelist or a blank Anything else
52. e in which the difference was discovered centred over a carat which indicates the first character found to be different For entirely different lines this will generally be the first character in the line The same A line indicates on which line in each file the files reconverge and contains the carats This particular report is of little use It basically states that the two files differ right from the start note that one file is indented with six blanks the other with seven happen to be the same again where both files have an empty comment line then differ throughout the rest of the files Since the files never reconverge the same at line for the second difference report is never issued and thus neither are the carats These two files are basically too different for an all difference report to be of much use In the second report which follows differences stemming from blanks were ignored It is a bit more useful than the first report since reported differences are more localised COMPARE COMPARE diff todi tod2 COMPARE line context line context COMPARE COMPARE 1 diff 1 program 1 C 4 1 COMPARE same 1 3 G COMPARE 2 diff 2 c 4 c COMPARING SIMILAR ASCII FILES 39 COMPARE same 4 4 COMPARE 3 diff 5 call dat 5 c PURPOSE COMPARE same 5 18 COMPARE 4 diff 6 write 6 19 c COMPAR
53. e new to this version of the code If the m file is then passed through PRECOM 2 NUMBER 83 or TARGET 85 the asterisk in column 74 is not copied to the f n or t file respectively MERGING SOURCE CODE 28 4 Note that the line numbers used in the MERGE edit statements are always those of the original master file That is to say the user does not have to worry that a MERGE edit made somewhere else in the change deck might affect the line numbering for other MERGE edits By the same token one may not make a MERGE edit on a MERGE edit in the current change deck Changes to MERGE edits should be done directly in the change deck s 5 Obviously care should be taken to ensure that MERGE edits do not refer to lines in the master source that have been deleted by other MERGE edits Such a conflict will generate a non fatal error message see A 2 6 All the punctuation in the MERGE commands is optional d tod 1 3 is just as valid as xd tod 1 3 The punctuation used in these examples reflects HISTORIAN syntax which EDITOR permits for the sake of compatibility As a source code preprocessor EDITOR is probably in its most useful state when the MERGE and PRECOM features are used in tandem which is accomplished by setting the appro priate input parameter 4 2 One can take a master file and a change deck merge them together to produce a m file precompile the m file to generate a f file replace all the namelists mi
54. e of contents NUMBER 3 3 merging a change deck with a source code thereby upgrading the source code without making changes directly to the master file MERGE 84 4 tidying up FORTRAN source code including relabelling targets indentation renum bering continuation characters alphabetising modules etc TARGET 5 5 comparing two ASCII files and reporting the differences found COMPARE 86 overlook ing some differences of specified type 6 splitting a long file into subroutine modules SPLIT 87 and INTRODUCTION 2 7 concatenating all files with a common suffix found in the current directory and all its subdirectories into a single file CONCAT 8 These jobs are all described in the sections indicated In addition to describing EDI TOR s most important task precompilation 2 introduces the first time user to language of EDITOR Finally 89 describes how EDITOR may be installed on a new platform DAC November 1992 1 2 VERSION 2 2 This is the first new release in almost 20 years In addition to half a dozen bugs found and corrected in that time the main difference to version 2 2 is correcting finally the mistaken notion that differences in specific FORTRAN calls e g timing functions had to do with the OS and not the compiler specifically In this version all mention of SUNOS LINUX etc are replaced in favour of compiler names such as G95 IFORT etc Supported compilers in this relea
55. ectly 19 20 22m Get files from home directory 21 if e xedit22 cp dclarke editor version2 2 xedit22 22 SSsssssssssssssss gt If necessary create the directory DIRECTORY 23 if e DIRECTORY mkdir DIRECTORY 24 Fessssssssssessssssss gt Create the input deck for EDITOR and execute 25 rm f inedit 26 cat lt lt EOF gt inedit 27 editpar inname SOURCECODE ibanner 1 job 4 idump 1 28 inmlst 1 iutask 0 iupdate 0 ext f 29 branch DIRECTORY makename MAKEFILE xeq EXECUTABLE 30 compiler COMPILER coptions debug 31 Llibs LIBRARIES 32 EOF 33 chmod 755 xedit22 34 xedit22 35 fe gt Tidy up directory 36 rm f editlp inedit output xedit22 A softcopy of precom s may be found in the file edit22 tar downloaded from the EDITOR website http www ap smu ca dclarke editor Note that the line numbers in the first five columns are not part of the file and are included only for reference PRECOMPILING SOURCE CODE 20 Comments for C shell script files are indicated by a in column 1 For all EDITOR C shell script files listed in this manual there are by convention two types of comments Those lead by a double line gt indicate that the following portion of the script file should rarely if ever require changing Those lead by a single line gt
56. eginning of the current module see inumber below The sixth column is the group name in which the current module is grouped 2 1 while the seventh column lists the name of the current module The user has some control over what labels are put on each line see inumber below and how the number of executable statements since the beginning of the current module is computed see ixclude below A full compliment of labels will expand an ordinary 72 column FORTRAN source listing to 132 columns so an appropriate printer must be used to print out the reformatted listing In addition EDITOR may be instructed to place a table of contents at the beginning of the listing To aid in locating a module rapidly the table of contents list the modules both sequentially and alphabetically 3 2 The number s script file A source listing may be reformatted with NUMBER by issuing the following command csh v number s where number s is as follows 1 2 3 3 2 1 SCRIPT FILE TO CREATE A NUMBERED LISTING User sets SOURCECODE Get files from home directory if e xedit22 cp dclarke editor version2 2 xedit22 faa gt Create the input deck for EDITOR and execute rm f inedit 10 cat lt lt EOF gt inedit 11 editpar inname SOURCECODE 12 ibanner 1 job 1 inumber 3 itable 1 ixclude
57. ents The first second and third elements pertain to continuation characters blanks and comments respectively If any element is 1 that type of difference is ignored otherwise it is reported So for example if one wanted to find the differences between two files with differences in continuation characters and comments overlooked but differences in the number of blanks between words reported one would set ignore 1 0 1 2 Comparison of declarations may cause an overflow to occur if EDITOR was compiled with parameter k9 set too small See 89 3 and A 1 7 SPLIT Splitting source code 7 1 Splitting a file As part of the precompilation process splitting up a file was discussed in 2 4 One can perform the split outside PRECOM using SPLIT but it does not include the checking feature that the precompilation split allows That is to say no effort is made to check if the file being overwritten needs to be updated This feature of EDITOR is very similar to fsplit The EDITOR SPLIT names each file it creates with the module name and the user specified extension appended It will allow the user to specify in which directory all files are to be placed 7 2 The split s script file A source listing may be split by issuing the following command csh v split s where split s is as follows 1 2 3 3 2 1 1 2 SCRIPT FILE TO SPLIT A SOURCE CODE INTO FILES FOR EACH DECK
58. ere in the input data file this message will be issued NAMELIST ERROR 2 gt column 2 reserved for delimiter If a character other than a blank or appears in the first column anywhere in the input data file this message will be issued NAMELIST ERROR 3 gt variable not found in namelist A variable is being set which was not part of the namelist declaration in the source code The usual reason for this error is a misspelled variable NAMELIST ERROR 4 gt unexpected character check syntax The usual reason for this message as in the example above is a missing comma Check the syntax of the offending line carefully NAMELIST ERROR 5 gt invalid logical expression A logical variable has been assigned a value other than true t false or f in cluding the periods NAMELIST ERROR 6 gt namelist does not exist or is out of sequence The source code attempts to read a namelist not found in the namelist input data file This is usually caused by a misspelled namelist name or a namelist that appears out of order in the data file Note that the order of the namelists in the data file must be the same as the order in which the source code reads them ERROR MESSAGES 61 NAMELIST ERROR 7 gt error reading input deck Does the namelist input data file exist on disc in the directory in which the executable was executed NAMELIST ERROR 8 gt variable not declared as a vector A scalar is assigned values as
59. evelopment project which in 1990 had to operate under three different compilers Thus a portable namelist emulator was de veloped and EDITOR can be instructed to replace all namelist syntax in the code with calls to a namelist library which includes features that the 90 namelist does not e g ability to assign values to 2D arrays allowing variables passed by a subroutine argument list to be namelist variables The discussion in this subsection therefore is restricted to the EDITOR flavour of namelists Namelists provide an extremely useful and flexible way of supplying user determined data to a program Traditionally FORTRAN source codes have relied upon prompting users for data and or formatted reads to disc files For many input parameters the former can tax the user s patience while the latter can be frustrating because of the need to comply with a strict format for the input data Namelists eliminate these problems as illustrated in the following example integer in jn parameter in 100 jn 100 character 128 cscalar cvector in carray in jn integer iscalar ivector in iarray in jn oOPWNEF a PRECOMPILING SOURCE CODE 10 6 real rscalar rvector in rarray in jn 7 logical lscalar lvector in larray in jn 8 c 9 10 11 c 12 c Open the ASCII file infile which contains the namelist data and 13 c ASCII file outfile to which a namelist summary may be written 14 c 15 open 51 file indata
60. extent and which EDITOR macros have been set The second pass precompiles the source code according to the macro settings In this way the compiler will only see that portion of the code which the user has deemed relevant to the problem at hand There are two types of EDITOR macros definitions and aliases Setting macros is done by inserting any number of the following EDITOR commands anywhere in the master source file or in the change deck if MERGE is being used in tandem with PRECOM 84 Note that these statements are global in that they will have effect throughout the code no matter where in the code they appear There is for example no way to impose a macro for part of the source code then turn it off for the rest define def1 def2 def defl def2 alias alias alias2 xal alias1 alias2 where def1 def2 etc are user selected alpha numeric keywords which determine active segments of the source code The alias statement instructs EDITOR to replace all occur rences of the alpha numeric keyword alias1 with alias2 except for those which appear in comment statements Note that define and def are synonyms as are alias and al Having determined which EDITOR macros have been set the precompiler makes a second pass through the source code to look for if define or if alias statements These PRECOMPILING SOURCE CODE 5 determine which segments of the program are to be included in the precom
61. fending system calls and make the necessary replacements Then once again type FCOMP o xedit22 edit22 FCOMP f remembering to replace FCOMP with the actual name of your compiler This should produce a preliminary edit22 executable xedit22 needed through step 4 Step 2 From directory editor_v2 2_ICA open the script file bldlib2 in your text editor The entire file should be platform independent with the possible exception of line 33 which invokes the gfortran compiler whose given options create object files without linking c and uses the fastest safe optimisation level 02 If a compiler other than gfortran is being used line 33 must be changed appropriately Options for other commonly used compilers for optimising and debugging are given in the header Step 3 From the directory nmlst issue the following commands csh v namelist s csh v dnamelist s These commands will create single and double precision versions of the platform independent namelist libraries libnmlst a and libdnmlst a respectively The former is required for edit22 while the latter is included to link to double precision software that the user may wish to manage with EDITOR Step 4 If you are using one of the seven supported compilers go to step 5 If not you must put all the changes you made to create edit22 FCOMP f into the master copy of EDITOR namely edit22 From the directory editor open edit22 FCOMP f in one text editing window edit22
62. fers to a deck not found in the master source code The most likely reason is that the deckname has been misspelled MERGE ERROR 23 Expecting a line number to follow deck name MERGE edits require at least one reference to a line number If no line numbers were given this error message is issued MERGE ERROR 24 Last line number must be greater than first For the MERGE edit delete filename n m m must be greater than n MERGE ERROR 25 Specified range not found in deck The specified lines in the delete statement were not found in the specified deck Check the fifth column of the source code formatted by NUMBER and make sure the lines do indeed exist MERGE ERROR 26 Cannot find specified line Was it deleted Probable cause of this error message is a previous delete statement removed the line s that the current MERGE edit is trying to affect NMLST ERROR 27 Missing opening delimiter The NMLST errors should not be confused with the namelist error messages that may appear during run time of the user s program should syntax errors be found in the namelist input data file The NMLST errors are those generated by improper syntax of the namelist statement in the user s source code itself This error message indicates that the opening slash is absent from the namelist designation See 2 2 for an example of proper namelist syntax NMLST ERROR 28 Missing closi
63. fied directory or any of its subdirectories into a single source file 8 1 The concat s script file Source listings may be concatenated by issuing the following command csh v concat s where concat s is as follows 1 2 3 3 2 1 SCRIPT FILE TO CONCATENATE FILES INTO ONE FILE User sets OUTFILE DIRECTORY Get files from home directory if e xedit22 cp dclarke editor version2 2 xedit22 A gt Create the input deck for EDITOR and execute rm f inedit 10 cat lt lt EOF gt inedit 11 editpar outname OUTFILE ibanner 1 job 7 idump 1 ext f 12 branch DIRECTORY 13 EOF 14 chmod 755 xedit22 15 xedit22 16 fo gt Tidy up directory 17 xm f editlp inedit output xedit22 OONDOTPWNHE A softcopy of concat s may be found in the file edit22 tar downloaded from the EDITOR website http www ap smu ca dclarke editor The first segment retrieves xedit22 from the user s home directory if needed The second segment prepares the input deck for EDITOR appropriate for concatenating source listings In addition to the general namelist parameters described in 32 5 two of the namelist parameters used to control PRECOM are also used by CONCAT These are described below parameter description default CONCAT job 7 branch cha
64. g the end and err options in the parameter lists of read and open statements are considered together and by default are assigned labels between 10 and 990 All input statements read decode are resequenced between 1010 and 1990 and all output statements write print encode are resequenced between 2010 and 2990 This allows one to identify at a glance which targets belong to do goto statements which belong to input statements and which belong to output statements As part of the resequencing process TARGET will force all do loop and goto statements to land on a continue statement thus displacing the original targeted statement by one line For do loop targets the continue statement is put after the original targeted statement while for goto statements the continue statement is placed before the original targeted statement This leaves the logical intent of the code intact Besides resequencing origin target statements TARGET may be instructed to relabel con tinuation statements and force uniform indentation These three features are illustrated in the following example Original code subroutine sub1 in jn x y array iret real x in y jn array in jn go to 1 31 iret 31 continue do 10 j 1 jn do 10 i 1 in 10 array i j x i 2 2 0 x i y j y j 2 if imax le 100 then imax 100 else imax 200 endif 1 continue return end FORTRAN TIDY UP 34 Tidied code subroutine in jn x
65. gram module Using FSPLIT is unsatisfactory because it pays no attention to which modules have been changed and which have not forcing MAKE to recompile all the program modules not just the ones that were changed The EDITOR precompiler offers an easy way around this problem One may instruct the precompiler to make yet another pass through the master source file and this time split it into individual files for each module The naming convention for these files is as one might hope the name of the module with a specified extension default is f One can even specify in which directory these files should be placed Before writing a file to disc the precompiler will check to see if there is already a file by that name on disc in the specified directory If there is not a new file is created If there is the precompiler compares line for line the version of the module it just split off the master file with the disc file If the two differ the disc file is updated If the two are identical the disc file is not updated leaving its timestamp unaltered In this way MAKE will not recompile unaltered program modules For large source codes and slow compilers this is no small consideration At the same time the EDITOR preprocessor will generate a makefile if makename is specified see 2 5 The user may tell EDITOR which compiler compiler options loader and loader options to use in the makefile or to use sensible defaults If you need
66. hanges which need to be the most accessible setting the parameter values for example would remain in the script file itself Similarly if there were numerous changes to be merged into the code before precompilation these could be put into a separate file called chged22 say then the statement read chged22 would be inserted after line 20 Again this keeps the file edit22 s uncluttered The fifth segment generates the namelist input data file inedit which instructs the current version of the EDITOR binary executable xedit22 how to preprocess edit22 In this example the namelist parameters are set so that chgedit will first be merged into edit22 which is then precompiled since ipre 1 for gfortran with the namelist replace ment feature on inmlst 1 the conditional splitting feature on iupdate 1 and the micro tasking feature off iutask 0 All files split from the merged master source code will be placed in the directory editor2 2 and will have the extension f appropriate for FORTRAN source code Since iupdate 1 and makename is set to a non blank character string in the input deck a makefile with the name makeedit will be generated The makefile will use the compiler gfortran c and loader gfortran with the highest safe optimisa tion coptions optimise not commented out The library libnmlst a will be linked INSTALLING EDITOR 49 with the EDITOR object code to generate a binary executable called xedit22 Finally the current ver
67. haps overly aggressive Thus the user should be aware of nested loops with goto statements which redirect execution outside the loop and instruct the EDITOR auto scoper to pass over the loop This is done with the c nopar directive 1 c nopar 2 do 30 i i1 i2 3 do 20 k k1 k2 4 do 10 j j1 j2 5 if d i j k gt factor d ism1 j k go to 40 6 10 continue 7 20 continue 8 30 continue 9 40 continue Note that the c nopar is interpreted only by EDITOR Thus if source code unscoped by the EDITOR auto scoper is passed through the compiler s auto tasker an attempt may still be made by the compiler to generate the appropriate cmic directives Example 5 The second case where the EDITOR auto scoper can fail is more subtle The EDITOR auto scoper will scope nested loops in which there is a call to a subroutine If the user determines that the subroutine call destroys parallelism the loop should not be scoped and the user should place a c nopar directive before the outer loop If on the other hand the subroutine call does not destroy parallelism one still has to be careful There may still be the problem of scoping the variables in the subroutine argument list In the example below the variable vp is assigned values by the subroutine x3zc1d and not by an assignment statement explicitly in the loop itself Without looking in the subroutine and EDITOR is not sophisticated enough to do this EDITOR declares vp to PRECOMPILING SOURCE CODE 18
68. he desired FORTRAN compiler is selected Here FCOMP is a system variable no longer representing the user s hypothetical FORTRAN compiler in 89 1 set by the UNIX setenv command and is used in two places First on line 17 it serves as the EDITOR macro to tailor edit22 to the chosen compiler Second on line 28 it is the setting for the namelist parameter compiler in the input deck inedit which determines which compiler is used to compile edit22 Line 11 of the second segment retrieves the namelist library 1libnm1st a from the direc tory nmlst Line 13 of the third segment creates the directory editor2 2 into which all files split from the master source file edit22 and object files once compiled are placed The fourth segment lines 14 21 generates the change deck chgedit which gets merged with the master file edit22 Line 17 sets the compiler by defining the appropriate EDITOR definition and if there were any other EDITOR definitions or aliases to set they could be set here too Next the change deck sets values for the parameters described in 89 3 Because of the memory management built into EDITOR it is unlikely that these values would ever have to be changed from those given If there were numerous EDITOR macro settings one might consider placing them all in a separate file called for example edit22 mac and then replace line 17 with the statement read edit22 mac In this way the script file will remain concise and only those c
69. he first column EDITOR will not attempt to read statements that do not adhere to the precise syntax COPY ERROR 9 Syntax Extra space after EDITOR sentinel This message indicates that the EDITOR sentinel is not followed immediately by the rest of the command Again strict compliance with the syntax is required ERROR MESSAGES 55 CTOI ERROR 10 A non numeric character detected Some EDITOR commands have fields inside which integers are expected Thus if a user inadvertently types delete sub1 io where the io should have been a 10 ERROR 10 will be generated There is no error message 11 ERRSET ERROR 12 Number of issued errors exceeds ki Trouble If one really wants to see all the errors at the same time go ahead and recompile EDITOR with a higher value of k1 However there is probably something really wrong with the input files and this will have to be corrected Once the errors are fixed this error message should go away as well INOREX ERROR 13 Unrecognised EDITOR command EDITOR didn t recognise what followed the sentinel as a valid EDITOR command Check syntax INOREX ERROR 14 More than ten nested if statements EDITOR only allows as many as 10 nested if statements whether they be if define or if alias One needs to simplify the nested structure INOREX ERROR 15 Expecting a character expression See ERROR 3 INOREX ERROR 16
70. icit 10 implicit none 11 cdeck common 12 if define CF77 13 characterx 8 tod 14 endif CF77 15 if define PGF77 16 character 24 tod 17 endif PGF77 18 if define XLF 19 character 26 tod 20 endif XLF 21 common com tod 22 cdeck declare 23 call implicit 24 call common 25 deck tod 28 program tod 30 c PURPOSE This program returns the time of day on various systems 34 call declare 35 if define PGF77 36 character 24 fdate 37 endif PGF77 38 external WRITE 39 c 40 CA O O O rn 41 c 42 c Get time of day tod 43 c 44 x if define CF77 45 call date tod 46 endif CF77 47 if define PGF77 48 tod fdate 49 endif PGF77 50 x if define XLF 51 call fdate_ tod 52 endif XLF 53 c PRECOMPILING SOURCE CODE 7 54 c Write result to CRT using desired i o routine aliased to WRITE 55 c 56 call WRITE 57 stop 58 end 59 c 60 x deck writel 63 c subroutine writel 64 x if alias WRITE eq writel 65 c 66 c PURPOSE This subroutine writes tod to the CRT Or lt lt 68 ee 69 c 70 call declare T oc a ta a a a a i a a a a a el oa 73 74 write 6 2000 tod 75 if define CF77 76 2000 format Time of day according to Cray s CF77 is a 77 endif CF77 78 if define PGF77 79 2000 format Time of day according to Portland Group s PGF77 is a 80 endif PGF77 81 if define XLF 82 2000 format Time of day according to IBM s XLF
71. ile but in all likelihood all one can do is to reset k2 and or safety Following are the OVERFLOW fatal error messages They indicate which subroutine originally detected the overflow and whether to recompile with a higher value for k2 or to resubmit with a lower value of safety The last message is probably trouble since it implies that enough error messages were inserted to exceed array bounds OVERFLOW File overflow in CDECKS Increase parameter k2 OVERFLOW Overflowed text file written to file OVERFLOW TXT OVERFLOW ABORTS OVERFLOW File overflow in MERGE Increase parameter k2 OVERFLOW Overflowed text file written to file OVERFLOW TXT OVERFLOW ABORTS OVERFLOW File overflow in MERGE Specify lower value for safety than x OVERFLOW Overflowed text file written to file OVERFLOW TXT OVERFLOW ABORTS OVERFLOW File overflow in NMLST Specify lower value for safety than x OVERFLOW Overflowed text file written to file OVERFLOW TXT OVERFLOW ABORTS OVERFLOW File overflow in PARALLEL Increase parameter k2 OVERFLOW Overflowed text file written to file OVERFLOW TXT ERROR MESSAGES 53 OVERFLOW ABORTS OVERFLOW File overflow in PRECOM Specify lower value for safety than x OVERFLOW Overflowed text file written to file OVERFLOW TXT OVERFLOW ABORTS OVERFLOW File overflow in TARGET Specify lower value for safety than x OVERFLOW Overflowed text file written to file OVERFLOW TXT OVERFLOW ABORT
72. independent of each other and or PRECOMPILING SOURCE CODE 14 one may micro task a code by sending separate iterations through a do loop to separate processors Of the two micro tasking is really the only way to fully exploit the inherent parallelism in a code Critical to micro tasking a code is the concept of private and shared variables Private variables are those for which each processor has a separate and independent copy Shared variables are those which all processors read from and perhaps write to The rules for determining which variables are private and which are shared are fairly straight forward A variable is private if 1 The first time it appears within a do loop structure it appears on the left hand side of an equals sign and 2 It is not indexed by the outer do loop index Otherwise the variable is shared The key to micro tasking is to identify correctly which variables are private and which are shared a task known as scoping Only if the variables are scoped properly can a micro tasked code be generated which yields the same results as the original serial code A number of platforms offer compiler options to help users macro task and micro task their codes In developing the ZEUS code for example the author found that the auto tasking features provided by Cray around 1990 often made scoping errors and or were too timid in some of the loops they attempted to scope and a more aggressive and accur
73. ing source code is kept if the source code following the previous if and all the way to this else statement was not kept i e if the truth value of the previous if is false Note that el is an acceptable abbreviation endif closes the previous if else structure All source code following the endif statement is not affected by the previous if or else statements For every if statement there must be an endif statement which follows Note that ei is an acceptable abbreviation call deckname includes the contents of the common deck deckname at the location of the call statement Note that ca is an acceptable abbreviation for call Finally one may insert comment statements if desired by putting an asterisk in both columns 1 and 2 These comments will appear in the master source code where the user places them but will not be copied over to the file which EDITOR prepares for the compiler Following is a simple example showing how these statements can be used The function of the program is simply to return the time of day Note that the line numbers in the first PRECOMPILING SOURCE CODE 6 five columns are included for reference only and are not modifications made by the EDITOR precompiler Master source file 1 2 Select compiler Choices are CF77 PGF77 or XLF 3 xx 4 define PGF77 5 6 Select i o subroutine by setting an alias for WRITE 7 xx 8 alias WRITE writel 9 cdeck impl
74. is a 83 endif XLF 84 x endif 85 return 86 end 87 c 88 deck write2 90 c 91 subroutine write2 92 if alias WRITE eq write2 93 c 94 c PURPOSE This subroutine writes tod to the CRT using a different 95 c format than WRITE1 96 c Of CH S333 33 333 3S SS SS SS 98 c 99 call declare 100 c 101 Coe rr rn er ene 102 c 103 write 6 2000 tod 104 2000 format Time of day is a 105 endif 106 return 107 end With the EDITOR macros settings as defined in lines 4 and 8 the precompiler would convert this code into the following form e g see tod s at the end of 2 5 which would be read by the compiler Note that the line numbers from the master code have been preserved PRECOMPILING SOURCE CODE 8 Precompiled source file 2f e 28 Cc program tod 29 c 30 c PURPOSE This program returns the time of day on various systems 31 c 32 ro e 33 c 10 implicit none 16 character 24 tod 21 common com tod 36 character 24 fdate 38 external writel 39 c IN SSSR SSS SS SS SS SSSR aR SS SSS aaa SS Sa a ease aS SS esse 41 c 42 c Get time of day tod 43 c 48 tod fdate 53 c 54 c Write result to CRT using desired i o routine aliased to WRITE 56 call writel 57 stop 58 end 59 c 61 c 4 1 4 2 4 3 4 4 4 4 f 4 62 c 63 c subroutine writel 65 c 66 c PURPOSE This subroutine writes tod to the CRT
75. is error message being issued TARGET ERROR 43 Too many do s and or goto s in this deck The sum of the number of do loops and the number of goto statements including gotos im plied by the err and end parameters in open and read statements exceed ienddo ibegdo 1 where ibegdo and ienddo are namelist input parameters see 5 1 One must either de crease the number of targets in this module or increase the difference between ibegdo and ienddo TARGET ERROR 44 Too many read s in this deck The number of formatted read statements exceeds iendre ibegret1 where ibegre and iendre are namelist input parameters see 5 1 One must either decrease the number of read targets in this module or increase the difference between ibegre and iendre ERROR MESSAGES 59 TARGET ERROR 45 Too many write s in this deck The number of formatted write statements exceeds iendwr ibegwr 1 where ibegwr and iendwr are namelist input parameters see 5 1 One must either decrease the number of write targets in this module or increase the difference between ibegwr and iendwr TARGET ERROR 46 More than 2 decks defined Part of file lost Program has more modules subroutines or decks than can be accommodated by EDITOR as compiled Either reduce the number of modules in the program or recompile EDITOR with a larger value for k4 PARALLEL ERROR 47 Too many variables in do loop Increase K9
76. l error messages generated by EDITOR 2 If on the one hand MERGE and PRECOM are performed together on the file myprog then EDITOR will generate two additional source files namely myprog m and myprog f The former will be the result of the merger with all the precompiler commands if any remaining while the latter will be a precompiled version ready for the compiler containing nothing but FORTRAN having had all the precompiler commands carried out and then expunged If on the other hand MERGE is used with ipre 0 then only a m file will be generated Then if myprog m is passed through the precompiler using precom s the precompiled file will be named myprog m f Note that if the EDITOR namelist parameters in the two scenarios have the same values then the files myprog f and myprog m f will be identical 5 TARGET FORTRAN tidy up The TARGET feature of EDITOR was designed to rewrite a user s source code with uniform origin target labels continuation characters and indentation as well as rearranging the various decks and groups alphabetically TARGET can also be instructed to replace do enddo structures with targeted do loops but not the reverse reflecting the author s bias By default a separate file whose name is the same as the input file with the extension t appended is created containing the tidied source listing The original file is left as is TARGET s primary function is to resequence numbered statements targets
77. lable under the Cray Time Sharing System CTSS which was widely used on Cray machines before 1989 and in the opinion of the author one of the most useful and flexible precompilers of its day In the years since EDITOR has undergone many changes that has taken 1t beyond HISTORIAN and it remains the precompiler for the ZEUS family of astrophysical MHD codes http www ica smu ca zeus3d To use EDITOR one must insert various types of EDITOR commands all relatively unobtrusive into an existing FORTRAN source code All EDITOR commands go on sep arate lines and begin with an asterisk in the first column There may be one EDITOR command per line Depending on the task chosen EDITOR will make from 1 to 7 passes through the source code carrying out various directives as specified by the EDITOR com mands During precompilation the resulting source code will be standard FORTRAN void of any EDITOR commands and ready for the compiler It is unlikely that users with small easily managed source codes will want to bother with any precompiler But curators of particularly large codes which offer a variety of features work for a variety of compilers and are modified by several people simultaneously will want to consider some sort of preprocessor such as EDITOR For example codes which need to work with more than one compiler will almost certainly require a separate version for each compiler to accommodate the different extensions e g timing routines
78. ng delimiter This error message indicates that the closing slash is absent from the namelist designation See 2 2 for an example of proper namelist syntax ERROR MESSAGES 57 NMLST ERROR 29 Too many variables in namelist Increase K9 This error message indicates that the user has defined more variables in the namelist state ment than may be accommodated by the current setting of the internal parameter k9 One may break up the namelist into smaller namelists or recompile EDITOR with a larger value of k9 89 3 NMLST ERROR 30 Too many vars in namelist Increase inmlst This error message indicates that the user has defined more variables in the namelist state ment than the user selected value of inmlst 2 5 would allow One may break up the namelist into smaller namelists or reset inmlst to a higher value NMLST ERROR 31 No variables found in namelist There must be at least one valid variable listed in each namelist defined NMLST ERROR 32 Unrecognised syntax in dimension statement In replacing the namelist statement with calls to subroutines in namelist a EDITOR must make decisions as to which subroutines to call In so doing EDITOR scans the declarations at the head of the program module to learn about the attributes real integer etc and dimensions if any of each variable in the namelist Should it find any FORTRAN syntax error in the declaration list that impe
79. ode as determined by the settings of the EDITOR macro definitions see 2 1 from the computation of the current statement number fourth column 4 MERGE Merging source code 4 1 Change decks One important feature of EDITOR is the ability to merge a change deck into an existing source code This feature is useful from the standpoint of keeping the changes to a working version of a source code separate from the source code itself Further change decks are useful to code development projects in which there are several contributors In principle a curator of a code may gather in all change decks and let EDITOR merge these change decks into the current master code thereby generating the next version Finally each code developer may independently and temporarily merge their own change deck into the current version of the code in order to develop and debug their changes Change decks consist largely of the new lines of FORTRAN that the user wishes to place into an existing code along with any EDITOR precompiler statements that may be required These code segments may either be inserted into the code at a specified location or replace a specified part of existing code There are four EDITOR commands that control a MERGE 1 insert deckname n inserts text immediately following the insert command into the source code directly after line n in c deck deckname 2 delete deckname n m deletes lines n through m in c deck deckname
80. orm to ANSI standard FORTRAN 77 TARGET ERROR 38 Expecting a numerical target A FORTRAN statement which is supposed to include a numerical target e g goto did not have a numerical target where one was expected TARGET ERROR 39 Too many origins Going on to next deck Too many origins in the program module The tidy up process cannot continue with current module so execution continues with the next module Either break the module up into smaller modules or recompile EDITOR with a larger value of k3 89 3 TARGET ERROR 40 Target defined more than once Two or more target statements use the same target number TARGET ERROR 41 Origin has no target The origin refers to a non existent targeted statement TARGET ERROR 42 Ambiguous targets This error stems from the TARGET feature which replaces do enddo structures with targeted do loops This is a badly designed feature because it requires the enddo statement to include the do loop index in order to perform the replacement Thus the statement do i i1 i2 must end on the statement enddo i not just enddo The trouble is that compilers which offer the do enddo extension treat the do loop index on the enddo statement as optional not mandatory Thus the TARGET feature to replace do enddos with targeted do loops is not as general as it could be In particular enddo statements which do not echo the do loop index will result in th
81. orted PRECOMPILING SOURCE CODE 13 13 The last character on the last line of a namelist assignment must be the closing sentinel Be careful that this does not go beyond the 72nd column If it is left out or inadvertently placed beyond the 72nd column an error message will be generated and execution will abort 14 One is free to define as many namelists as desired in the source code However once one namelist is defined it must be read from the namelist input data file by a read statement line 47 above before a new namelist is defined Thus only one namelist may be pending at a time This is not a restriction of 90 namelist 15 The order of the namelists not the variables but the namelists themselves must be the same in the namelist input data file as they are read by the source code Thus if the source code is written so that namelist data2 is read after namelist data1 then the variable assignments for data2 must appear after the variable assignments for data1 in the namelist input data file If data2 should appear before data1 in the namelist input data file the read to data1 will cause the data for data2 to be skipped Thus when it comes time to read data2 these data will not be found and an error message will ensue 16 For every namelist read by the source code there must be an entry with the same namelist name in the namelist input data file If for example none of the parameters for namelist data2 are to be assigned
82. piled version of the source code which is ultimately sent to the compiler The following lists the legal syntax for EDITOR if statements 10 if define macro the following source code is kept provided the macro is defined by a define statement somewhere in the file Note that the comma following if define is optional It was introduced in order to mimic HISTORIAN where it is not optional Note to HISTORIAN users the alias feature has no analogue in HISTORIAN if define macro the following source code is kept provided the macro is not defined by a define statement somewhere in the file if def not macro same as 2 Note that def is an acceptable abbreviation for define if def macrol and macro2 the following source code is kept provided both macros are defined by a def statement somewhere in the file if def macrol or macro2 the following source code is kept provided either macro is defined by a def statement somewhere in the file if alias macro eq phrase the following source code is kept provided the alias macro has been set to the character string phrase by an alias statement somewhere in the file if al macro ne phrase the following source code is kept provided the alias macro has not been set to the character string phrase by an alias statement somewhere in the file Note that al is an acceptable abbreviation for alias else the follow
83. port below the loop in comments and adds no cmic statement before it so that the compiler can have to have a crack at it if its auto parallelisation feature is enabled In addition I O and character operations within a loop will prevent parallelisation 1 imax 0 2 ival il 3 do 40 j j1 j2 PRECOMPILING SOURCE CODE 16 4 do 30 i i1 i2 5 iarray i j ival 6 ival i 1 7 imax max0 imax iarray i j 8 30 continue 9 40 continue 10 EEEE K od ale k k k kk kK kK k k k K kK K k KK K K kK K K k K K K K K KK K K al le dad FK K KK FK K K KK K K KK FK K K KK a K K KK K 11 ox EDITOR NO CMIC DIRECTIVE REPORT FOR LOOP 40 9 ek KKRRE 12 CK o od OK OK OK OK OK K OK K K K K K K 2K 2K 2K 2K K 2K 2K 2K 2K 2K 2K 2K a K K K K K K K 2K 2K 2K 2K 2K 2K 2K 2K 2K 2K 2K 2K 2K K K K ale K kK K K ade 2K 2K 2K 2K 2K 2K 2K K ak ak ak ok 13 c No parallel directives issued because the following variable s 14 cx was were found to generate dependencies or reductions 15 c ival dependency xk 16 c imax reduction xk 17 Ck ak ak ak ak ak ak ak ak bb aK aK aK aK aK aK ee 3K 3K K K K aK K aK aK 2K aK ak ak 3k 3k 3 3K 3K 3K 3K 3K 3K 3K 3K K K KKK KK K K K K K 1 do 130 j j1 j2 do 120 i i1 i2 3 chqty i j char iqty i j 4 120 continue 5 write iodmp chqty i j i i1 i2 6 130 continue T EEK k k k k K K K 3K 3K 3K 3K AAAI K K K K aK aK ACA ACAI A I I I 3K 3K 2k 2k 2k 2k K Bock EDITOR NO CMIC DIRECTIVE REPORT FOR LOOP 130
84. racter 32 string indicating top directory from blank which files are sought ext common extension of files character 8 gt src 44 9 Installing EDITOR 9 1 Installation This section describes how to install EDITOR on your UNIX based system From the website http www ap smu ca dclarke editor download the gzipped file edit22 tar gz into a directory you wish to contain the EDITOR directory Then upon issuing the commands gunzip edit22 tar gz tar xvf edit22 tar cd editor_v2 2_ICA ls FC the following should appear on your screen README bldlib2 editor compare s edit22 GFORTRAN f merge_precom s concat s edit22 IFORT f number s edit22 edit22 PGF77 f precom s edit22 CF77 f edit22 XLF f split s edit22 F90 f edit22 s target s edit22 G95 f merge s manuals edit22_man pdf nmlst dnamelist dnamelist s namelist namelist s These are all the files needed to run and operate the program edit22 version 2 2 of EDITOR EDITOR actually manages itself That is peppered throughout EDITOR are numerous EDITOR commands described in 82 1 Other than the dk and cd statements these are mostly if def endif constructs to account for the various compilers EDITOR supports Therefore to get things started precompiled versions of edit22 for each supported compiler named edit22 lt comp gt f where lt comp gt is one of CF77 F90 XLF are provided in the directory editor each stripped of all EDITOR commands
85. ructure that the author finds very useful and is why this specific example has been included in this otherwise general template In this case a program has been written with all the parameter statements placed together in a common deck called par Every subroutine that requires knowledge of the parameter values then has a call par statement at the beginning of the declaration list If for every job run a different set of parameter values is required the easiest and most accessible place to make this change is right in the script file which merges and precompiles the source code Thus right in merge_precom s one might include the most often needed changes using the MERGE edit structures described in this section Then as before one can issue a read command to bring in the bulk of the changes contained in the user supplied file CHANGEDECK Third the now fourth segment includes settings to the input parameters peculiar to PRECOM as discussed in 2 5 MERGING SOURCE CODE 31 Some notes 1 Should the EDITOR merger detect any EDITOR syntax errors EDITOR will insert an error message immediately following the offending statement in the amalgamated change deck m extension The user will be told that errors were detected and how to find them Once the errors are corrected in the original change deck i e not the m file where the errors were reported the user can attempt to merge the files again See A 2 for a description of the non fata
86. s described in 2 5 there are three namelist parameters which are peculiar to MERGE parameter description default MERGE job 3 chgdk name of change deck to be merged with inname character 64 inum 1 gt a NUMBERed file will be created 0 0 gt no NUMBERed file ipre 1 gt a PRECOMpiled file will be created 0 0 gt no PRECOMpiled file One can use MERGE in tandem with either or both NUMBER and PRECOM In the case of the former inum should be set to 1 and all the input parameters peculiar to NUMBER 3 2 become applicable If the cse of the latter ipre should be set to 1 and all the input parameters peculiar to PRECOM 82 5 become applicable Probably the most useful function performed by EDITOR is the MERGE and PRECOM features used in tandem A precompiled version of a merged FORTRAN source code may be generated by issuing the following command csh v merge_precom s where merge_precom s is as follows 1 1 2 3 3 2 1 MERGING SOURCE CODE 30 2 SCRIPT FILE TO MERGE TWO FILES AND PRECOMPILE THE RESULT 3 4 User sets DIRECTORY CHANGEDECK SOURCECODE MAKEFILE EXECUTABLE 5 COMPILER LIBRARIES 6 7 See precom s for list of compilers and preset compiler options 8 9 FeSsSsssssssssssssssssssssssssssssss gt Get files from home directory 10 if e xedit22 cp dclarke editor version2 2 xedit22 11
87. scovered What makes EDITOR s COMPARE different from diff on most UNIX platforms is that it may be instructed to ignore superficial or unimportant differences such as those found in FORTRAN comments i e lines with a c or C in the first column the number of blanks left between words and the FORTRAN continuation characters chosen character in column 6 This is an attempt to get beyond the most common differences in programming style and uncover only those differences which may alter the logic of the program COMPARE is also much better at finding where the files reconverge than diff Finally if there are an unruly number of differences one may instruct EDITOR to stop searching after a specified number of differences have been found EDITOR reports the differences by dumping the portion of the line from both files where the difference was found and points to the very character which triggered the report It also tells the user on which line the two files reconverge Below is an example of two files with some differences and the EDITOR COMPARE reports generated by comparing these two files un various ways File 1 tod1 program tod CASERAS AS gt This program returns the time of day on various systems character 8 tod call date tod write 6 10 tod 10 format Time of day is a stop end OONDOAEWNEKE program tod 1 2 3 4 5 c PURPOSE This program returns the time of day on various systems 6 7 8 9 impli
88. se include 1 CF77 Cray nearest former OS equivalent UNICOS 2 F90 Sun nearest former OS equivalent SUNOS 3 G95 Gnu 4 GFORTRAN Gnu 5 IFORT Intel 6 PGF77 Portland Group 7 XLF IBM nearest former OS equivalent AIX with some being tested more thoroughly than others Former OS designations LINUX and CONVEXOS have no specific replacements Some warnings CF77 and XLF have not been tested at all they are carried over directly from UNICOS and AIX in Version 2 1 There were certain peculiarities for 77 under SUNOS SOLARIS such as requiring a double backslash in subroutine UPDATE and non standard OpenMP statements in subroutine PARALLEL that may or may not still be true for Sun s 90 77 compiler G95 GFORTRAN and IFORT are the three best tested compilers Other changes include 1 Parallelisation commands c shared and c private have been added 82 3 2 EDITOR now has its own web site http www ap smu ca dclarke editor DAC June 2011 2 PRECOM Precompiling source code 2 1 Basic precompiling The main purpose of EDITOR is to precompile large FORTRAN source codes By default the EDITOR precompiler creates a separate file whose name is the same as the original file with the extension f appended containing the precompiled source listing The file contain ing the original source code is left as is EDITOR was designed to mimic HISTORIAN the precompiler avai
89. sion of xedit22 is launched by line 34 and edit22 is preprocessed Line 36 in the sixth segment fires up the makefile makeedit generated in the previ ous segment This compiles and links the new EDITOR code generating a new version of xedit22 overwriting the version of xedit22 which did the preprocessing Finally line 38 of the last segment removes some of the intermediate files no longer needed A few of the intermediate files e g edit22 f edit22 m and makeedit are left intact as these can be useful for debugging should something go awry 93 EDITOR parameters As FORTRAN uses static memory there are numerous parameters that EDITOR requires to set internal array sizes For the most part the default settings should be fine for any application with any compiler However in case the user needs to change any of them an exhaustive list of EDITOR s parameters what they limit and their default values are given below parameter interpretation default k1 maximum number of errors to be reported 1 000 k2 maximum number of lines in source code to be processed 100 000 k3 maximum number of origins per module TARGET 2 000 k4 maximum number of decks in source code 2 000 k5 maximum number of targets per module TARGET 2 000 k6 maximum number of characters per line of source code 128 k7 maximum number of EDITOR definitions 1 000 k8 maximum number of EDITOR aliases 1 000 k9 maximum number of variables within a module 4 000 The purpose of the
90. status old 16 open 52 file outdata status unknown 17 c 18 c Define list of parameters which may be set by namelist datal 19 c 20 namelist datal cscalar iscalar rscalar lscalar 21 cvector ivector rvector lvector 22 carray iarray rarray larray 23 c 24 c Default values for namelist parameters 25 c 26 cscalar 27 iscalar 0 28 rscalar 0 0e00 29 lscalar false 30 do 10 i 1 in 31 cvector i 32 ivector i 0 33 rvector i 0 0e00 34 lvector i false 35 10 continue 36 do 30 j 1 jn 37 do 20 i 1 in 38 carray i 39 iarray i 0 40 rarray i 0 0e00 41 larray i false 42 20 continue 43 30 continue 44 c 45 c Read namelist from logical unit 51 46 c 47 read 51 datal 48 c 49 c Write a namelist summary to logical unit 52 50 c 51 write 52 datal Namelists read data from an ASCII namelist input data file named indata in this example which the user prepares before executing the binary Line 15 is an ordinary open statement appropriate for linking an existing ASCII disc file to the program at execution time Unit 51 was chosen arbitrarily Most any unit number other than 5 or 6 may be chosen The namelist statement on line 20 defines which variables belong to the namelist data1 and thus which variables may be assigned values in the namelist input data file indata Line 47 is where the data in the namelist data1 are read from ind
91. sue the following differ ence report COMPARE COMPARE The following declarations were not found in file decl m COMPARE real s11 COMPARE real s12 COMPARE real reqs 20 COMPARE equivalence reqs 2 s3 COMPARE equivalence reqs 11 s11 COMPARE equivalence reqs 12 s12 COMPARE equivalence reqv jdim 3 idim 1 wi 1 COMPARE COMPARE The following declarations were not found in file dec2 li COMPARE real regs 10 COMPARE equivalence reqs 3 s3 COMPARE equivalence reqv jdim 3 idim 1 w2 1 COMPARE Obviously several changes other than formatting changes were introduced when dec1 was recast into dec2 Some of the changes may have been deliberate the addition of variables s11 and s12 increasing the dimension of reqs from 10 to 20 while the remainder are probably typos in the equivalence statements in dec2 reqs 2 and w1 appear twice while reqs 3 and w2 do not appear at all 6 3 The compare s script file Two source listings may be compared by issuing the following command csh v compare s where compare s is as follows 1 2 3 3 2 1 User sets SOURCECODE1 SOURCECODE2 Get files from home directory if e xedit22 cp dclarke editor version2 2 xedit22 q gt Create the input deck for EDITOR and execute rm f inedit 10 cat lt lt EOF gt inedi
92. t 11 editpar inname SOURCECODE1 in2name SOURCECODE2 12 ibanner 1 job 5 icompar 1 ndiff 100 ignore 0 0 0 13 EOF 14 chmod 755 xedit22 15 xedit22 16 f gt Tidy up directory 17 xm f editlp inedit output xedit22 OONDOAEWNHE COMPARING SIMILAR ASCII FILES 42 A softcopy of compare s may be found in the file edit22 tar downloaded from the EDITOR website http www ap smu ca dclarke editor The first segment retrieves xedit22 from the user s home directory if needed You may wish to add two similar lines to retrieve from their home directories the two files to be compared SOURCECODE1 and SOURCECODE2 The second segment prepares the input deck for EDITOR appropriate for comparing two source listings In addition to the general namelist parameters described in 82 5 there are four namelist parameters peculiar to COMPARE These are described below parameter description default COMPARE job 5 in2name name of file to be compared with inname charx 64 icompar 1 gt report first ndiff differences 1 2 gt list discrepancies in declarations ndiff maximum number of differences to report 100 icompar 1 only ignore integer vector indicating types of differences to 0 0 0 report 0 or ignore 1 ignore 1 continuation characters ignore 2 blanks ignore 3 comments icompar 1 only Some notes 1 ignore is a vector with 3 elem
93. tents of their respective declaration lists without regard to format This mode of comparison does not extend into the body of the FORTRAN module containing the FORTRAN executables The utility of this feature is perhaps best illustrated by an example In an attempt to align a subroutine with a particular coding style suppose one wishes to reformat all the declarations at the beginning of a program module from the style illustrated in the file dec1 to that in file dec2 below Style 1 file dec1 implicit none integer idim jdim parameter idim 100 jdim 100 integer i j is ie js je ieqs 10 real si vi idim w1 jdim a1 idim jdim s2 v2 idim w2 jdim COMPARING SIMILAR ASCII FILES a2 idim jdim s3 v3 idim w3 jdim s4 s5 s6 s7 s8 s9 s10 reqs 10 reqv 3 idim 3 jdim equivalence ieqs 1 i ieqs 2 is ieqs 3 ie ieqs 4 j Cieqs 5 js ieqs 6 je equivalence reqs 1 s1 reqs 2 s2 reqs 3 s3 reqs 4 s4 reqs 5 s5 reqs 6 s6 reqs 7 87 reqs 8 s8 reqs 9 s9 reqs 10 s10 reqv 1 v1 1 reqv idim 1 v2 1 reqv 2 idim 1 v3 1 reqv 3xidim 1 w1 1 reqv jdim 3xidim 1 w2 1 reqv 2 jdim 3 idim 1 w3 1 common comi ieqs common comr reqs reqv al a2 Style 2 file dec2 A A ee ee eee es HH HS IMPLICIT STATEMENT 2 gt 25 22 2225 22 2522 2 ERE AA A AI implicit none II ee ee ee a PA
94. that the EDITOR auto scoper is able to distinguish between proper arrays with argument lists such as btot in lines 13 and 14 which are declared and scoped and intrinsic functions such as sqrt in line 14 which are not declared nor scoped Similarly user written functions whose attribute real integer etc is not declared will not be scoped User written functions whose attribute is declared will not be scoped provided they are also declared as external A user written function with declared attribute not declared external will be scoped and this may or may not have deleterious effects Example 2 If dependencies and or reductions are found in the loop the loop as written is not parallelisable and is not scoped A reduction is when the value assigned to a private variable depends on the value of that variable as determined by a previous iteration as is the case for imax below or on another element of that variable should the variable be an array A dependency is where a variable is first used as a shared variable then as a private variable as is the case for ival below A loop containing either a dependency or a reduction will in general generate different answers depending upon whether it is run serially or in parallel and thus is non parallelisable Most compilers are sophisticated enough to rewrite code to eliminate most reductions and some dependencies and thus if EDITOR finds a non parallel loop it inserts a No cmic directive re
95. though it were a vector NAMELIST ERROR 9 gt next namelist begun before closing quote found Character assignments may run over several lines Thus if a namelist opening sentinel is found in the second column of a line before the closing quote of the current character assignment is found this message results A common cause of this message is if the closing quote has been inadvertently shoved beyond the 72nd column or if the closing quote is a single double quote while the opening quote is a double single quote NAMELIST ERROR 10 gt missing opening quote If the first non blank character after the in a character assignment is not a single or a double quote this message is issued NAMELIST ERROR 11 gt blank data A variable is assigned a null field NAMELIST ERROR 12 gt premature end of file File appears to have ended before the closing sentinel of the current namelist was found Common cause is if the closing sentinel of the last namelist was inadvertently shoved beyond the 72nd column NAMELIST ERROR 13 gt missing sentinel to close namelist Next namelist has begun a sentinel was found in column 2 before the closing sentinel of the current namelist was found Common cause is if the closing sentinel is inadvertently shoved beyond the 72nd column NAMELIST ERROR 14 gt exponent must not exceed 999 The EDITOR namelist will not permit exponents in real variable assignments to exceed 999 or
96. tion statements to be given numerical continuation characters in the following sequence 1 2 3 4 5 6 7 8 9 1 2 3 etc Zero 0 is not used since it is an illegal continuation character in FORTRAN Finally TARGET can be instructed to rearrange the modules alphabetically according to the full deck name which consists of the group name as determined by the most recent group statement 82 1 followed by the deck name as determined by the most recent deck or cdeck statement 2 1 Common decks will be placed before ordinary decks The user may single out a few decks to be placed before all else regardless of where they belong alphabetically Thus for example if there were a deck containing opening comments or if it was desired to place the program before the subroutines this may be accommodated by setting the appropriate namelist parameters as described in the next subsection FORTRAN TIDY UP 35 5 1 The target s script file A source listing may be tidied by issuing the following command csh v target s where target s is as follows 1 2 3 3 2 1 SCRIPT FILE TO TIDY UP FORTRAN SOURCE CODE User sets SOURCECODE FIRST SECOND FIRSTCD FIRSTDK OONDOAEWNHE rm f inedit 10 cat lt lt EOF gt inedit 11 editpar inname SOURCECODE ibanner 1 job 2 idump 1 12 ibegdo 10 ienddo 990 ibegre 1010 iendre
97. to compile a few routines with different compiler options than the majority you may specify these special compiler options as well as the routines for which these special options apply PRECOMPILING SOURCE CODE 19 In addition the desired name for the binary executable may be specified Thus once the EDITOR preprocessor has processed the master source code the code may be compiled simply by typing make f makename where makename is the name of the makefile specified by the user 2 5 The precom s script file A precompiled version of a FORTRAN source code may be generated by issuing the following command csh v precom s where precom s is an ordinary C shell script file as follows Ul qe 4 2 Sp ete y tos p lle 4 p 2 SCRIPT FILE TO PRECOMPILE A SOURCE CODE f 3 4 User sets DIRECTORY SOURCECODE MAKEFILE EXECUTABLE COMPILER 5 LIBRARIES 6 7 Supported compilers have preset optimise and debug settings 8 9 compiler optimise debug 10 cf77 04 g 11 f90 f77 04 g C ftrap common 12 g95 02 g fbounds check ftrace full 13 gfortran 02 g fbounds check ffpe trap i z 0 de 14 ifort 02 m32 g debug parameters check fpel traceback m32 15 pgf77 fast g Ktrap fp Mbounds 16 xlf 04 g C qextchk qflttrap qsigtrap 17 18 otherwise user sets compiler coptions loader loptions dir
98. ule only Where ever possible EDITOR will abide by the user s choice for inc A 4 NAMELIST errors Namelist error messages as opposed to the NMLST error messages described in A 2 arise only at run time of software that was precompiled with the namelist replacement option ERROR MESSAGES 60 turned on These messages appear if any syntax errors are found in the namelist input disc files An example of an EDITOR namelist error message follows TIP TCL e CCC rrrrrrrrrrrrrrrrrrrrrcrrrrrrrrrrrerrrrrrrrrrrrrerrrrerrr errr ok ok q1 1 0e 10 infile indata inam 1 1 2 2 3 NAMELIST ERROR 4 gt unexpected character check syntax FEI I I IC ICICI ff A ACA AC AC ak k ak 3k 3k 3K 3K 3K 3K K K K K K k k k k k A K The error message echos the offending line in the namelist input data file places a carat immediately under the offending character in that line then explains what is wrong In this case there is a missing comma The only problem with EDITOR namelist error messages is that only one message can be generated at a time Each error message aborts execution and thus it may take several tries before all the syntax errors are found and corrected Below is a list of the possible namelist errors along with brief descriptions NAMELIST ERROR 1 gt column 1 reserved for comment sentinel c The rules of namelist input decks must be adhered to exactly If a character other than a blank c or C appears in the first column anywh
99. which keeps track of every line added or deleted from the file so that the pointers which indicate where the error messages should be inserted are kept up to date This logic is prone to flaws and while the author hasn t noted a single case of a misplaced error message in several years of constant use it is still conceivable that the occasional error message will appear out of context Non fatal error messages may be generated only by PRECOM 2 MERGE 4 or TARGET 85 The appropriate section should be consulted for the correct syntax of the desired operation Note that the input files are never altered by EDITOR Thus error messages appear in the f m or t output files only not the input files Nevertheless corrections should be made to the original input files making them to the output files where the error messages appear will have no effect ERROR MESSAGES 54 CDECKS ERROR 1 gt 10 nested calls Does a cdeck call itself This indicates that the user has exceeded the internal EDITOR limit of 10 nested calls to common decks Since it is unlikely such a complex structure would be deliberate the message suggests that perhaps the calling tree is closed e g perhaps common deck 1 calls common deck 2 which calls common deck 3 which calls common deck 1 or something to that effect If so this should be corrected CDECKS ERROR 2 Call made to an unknown common deck A call has been made to an undefined
100. will cause an error message to be generated and execution to abort PRECOMPILING SOURCE CODE 12 10 IMA 12 The first word to appear after the opening sentinel should be the namelist name as defined in the program in this case data1 There may be spaces between the opening sentinel and the namelist name but nothing else After the namelist name the user is free to set whichever variables within the namelist to whatever values are desired Note that the order in which the variables are set need not be the same as the order in which they are listed in the namelist statement One does not need to set all the variables listed either However any variable set in the data file which is not listed in the corresponding namelist statement in the program will generate an error message and abort execution Variable assignments may appear anywhere between and including columns 3 and 72 Variable assignments are separated by a comma and as many including none blanks as desired Variables are set by typing the variable name followed by an equals sign followed by the desired value in a format consistent with the variable type Legal values which may be assigned to a logical variable are true t false or f where the first two and last two are synonyms Note that the periods must be included Character strings are set by enclosing the desired text inside a pair of single quotes or a pair of double

Download Pdf Manuals

Related Search

Related Contents

Tecumseh AEA2410AXAXC Drawing Data  Fisher-Price Camera Digital Camera User Manual  2 - Christie  Tripp Lite DVI Y Splitter Cable, Digital and VGA Monitors (DVI-I M to DVI-D F and HD15 F) 6-in.      

Copyright © All rights reserved. Failed to retrieve file