NCL statements

Statements are the fundamental element of NCL. Everything NCL does happens only after a statement is entered. Statements are not restricted to being a single line of source, and statements can be nested within statements. There are 17 different kinds of statements: assignment, procedure call, function definition, procedure definition, block, do, if-then, if-then-else, break, continue, setvalues, getvalues, return, record, new, stop, and quit.

There are two very important things to understand about statements. First, each statement only executes after it has been parsed and is found to be free of syntax errors. Second, if a runtime error occurs while executing a statement, execution of the statement and any statements in which the erroneous statement is nested is immediately terminated.

Blocks

begin


statement list

end

if statements

The are two kinds of if statements: the if-then statement and the if-then-else statement. These function like if statements in other popular programming languages. The following is the syntax for the NCL if statements:

if(scalar_logical_expression) then


statement list

end if
if( scalar_logical_expression) then

statement list

else

statement list

end if

The scalar_logical_expression is an expression made of relational operators. For if statements, the result of the logical expression within the parentheses must result in a single scalar value and must not be a missing value.

Important note: never search for a missing value using a logical expression. For example if statements of the following form should not be used:

	if( a(i) .eq. a@_FillValue) then
		. . .

The above statement will return a missing value when a is equal to the attribute "_FillValue". This will in turn cause an error message and premature termination of the script. In NCL when expressions, even logical expressions, contain a missing value the missing value is propagated to the result. See the discussion on Expressions and missing values.

Logical operators operate on entire arrays of values, when this is the case they produce array results, and each element in the array result could be True, False, or a missing value. Since if statements require the results of the logical expression to be a single scalar logical value a FATAL error message is generated and execution is terminated if the conditional part of the if statement is not scalar. Therefore there are three functions that help with the above problems. The functions any and all return a single True scalar value if any element in a logical array is True, or if all elements in a logical array are True, respectively. The function ismissing returns an array of True or False values at locations where the input is either a missing value or a normal value Combined with lazy conditional expression evaluation, the ismissing function can filter possible error conditions before they occur.

Lazy expression evaluation means that if the first term of an .AND. expression is False, or the first term of an .OR. expression is True, the entire expression--regardless of the result of the remaining terms--is False and True respectively. When this is the case, NCL does not evaluate the remaining terms. This is a very useful tool for avoiding error conditions. For example, consider the integer i and the array a. Lazy evaluation can avoid indexing the array a with i when i is out-of-range. The following example demonstrate this:

	if((i .lt. dimsizes(a)) .and. (a(i) .gt. 10 )) then 
	. . . 
	end if

	if(.not.ismissing(a(i)) .and. (a(i) .gt. 10)) then
	. . .
	end if

Loops

do

For the do loop, an identifier, a scalar integer start expression, a scalar integer end expression, and an optional positive scalar integer stride expression are required. The identifier can be either a) a defined variable or variable subsection or b) an undefined name. Before the loop starts, the start_expr value is assigned to the identifier. Then after each iteration of the loop, either the identifier is incremented or the identifier is assigned its next value based on the stride specified and the direction. The following is an example of a loop without specification of the stride. In this kind of loop, the identifier is incremented by one after each iteration. If the start expression is greater than the end expression, no iterations of the loop occur. If the start expression is equal to the end, then one iteration occurs. To loop backward, see the next example.

do identifier = scalar_start_expr , end_expr


statement list

end do

The following shows how to specify a stridden loop. The following form is also necessary to loop backwards. With this form, if start is greater than end, then the identifier is decremented by the stride value, which must always be positive. If the start is less than the end, then the identifier is incremented by the stride value.

do identifier = scalar_start_expr , scalar_end_expr , scalar_stride_expr

statement list

end do

while

This example shows the while loop syntax. The scalar_logical_expression adheres to the same restrictions placed on the conditional expression of the if statement. Specifically, it must be a scalar logical value and not be a missing value. Also lazy evaluation of .AND. and .OR. statements occurs.

