A UGAMP GUIDE TO NUPDATE ======================== VERSION 1.0 04.06.93 Lois Steenman-Clark Dept. of Meteorology University of Reading NUPDATE is a Cray utility used by UGAMP to maintain large model and diagnostic codes. NUPDATE is the new version of UPDATE and it is now the only version which can be used under UNICOS 7. There is no manual for NUPDATE and the only documentation currently available is the man page. This contains no information about NUPDATE directives although they are essentially the same as for UPDATE. This guide, therefore, outlines the basic features that are commonly used within UGAMP. 1. Introduction NUPDATE allows you to create a file, the program library, containing blocks of code, where each block is called a deck. Each line of code in a deck is identified with the name of the deck and a sequence number within that deck, so that once a program library has been created each line of code is uniquely identified. Both the UGAMP model and diagnostics codes are kept in such program libraries. NUPDATE then allows you to modify the code, with what is effectively a line editor, so that you may subsequently compile, link and run the modified code without needing to create a new program library. The original source code is not changed. NUPDATE allows you to obtain a listing of the modified program library, again without changing the original source code. NUPDATE is therefore an important source code maintenance utility which enables you to experiment without actually changing the original code. The action of NUPDATE is determined either by directives, which are just commands in an input file, or by arguments to NUPDATE itself, or both. NUPDATE can produce up to four files; a program library (either new or modified), a source code file (to give you a list of the code), a compile file (which can be input to the compiler) and a listing file (which contains messages and requested information). 2. NUPDATE directives A program library is a file containing a number of decks and a directory of those decks. There are two types of decks; regular decks that contain source code, such as subroutines; and common decks, which contain code common to several areas of the program, for example, common blocks, parameter statements and namelists. Both types of deck can contain NUPDATE directives in addition to code. To create a program library from a Fortran program you first need to insert some extra lines in your program which contain the directives to specify the regular and common decks. The first line of a regular deck is the directive *DECK FRED where FRED is the name of the deck which will identify all the lines of that deck. Line 1 of this deck, the directive line itself, will be identified as FRED.1. The first line for a common deck is *COMDECK COMMON1 where COMMON1 perhaps identifies a common block. If this common block occurs several times in the program then each occurrence can be replaced by a call to the common deck using the directive *CALL COMMON1 NUPDATE allows the use of long identifiers, up to 240 characters, for these deck names but the UGAMP standard is 8 characters. The UGAMP naming convention for identifiers is described in the UGAMP standards document. You can modify a program library by adding or removing decks and/or by adding and deleting lines from existing decks. You can apply these modifications to produce a new compile file or a new source file (to obtain a program listing). The compile file has all the common decks expanded but the source file still has the *CALL directives in it. You could also produce a new program library but for the UGCM and diagnostics programs only the coordinators will create new program libraries. The purpose of using NUPDATE in UGAMP is to maintain one central source of code with known line numbers and any modifications will be kept as updates until such time as a new version is considered necessary. Modifications are carried out using directives. Only the most frequently used directives will be described here and their abbreviations are given in brackets. These modifications range from the addition of a new deck using the *DECK directive to changing existing decks and they are usually grouped together in an update file. Comments can be included in this update file but these comments do not get processed by NUPDATE and so they do not appear in the source and compile files. Comment lines must start with */. To identify a particular set of modifications (called a modification set) the following directive should be used as the first line *IDENT SC910718 (*ID SC910718) which means that all the changes that follow, until the next *IDENT directive, will be identified by the name SC910718 and a sequence number. You can insert lines in a deck using either the directive *INSERT PHYS.529 (*I PHYS.529) which means that the lines following this directive and up to the next directive will be inserted after the line 529 in the deck named PHYS, or the directive *BEFORE PHYS.529 (*B PHYS.529) which means that the lines following this directive and up to the next directive will be inserted before line 529 in the deck PHYS. You can delete a line in an existing deck using the directive *DELETE PHYS.529 (*D PHYS.529) and the lines following this directive and up to the next directive will replace that line. You can delete a range of lines using the following directive in its long form *DELETE PHYS.529,PHYS.533 (*D PHYS.529,PHYS.533) or in its shortened form *DELETE PHYS.529,533 (*D PYHS.529,533) Be warned that all lines are deleted between the two lines specified even modifications with different identifiers and sequence numbers. You can also delete a range of lines, for example *DELETE PHYS.529,SC910718.5 (*D PHYS.529,SC910718.5) provided that the delete range does not cross a deck boundary. The program library can be edited using directives to make changes to entire modification sets or decks. These do not change the program library and they are not associated with a modification set, that is, they do not have to have an identifier as do the modification directives described above. To remove previous modification sets the directive *PURGE SC910718 will remove all text added in a modification set and restore all lines deleted by that set. If more than one modification set is specified then the purge starts from the last one listed and works in reverse order. The directive *PURGEDK PHYS will remove the deck PHYS. If a new program library is being created with these directives then the changes are permanent in the new library. To temporarily delete decks, common decks and modification sets, even when creating a new program library, then use the directive *YANK PHYS which will deactivate (temporarily remove) rather than delete the deck PHYS in the new program library and it can be reactivated using the directive *UNYANK PHYS The only difference between the directives *PURGEDK and *YANK is when creating a modified program library using them, the former is a permanent change and the latter is a reversible change. The source and compile files using these directives are identical. When updating a program library using the normal mode to create a compile file it is necessary to specify which decks need compiling (all modified decks will be in the compile file automatically) using the directive *COMPILE PHYS,ALLOCA (*C PHYS,ALLOCA) The decks PHYS and ALLOCA will then be included in the compile file. You could also use the -q option on NUPDATE. If you use the directive *COMPILE PHYS:ALLOCA (*C PHYS:ALLOCA) then all decks between PHYS and ALLOCA will be included in the compile file. If you are using full mode update then you do not need to include any *COMPILE directives. It is convenient to group modification sets or groups of directives into files like the update files in /home/ymp8/kd/ugcm or /home/ymp8/kd/ugcm2. The standard structure for UGAMP update files is described in the UGAMP standards document. NUPDATE is much more exacting about these update files than UPDATE. This means that the update files must have an end of file marker ie a carridge return at the end of the file otherwise the last directive is not interpreted and no warning is given. NUPDATE also cannot process blank lines in an update file. These update files can be read in from any other update file using the directive *READ file_name (*RD file_name) where the file name can be a directory path and file name or just the file name in the current directory. NUPDATE can handle modifications to text added earlier in the same NUPDATE run, but overlapping or conflicting modifications generate caution and note messages. Messages about overlapping modifications are written if the message level is less than the default value. These messages are for information, they indicate that the updates are order dependent. There are a few more directives that may be encountered in UGAMP code but they are not generally used for writing new updates. When new decks are added to a program library they are added to the end of the other decks. Sometimes it is preferable to add new decks to a specified place, for example, to preserve the alphabetic order. The following directive causes NUPDATE to move an entire deck to a point immediately following a specified deck. The sequencing information within the moved deck remains unchanged. The directive is *MOVEDK FRED:FIRST where the deck FRED will now be immediately after the deck FIRST. The deck can be moved to the beginning of the program library using the directive *MOVEDK FRED:. Conditional directives are used for code and directives that are always in the program library but they are not always needed in the compile file. The full details of these directives is beyond tha scope of this guide so only the directives that are found in UGAMP code is described here. By topping and tailing code with the directives *IF DEF,DOC *ENDIF the code in between is only present in the compile file when NUPDATE is invoked with the option -d DOC. Otherwise this code is written to a new program library and the source file but not the compile file. 3. Invoking NUPDATE The full list of options for the NUPDATE command can be found in the man page on the Cray. Only those options which are usually used by UGAMP code and those which are different from UPDATE will be described here. NUPDATE can be used to create a new program library nupdate -n mylib.npl -i infile -f -o nd,um where -n mylib.npl is the name of the new program library (the extension .npl will be used for all UGAMP NUPDATE program libraries) -i infile is the input file name -f here full mode is more efficient when creating new program libraries -o nd uses the single file format rather than the directory format um writes unprocessed modifications to a listing file There are three modes of NUPDATE, full, quick and normal. In full mode all the decks, both regular and common, will be in the compile and source files and in the program library directory. In quick mode only those regular decks which have been specified with the -q option or the *COMPILE directive will be put in the compile and source file. This is a useful option when you need to list or test the compilation of specified decks. In normal mode only those decks specified by the *COMPILE directive, modified decks and decks calling modified common decks will be in the compile and source files. Normal mode is the default mode. Normal mode would be useful if a relocatable binary version of the program already existed as only modified decks would be used, the rest would come from the binary. It is also useful for listing only the modified decks. NUPDATE allows two formats for the program library. The first is a single file and this is the format used for UGAMP program libraries. By ommitting the option nd the program library is a directory where each deck and comdeck is in a separate file. NUPDATE can be called, for example, to create a modified compile file nupdate -p mylib.npl -i model.upd -c compfile -o ed,id -m 2 -f -w 128 or to create a modified source file for a listing nupdate -p mylib.npl -i model.upd -o in,sq -s code.src -f or to list a deck from the program library nupdate -p mylib.npl -q FRED -o sq -s fred.src where -p mylib.npl is the name of the program library -i model.upd is the input update file containing all directives -c compfile is the compile file which will be named compfile.f if the code is Fortran -o are output option arguments ed - line modification summary to standard output (this will now work on the Cray after 4.6.93) id - identifier summary to standard output (warning the output puts one identifier per line and so the listing can be very long) in - lists the input directives sq - includes the sequence numbers on the source and compile files (there are more options to select sequence numbers on either the source or the compile file) -m n is the message level with n=1 comment, n=2 note, n=3 caution, n=4 warning, n=5 error (the default is 3) -f for full mode (normally used in UGAMP jobdecks) -s code.src is the source file name -q FRED for quick mode with a list of decks to be processed by NUPDATE -w 128 the data width (NUPDATE has a default data width, which is the width of a line of code, of 72. Some UGAMP code has lines longer than 72 characters and if -w 128 is not specified when producing the compile file the compiler gives a warning for each one of these lines. The listing from the compiler can in consequence be quite long) 4. NUPDATE features There is no NUPDATE manual which means that much of the information contained in this document has been copied from the old UPDATE manual, which is still valid for most of the syntax for NUPDATE, and gleaned from user experience. The major differences between NUPDATE and UPDATE found so far are listed below - the need to use a comma as a separator for the -o options not a blank - the possibility of having variable data width for the decks and the default being 72 not 80 - the option to have a program library in directory format - the use of long identifiers - the need for an end of file character and no blank lines in update files There are some very useful features for example producing one file for each deck processed for the compile, source or listing files using the NUPDATE options -D, -S and -L respectively. 5. Conclusion There is little documentation for NUPDATE and most of the information given in this document has been gleaned from personal experience. If you find more features or bugs that you think should be included in this document then please contact me. Lois Steenman-Clark telephone: 0734 318326 email : lsc@uk.ac.rl.ib