1 xsql

The XSQL language provides a simple way to query or update databases and produce XML documents from the results of database operations.

This document specifies the structure and meaning of XSQL programs. XSQL is an XML-based language. The structure of an XSQL program is described by its DTD, along with narrative rules, which express further syntax constraints that can not be fully expressed through the DTD. Each language construct consists of one or more elements defined by the DTD. Moreover, some of the values of attributes an elements must conform to a well-formed syntax. In these cases, the standard Extended Backus-Naur Form (EBNF) notation is used to describe the syntax.

The meaning of an XSQL program is described by narrative rules that describe the meaning and composition rules for each language construct.

An XSQL program is given as a set of statements nested in a root element, whose tag is xsql.

<!ELEMENT xsql
          ((%xsql-statement;)*)>

<!ATTLIST xsql 
          root-tag  CDATA  #IMPLIED>

Attribute Definitions

Attribute Description Required
root-tag Defines the tag used for the root element of the document produced by an XSQL program. If this attribute is not specified, then the tag root will be used. No

The contained element xsql-statement* defines a list of XSQL statements to be executed. The statements are executed in the order specified.

Example of an XSQL specification:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE xsql SYSTEM "http://xsql.dtd">
<xsql>
   <select name="parts-list" record-tag-name="part">
      <sql>
         select PART as PARTNO, LLC, PLANNER
            from WDS61.IM_TABLE
            where part = '114S2608-44'
       </sql>
   </select>
</xsql>

The XML document produced by the XSQL specification above:

<root>
  <parts-list>
    <part>
      <PARTNO>114S2608-44</PARTNO>
      <LLC>3</LLC>
      <PLANNER>P5</PLANNER>
    </part>
  </parts-list>
</root>

2 xsql-statement

A statement defines an action to be performed when it is exeucted.

XSQL supports several kinds of statements. Each type of statement is explained in later sections.

<!ENTITY % xsql-statement
          "( if
           | write
           | log
           | xml
           | query-statement
           | select
           | insert
           | update
           | delete
           | define-proc
           | call-proc
           | te-process
           | call-te
           | import-class)">

Many statements can include XSQL expressions in either attributes or subelements. Expressions appear in attributes and elements in one of the following two ways

  1. The value of the attribute or element is a complete XSQL expression.

    For example, in an if-statement, the attribute condition contains a complete XSQL expression. Consider the following if-statment:

       <if condition="count != 0">
          .
          .
          .
       </if>
    
    When it is executed the expression is evaluated, and the value of the expression is used to determine how the remainder of the if-statement is executed.

  2. The value of the attribute or element contains embedded expressions. In this case, the expressions appear between the delimeters {% and %}. The final value of the attribute or element is defined as the original text value with each expression replaced by its value.

    For example, when the following write statement is executed:

       <write value="Let's sit in row {%12 + 5%}."/>
    
    the string
       Let's sit in row 17.
    
    is written.

The next section describes expressions in more detail.

2.1 Expressions

An expression defines a computation to be performed by applying operators to operands. The operands can be either constant values, variables, or other expressions.

An expression consists of a sequence of white space and lexical elements. White space is either the space character, the horizontal tab character, the carriage return character, or the new line character.

A lexical element is a well-formed sequence of characters and is either an identifier, a constant, or a special symbol. There may be The meaning of an expression is not affected by white space, and depends only on the sequence of lexical elements.

Special Symbols

Special symbols are made up or one or two characters. They are used in expressions to denote operators or to parenthesize parts of expressions.

The one character speical symbols are:

(  )  [  ]  +  -  *  /  %  .  ,  <  >  !  =

The two character special symbols are:

<=  >=  ==  &&  ||

Lexical elements cannot contain white space, with the exception of string literals, which may contain the space character.

Identifiers

