Mini-Language Reference Manual

1 NCAR Command Language (NCL) Mini-Language Reference Manual NCL Version February 2017 This Manual includes a brief description of the NCL language, file IO, printing, data processing, command line options, and using external codes. Send direct comments about this Manual to keyword courier-bold built-in functions courier-bold blue contributed functions courier-bold green symbols bold plot templates courier-bold green plot resources courier-bold user variables italics WWW links underline Copyright, 2017, National Center for Atmospheric Research, 1850 Table Mesa Drive, Boulder CO 80305. The use of NCL is governed by separate Binary and Source Code License Agreements i Section 1: Introduction.

2 1 Section Setting the user path .. 1 Section Executing NCL .. 1 Section 2: Language .. 2 Section Symbols .. 2 Section Data types .. 3 Section Reserved keywords .. 3 Section Expressions .. 3 Section Variables .. 4 Section Statements .. 4 Section Loops .. 4 Section Blocks and if statements .. 5 Section Dimensions and subscripting .. 6 Section Dimension reduction .. 6 Section Named dimensions .. 7 Section Coordinate variables .. 7 Section Attributes .. 8 Section _Fill Value .. 8 Section Coercion .. 8 Section Variables and metadata .. 9 Section Variable Reassignment .. 10 Section Variable of Type List (Container Variable) .. 11 Section 3: NCL File input/output .. 11 Section Supported formats .. 11 Section Creation of a file Reference .

3 11 Section Reading Variables from Supported File Formats .. 12 Section When to use the $ syntax .. 13 Section Printing the contents of a supported file .. 14 Section Reordering a variable on input .. 14 Section Importing byte or short data with conversion to float .. 14 Section Spanning multiple files .. 14 Section Altering the default behavior of addfile(s) .. 15 Section ncl_filedump .. 15 Section ncl_convert2nc .. 15 Section Binary data files .. 16 Section ASCII .. 17 Section Writing netCDF/HDF .. 18 Section Remote file access: OPeNDAP .. 20 Section 4: Printing .. 21 Section printVarSummary .. 21 Section print .. 21 Section sprintf, sprinti .. 22 Section Pretty Print: write_matrix, print_table .. 22 Section 5: Data analysis and Arrays.

4 23 Section Array ordering and syntax .. 23 Section Array conformance .. 24 Section Array memory allocation .. 24 Section Functions and procedures .. 25 Section Built-in functions and procedures .. 26 Section .. 28 Section User-defined functions and procedures .. 29 Section System interaction .. 31 Section 6: Command line options and assignments .. 32 Section Options altering behavior when NCL is invoked .. 32 Section Specifying variable assignments on command line .. 33 ii Section 7: Using external codes .. 34 Section NCL/Fortran interface .. 34 Section f77 subroutines .. 35 Section f90 subroutines .. 36 Section Accessing the LAPACK library distributed with NCL .. 37 Section Using commercial libraries .. 37 Section What WRAPIT does.

5 38 Section NCL/Fortran array mapping .. 39 Section NCL and Fortran (or C) in Unix shell script .. 39 Section Using NCL as a scripting language .. 40 1 Section 1: Introduction The NCAR Command Language (NCL) is an interpreted programming language, specifically designed for the access, analysis, and visualization of data. NCL has many features common to modern programming languages: variables (numeric and non-numeric types), operators, expressions, conditional statements, loops, and functions and procedures. The most complete and current documentation for NCL is the Reference Manual located at: NCL may already be installed on your local system. If not, NCL binaries and source code are free and are available for the most common Linux/Unix, MacOSX and Cygwin (Windows) operating systems.

6 Click Download at: Section Setting the user path In order to run NCL, you must set your NCARG_ROOT environment variable to the root location of where the NCL software is installed. You also need to make sure that the directory where the NCL executables reside is in your search path. It is best to do this from one of your .* files in your home directory. If you are not sure which shell you are running, you can do an "echo $SHELL". One of the most common errors after NCL installation is that the NCARG_ROOT environment variable has not been set or has been set incorrectly. If NCL resides in (say) /usr/local, the following setting would be appropriate: From C-shell (csh): setenv NCARG_ROOT /usr/local setenv PATH $NCARG_ROOT:${PATH} From bash, ksh: export NCARG_ROOT=/usr/local export PATH=/usr/local/bin:$PATH If an error is encountered, please see the following for more details: #err_msgs_002 Section Executing NCL NCL may be executed interactively.

7 NCL is case sensitive, and all statements require a return to terminate a statement. NCL s interactive environment is not as sophisticated as some other tools but it is adequate for simple tasks. Note that it is possible to save the 2 statements entered using the optional record and stop record statements (Section ). Interactive mode: ncl <return> record "savefile" ; optional (this is not commonly used) statement(s) stop record ; only if record is present quit Batch mode: When a script containing a sequence of prewritten NCL statements is executed it is called batch-mode. Batch-mode scripts often have a .ncl suffix. However, this is a convention only and is not required. The batch-mode script may be invoked at the command line via: ncl ncl >&!

8 [C-Shell; output sent to ] ncl >&! & [C-Shell; run in background] ncl < [acceptable but not often used] NCL allows the user to specify several options on the command line that may alter NCL s behavior. Using ncl h will display currently supported options. See Section 6. External NCL functions/procedures (Section 5) and shared objects (Section 7) can be accessed in interactive or batch mode via: load " " load "$HOME/ " external DEMO "/tmp/ " Section 2: Language Section Symbols NCL has a suite of syntax symbols that facilitate assorted tasks. Commonly used syntax symbols include: ; begins a comment. Text to the right of ; is ignored. /; .. ;/ Block comment; all text/lines bracketed are ignored (available in ) = assignment := reassignment (available in ) @ create or Reference attributes !

9 Create or Reference named dimensions & create or Reference a coordinate variable {..} used for coordinate subscripting $ enclose strings when importing/exporting variables via addfile [..] subscript variables of type list 3 (/../) construct an array : used in array syntax | used as a separator for named dimensions \ continue statement for spanning multiple lines :: used as separator when calling external codes -> used for variable input/output with supported data formats => used to access netCDF-4/HDF5 groups Section Data types Numeric: double (64 bit), float (32 bit), long (32 or 64 bit), integer (32 bit), short (16 bit), byte (8 bits), complex is not supported. NCL was expanded to include many additional numeric types.

10 This was done to be consistent with the numeric types supported by netCDF4 and HDF5. Non-numeric: string, character, graphic, file, logical, list. Please see a complete description of NCL s data types at Section Reserved keywords begin, break, byte, character, continue, create, defaultapp, do, double, else, end, enumeric, external, False, file, float, function, getvalues, graphic, if, integer, int64, list, load, local, logical, long, _Missing, Missing, new, noparent, numeric, procedure, quit, Quit, QUIT, record, return, setvalues, short, string, then, True, undef, while and all built-in function and procedure names. A current list of all NCL keywords is at: Section Expressions Precedence rules can be circumvented by use of parentheses "(.)