A UGAMP GUIDE TO NUPDATE

version 1.1

Lois Steenman-Clark, CGAM, Department of Meteorology, University of Reading

NUPDATE is a Cray utility, now in the public domaine, used by UGAMP and the UK Met. Office (UKMO) to maintain large model and diagnostic codes. The only documentation currently available is the man page. This contains no information about NUPDATE directives so this guide 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 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 and UKMO standard is 8 characters.

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 the purpose of using NUPDATE in UGAMP and UKMO 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 also called a modification set (modset). Comments can be included in this modset 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 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.

Modsets, 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)
A default option is used in the UKMO Unified Model code which is maintained using Cray NUPDATE. This option -o dc, requires that each modset needs to include a *DECLARE statement for the DECK being modified, otherwise NUPDATE fails.

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 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.