Identifiers are used as names.

       identifier ::= letter {[underline] letter_or_digit}

       letter_or_digit ::= letter | digit

       letter ::=
             a | b | c | d | e | f | g | h | i | j | k | l |
             m | n | o | p | q | r | s | t | u | v | w | x |
             y | z | A | B | C | D | E | F | G | H | I | J |
             K | L | M | N | O | P | Q | R | S | T | U | V |
             W | X | Y | Z

       digit ::= 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9

       underline ::= _
An identifier can be the name of variable, constant, field (of a structured type), or method.

All characters of an identifier are signficant, and upper and lower case letters are not considered the same.

Examples of identifiers:

      a        index   lastName
      String   T3      The_Last_Record

Numeric Literals

Numeric literals represent constant number values. There are two types of numeric literals, real numbers and integers. Real numbers have a decimal point and integers do not.

       numeric_literal ::= digits [.digits]

       digits ::= digit {digit}

Examples of integers:

      23     100     51

Examples of reals:

      23.0     100.2332     0.51

String Literals

String literals represent string values. A string is a sequence of zero or more characters.

       string_literal ::= "{character}" | '{character}'

Examples of strings:

      ""             // the empty string
      ''             // the empty string
      "A" 
      "He can't go"  // A string that contains a '
      '121'
      '"Help"'       // A string that contains a "

Expression Syntax

The syntax for an expression is given by the following rules:
       expression ::=
            relation {&& relation} | relation {|| relation}

       relation ::=
            simple_expression [relational_operator simple_expression]

       relational_operator ::=
            < | <= | > | >= | != | ==

       simple_expression ::=
            [adding_operator] term {adding_operator term}

       adding_operator ::= + | -

       term ::= factor {multiplying_operator factor}

       multiplying_operator ::= * | / | %

       factor ::= primary | ! primary

       primary ::=
            numeric_literal
          | string_literal
          | identifier
          | (expression)
          | primary [expression]
          | primary . identifier
          | primary ( [expression {, expression}] )

Expression Evaluation

Expressions are evaluated from left to right using the following precedence rules: first primaries are evaluated, then factors are evaluated, then terms are evaluated, then simple expressions are evaluated, then relations are evaluated, and finally the complete expression is evaluated.

Types and Operations

A type defines a set of values that may be assumed by an expression and the operations that may be performed on the expression.

Boolean Type

The values of the type boolean are false and true. The following logical operators are defined for booleans.
   !      not
   &&     and
   ||     or
The ! operator takes a boolean and return an boolean. The && and || operators take two boolean and return an boolean.

Integer Type

The values of the type integer are the finite, successive, whole numbers. The following arithmetic operators are defined for integers.
   +     unary plus
   -     unary minus
   +     addition
   -     subtraction
   *     multiplication
   /     integer division
   %     modulus
The unary plus and minus operators take an integer and return an integer. The other operators take two integers and return an integer.

The following relational operators are defined for integers. These operators take two integers and return a boolean.

   <     less than
   <=    less than equal
   >     greater than
   >=    greater than equal
   ==    equal
   !=    not equal
If one of the operands of the binary arithmetic or relational operators, except the + operator, is an integer and the other is a string, then the string is converted to an integer and the operation is performed on the two integers. If the string does not represent a valid integer constant, then an error occurs.

Note that the + operator was excluded from the implicit conversion rule above, because, if either operand of the + operator is a string, then the other operand is converted to a string and the string concatenation operation is performed.

Real Type

The values of the type real are a finite subset of the real numbers. The following arithmetic operators are defined for reals.
   +     unary plus
   -     unary minus
   +     addition
   -     subtraction
   *     multiplication
   /     division
   %     modulus
The unary plus and minus operators take a real and return a real. The other operators take two reals and return a real.

The following relational operators are defined for reals. These operators take two reals and return a boolean.

   <     less than
   <=    less than equal
   >     greater than
   >=    greater than equal
   ==    equal
   !=    not equal
If one of the operands of a binary arithmetic or relational operator is a real and the other is an integer, then the integer is converted to a real, and the operation is performed on the two reals.

