2 Fundamentals of the PL/SQL Language

Reserved Words

Some identifiers, called reserved words, have a special syntactic meaning to PL/SQL. For example, the words BEGIN and END are reserved. Often, reserved words are written in upper case for readability.

Trying to redefine a reserved word causes a compilation error. Instead, you can embed reserved words as part of a longer identifier. For example:

DECLARE
-- end BOOLEAN; the use of "end" is not allowed; causes compilation error
   end_of_game BOOLEAN;  -- allowed

In addition to reserved words, there are keywords that have special meaning in PL/SQL. PL/SQL keywords can be used for identifiers, but this is not recommended. For a list of PL/SQL reserved words and keywords, see Table D-1, "PL/SQL Reserved Words" and Table D-2, "PL/SQL Keywords".

Predefined Identifiers

Identifiers globally declared in package STANDARD, such as the exception INVALID_NUMBER, can be redeclared. However, redeclaring predefined identifiers is error prone because your local declaration overrides the global declaration.

Quoted Identifiers

For flexibility, PL/SQL lets you enclose identifiers within double quotes. Quoted identifiers are seldom needed, but occasionally they can be useful. They can contain any sequence of printable characters including spaces but excluding double quotes. Thus, the following identifiers are valid:

The maximum size of a quoted identifier is 30 characters not counting the double quotes. Though allowed, using PL/SQL reserved words as quoted identifiers is a poor programming practice.

Numeric Literals

Two kinds of numeric literals can be used in arithmetic expressions: integers and reals. An integer literal is an optionally signed whole number without a decimal point. Some examples follow:

030 6 -14 0 +32767

A real literal is an optionally signed whole or fractional number with a decimal point. Several examples follow:

6.6667 0.0 -12.0 3.14159 +8300.00 .5 25.

PL/SQL considers numbers such as 12.0 and 25. to be reals even though they have integral values.

A numeric literal value that is composed only of digits and falls in the range -2147483648 to 2147483647 has a PLS_INTEGER datatype; otherwise this literal has the NUMBER datatype. You can add the f of d suffix to a literal value that is composed only of digits to specify the BINARY_FLOAT or BINARY_TABLE respectively. For the properties of the datatypes, see "PL/SQL Number Types".

Numeric literals cannot contain dollar signs or commas, but can be written using scientific notation. Simply suffix the number with an E (or e) followed by an optionally signed integer. A few examples follow:

2E5 1.0E-7 3.14159e0 -1E38 -9.5e-3

E stands for times ten to the power of. As the next example shows, the number after E is the power of ten by which the number before E is multiplied (the double asterisk (**) is the exponentiation operator):

5E3 = 5 * 10**3 = 5 * 1000 = 5000

The number after E also corresponds to the number of places the decimal point shifts. In the last example, the implicit decimal point shifted three places to the right. In this example, it shifts three places to the left:

5E-3 = 5 * 10**-3 = 5 * 0.001 = 0.005

The absolute value of a NUMBER literal can be in the range 1.0E-130 up to (but not including) 1.0E126. The literal can also be 0. See Example 2-1. For information on results outside the valid range, see "NUMBER Datatype".

DECLARE
  n NUMBER; -- declare n of NUMBER datatype
BEGIN
  n :=  -9.999999E-130;  -- valid
  n := 9.999E125; -- valid
--  n := 10.0E125; -- invalid, "numeric overflow or underflow"
END;
/

Real literals can also use the trailing letters f and d to specify the types BINARY_FLOAT and BINARY_DOUBLE, as shown in Example 2-2.

DECLARE
   x BINARY_FLOAT := sqrt(2.0f); -- single-precision floating-point number
   y BINARY_DOUBLE := sqrt(2.0d); -- double-precision floating-point number
BEGIN
   NULL;
END;
/

Character Literals

A character literal is an individual character enclosed by single quotes (apostrophes). Character literals include all the printable characters in the PL/SQL character set: letters, numerals, spaces, and special symbols. Some examples follow:

'Z' '%' '7' ' ' 'z' '('

PL/SQL is case sensitive within character literals. For example, PL/SQL considers the literals 'Z' and 'z' to be different. Also, the character literals '0'..'9' are not equivalent to integer literals but can be used in arithmetic expressions because they are implicitly convertible to integers.

String Literals

A character value can be represented by an identifier or explicitly written as a string literal, which is a sequence of zero or more characters enclosed by single quotes. All string literals except the null string ('') have datatype CHAR.

The following are examples of string literals:

PL/SQL is case sensitive within string literals. For example, PL/SQL considers the following literals to be different:

To represent an apostrophe within a string, you can write two single quotes, which is not the same as writing a double quote:

