Verbs and Built-in Functions › &NDBQUOTE

&NDBQUOTE

Places quotes around data to protect special characters.

&NDBQUOTE data

The &NDBQUOTE built-in function allows an NCL procedure to protect data that contains special characters, that would otherwise cause premature truncation of the value, or syntax errors, when used on an &NDBxxx statement that accepts free-form text.

The rules that &NDBQUOTE uses are as follows:

• If the data contains any special characters, quoting is required.
• If the data commences with either a single (') or double (”) quote, quoting is required.
• If quoting is required, then, if the data contains no double quotes, place a double quote at each end. Otherwise, if the data contains no single quotes, place a single quote at each end. Otherwise, place a single quote at each end, and replace each embedded single quote by two single quotes.

The result of this operation is a single data entity that is preserved when processed by the free-form text parsing logic.

&NDBQUOTE is a built-in function and must be used to the right of an assignment statement.

Operands:

data

The data to be quoted. A null value is acceptable, and is reflected by a null value being returned by &NDBQUOTE.

Example: &NDBQUOTE

This example illustrates the rules &NDBQUOTE uses. The brackets are used to outline the new values.

&D1 = &STR AB C
&D2 = &STR AB & C
&D3 = &STR AB'C
&D4 = &STR A'B”C
&D5 = &STR 'AB C&
DQ1 = &NDBQUOTE &D1   -* &DQ1 = < AB C >
&DQ2 = &NDBQUOTE &D2  -* &DQ2 = < ”AB & C” >
&DQ3 = &NDBQUOTE &D3  -* &DQ3 = < AB'C >
&DQ4 = &NDBQUOTE &D4  -* &DQ4 = < 'A''B”C' >
&DQ5 = &NDBQUOTE &D5  -* &DQ5 = < ”'AB C” >

Notes:

Input data, for example, from a panel, should always be processed by &NDBQUOTE if it can contain special characters.

&NDBQUOTE will always handle the current list of special characters, so the NCL code will not need to be altered if a new release of NDB changes the list of special characters.

Although character format data may be up to 255 characters long, &NDBQUOTE overheads can reduce the effective length, due to the NCL restriction that no word can exceed 256 characters during substitution. For example, a 255 character string containing an ampersand (&) would require quoting, and thus become 257 characters long. This is too long for an NCL variable.

Should the data be too long to quote, the procedure will be terminated with an error message.