If one of the operands of a binary arithmetic or relational operator, except the + operator, is a real and the other is a string, then the string is converted to a real and the operation is performed on the two reals. If the string does not represent a valid real constant, then an error occurs.

String Type

The values of the type string are sequences of zero or more characters.

The following relational operators are defined for strings. These operators take two strings and return a boolean.

   <     less than
   <=    less than equal
   >     greater than
   >=    greater than equal
   ==    equal
   !=    not equal

The operation string concatenation is also defined for strings. It takes two strings and returns a string.

   +     string concatenation

If either operand of the binary + operator is a string, then the other operand is converted to a string and the concatenation operation is performed on the two strings.

List Type

A list is a sequence of zero or more values of any type. Each value in the list has a fixed ordinal position. The position of the first value is zero. The length of the list is the number of values in the list.

The operators defined for lists are

   [expression]     subscript
   .length          get length 

The subscript opertion returns a value at a given position in the list. The position is given by an integer valued expression between the two brackets. The position must be in the range 0..list.length-1 or an error occurs.

The .length returns an integer, which is the length of the list.

Record Type

A record is composite type consisting of zero or more fields. Each field has name and contains a value. The values may be of different types.

The operators defined for records are

   .field-name     field selection

The field selection opertion returns the value of the named field. If the record does not contain a field with specified name, then an error occurs.

Class Type

Every XSQL type is associated with a Java class type. The following table shows the the association.

XSQL TypeJava Class Type
booleanBoolean
integerInteger or Long
realDouble
stringString
listAny Java class type that implements the XSQL array interface
recordAny Java class type that implements the XSQL record interface

In addition, the user may set XSQL variables to objects that belong to any Java class type. XSQL provides operators to access fields and methods of these objects.

The operators defined for all values are

   .field-name     field selection
   .method-name(parameter-list)     method call

3 if

An if statement selects one of it's enclosed statement lists for execution.
<!ELEMENT if
          (then,
           else?)>

<!ATTLIST if 
          condition  CDATA  #REQUIRED>

Attribute Definitions

Attribute Description Required
condition A boolean valued XSQL expression. Yes
<!ELEMENT then
          ((%xsql-statement;)*)>
<!ELEMENT else
          ((%xsql-statement;)*)>

The contained element xsql-statement* defines a list of XSQL statements to be executed.

When an if statement is executed, the condition is evaluated. If the condition evaluates to true, the statement list in the then element is executed. If the condition evalutes to false and an else element is included, then the statement list in the else element is executed. Otherwise, no included statement lists are executed.

Example of a basic if statement:

<if condition="6*2==12">
   <then><write value="then part executed"/></then>
   <else><write value="else part executed"/></else>
</if>

Example of an if statement that conditionally executes a call-te statement based on the results of a query:

<select name="partExistance">
   <sql>
      select count(*) as count
        from WDS61.IM_TABLE
        where PART = '$CP5'
   </sql>
</select>

<if condition="partExistance.COUNT==1">
   <then>
      <call-te procedure-name="EXEC_ALL"
        package-name="ENGINEERING_ADDPART" schema-name="WDS61">
         <arg name="PART" value="$CP5"/>
         <arg name="VDESC" value="CP3"/>
         <arg value="EA" name="UM"/>
         <arg name="PUR_MFG" value="M"/>
         <arg value="L" name="PART_TYPE"/>
         <arg name="DFLT_STKRM" value="54"/>
     </call-te>
   </then>
</if>

4 write

A write statement writes a value to standard out. It is provided to help debug XSQL programs.
<!ELEMENT write
          (value?)>

<!ATTLIST write 
          value  CDATA  #IMPLIED>