Doubling the quotation marks within a complicated literal, particularly one that represents a SQL statement, can be tricky. You can also use the following notation to define your own delimiter characters for the literal. You choose a character that is not present in the string, and then do not need to escape other single quotation marks inside the literal:

You can use delimiters [, {, <, and (, pair them with ], }, >, and ), pass a string literal representing a SQL statement to a subprogram, without doubling the quotation marks around 'INVALID' as follows:

For NCHAR and NVARCHAR2 literals, use the prefix nq instead of q:

For more information about the NCHAR datatype and unicode strings, see Oracle Database Globalization Support Guide.

BOOLEAN Literals

BOOLEAN literals are the predefined values TRUE, FALSE, and NULL. NULL stands for a missing, unknown, or inapplicable value. Remember, BOOLEAN literals are values, not strings. For example, TRUE is no less a value than the number 25.

Datetime Literals

Datetime literals have various formats depending on the datatype. For example:

DECLARE
   d1 DATE := DATE '1998-12-25';
   t1 TIMESTAMP := TIMESTAMP '1997-10-22 13:01:01';
   t2 TIMESTAMP WITH TIME ZONE := TIMESTAMP '1997-01-31 09:26:56.66 +02:00';
-- Three years and two months
-- For greater precision, we would use the day-to-second interval
   i1 INTERVAL YEAR TO MONTH := INTERVAL '3-2' YEAR TO MONTH;
-- Five days, four hours, three minutes, two and 1/100 seconds
   i2 INTERVAL DAY TO SECOND := INTERVAL '5 04:03:02.01' DAY TO SECOND;

You can also specify whether a given interval value is YEAR TO MONTH or DAY TO SECOND. For example, current_timestamp - current_timestamp produces a value of type INTERVAL DAY TO SECOND by default. You can specify the type of the interval using the formats:

• (interval_expression) DAY TO SECOND

• (interval_expression) YEAR TO MONTH

For details on the syntax for the date and time types, see the Oracle Database SQL Reference. For examples of performing date and time arithmetic, see Oracle Database Application Developer's Guide - Fundamentals.

Single-Line Comments

Single-line comments begin with a double hyphen (--) anywhere on a line and extend to the end of the line. A few examples follow:

DECLARE
   howmany    NUMBER;
   num_tables NUMBER;
BEGIN
-- begin processing
   SELECT COUNT(*) INTO howmany FROM USER_OBJECTS
      WHERE OBJECT_TYPE = 'TABLE'; -- Check number of tables
   num_tables := howmany;          -- Compute some other value
END;
/

Notice that comments can appear within a statement at the end of a line.

While testing or debugging a program, you might want to disable a line of code. The following example shows how you can disable a line by making it a comment:

-- DELETE FROM employees WHERE comm_pct IS NULL;

Multi-line Comments

Multi-line comments begin with a slash-asterisk (/*), end with an asterisk-slash (*/), and can span multiple lines, as shown in Example 2-5. You can use multi-line comment delimiters to comment-out whole sections of code.

DECLARE
   some_condition BOOLEAN;
   pi NUMBER := 3.1415926; 
   radius NUMBER := 15; 
   area NUMBER;
BEGIN
  /* Perform some simple tests and assignments */
  IF 2 + 2 = 4 THEN
    some_condition := TRUE; /* We expect this THEN to always be performed */
  END IF;
  /* The following line computes the area of a circle using pi, which is the
     ratio between the circumference and diameter. After the area is computed,
     the result is displayed. */
  area := pi * radius**2;
  DBMS_OUTPUT.PUT_LINE('The area is: ' || TO_CHAR(area));
END;
/

Restrictions on Comments

You cannot nest comments. You cannot use single-line comments in a PL/SQL block that will be processed by an Oracle Precompiler program because end-of-line characters are ignored. As a result, single-line comments extend to the end of the block, not just to the end of a line. In this case, use the /* */ notation instead.

Aggregate Assignment

Although a %ROWTYPE declaration cannot include an initialization clause, there are ways to assign values to all fields in a record at once. You can assign one record to another if their declarations refer to the same table or cursor. Example 2-10 shows record assignments that are allowed.

DECLARE
   dept_rec1 departments%ROWTYPE;
   dept_rec2 departments%ROWTYPE;
   CURSOR c1 IS SELECT department_id, location_id FROM departments;
   dept_rec3 c1%ROWTYPE;
BEGIN
   dept_rec1 := dept_rec2;  -- allowed
-- dept_rec2 refers to a table, dept_rec3 refers to a cursor
-- dept_rec2 := dept_rec3;  -- not allowed
END;
/

You can assign a list of column values to a record by using the SELECT or FETCH statement, as the following example shows. The column names must appear in the order in which they were defined by the CREATE TABLE or CREATE VIEW statement.

DECLARE
   dept_rec departments%ROWTYPE;