do while (scalar_logical_expression)

statement list

end do

Assignment

The assignment statement can be used to assign values of any type to variables, subsections of variables, coordinate variables, and attributes. In addition, the assignment statement is used to assign string values to dimension names. Several NCL language constructs are used to identify what type of assignment is to take place. The constructs '->', '!', '&', and '@' are used to specify file variable assignment, dimension name assignment, coordinate variable assignment, and attribute assignment, respectively. Without these constructs, normal-value-to-variable assignment occurs.

The following passages cover the syntax of the various assignment statements. The section on variable assignment covers the semantics of variable-to-variable assignment. Variable-to-variable assignment copies not only a variable's value but all attributes, dimensions, and coordinate variables associated with that variable. The variable assignment section as well as the properties of variables are a very important sections to read and understand.

Dimension name assignment

		a!0 = "Dimension1"
		thefile->a!0 = "Dimension1"

Coordinate variable assignment

		a&Dimension1 = (/.1,.2,.3,.4,.5,.../)
		thefile->a&Dimension1 = (/.1,.2,.3,.4,.5,.../)

		dimname = "Dimension1"
		a&$dimname$ = (/.1,.2,.3,.4,.5,.../)

		dimname = "Dimension1"
		varname = "a"
		thefile->$varname$&$dimname$ = (/.1,.2,.3,.4,.5,.../)

Attribute assignment

		a@units = "Degrees C"
		a@_FillValue = -9999.0
		thefile->a@units = "Degrees C"

		attnames = (/"units","_FillValue"/)
		a@$attnames(0)$ = "Degrees C"
		a@$attnames(1)$ = -9999.0

		attnames = (/"units","_FillValue"/)
		varname = "a"
		thefile->$varname$&$attnames(0)$ = "Degrees C"
		thefile->$varname$&$attnames(1)$ =  -9999.0

Procedures

NCL procedures, in many ways, are the same as in most programming languages, but NCL procedures also have some distinct differences. The key differences are in how the types and dimension sizes for parameters are specified and handled by NCL. In NCL, parameters can be specified to be very constrained and require a specific type, number of dimensions, and a dimension size for each dimension, or parameters can have no type or dimension constraints. Parameters in NCL are always passed by reference, meaning changes to their values, attributes, dimension names, and coordinate variables within functions change their values outside of the functions. There is one very important exception that does generate a WARNING message: when an input parameter must be coerced to the correct type for the procedure, NCL is not able to coerce data in the reverse direction so the parameter is not affected by changes made to it within the procedure. See the discussion on coercion.

Parameters that are subsections of variables (i.e. subscripted elements) are passed by reference. Which means when the procedure finishes, the values of the subsection are mapped back into their original locations in the referenced variable.

External Procedures

External procedures are procedures that exist in external shared libraries. These procedures are loaded during execution of the external statement. To call one of these procedures or functions, you preceded the procedure name and argument list with the name provided to the external statement followed by two colons. For example:

	external elib "./elib.so"

	. . .

	elib::eproc(param0,param1)

Function and procedure definitions

Functions and procedures are defined using a similar syntax; the only difference is that the keyword procedure is used instead of the keyword function. To define a new function, the proper keyword is entered, followed by the symbol name of the function, followed by a list of declarations that can optionally be followed by a list of local variable names. Finally, a block of statements enclosed in begin and end follows.

function function_name ( declaration_list )
local local_identifier_list
begin

statement list
return(return_value)
end

The local statement and function and procedure scope

It is very important to note that if a variable intended to be local to the function or procedure does not occur in the local list, then the function may find that variable name outside of the scope of the function or procedure.

It is also important to note the consequences of not putting a local variable into the local list. There are two possibilities. First, if the variable is defined at the time of function definition and is in the function's scope, the variable will be referenced. If the variable is not defined at the time of definition, it will be an undefined variable local to the function.

