Appropriate Content: Informix Documentation Team

This entry is provided by Tom Houston, our esteemed SQL writer. He will be contributing the occasional entry about how to interpret syntax diagrams as they are used in IBM® Informix® documentation.

The Informix documentation uses syntax diagrams to summarize in a graphic format the syntax tokens -- the keywords, input values, delimiters, and other symbols -- and the order in which they can appear in a valid statement or command.  Syntax diagrams that Informix user documents like Administrator's Reference and Guide to SQL:Syntax use a standard graphical notation that many IBM products currently use.  Syntax diagrams are described in the Introduction chapter of PDF manuals and in the information centers.

The term syntax note refers to

• one or two digits (within parentheses) within the syntax diagram
• and a matching number immediately to the left of a note within a list of one or more notes that immediately follows the diagram.

Several instances of the same parenthetical digit (or digits) within the diagram can reference the same note below the diagram.

This blog entry addresses two potential ways to interpret a syntax note:

• syntax notes that specify cross-references to other topics
• syntax notes that restrict the contexts where a syntax path is valid.

This diagram of the CONNECT statement of SQL (for the Informix 11.70 database server) includes two restrictive syntax notes and two cross-reference syntax notes:

  
>>-CONNECT TO--------------------------------------------------->

                              (1)                                                   
>--+-| Database Environment |------+------------------------------------------+-+-->
   |                               |  (2)                                 (3) | |   
   |                               '-------| USER Authentication Clause |-----' |   
   '-DEFAULT--------------------------------------------------------------------'   

>--+-----------------------------------+--+---------+----------><
   |  (4)                              |  '-TRUSTED-'   
   '-------WITH CONCURRENT TRANSACTION-'                

Notes:
1.    See Database Environment
2.    ESQL/C and DB-Access only
3.    See USER Validation Clause
4.    ESQL/C only

Here the cross-referencing note (1) that follows the Database Environment syntax segment matches the digit that precedes the
text of the "See Database Environment" note below the diagram, which is a link to the topic that shows the syntax of the Database
Environment syntax segment.  Similarly, the cross-referencing note (3) that follows the USER Authentication Clause  
syntax segment matches the digit that precedes the text of the "See USER Validation Clause " note below the diagram, which is a link to
the topic that shows the syntax of the USER Authentication Clause syntax segment.

The digit 2 delimited by parentheses (2) preceding the optional USER Authentication Clause syntax segment matches the digit that precedes the "ESQL/C and DB-Access only" syntax note text, restricting that clause to IBM Informix ESQL/C routines and to scripts of the DB-Access utility.  This note implies, for example, that the database server will throw an exception if you attempt to run an SPL routine that attempts to connect to a database by using a CONNECT statement that includes this clause.

Similarly, the digit 4 delimited by parentheses (4) preceding the optional WITH CONCURRENT TRANSACTION keywords matches the digit that precedes the "ESQL/C only" syntax note text, restricting that clause to IBM Informix ESQL/C routine.  In this diagram, the optional TRUSTED keyword is outside the scope.of syntax note (4), because a CONNECT statement that omits the WITH CONCURRENT TRANSACTION keywords can reach the TRUSTED keyword without following a path that syntax note (4) restricts.

In both instances, the restrictive syntax notes appear immediately above the path of the syntax tokens that the syntax note references, and to the left of those tokens. Syntax notes do not refer to the path above the digit that identifies the note.  To apply the same syntax note to several independent paths in a diagram, the parenthetical digit that identifies the syntax note must be repeated for each path.

In an SPL routine, the following SQL statement fails with an error:

CONNECT TO DEFAULT WITH CONCURRENT TRANSACTION TRUSTED;

Even if a default database environment is defined for the current session, this statement fails because CONNECT statements that include the WITH CONCURRENT TRANSACTION keywords are not supported in SPL applications (unless the SPL routine invokes an ESQL/C routine to issue the CONNECT statement).

In summary, a cross-reference syntax note

• always appears to the right of the pipe-delimited name of a syntax segment,
• and always appears immediately above the path of the syntax segment that it references

A restrictive syntax note

• always appears to the left of the pipe-delimited name of a syntax segment,
• always appears immediately above the path of the syntax segment that it references,
  
• and includes in its scope every subsequent syntax token on the path that it restricts, and on subsequent paths that cannot be reached without passing through that restricted path.