BEGIN
   SELECT * INTO dept_rec FROM departments
      WHERE department_id = 30 and ROWNUM < 2;
END;
/

However, there is no constructor for a record type, so you cannot assign a list of column values to a record by using an assignment statement.

Using Aliases

Select-list items fetched from a cursor associated with %ROWTYPE must have simple names or, if they are expressions, must have aliases. Example 2-11 uses an alias called complete_name to represent the concatenation of two columns:

BEGIN
-- We assign an alias (complete_name) to the expression value, because
-- it has no column name.
   FOR item IN
   (  SELECT first_name || ' ' || last_name complete_name
      FROM employees WHERE ROWNUM < 11  )
   LOOP
-- Now we can refer to the field in the record using this alias.
     DBMS_OUTPUT.PUT_LINE('Employee name: ' || item.complete_name);
   END LOOP;
END;
/

Order of Evaluation

When you do not use parentheses to specify the order of evaluation, operator precedence determines the order. Compare the following expressions:

NOT (valid AND done)  |  NOT valid AND done

If the BOOLEAN variables valid and done have the value FALSE, the first expression yields TRUE. However, the second expression yields FALSE because NOT has a higher precedence than AND. Therefore, the second expression is equivalent to:

(NOT valid) AND done

In the following example, notice that when valid has the value FALSE, the whole expression yields FALSE regardless of the value of done:

valid AND done

Likewise, in the next example, when valid has the value TRUE, the whole expression yields TRUE regardless of the value of done:

valid OR done

Short-Circuit Evaluation

When evaluating a logical expression, PL/SQL uses short-circuit evaluation. That is, PL/SQL stops evaluating the expression as soon as the result can be determined. This lets you write expressions that might otherwise cause an error. Consider the OR expression in Example 2-23.

DECLARE
   on_hand  INTEGER := 0;
   on_order INTEGER := 100;
BEGIN
-- Does not cause divide-by-zero error; evaluation stops after first expression
   IF (on_hand = 0) OR ((on_order / on_hand) < 5) THEN
      DBMS_OUTPUT.PUT_LINE('On hand quantity is zero.');
   END IF;
END;
/

When the value of on_hand is zero, the left operand yields TRUE, so PL/SQL does not evaluate the right operand. If PL/SQL evaluated both operands before applying the OR operator, the right operand would cause a division by zero error.

Short-circuit evaluation applies to IF statements, CASE statements, and CASE expressions in PL/SQL.

Comparison Operators

Comparison operators compare one expression to another. The result is always true, false, or null. Typically, you use comparison operators in conditional control statements and in the WHERE clause of SQL data manipulation statements. Example 2-24 provides some examples of comparisons for different types.

DECLARE
   PROCEDURE assert(assertion VARCHAR2, truth BOOLEAN)
   IS
   BEGIN
      IF truth IS NULL THEN
         DBMS_OUTPUT.PUT_LINE('Assertion ' || assertion || ' is unknown (NULL)');
      ELSIF truth = TRUE THEN
         DBMS_OUTPUT.PUT_LINE('Assertion ' || assertion || ' is TRUE');
      ELSE
         DBMS_OUTPUT.PUT_LINE('Assertion ' || assertion || ' is FALSE');
      END IF;
   END;
BEGIN
   assert('2 + 2 = 4', 2 + 2 = 4);
   assert('10 > 1', 10 > 1);
   assert('10 <= 1', 10 <= 1);
   assert('5 BETWEEN 1 AND 10', 5 BETWEEN 1 AND 10);
   assert('NULL != 0', NULL != 0);
   assert('3 IN (1,3,5)', 3 IN (1,3,5));
   assert('''A'' < ''Z''', 'A' < 'Z');
   assert('''baseball'' LIKE ''%all%''', 'baseball' LIKE '%all%');
   assert('''suit'' || ''case'' = ''suitcase''', 'suit' || 'case' = 'suitcase');
END;
/

Relational Operators

The following table lists the relational operators with their meanings.

IS NULL Operator

The IS NULL operator returns the BOOLEAN value TRUE if its operand is null or FALSE if it is not null. Comparisons involving nulls always yield NULL. Test whether a value is null as follows:

IF variable IS NULL THEN ...

LIKE Operator

You use the LIKE operator to compare a character, string, or CLOB value to a pattern. Case is significant. LIKE returns the BOOLEAN value TRUE if the patterns match or FALSE if they do not match.

The patterns matched by LIKE can include two special-purpose characters called wildcards. An underscore (_) matches exactly one character; a percent sign (%) matches zero or more characters. For example, if the value of last_name is 'JOHNSON', the following expression is true:

last_name LIKE 'J%S_N'

To search for the percent sign and underscore characters, you define an escape character and put that character before the percent sign or underscore. The following example uses the backslash as the escape character, so that the percent sign in the string does not act as a wildcard:

IF sale_sign LIKE '50\% off!' ESCAPE '\' THEN...

BETWEEN Operator

The BETWEEN operator tests whether a value lies in a specified range. It means "greater than or equal to low value and less than or equal to high value." For example, the following expression is false:

45 BETWEEN 38 AND 44

IN Operator

The IN operator tests set membership. It means "equal to any member of." The set can contain nulls, but they are ignored. For example, the following expression tests whether a value is part of a set of values:

letter IN ('a','b','c')

Be careful when inverting this condition. Expressions of the form:

value NOT IN set

yield FALSE if the set contains a null.

Concatenation Operator

Double vertical bars (||) serve as the concatenation operator, which appends one string (CHAR, VARCHAR2, CLOB, or the equivalent Unicode-enabled type) to another. For example, the expression

'suit' || 'case'

returns the following value:

'suitcase'

If both operands have datatype CHAR, the concatenation operator returns a CHAR value. If either operand is a CLOB value, the operator returns a temporary CLOB. Otherwise, it returns a VARCHAR2 value.

BOOLEAN Arithmetic Expressions

You can use the relational operators to compare numbers for equality or inequality. Comparisons are quantitative; that is, one number is greater than another if it represents a larger quantity. For example, given the assignments

the following expression is true:

number1 > number2

BOOLEAN Character Expressions

You can compare character values for equality or inequality. By default, comparisons are based on the binary values of each byte in the string. For example, given the assignments

the following expression is true:

string1 > string2

By setting the initialization parameter NLS_COMP=ANSI, you can make comparisons use the collating sequence identified by the NLS_SORT initialization parameter. A collating sequence is an internal ordering of the character set in which a range of numeric codes represents the individual characters. One character value is greater than another if its internal numeric value is larger. Each language might have different rules about where such characters occur in the collating sequence. For example, an accented letter might be sorted differently depending on the database character set, even though the binary value is the same in each case.

Depending on the value of the NLS_SORT parameter, you can perform comparisons that are case-insensitive and even accent-insensitive. A case-insensitive comparison still returns true if the letters of the operands are different in terms of uppercase and lowercase. An accent-insensitive comparison is case-insensitive, and also returns true if the operands differ in accents or punctuation characters. For example, the character values 'True' and 'TRUE' are considered identical by a case-insensitive comparison; the character values 'Cooperate', 'Co-Operate', and 'coöperate' are all considered the same. To make comparisons case-insensitive, add _CI to the end of your usual value for the NLS_SORT parameter. To make comparisons accent-insensitive, add _AI to the end of the NLS_SORT value.

There are semantic differences between the CHAR and VARCHAR2 base types that come into play when you compare character values. For more information, see "Differences between the CHAR and VARCHAR2 Datatypes".

Many types can be converted to character types. For example, you can compare, assign, and do other character operations using CLOB variables. For details on the possible conversions, see "PL/SQL Character and String Types".

BOOLEAN Date Expressions

You can also compare dates. Comparisons are chronological; that is, one date is greater than another if it is more recent. For example, given the assignments

the following expression is true:

date1 > date2

Guidelines for PL/SQL BOOLEAN Expressions

In general, do not compare real numbers for exact equality or inequality. Real numbers are stored as approximate values. For example, the following IF condition might not yield TRUE:

DECLARE
   fraction BINARY_FLOAT := 1/3;
BEGIN
   IF fraction = 11/33 THEN
      DBMS_OUTPUT.PUT_LINE('Fractions are equal (luckily!)');
   END IF;
END;
/

It is a good idea to use parentheses when doing comparisons. For example, the following expression is not allowed because 100 < tax yields a BOOLEAN value, which cannot be compared with the number 500:

100 < tax < 500 -- not allowed

The debugged version follows:

(100 < tax) AND (tax < 500)

A BOOLEAN variable is itself either true or false. You can just use the variable in a conditional test, rather than comparing it to the literal values TRUE and FALSE. In Example 2-25 the loops are all equivalent.

DECLARE
   done BOOLEAN ;
BEGIN
-- Each WHILE loop is equivalent
   done := FALSE;
   WHILE done = FALSE
   LOOP
      done := TRUE;
   END LOOP;
   done := FALSE;
   WHILE NOT (done = TRUE)
   LOOP
      done := TRUE;
   END LOOP;
   done := FALSE;
   WHILE NOT done
   LOOP
      done := TRUE;
   END LOOP;
END;
/

Using CLOB values with comparison operators, or functions such as LIKE and BETWEEN, can create temporary LOBs. You might need to make sure your temporary tablespace is large enough to handle these temporary LOBs.

Simple CASE expression

