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.