Verbs and Built-in Functions › &NBLSTR › Free-form Syntax

Free-form Syntax

Several of the NDB verbs, which are described on the following pages, use a special syntax, which is different from normal NCL syntax, to allow easy coding of data definitions and scan requests. The relevant verb descriptions indicate the part that uses this free-form syntax. The free-form part must always be coded after any fixed-form, standard NCL-syntax operands on the same statement.

The rules for free-form syntax are as follows:

• Blanks are only required to delimit adjacent words, except inside data values. Blanks are not required, but is specified, around or next to special characters (listed below) that act as delimiters.

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

  Notes: 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

  p

  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, and greater than or equal respectively.

• Values is enclosed in quoted strings whenever the value might contain a special character, or a real blank.

  The quotes may 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, 'This''s a quoted value' will be regarded as the value This'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 is used instead of special characters, to aid clarity. If surrounded by other words, ensure at least one blank separates them.

  EQ (=)

  NE (p=)

  LT (<)

  GT (>)

  LE (< or =)

  GE (> or =)

  AND (&)

  OR (|)

  TO (:)

  NOT (p)

• Several statements support a START/DATA/END construct, that allows free-form expressions to be constructed that are longer than a single NCL statement is allowed to be. These statements is coded in the following way if the free-form text will fit on one statement (with possible continuations):

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

  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 [ operands ] START
  

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

  &NDBxxxx dbname END
  

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

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

  Note: The statements can 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 is 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,

  &NDBxxx dbname CANCEL
  

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