Xbasic

SQL::Query Object

Description

SQL::Query object methods and related enumerations and objects.

Discussion

The SQL::Query object implements Portable SQL. The SQL::Query object parses Portable SQL statements and converts them to the native SQL dialect of the target database. The SQL::Query object is the root of all queries. As a result, it has the most properties. Its children are the various clauses that make up a complete SELECT statement.

dim conn as SQL::Connection
dim qry as SQL::Query
dim rs as SQL::ResultSet
dim connString as C
dim select_exp as C
connString = "{A5API='Access', FileName='c:\program files\a5v7\mdbfiles\alphasports.mdb'}"
select_exp = "select Lastname from customer where bill_state_region = 'ma'"
conn.open(connString)
qry.execute(conn)
rs = qry.resultset

In the simplest case, you can declare a variable and parse a string. From there you can explore the resulting query as an Xbasic object, or dump the parse tree by looking at the .ParseTree property, or even convert the query to XML using the XML property. For example:

dim Q as SQL::Query
Q.Parse("select customer, cost, 'Hello' as Message from orderheader o order by customer")
? Q.ParseTree
= 
{ select:55  -1:213   0:213   NONE:202 
  { SELECT_LIST:180
    { SELECT_ITEM:181
      { COLUMN_REFERENCE:188  :193   customer:143 }      :192 }  
    { SELECT_ITEM:181
      { COLUMN_REFERENCE:188  :193   cost:143 }      :192 }  
    { SELECT_ITEM:181
      { VALUE_EXPRESSION:212  NONE:140 
        { LIST:178  Hello:214 }      }      Message:192 }  }
  { TABLE_LIST:184
    { SELECT_TABLE_REFERENCE:189  :195   orderheader:193   o:194   JOIN_LIST:196 }  }
  { LOGICAL_EXPRESSION:211  EMPTY:170   LIST:178 }
  { GROUPBY_CLAUSE:207  GROUPBY_LIST:208 
    { LOGICAL_EXPRESSION:211  EMPTY:170   LIST:178 }  }
  { ORDERBY_CLAUSE:204
    { ORDERBY_ITEM:205
      { COLUMN_REFERENCE:188  :193   customer:143 }      EMPTY:170 }  }  UNION_LIST:209   ORDERBY_CLAUSE:204 }

? Q.XML
= <CommonAST text="select" type="55">
<CommonAST text="-1" type="213">
</CommonAST>
<CommonAST text="0" type="213">
</CommonAST>
<CommonAST text="NONE" type="202">
</CommonAST>
<CommonAST text="SELECT_LIST" type="180">
<CommonAST text="SELECT_ITEM" type="181">
<CommonAST text="COLUMN_REFERENCE" type="188">
<CommonAST text="" type="193">
</CommonAST>
<CommonAST text="customer" type="143">
</CommonAST>
</CommonAST>
<CommonAST text="" type="192">
</CommonAST>
</CommonAST>
<CommonAST text="SELECT_ITEM" type="181">
<CommonAST text="COLUMN_REFERENCE" type="188">
<CommonAST text="" type="193">
</CommonAST>
<CommonAST text="cost" type="143">
</CommonAST>
</CommonAST>
<CommonAST text="" type="192">
</CommonAST>
</CommonAST>
<CommonAST text="SELECT_ITEM" type="181">
<CommonAST text="VALUE_EXPRESSION" type="212">
<CommonAST text="NONE" type="140">
</CommonAST>
<CommonAST text="LIST" type="178">
<CommonAST text="Hello" type="214">
</CommonAST>
</CommonAST>
</CommonAST>
<CommonAST text="Message" type="192">
</CommonAST>
</CommonAST>
</CommonAST>
<CommonAST text="TABLE_LIST" type="184">
<CommonAST text="SELECT_TABLE_REFERENCE" type="189">
<CommonAST text="" type="195">
</CommonAST>
<CommonAST text="orderheader" type="193">
</CommonAST>
<CommonAST text="o" type="194">
</CommonAST>
<CommonAST text="JOIN_LIST" type="196">
</CommonAST>
</CommonAST>
</CommonAST>
<CommonAST text="LOGICAL_EXPRESSION" type="211">
<CommonAST text="EMPTY" type="170">
</CommonAST>
<CommonAST text="LIST" type="178">
</CommonAST>
</CommonAST>
<CommonAST text="GROUPBY_CLAUSE" type="207">
<CommonAST text="GROUPBY_LIST" type="208">
</CommonAST>
<CommonAST text="LOGICAL_EXPRESSION" type="211">
<CommonAST text="EMPTY" type="170">
</CommonAST>
<CommonAST text="LIST" type="178">
</CommonAST>
</CommonAST>
</CommonAST>
<CommonAST text="ORDERBY_CLAUSE" type="204">
<CommonAST text="ORDERBY_ITEM" type="205">
<CommonAST text="COLUMN_REFERENCE" type="188">
<CommonAST text="" type="193">
</CommonAST>
<CommonAST text="customer" type="143">
</CommonAST>
</CommonAST>
<CommonAST text="EMPTY" type="170">
</CommonAST>
</CommonAST>
</CommonAST>
<CommonAST text="UNION_LIST" type="209">
</CommonAST>
<CommonAST text="ORDERBY_CLAUSE" type="204">
</CommonAST>
</CommonAST>

