&NDB Verbs, Built-in Functions, and System Variables › Free-form Syntax

Free-form Syntax

Several NCL statements use a special syntax, different from normal NCL syntax, to allow easy coding of data definitions and scan requests. The relevant statement descriptions indicate the part of the statement that uses the free-form syntax. The free-form part must always be coded after any fixed-form, standard NCL-syntax parameters on the same statement. The rules for this free-form syntax are:

• Blanks are only required to delimit adjacent words, except inside data values. Blanks are not required, but may be specified, around or next to special characters that act as delimiters.

  Blanks inside data values are significant, except that trailing blanks are never stored in character-format data.

  NCL variables with blanks in the value are regarded as a special case, and the blank is regarded as part of the data value. This is because blanks inside NCL variables are represented internally in a special way.

• The following special characters act as delimiters, unless enclosed in a quoted string. They have special meaning to the syntax:

  ( Left bracket

  ) Right bracket

  : Colon (meaning: range)

  = Equal sign

  ¬ Not sign

  < Less than sign

  > Greater than sign

  & Ampersand (meaning: AND)

  | Bar (meaning: OR)

  , Comma

  Real blank (not embedded in an NCL variable)

  Certain combinations of these characters are treated as a single token for parsing. These combinations are p =, < =, >=, and =<, =>, meaning not equal, less than or equal, greater than or equal, less than or equal, and greater than or equal, respectively.

• Values may be enclosed in quoted strings whenever the value contains a special character, or a real blank.

  The quotes can be single (') or double(”). If the data value being quoted contains a single or double quote, you can quote the data with the other quote, or double up each occurrence of the quote character.

  For example, 'It”s a quoted value' will be regarded as the value It's a quoted value.

  The &NDBQUOTE built-in function provides an easy way to automatically quote data when necessary.

  A data value can always be quoted, even date, hexadecimal, or numeric values. Quoting also prevents any possibility of the value being regarded as a keyword.

• The following words can be used instead of special characters, as an aid to clarity. If surrounded by other words, ensure at least one blank separates them.
  • EQ can be used to replace =
  • NE can be used to replace ¬=
  • LT can be used to replace<
  • GT can be used to replace >
  • LE can be used to replace=<
  • GE can be used to replace=>
  • AND can be used to replace&
  • OR can be used to replace |
  • TO can be used to replace :
  • NOT can be used to replace ¬
• Several statements support a START/DATA/END construct to allow free-form expressions to be constructed that are longer than a single NCL statement is allowed to be. These statements can be coded as:

  &NDBxxxx  dbname [ parameters ] [ DATA ] free-form text
  

  if the free-form text can fit on one statement (with possible continuations).

  To overcome NCL statement length limitations, and also to allow the free-form text to be built piece-meal (for example, by indirect variable reference), the statements can also be coded as:

  &NDBxxxx dbname [ parameters ] START
  &NDBxxxx dbname [ DATA ]  part-of-free-form-text
  &NDBxxxx dbname END
  

  The free-form text can be broken anywhere a blank is valid. Any number of intermediate statements can be used to build the complete free-form text. The database is not called until the END statement is encountered.

  Any other parameters must be coded on the &NDBxxx START statement.

  Note: The statements may be interspersed with other NCL statements, including statements referencing other or even the same database, and even statements building free-form text for the same database, as long as they are different statements. That is, you can be concurrently building a multi-statement add and update for the same database, but not two different adds for the same database.

  To cancel a partially built statement, use:

  &NDBxxx dbname CANCEL
  

  This statement is valid even if no current START/END set is being built; thus it can be used in general error routines.