A simple CASE expression selects a result from one or more alternatives, and returns the result. Although it contains a block that might stretch over several lines, it really is an expression that forms part of a larger statement, such as an assignment or a procedure call. The CASE expression uses a selector, an expression whose value determines which alternative to return.

A CASE expression has the form illustrated in Example 2-26. The selector (grade) is followed by one or more WHEN clauses, which are checked sequentially. The value of the selector determines which clause is evaluated. The first WHEN clause that matches the value of the selector determines the result value, and subsequent WHEN clauses are not evaluated. If there are no matches, then the optional ELSE clause is performed.

DECLARE
   grade CHAR(1) := 'B';
   appraisal VARCHAR2(20);
BEGIN
   appraisal :=
      CASE grade
         WHEN 'A' THEN 'Excellent'
         WHEN 'B' THEN 'Very Good'
         WHEN 'C' THEN 'Good'
         WHEN 'D' THEN 'Fair'
         WHEN 'F' THEN 'Poor'
         ELSE 'No such grade'
      END;
   DBMS_OUTPUT.PUT_LINE('Grade ' || grade || ' is ' || appraisal);
END;
/

The optional ELSE clause works similarly to the ELSE clause in an IF statement. If the value of the selector is not one of the choices covered by a WHEN clause, the ELSE clause is executed. If no ELSE clause is provided and none of the WHEN clauses are matched, the expression returns NULL.

Searched CASE Expression

A searched CASE expression lets you test different conditions instead of comparing a single expression to various values. It has the form shown in Example 2-27.

A searched CASE expression has no selector. Each WHEN clause contains a search condition that yields a BOOLEAN value, so you can test different variables or multiple conditions in a single WHEN clause.

DECLARE
   grade CHAR(1) := 'B';
   appraisal VARCHAR2(120);
   id NUMBER := 8429862;
   attendance NUMBER := 150;
   min_days CONSTANT NUMBER := 200;
FUNCTION attends_this_school(id NUMBER) RETURN BOOLEAN IS
   BEGIN RETURN TRUE; END;
BEGIN
   appraisal :=
      CASE
         WHEN attends_this_school(id) = FALSE THEN 'N/A - Student not enrolled'
-- Have to test this condition early to detect good students with bad attendance
         WHEN grade = 'F' OR attendance < min_days 
            THEN 'Poor (poor performance or bad attendance)'
         WHEN grade = 'A' THEN 'Excellent'
         WHEN grade = 'B' THEN 'Very Good'
         WHEN grade = 'C' THEN 'Good'
         WHEN grade = 'D' THEN 'Fair'
         ELSE 'No such grade'
      END;
   DBMS_OUTPUT.PUT_LINE('Result for student ' || id || ' is ' || appraisal);
END;
/

The search conditions are evaluated sequentially. The BOOLEAN value of each search condition determines which WHEN clause is executed. If a search condition yields TRUE, its WHEN clause is executed. After any WHEN clause is executed, subsequent search conditions are not evaluated. If none of the search conditions yields TRUE, the optional ELSE clause is executed. If no WHEN clause is executed and no ELSE clause is supplied, the value of the expression is NULL.

NULLs and the NOT Operator

Recall that applying the logical operator NOT to a null yields NULL. Thus, the following two IF statements are not always equivalent:

The sequence of statements in the ELSE clause is executed when the IF condition yields FALSE or NULL. If neither x nor y is null, both IF statements assign the same value to high. However, if either x or y is null, the first IF statement assigns the value of y to high, but the second IF statement assigns the value of x to high.

NULLs and Zero-Length Strings

PL/SQL treats any zero-length string like a null. This includes values returned by character functions and BOOLEAN expressions. For example, the following statements assign nulls to the target variables:

DECLARE
   null_string VARCHAR2(80) := TO_CHAR('');
   address VARCHAR2(80);
   zip_code VARCHAR2(80) := SUBSTR(address, 25, 0);
   name VARCHAR2(80);
   valid BOOLEAN := (name != '');

Use the IS NULL operator to test for null strings, as follows:

IF v_string IS NULL THEN ...

NULLs and the Concatenation Operator

The concatenation operator ignores null operands. For example, the expression

'apple' || NULL || NULL || 'sauce'

returns the following value:

'applesauce'

NULLs as Arguments to Built-In Functions

If a null argument is passed to a built-in function, a null is returned except in the following cases.

The function DECODE compares its first argument to one or more search expressions, which are paired with result expressions. Any search or result expression can be null. If a search is successful, the corresponding result is returned. In Example 2-29, if the column manager_id is null, DECODE returns the value 'nobody':

DECLARE
   the_manager VARCHAR2(40);
   name employees.last_name%TYPE;