In addition, the XML string can be assigned to a different query.

dim Q2 as SQL::Query
Q2.XML = Q.XML
? Q2.ParseTree
= 
{ select:55  -1:213   0:213   NONE:202 
  { SELECT_LIST:180
    { SELECT_ITEM:181
      { COLUMN_REFERENCE:188  :193   customer:143 }      :192 }  
    { SELECT_ITEM:181
      { COLUMN_REFERENCE:188  :193   cost:143 }      :192 }  
    { SELECT_ITEM:181
      { VALUE_EXPRESSION:212  NONE:140 
        { LIST:178  Hello:214 }      }      Message:192 }  }
  { TABLE_LIST:184
    { SELECT_TABLE_REFERENCE:189  :195   orderheader:193   o:194   JOIN_LIST:196 }  }
  { LOGICAL_EXPRESSION:211  EMPTY:170   LIST:178 }
  { GROUPBY_CLAUSE:207  GROUPBY_LIST:208 
    { LOGICAL_EXPRESSION:211  EMPTY:170   LIST:178 }  }
  { ORDERBY_CLAUSE:204
    { ORDERBY_ITEM:205
      { COLUMN_REFERENCE:188  :193   customer:143 }      EMPTY:170 }  }  UNION_LIST:209   ORDERBY_CLAUSE:204 }

Using Arguments 

This script show how to use an argument when you want to substitute a value at run time. This syntax does not directly use a SQL::Arguments object. Instead, it allows the SQL::Query object to create its own SQL::Arguments object.

q.Parse("SELECT CompanyName, City FROM Customers WHERE City = :city")
? q.Arguments.Count
= 1
? q.Arguments.Set("City", "London")
= .T.
c.Open(cs)
q.Execute(c)
? q.ResultSet.ToString()
= B's Beverages London
Consolidated Holdings London
Eastern Connection London
North/South London
Seven Seas Imports London

This syntax uses a SQL::Arguments object, adds a name/value pair with the SQL::Argument.Add() method, and passes the object as part of the SQL::Connection::Execute() query.

dim args as SQL::Arguments
dim conn as SQL::Connection
sql = "SELECT TOP 2 CompanyName, City FROM Customers WHERE City = :city"
args.Add("city", "London")
? conn.Execute(sql, args)
= .T.
? conn.ResultSet.ToString()
= B's Beverages London
Consolidated Holdings London
Eastern Connection London
North/South London
Seven Seas Imports London

Related Objects 

Name
Description
SQL::Query::Assignment Object

Internal Use Only.

SQL::Query::ColumnOrder Object

Internal use only. A SQL::Query::ColumnOrder object describes an entry in the ORDER BY clause.

SQL::Query::ColumnReference Object

Internal use only. Describes a reference to a table column.

SQL::Query::GroupBy Object

Internal use only. The SQL::Query::GroupBy object describes the GROUP BY and HAVING expressions of a SELECT statement. The GROUP BY clause contains an optional ALL keyword and a list of column expressions upon which to group the result set. The optional HAVING clause is evaluated for each aggregated row to determine whether the summary will be included in the output.

SQL::Query::Join Object

Internal use only. The SQL::Query::Join object fully describes the joining of a parent table to a referenced table. Key properties include .JoinType and (if an outer join) the .OuterJoinType.

SQL::Query::LogicalExpression Object

Internal use only. The SQL::Query::LogicalExpression object describes a logical expression used in a SELECT statement. A logical expression returns a logical (boolean) result. Logical expressions are used in the WHERE clause and as input to value expressions and function arguments. The SQL::Query::LogicalExpression object is simple, but any operand may be an expression itself, meaning that a tree of operator and their respective operands can nest down many levels.

SQL::Query::ReplaceOption Object

Internal use only.

SQL::Query::SelectItem Object

