documentation for new sql clauses case, coalesce and nullif

contributed by Arno Brinkman <firebird@abvisie.nl>

doc/sql.extensions/README.case

@@ -0,0 +1,83 @@
+Function:
+    Allow the result of a column to be determined by a the results of a 
+    case expression.
+
+Author:
+    Arno Brinkman <firebird@abvisie.nl>
+
+Format:
+
+
+  <case expression> ::=
+      <case abbreviation>
+    | <case specification>
+
+  <case abbreviation> ::=
+      NULLIF <left paren> <value expression> <comma> <value expression> <right paren>
+    | COALESCE <left paren> <value expression> { <comma> <value expression> }... <right paren>
+
+  <case specification> ::=
+      <simple case>
+    | <searched case>
+
+  <simple case> ::=
+    CASE <value expression>
+      <simple when clause>...
+      [ <else clause> ]
+    END
+
+  <searched case> ::=
+    CASE
+      <searched when clause>...
+      [ <else clause> ]
+    END
+
+  <simple when clause> ::= WHEN <when operand> THEN <result>
+
+  <searched when clause> ::= WHEN <search condition> THEN <result>
+
+  <when operand> ::= <value expression>
+
+  <else clause> ::= ELSE <result>
+
+  <result> ::=
+      <result expression>
+    | NULL
+
+  <result expression> ::= <value expression>
+
+
+Syntax Rules:
+
+
+Examples:
+
+A) (simple)
+  SELECT
+    o.ID,
+    o.Description,
+    CASE o.Status
+      WHEN 1 THEN 'confirmed'
+      WHEN 2 THEN 'in production'
+      WHEN 3 THEN 'ready'
+      WHEN 4 THEN 'shipped'
+      ELSE 'unknown status ''' || o.Status || ''''
+    END
+  FROM
+    Orders o
+
+B) (searched)
+  SELECT
+    o.ID,
+    o.Description,
+    CASE
+      WHEN (o.Status IS NULL) THEN 'new'
+      WHEN (o.Status = 1) THEN 'confirmed'
+      WHEN (o.Status = 3) THEN 'in production'
+      WHEN (o.Status = 4) THEN 'ready'
+      WHEN (o.Status = 5) THEN 'shipped'
+      ELSE 'unknown status ''' || o.Status || ''''
+    END
+  FROM
+    Orders o
+

doc/sql.extensions/README.coalesce

@@ -0,0 +1,38 @@
+Function:
+    Allow a column value to be calculated by a number of expressions, 
+    the first expression returning a non NULL value is returned as the 
+    column value
+
+Author:
+    Arno Brinkman <firebird@abvisie.nl>
+
+Format:
+
+  <case abbreviation> ::=
+    | COALESCE <left paren> <value expression> { <comma> <value expression> }... <right paren>
+
+
+Syntax Rules:
+    1) COALESCE (V1, V2) is equivalent to the following <case specification>:
+         CASE WHEN V1 IS NOT NULL THEN V1 ELSE V2 END
+    2) COALESCE (V1, V2,..., Vn), for n >= 3, is equivalent to the following
+         <case specification>:
+         CASE WHEN V1 IS NOT NULL THEN V1 ELSE COALESCE (V2,...,Vn) END
+
+
+Examples:
+A)
+
+  SELECT
+    PROJ_NAME AS Projectname,
+    COALESCE(e.FULL_NAME,'[> not assigned <]') AS Employeename
+  FROM
+    PROJECT p
+    LEFT JOIN EMPLOYEE e ON (e.EMP_NO = p.TEAM_LEADER)
+
+B)
+  SELECT
+    COALESCE(Phone,MobilePhone,'Unknown') AS "Phonenumber"
+  FROM
+    Relations
+

doc/sql.extensions/README.nullif

@@ -0,0 +1,23 @@
+Function:
+    Speicify an alternative value for a column to return when it has a NULL 
+    value.
+
+Author:
+    Arno Brinkman <firebird@abvisie.nl>
+
+Format:
+
+  <case abbreviation> ::=
+      NULLIF <left paren> <value expression> <comma> <value expression> <right paren>
+
+
+Syntax Rules:
+    1) NULLIF (V1, V2) is equivalent to the following <case specification>:
+         CASE WHEN V1 = V2 THEN NULL ELSE V1 END
+
+
+Examples:
+A)
+  UPDATE PRODUCTS
+    SET STOCK = NULLIF(STOCK,0)
+