BEGIN
-- NULL is a valid argument to DECODE. In this case, manager_id is null
-- and the DECODE function returns 'nobody'.
   SELECT DECODE(manager_id, NULL, 'nobody', 'somebody'), last_name
      INTO the_manager, name FROM employees WHERE employee_id = 100;
   DBMS_OUTPUT.PUT_LINE(name || ' is managed by ' || the_manager);
END;
/

The function NVL returns the value of its second argument if its first argument is null. In Example 2-30, if the column specified in the query is null, the function returns the value -1 to signify a non-existent employee in the output:

DECLARE
   the_manager employees.manager_id%TYPE;
   name employees.last_name%TYPE;
BEGIN
-- NULL is a valid argument to NVL. In this case, manager_id is null
-- and the NVL function returns -1.
   SELECT NVL(manager_id, -1), last_name
      INTO the_manager, name FROM employees WHERE employee_id = 100;
   DBMS_OUTPUT.PUT_LINE(name || ' is managed by employee Id: ' || the_manager);
END;
/

The function REPLACE returns the value of its first argument if its second argument is null, whether the optional third argument is present or not. For example, the call to REPLACE in Example 2-31 does not make any change to the value of OLD_STRING:

DECLARE
   string_type VARCHAR2(60);
   old_string string_type%TYPE := 'Apples and oranges';
   v_string  string_type%TYPE := 'more apples';
-- NULL is a valid argument to REPLACE, but does not match
-- anything so no replacement is done.
   new_string string_type%TYPE := REPLACE(old_string, NULL, v_string);
BEGIN
   DBMS_OUTPUT.PUT_LINE('Old string = ' || old_string);
   DBMS_OUTPUT.PUT_LINE('New string = ' || new_string);
END;
/

If its third argument is null, REPLACE returns its first argument with every occurrence of its second argument removed. For example, the following call to REPLACE removes all the dashes from DASHED_STRING, instead of changing them to another character:

DECLARE
   string_type VARCHAR2(60);
   dashed string_type%TYPE := 'Gold-i-locks';
-- When the substitution text for REPLACE is NULL,
-- the text being replaced is deleted.
   name   string_type%TYPE := REPLACE(dashed, '-', NULL);
BEGIN
   DBMS_OUTPUT.PUT_LINE('Dashed name    = ' || dashed);
   DBMS_OUTPUT.PUT_LINE('Dashes removed = ' || name);
END;
/

If its second and third arguments are null, REPLACE just returns its first argument.

Conditional Compilation Control Tokens

The conditional compilation trigger character is $ and is used to identify code that is processed before the application is compiled. A conditional compilation control token is of the form:

preprocessor_control_token ::= $plsql_identifier

The $ must be at the beginning of the identifier name and there cannot be a space between the $ and the name. The $ can also be embedded in the identifier name, but it has no special meaning. The reserved preprocessor control tokens are $IF, $THEN, $ELSE, $ELSIF, $END, and $ERROR. For an example of the use of the conditional compilation control tokens, see Example 2-34.

Using Conditional Compilation Selection Directives

The conditional compilation selection directive evaluates static expressions to determine which text should be included in the compilation. The selection directive is of the form:

boolean_static_expression must be a BOOLEAN static expression. For a description of BOOLEAN static expressions, see "Using Static Expressions with Conditional Compilation". For information on PL/SQL IF .. THEN control structures, see "Testing Conditions: IF and CASE Statements".

Using Conditional Compilation Error Directives

The error directive $ERROR raises a user-defined error and is of the form:

$ERROR varchar2_static_expression $END

varchar2_static_expression must be a VARCHAR2 static expression. For a description of VARCHAR2 static expressions, see "Using Static Expressions with Conditional Compilation". See Example 2-33.

Using Conditional Compilation Inquiry Directives

The inquiry directive is used to check the compilation environment. The inquiry directive is of the form:

inquiry_directive ::= $$id

An inquiry directive can be predefined as described in "Using Predefined Inquiry Directives With Conditional Compilation" or be user-defined. The following describes the order of the processing flow when conditional compilation attempts to resolve an inquiry directive:

1. The id is used as an inquiry directive in the form $$id for the search key.

2. The two-pass algorithm proceeds as follows:

   The string in the PLSQL_CCFLAGS initialization parameter is scanned from right to left, searching with id for a matching name (case insensitive); done if found.

   The predefined inquiry directives are searched; done if found.

3. If the $$id cannot be resolved to a value, then the PLW-6003 warning message is reported if the source text is not wrapped. The literal NULL is substituted as the value for undefined inquiry directives. Note that if the PL/SQL code is wrapped, then the warning message is disabled so that the undefined inquiry directive is not revealed.

For example, given the following session setting:

The value of $$debug is 0 and the value of $$plsql_ccflags is TRUE. Note that the value of $$plsql_ccflags resolves to the user-defined plsql_ccflags inside the value of the PLSQL_CCFLAGS compiler parameter. This occurs because a user-defined directive overrides the predefined one.