Placing the local variable's name in the local list assures that the variable truly is local only to the current function. The scope rules for NCL are identical to Pascal. The main NCL prompt is the bottom level of NCL's scope. Function and procedure blocks are the next level. When a variable is referenced in a function, NCL first looks within the scope of the function for that variable. If it doesn't exist, NCL looks in the scope containing the function and continues to search outward until either the bottom level is reached or a variable of the correct name is found. If it is not found, then an undefined variable reference error message is generated.

Constraining the type and dimensionality of input parameters

As noted previously, parameters can be constrained or unconstrained. The following shows the syntax of the variable declaration. The square brackets ( '[' and ']' ) are used to denote optional parts of the declaration syntax and are not part of the structure of the declaration list. Each declaration in the declaration list is separated by a comma.

Declaration list element syntax:

variable_name [ dimension_size_list ] [ : data_type ]

Unlike the preceding example syntax, the characters '[' and ']' are part of the syntax for the dimension size list. They are used to separate dimension sizes. Each pair of brackets can contain an integer representing the size of the dimension or a star to indicate that the dimension may be any size. The number of pairs of brackets is the number of dimensions the parameter will be constrained to.

Dimension size list syntax:

[ dimension_size ]
or
[ * ]

Local variable list syntax:

identifier_name , identifier_name , . . .

The local variable list is very important. If a local variable name is not in the local list and the same identifier is defined in a lower scope level, then the variable reference in the function or procedure will refer to that variable. Sometimes this may be the desired effect. However, if the variable is to be local, it should be referenced in the local list.

Visualization blocks

• HLU user guide
• HLU reference guide
• Pick a utility page
• NCL scientific tutorial

create

The create visualization block is actually an expression; it is described here for consistency. The create block returns an id to a newly created HLU object. HLU resources are assigned using the syntax for the NCL resource list. In NCL resource lists, resource names are entered by their string representation followed by a colon (':') and an NCL expression. The create block requires a string name for the HLU object, which can be different than the name of the variable it is being assigned to. Create also requires a HLU object class identifier that tells NCL what type of HLU object to create. Finally create either needs a reference to the object's parent, usually a workstation, or the keyword "defaultapp" to signify that the object's parent is the default application class. Refer to the HLU user guide and reference guide for a discussion of HLU objects and application classes.

obj = create obj_name obj_class parent

resource_string : value_expression

end create

The following is a list of all the HLU class identifiers recognized by NCL:

• annoManagerClass
• appClass
• contourPlotClass
• coordArraysClass
• irregularPlotClass
• graphicStyleClass
• labelBarClass
• legendClass
• logLinPlotClass
• mapPlotClass
• psWorkstationClass
• scalarFieldClass
• streamlinePlotClass
• textItemClass
• tickMarkClass
• titleClass
• ncgmWorkstationClass
• vectorFieldClass
• vectorPlotClass
• xWorkstationClass
• xyPlotClass

setvalues

Use setvalues to modify resources in an HLU object after it has been created. setvalues takes an NCL resource list in the same fashion that create does. It then sets each resource to its corresponding value. Note: obj_reference can be one or more HLU objects. If more than one the resources are repeatedly applied to each HLU object.

setvalues obj_reference

resource_string : value_expression

end setvalues

getvalues

Use getvalues to retrieve resource values from HLU objects. It is different than the setvalues and create NCL resource list because it requires an identifier rather than an expression after the colon. getvalues functions identically to the assignment with respect to how it assigns values to the identifier.
getvalues obj_reference

resource_string : identifier

end getvalues

load a shared library

external string_name path_name

load script from a file

load "file_path"

record commands

The record command will cause all syntactically correct commands entered at the command line to be saved in the file pointed to by the file_path constant string value. The "stop record" command terminates this process.

record "file_path"
...
statements
...
stop record

Reference Manual Control Panel

NG4.1 Home, Index, Examples, Glossary, Feedback, Ref Contents, Ref WhereAmI?