Internal use only. Describes a data item to be retrieved by a SELECT statement.

SQL::Query::SelectTableReference Object

Internal use only. Describes a reference to a table.

SQL::Query::TableReference Object

Internal use only.

SQL::Query::Union Object

Internal use only.

SQL::Query::ValueExpression Object

Internal use only. The SQL::Query::ValueExpression object describes a value expression used in a SELECT statement. A value expression returns a data value. Value expressions are used in the select list, the WHERE clause and as input to logical and value expressions and as function arguments. The expression object is simple, but any operand may be an expression itself, meaning that a tree of operator and their respective operands can nest down many levels.

Related Enumerations 

Name
Description
SQL::Query::ArithmeticOperator Enumerated Type

Internal use only. This is an enumerated type with one of the values below.

SQL::Query::DuplicateOption Enumerated Type

Internal use only. This is an enumerated type with one of the values in the list below:

SQL::Query::LogicalOperator Enumerated Type

Internal use only. This is an enumerated type with one of the values in the list below:

SQL::Query::Order Enumerated Type

Internal use only. This is an enumerated type with one of the values in the list below:

SQL::Query::OuterJoinType Enumerated Type

Internal use only. This is an enumerated type with one of the values in the list below:

Properties

ArgumentsSQL::Arguments

Arguments for the current query.

CallResultSQL::CallResult

Call results.

ColumnList of SQL::Query:: SelectItem

List of the items in the select column list.

ColumnReferencesReferenceList of SQL::Query::ColumnReference

An array of all column references in the query (including nested occurrences). Behaves the same way as .SelectTableReferences.

ConnectionSQL::Connection

Current open connection

DuplicateOptionSQL::Query::DuplicateOption

See Enumerated Type Values.

ErrorColumnNumeric

The column number of the last error reported by the parser.

ErrorTextCharacter

The text of the last parser error reported.

FirstNumeric

 

FunctionReferencesReferenceList of SQL::Query::ValueExpression

An array of all function calls. Behaves the same way as .SelectTableReferences.

GroupBySQL::Query::GroupBy

The GROUP BY clause. This object always exists. If the list inside is empty, no GROUP BY was coded.

NestedOrderByList of SQL::Query::ColumnOrder

A list of column order objects. If the list is empty, no ORDER BY clause was coded. .NestedOrderBy comes before .Union. This was in a test case, so I am supporting it (for now).

ObjectDefinitionsCharacter

For internal debugging. Returns a string description of the mapping between the ANTLR grammar and the Xbasic objects.

OrderByList of SQL::Query::ColumnOrder

A list of column order objects. If the list is empty, no ORDER BY clause was coded.

ParseTreeCharacter

For internal debugging. A string description of the underlying parse tree.

ResolveColumnTablesLogical

Set to .T. if Execute should populate descriptions of tables and columns. This can affect performance.

ResultSetSQL::ResultSet

Descriptions and/or data from the last Execute or Validate function call.

SelectTableReferencesReferenceList of SQL::Query::SelectTableReference

An array of all table references in the from clause and those joined to them. This array is created when the property is requested, but can become out of date. Use the Resynch() function on any variable holding this list when any changes are made.

SQLStatementCharacter

A variable that can be assigned a syntax string without parsing it. If no value is passed to the .Parse() method, this value is used.

TableList of SQL::Query::SelectTableReference

The items in the FROM clause or in a JOIN clause.

TableReferencesReferenceList of SQL::Query::SelectTableReference

An array of all table references in the query (including those nested inside of sub-selects and joins). This array is created when the property is requested, but can become out of date. Use the Resynch() function on any variable holding this list when any changes are made.

TokenTypeNameCharacter

"Query"

UnionList of SQL::Query::Union

A list (could be empty) of UNION clauses with their respective queries.

WhereSQL::Query::LogicalExpression

An expression for the WHERE clause.

XMLCharacter

Creates XML from the tree or recreates the tree from the XML.

Methods

Execute Method

Execute the current statement using the current or passed connection. Optionally providing argument values as an object or as XML. Note: Argument values are merged with those already set on the query.

Format Method

Format the original source (by default, lines are broken at significant keywords)..

GenerateNativeSyntax Method

Generate a native SQL statement using the selected syntax associated with the current or passed connection.

OpenConnection Method

Generate a native SQL statement using the selected syntax associated with the current or passed connection.

Parse Method

Parse the SQLStatement passed (or the value previously set into the SQLStatement property).

ReleaseConnection Method

Clear out the connection property.

Reset Method

Reset the query as if it had just been created.

Validate Method

Execute the current statement using the current or passed connection.

See Also