Given this session setting:

ALTER SESSION SET PLSQL_CCFLAGS = 'debug:true'

Now the value of $$debug is TRUE, the value of $$plsql_ccflags is 'debug:true', the value of $$my_id is the literal NULL, and the use of $$my_id raises PLW-6003 if the source text is not wrapped.

For an example of the use of an inquiry directive, see Example 2-34.

Using Predefined Inquiry Directives With Conditional Compilation

This section describes the inquiry directive names that are predefined and can be used in conditional expressions. These include:

• The Oracle initialization parameters for PL/SQL compilation, such as PLSQL_CCFLAGS, PLSQL_DEBUG, PLSQL_OPTIMIZE_LEVEL, PLSQL_CODE_TYPE, PLSQL_WARNINGS, and NLS_LENGTH_SEMANTICS. See "Initialization Parameters for PL/SQL Compilation". For an example, see Example 2-34.

  Note that recompiling a PL/SQL unit with the REUSE SETTINGS clause of the SQL ALTER statement can protect against changes made to initialization parameter values in the current PL/SQL compilation environment. See Example 2-35.

• PLSQL_LINE which is a PLS_INTEGER literal value indicating the line number reference to $$PLSQL_LINE in the current unit. For example:

  $IF $$PLSQL_LINE = 32 $THEN ...

  Note that the value of PLSQL_LINE can be defined explicitly with PLSQL_CCFLAGS.

• PLSQL_UNIT which is a VARCHAR2 literal value indicating the current source unit. For a named compilation unit, $$PLSQL_UNIT contains, but might not be limited to, the unit name. For an anonymous block, $$PLSQL_UNIT contains the empty string. For example:

  IF $$PLSQL_UNIT = 'AWARD_BONUS' THEN ...

  Note that the value of PLSQL_UNIT can be defined explicitly with PLSQL_CCFLAGS. Also note that the previous example shows the use of PLSQL_UNIT in regular PL/SQL. Because $$PLSQL_UNIT = 'AWARD_BONUS' is a VARCHAR2 comparison, not a static expression, it is not supported with $IF. One valid use of $IF with PLSQL_UNIT is to determine an anonymous block:

  $IF $$PLSQL_UNIT IS NULL $THEN ...

Using Static Expressions with Conditional Compilation

Only static expressions which can be fully evaluated by the compiler are allowed during conditional compilation processing. Any expression that contains references to variables or functions that require the execution of the PL/SQL are not available during compilation and cannot be evaluated. For information on PL/SQL datatypes, see "Overview of Predefined PL/SQL Datatypes".

A static expression is either a BOOLEAN, PLS_INTEGER, or VARCHAR2 static expression. Static constants declared in packages are also static expressions.

CREATE PACKAGE my_debug IS
  debug CONSTANT BOOLEAN := TRUE;
  trace CONSTANT BOOLEAN := TRUE;
END my_debug;
/
CREATE PROCEDURE my_proc1 IS
BEGIN
  $IF my_debug.debug $THEN DBMS_OUTPUT.put_line('Debugging ON'); 
  $ELSE DBMS_OUTPUT.put_line('Debugging OFF'); $END
END my_proc1;
/
CREATE PROCEDURE my_proc2 IS
BEGIN
  $IF my_debug.trace $THEN DBMS_OUTPUT.put_line('Tracing ON'); 
  $ELSE DBMS_OUTPUT.put_line('Tracing OFF'); $END
END my_proc2;
/

Setting the PLSQL_CCFLAGS Initialization Parameter

You can set the dynamic PLSQL_CCFLAGS initialization parameter to flag names with associated values to control conditional compilation on PL/SQL units. For example, the PLSQL_CCFLAGS initialization parameter could be set dynamically with ALTER SESSION to turn on debugging and tracing functionality in PL/SQL units as shown in Example 2-34.

You can also set the PLSQL_CCFLAGS initialization parameter to independently control conditional compilation on a specific PL/SQL unit with as shown in Example 2-35 with the SQL ALTER PROCEDURE statement.

The flag names can be set to any unquoted PL/SQL identifier, including reserved words and keywords. If a flag value is explicitly set, it must be set to a TRUE, FALSE, PLS_INTEGER, or NULL. The flag names and values are not case sensitive. For detailed information, including restrictions, on the PLSQL_CCFLAGS initialization parameter, see Oracle Database Reference.

Using DBMS_DB_VERSION Package Constants