<!ELEMENT value
          (#PCDATA)>

Attribute Definitions

Attribute Description Required
value The value to be written, given as an attribute. No

The optional contained element value? specifies the value to be written, given as a element.

5 log

A log statement writes a value to the XSQL log.
<!ELEMENT log
          (value?)>

<!ATTLIST log 
          level  (debug|info|error|warning)  #IMPLIED
          value  CDATA  #IMPLIED>

<!ELEMENT value
          (#PCDATA)>

Attribute Definitions

Attribute Description Required
level The level of severity to be associated with the log message.

The legal values for this attribute are (debug|info|error|warning).

No
value The value to be written, given as an attribute. No

The optional contained element value? specifies the value to be written, given as a element.

6 xml

An XML statement adds an element to the current XML document.
<!ELEMENT xml
          (value?,
           (%xsql-statement;)*)>

<!ATTLIST xml 
          tag  CDATA  #REQUIRED
          value  CDATA  #IMPLIED>

<!ELEMENT value
          (#PCDATA)>

Attribute Definitions

Attribute Description Required
tag The tag for the element to be added. Yes
value The text contents of the element. No

The optional contained element value? specifies the text contents of the element specified by an element instead of an attribute.

The contained element xsql-statement* defines a list of XSQL statements to be executed. These statements will add any XML they produce to the element created by this statement.

7 query-statement

Query statements are used to select, insert, update, or delete data from a database.
<!ENTITY % query-statement
          "( select
           | insert
           | update
           | delete)">

<!ELEMENT sql
          (#PCDATA)>

8 select

The select statement is used to read data from a database and store the result in an XML document.
<!ELEMENT select
          (sql,
           (%xsql-statement;)*)>

<!ATTLIST select 
          name  CDATA  #REQUIRED
          record-tag  CDATA  #IMPLIED>

<!ELEMENT sql
          (#PCDATA)>

Attribute Definitions

Attribute Description Required
name The name of query statement. Yes
record-tag The value to be used for the surrounding XML document tag for each record returned from the record set. No

The contained element sql specifies the SQL for the query statement. The query string may contain embedded XSQL expressions.

The contained element xsql-statement* defines a list of XSQL statements to be executed. These statements will be executed for each row returned by the select statement. Before these statements are executed the current XML document will be set to the element produced for the associated row. Thus, these statements will add any XML document they produce to the document for the row.

The select statement executes the specified SQL statement and stores the results in the current XML document.

The root element of the XML document produced by the select statement has the tag given by the attribute name. It contains an element for each row returned by the select statement. The tag for each row element is given by the attribute record-tag. Each row element contains an element for each column in the returned row. The tag for each column element is the name of column. Each column element contains parsed character data, which is its value.

Moreover, a select statement declares a new variable and sets the variable's value to the results of the query. The name of the variable is the name given by the name attribute. The value is a list of records, one record for each row returned. Each record contains a field for each in the returned row. The name of the field is the name of the column, and the value of the field is the value of the column.

Example of a select statement:

   <select name="parts-list" record-tag="part">
      <sql>
         select PART as PARTNO, LLC, PLANNER
            from WDS61.IM_TABLE
            where part = '114S2608-44'
       </sql>
   </select>
The XML document produced by the select statement above:

<root>
  <parts-list>
    <part>
      <PARTNO>114S2608-44</PARTNO>
      <LLC>3</LLC>
      <PLANNER>P5</PLANNER>
    </part>
  </parts-list>
</root>

9 insert

<!ELEMENT insert
          (sql)>

<!ATTLIST insert 
          name  CDATA  #REQUIRED>

<!ELEMENT sql
          (#PCDATA)>

Attribute Definitions

Attribute Description Required
name The name of query statement. Yes

The contained element sql specifies the SQL for the query statement. The query string may contain embedded XSQL expressions.

10 update

<!ELEMENT update
          (sql)>

<!ATTLIST update 
          name  CDATA  #REQUIRED>

<!ELEMENT sql
          (#PCDATA)>

Attribute Definitions

Attribute Description Required
name The name of query statement. Yes

The contained element sql specifies the SQL for the query statement. The query string may contain embedded XSQL expressions.

11 delete

<!ELEMENT delete
          (sql)>

<!ATTLIST delete 
          name  CDATA  #REQUIRED>

<!ELEMENT sql
          (#PCDATA)>

Attribute Definitions

Attribute Description Required
name The name of query statement. Yes

The contained element sql specifies the SQL for the query statement. The query string may contain embedded XSQL expressions.

12 define-proc

A define procedure statement associates a name with a database stored procedure definition. The name can then be used to invoke the database stored procedure from XSQL, using the call procedure statement.
<!ELEMENT define-proc
          (stored-proc)>

<!ATTLIST define-proc 
          name  CDATA  #REQUIRED>

Attribute Definitions

Attribute Description Required
name The name of the stored procedure being defined. Yes

The contained element stored-proc specifies the stored procedure definition.

<!ELEMENT stored-proc
          (return-parameter,
           parameter*)>

<!ATTLIST stored-proc 
          schema-name  CDATA  #IMPLIED
          package-name  CDATA  #IMPLIED
          procedure-name  CDATA  #REQUIRED
          record-tag  CDATA  #IMPLIED
          record-set-tag  CDATA  #IMPLIED>

<!ELEMENT return-parameter
          (parameter?)>

Attribute Definitions

Attribute Description Required
schema-name The name of the database schema that contains the stored procedure. No
package-name The name of the package that contains the stored procedure. No
procedure-name The name of the stored procedure as given in the data base. Yes
record-tag The value to be used for the surrounding XML document tag for each record returned from the record set (if applicable). No
record-set-tag The tag to be used to wrap the returned record set (if applicable). No

The contained element return-parameter? specifies the return type of the stored procedure, if the procedure is a function.

The contained element parameter* specifies the parameters for the stored procedure.

<!ELEMENT parameter
          EMPTY>

<!ATTLIST parameter 
          pos  CDATA  #REQUIRED
          name  CDATA  #REQUIRED
          mode  (in|out|inout)  "inout"
          jdbc-type  (BIGINT|BIT|BOOLEAN|CHAR|CURSOR|DATE|DECIMAL|DOUBLE|FLOAT|INTEGER|LONGVARCHAR|NUMERIC|REAL|SMALLINT|TIME|TIMESTAMP|TINYINT|VARCHAR)  #REQUIRED
          length  CDATA  #IMPLIED
          scale  CDATA  #IMPLIED
          simple-date-format  CDATA  #IMPLIED>

Attribute Definitions

Attribute Description Required
pos The position of the parameter. Yes
name The name of the parameter. Yes
mode The mode of the parameter.

The legal values for this attribute are (in|out|inout).

The default value for this attribute is inout.

Yes
jdbc-type The JDBC type of the parameter.

The legal values for this attribute are (BIGINT|BIT|BOOLEAN|CHAR|CURSOR|DATE|DECIMAL|DOUBLE|FLOAT|INTEGER|LONGVARCHAR|NUMERIC|REAL|SMALLINT|TIME|TIMESTAMP|TINYINT|VARCHAR).

Yes
length The length of the parameter. No
scale The scale attribute associated with the parameter. No
simple-date-format The Java simple date format (see java.text.SimpleDateFormat) expression that describes the input format used for specifying dates and times, and also, the format which will be used for displaying them within the generated XML document. No

13 call-proc

<!ELEMENT call-proc
          (arg*,
           (%xsql-statement;)*)>

<!ATTLIST call-proc 
          name  CDATA  #REQUIRED
          define-proc-name  CDATA  #IMPLIED
          schema-name  CDATA  #IMPLIED
          package-name  CDATA  #IMPLIED
          procedure-name  CDATA  #IMPLIED
          record-tag  CDATA  #IMPLIED
          record-set-tag  CDATA  #IMPLIED>

Attribute Definitions

Attribute Description Required
name The logical name of the statement. Yes
define-proc-name The name of the define-proc statement that defines the database procedure to be called. If not supplied, the logical name of the statement will be used. No
schema-name The name of the database schema that contains the stored procedure. No
package-name The name of the package that contains the stored procedure. No
procedure-name The name of the stored procedure as given in the data base. No
record-tag The value to be used for the surrounding XML document tag for each record returned from the record set (if applicable). No
record-set-tag The tag to be used to wrap the returned record set (if applicable). No

The contained element arg* specifies the arguments to call the stored procedure with.

The contained element xsql-statement* defines a list of XSQL statements to be executed. These statements will for each row returned by the stored procedure call.

<!ELEMENT arg
          (value?)>

<!ATTLIST arg 
          name  CDATA  #IMPLIED
          pos  CDATA  #IMPLIED
          simple-date-format  CDATA  #IMPLIED
          value  CDATA  #IMPLIED>

<!ELEMENT value
          (#PCDATA)>

Attribute Definitions

Attribute Description Required
name The name of the parameter this argument is associated with. No
pos The position of the parameter this argument is associated with. No
simple-date-format The Java simple date format (see java.text.SimpleDateFormat) expression that describes the input format used for specifying dates and times, and also, the format which will be used for displaying them within the generated XML document. No
value The value to be used for the parameter when the call is made. The value of an argument can contain embedded expressions. No

The optional contained element value? specifies the value, specified as an element instead of an attribute, to be used for the parameter when the call is made.

14 te-process

A TE process is used to represent the beginning and end of a sequence of TE calls. The TE process maintains the status of the TE calls inside the TE process by checking return codes. The TE process also handles the decision of whether or not to commit or rollback all TE's called inside the TE process. For example, while executing a statement list, if one or more te calls are made and complete without error the TE process will issue a syncCommit call. However, if one or more TE calls are made and an error occurs, the TE process will issue a syncRollback.

The only required attribute on the TE process is name, which is currently unused, but is to be incorporated into a future version of XSQL

<!ELEMENT te-process
          ((%xsql-statement;)*)>

<!ATTLIST te-process 
          name  CDATA  #IMPLIED
          schema  CDATA  #IMPLIED>

Attribute Definitions

Attribute Description Required
name Defines the name of the TE process. No
schema Defines the schema the TE process runs in. If the schema is not specified, the TE process will run in the schema whose name is established by the XSQL runtime environment. No

The contained element xsql-statement* defines a list of XSQL statements to be executed as part of a TE process.

15 call-te

A call TE statement invokes the execution of a TE. The call specifies the association of arguments with the formal parameters of the TE.
<!ELEMENT call-te
          (arg*)>

<!ATTLIST call-te 
          schema-name  CDATA  #IMPLIED
          package-name  CDATA  #REQUIRED
          procedure-name  CDATA  #REQUIRED>

Attribute Definitions

Attribute Description Required
schema-name The name of the database schema that contains the TE. No
package-name The name of the package that contains the TE's. Yes
procedure-name The name of the TE procedure to call. Yes

The contained element arg* specifies the arguments to call the TE with.

Example of a call TE statement:

<call-te procedure-name="EXEC_ALL"
  package-name="ENGINEERING_ADDPART" schema-name="WDS61">
    <arg name="PART" value="$CP5"/>
    <arg name="VDESC" value="CP3"/>
    <arg value="EA" name="UM"/>
    <arg name="PUR_MFG" value="M"/>
    <arg value="L" name="PART_TYPE"/>
    <arg name="DFLT_STKRM" value="54"/>
</call-te>

16 import-class

<!ELEMENT import-class
          EMPTY>

<!ATTLIST import-class 
          name  CDATA  #REQUIRED
          java-name  CDATA  #REQUIRED>

Attribute Definitions

Attribute Description Required
name This attribute is not currently supported. Yes
java-name This attribute is not currently supported. Yes