The DBMS_DB_VERSION package provides constants that are useful when making simple selections for conditional compilation. The PLS_INTEGER constants VERSION and RELEASE identify the current Oracle version and release numbers. The BOOLEAN constants VER_LE_9, VER_LE_9_1, VER_LE_9_2, VER_LE_10, VER_LE_10_1, and VER_LE_10_2 evaluate to TRUE or FALSE on the basis of less than or equal to the version and the release. For example, the constants in Oracle 10g release 2 evaluate as follows:

• VER_LE_10 represents the condition that the database version is less than or equal to 10; it is TRUE

• VER_LE_10_2 represents the condition that database version is less than or equal to 10 and release is less than or equal to 2; it is TRUE

• All constants representing Oracle 10g release 1 or earlier are FALSE

Example 2-33 illustrates the use of a DBMS_DB_VERSION constant with conditional compilation. Both the Oracle database version and release are checked. This example also shows the use of $ERROR.

BEGIN
$IF DBMS_DB_VERSION.VER_LE_10_1 $THEN
  $ERROR 'unsupported database release' $END
$ELSE
  DBMS_OUTPUT.PUT_LINE ('Release ' || DBMS_DB_VERSION.VERSION || '.' ||
                        DBMS_DB_VERSION.RELEASE || ' is supported.');
  -- Note that this COMMIT syntax is newly supported in 10.2
  COMMIT WRITE IMMEDIATE NOWAIT;
$END
END;
/

For information on the DBMS_DB_VERSION package, see Oracle Database PL/SQL Packages and Types Reference.

Using Conditional Compilation to Specify Code for Database Versions

In Example 2-34, conditional compilation is used to determine whether the BINARY_DOUBLE datatype can be utilized in the calculations for PL/SQL units in the database. The BINARY_DOUBLE datatype can only be used in a database version that is 10g or later. This example also shows the use of the PLSQL_CCFLAGS parameter.

-- set flags for displaying debugging code and tracing info
ALTER SESSION SET PLSQL_CCFLAGS = 'my_debug:FALSE, my_tracing:FALSE';

CREATE PACKAGE my_pkg AS
  SUBTYPE my_real IS
    $IF DBMS_DB_VERSION.VERSION < 10 $THEN NUMBER; -- check database version
      $ELSE                                BINARY_DOUBLE;
    $END
  my_pi my_real; my_e my_real;
END my_pkg;
/

CREATE PACKAGE BODY my_pkg AS
BEGIN -- set up values for future calculations based on DB version
  $IF DBMS_DB_VERSION.VERSION < 10 $THEN
       my_pi := 3.14016408289008292431940027343666863227;
       my_e  := 2.71828182845904523536028747135266249775;
    $ELSE
       my_pi := 3.14016408289008292431940027343666863227d;
       my_e  := 2.71828182845904523536028747135266249775d;
  $END
END my_pkg;
/

CREATE PROCEDURE circle_area(radius my_pkg.my_real) IS
  my_area my_pkg.my_real;
  my_datatype VARCHAR2(30);
BEGIN
  my_area := my_pkg.my_pi * radius;
  DBMS_OUTPUT.PUT_LINE('Radius: ' || TO_CHAR(radius) 
                       || ' Area: ' || TO_CHAR(my_area) );
  $IF $$my_debug $THEN -- if my_debug is TRUE, run some debugging code
    SELECT DATA_TYPE INTO my_datatype FROM USER_ARGUMENTS 
       WHERE OBJECT_NAME = 'CIRCLE_AREA' AND ARGUMENT_NAME = 'RADIUS';
     DBMS_OUTPUT.PUT_LINE('Datatype of the RADIUS argument is: ' || my_datatype);
  $END
END;
/

If you want to set my_debug to TRUE, you can make this change only for procedure circle_area with the REUSE SETTINGS clause as shown in Example 2-35.

ALTER PROCEDURE circle_area COMPILE PLSQL_CCFLAGS = 'my_debug:TRUE' 
   REUSE SETTINGS;

Using DBMS_PREPROCESSOR Procedures to Print or Retrieve Source Text

DBMS_PREPROCESSOR subprograms print or retrieve the post-processed source text of a PL/SQL unit after processing the conditional compilation directives. This post-processed text is the actual source used to compile a valid PL/SQL unit. Example 2-36 shows how to print the post-processed form of my_pkg in Example 2-34 with the PRINT_POST_PROCESSED_SOURCE procedure.

CALL DBMS_PREPROCESSOR.PRINT_POST_PROCESSED_SOURCE('PACKAGE', 'HR', 'MY_PKG');

When my_pkg in Example 2-34 is compiled on a 10g release or later database using the HR account, the output of Example 2-36 is similar to the following:

PRINT_POST_PROCESSED_SOURCE replaces unselected text with whitespace. The lines of code in Example 2-34 that are not included in the post-processed text are represented as blank lines. For information on the DBMS_PREPROCESSOR package, see Oracle Database PL/SQL Packages and Types Reference.