Foundation Class Library (Java):

IHierQuery is deprecated and is provided for backward compatibility only. New Java applications should use the standard servlet-JSP programming model.

For information about replacing IHierQuery functionality in existing applications, see the Migration Guide.

The IHierQuery interface represents a hierarchical query. IHierQuery provides methods for retrieving hierarchical information organized in nested levels of detail, as in the following example:

Asia          170

  China       110

  Japan        60

Europe         80

  France       70

  Portugal     10

A hierarchical query combines multiple flat queries organized in cascading, parent-child relationships. Each query is an IQuery object containing data selection criteria. The IHierQuery object contains the definition of the hierarchical structure of parent-child relationships among IQuery objects.

To use a hierarchical query, the AppLogic first creates each individual query and defines its selection criteria. Next, it creates theIHierQueryobject and calls addQuery( ) repeatedly to add a child query to a parent query for each level of detail in the hierarchical query.

After the hierarchical query is constructed, the AppLogic calls its execute( ) method to run the hierarchical query on the target data source and retrieve a hierarchical result set in an IHierResultSet object.

Alternatively, the AppLogic can load a hierarchical query stored in a file. For more information, see loadHierQuery( ) and createDataConnSet( ) in the AppLogic class (deprecated).

To create an instance of the IHierQuery interface, use createHierQuery( ) in the AppLogic class (deprecated), as shown in the following example:

IHierQuery hqry;

hqry = createHierQuery();

Package
com.kivasoft

Methods


Method	Description
addQuery( )	Adds a child query to a parent query, defining an additional level of detail in the hierarchical query.
delQuery( )	Removes a child query from its parent query.
execute( )	Executes a hierarchical query and returns a hierarchical result set.

Example 1

// Create the flat query

IQuery qry = createQuery();

qry.setTables("CTLusers");

qry.setFields("loginName, Password, AccessLevel") 

qry.setOrderBy("LoginName);



// Create the hierarchical query used for template processing

IHierQuery hqry = createHierQuery();



// Add the flat query object and data connection to hqry

hqry.addQuery(qry, conn, "USERS", "", "");



// Pass hierarchical query to evalTemplate() for reporting

if(evalTemplate("apps/template/userinfo.html", hqry)==0)

   return result("");

else

   return result("Failed to Generate HTML");

}

Example 2

// Create the flat query

IQuery qry = createQuery();

qry.setTables("CTLusers");

qry.setFields("loginName, Password, AccessLevel")

query.setWhere("UserId"+"="+wantedUser.hashCode());



// Create the hierarchical query

IHierQuery hqry = createHierQuery();

hqry.addQuery(qry, conn, "USERS", "", "");



// Execute the hierarchical query

IHierResultSet hrs = hqry.execute(0, 0, null);



// Process rows in result set . . .

if(hrs.getRowNumber("USERS")!=0)

addQuery( )
Adds a child query to a parent query, defining an additional level of detail in the hierarchical query.

Syntax

public int addQuery(
	IQuery pQuery,
	IDataConn pConn,
	String szAlias,
	String szParent,
	String szJoin)

pQuery. IQuery object that contains the flat query object to append as a child to the parent query.

pConn. IDataConn object that contains the data connection where the child query will be executed. Each flat query in the hierarchical query can retrieve data from a different data source.

szAlias. Name used to uniquely identify this child query in the query hierarchy. AppLogic must specify a child name that is unique within the hierarchical query.

szParent. Name of the parent query to contain this child query. Use an empty string ("") for the highest level in the hierarchical query. When adding a child query to an existing parent query, the specified parent name must have already been specified in a previous addQuery( ) call.

szJoin. Join clause used to specify a join for this query, defining the relationship between a field in the child query and a field in the parent query. Use an empty string for the highest level in the hierarchical query. Use the following Netscape-compliant syntax for the join clause:

"ParentQuery.table.column='childQuery.table.column'"

Optionally, you can specify the schema:

"ParentQuery.schema.table.column='childQuery.schema.table.column'"

Note. The only difference between the Netscape Application Server and SQL join syntax is that, with Netscape, you prepend the clause with the query name.

To refer to a field name in the parent query, include the parent query name before the field name, as shown in the following example, in which CITY is the name of the parent query:

hqr.addQuery(qryEMP, conn, "EMP", "CITY", "EMP.employee.city = 
'CITY.city'");

Use the AND and OR operators to specify additional join conditions. Use parentheses to specify the order of precedence in complex join criteria.

Usage
Use addQuery( ) when constructing the hierarchical query to define the hierarchical relationships among child and parent queries. The number of nested levels, and thus the number of addQuery( ) calls, is limited only by system resources.

Rules

The AppLogic must first create the data connection using createDataConn( ) in the AppLogic class (deprecated).

The AppLogic must then create the specified child query using createQuery( ) in the AppLogic class (deprecated). A separate child query must exist for every level of data.

Return Value
GXE.SUCCESS if the method succeeds.

Example 1

// Create the flat query

IQuery qry = createQuery();

qry.setTables("CTLusers");

qry.setFields("loginName, Password, AccessLevel") 

qry.setOrderBy("LoginName);



// Create the hierarchical query used for template processing

IHierQuery hqry = createHierQuery();



// Add the flat query object and data connection to hqry

hqry.addQuery(qry, conn, "USERS", "", "");



// Pass hierarchical query to evalTemplate() for reporting

if(evalTemplate("apps/template/userinfo.html", hqry)==0)

   return result("");

else

   return result("Failed to Generate HTML");

}

Example 2

// Create the City flat query

IQuery qryCTY;

qryCTY = createQuery();

qryCTY.setTables("emp");

qryCTY.setFields("city, Sum(salary) as sumsalary");

qryCTY.setGroupBy("city");



// Create the Employee flat query

IQuery qryEMP;

qryEMP = createQuery();

qryEMP.setTables("emp");

qryEMP.setFields("name, salary, city");



IHierQuery hqry;

hqry = createHierQuery();

// Add both queries to the hierarchical query object

hqry.addQuery(qryCTY, conn, "CTY", "", "");

hqry.addQuery(qryEMP, conn, "EMP", "CTY", "EMP.emp.city = 'CTY.city'");

// Run the report

evalTemplate("GXApp/EmpTrack/Templates/report.html", hqry);

return result(null);

IQuery interface (deprecated)

IDataConn interface (deprecated)

delQuery( )
Removes a child query from its parent query.

Syntax

public int delQuery(
	String szName)

szName. Name of the child query to remove.

Usage
Use delQuery( ) to remove a child query that is no longer needed. Any children of the deleted child query are also removed.

Rule
The specified child query must exist in the hierarchical query.

Return Value
GXE.SUCCESS if the method succeeds.

Example

// Create the City flat query

IQuery qryCTY;

qryCTY = createQuery();

qryCTY.setTables("emp");

qryCTY.setFields("city, Sum(salary) as sumsalary");

qryCTY.setGroupBy("city");



// Create the Employee flat query

IQuery qryEMP;

qryEMP = createQuery();

qryEMP.setTables("emp");

qryEMP.setFields("name, salary, city");



IHierQuery hqry;

hqry = createHierQuery();

// Add both queries to the hierarchical query object

hqry.addQuery(qryCTY, conn, "CTY", "", "");

hqry.addQuery(qryEMP, conn, "EMP", "CTY", "EMP.emp.city = 'CTY.city'");



// Execute the hierarchical query

IHierResultSet hrs = hqry.execute(0, 0, null);

if(hrs.getRowNumber("USERS")!=0)

   // Process rows in result set . . .



// Remove child query from hierarchical query

hqry.delQuery("qryEMP");



// Pass parent query to evalTemplate() for reporting

if(evalTemplate("apps/template/ctySumm.html", hqry)==0)

   return result("");

else

   return result("Failed to Generate HTML");

}

loadHierQuery( ) in the AppLogic class (deprecated)

execute( )
Executes a hierarchical query and returns a hierarchical result set.

Syntax

public IHierResultSet execute(
	int dwFlags,
	int dwTimeout,
	IValList pProps)

dwFlags. Specifies flags used to execute this hierarchical query.

For synchronous operations, the default, specify zero or GX_DA_EXECUTEQUERY_FLAGS.GX_DA_EXEC_SYNC.

For asynchronous operations, specify GX_DA_EXECUTEQUERY_FLAGS.GX_DA_EXEC_ASYNC.

To activate result set buffering, specify GX_DA_EXECUTEQUERY_FLAGS.GX_DA_RS_BUFFERING.

The AppLogic can pass both result set buffering and either synchronous or asynchronous queries as the flags parameter, as shown in the following example:

(GX_DA_EXECUTEQUERY_FLAGS.GX_DA_EXEC_ASYNC | GX_DA_EXECUTEQUERY_FLAGS.GX_DA_RS_BUFFERING).

dwTimeout. Specify 0 (zero).

pProps. IValList object that contains query properties, or null for no properties. After instantiating an object of the IValList interface, set any of the following properties:

RS_BUFFERING turns on result set buffering when set to "TRUE".

RS_INIT_ROWS specifies the initial size of the buffer, in number of rows. If the result set size exceeds this setting, a fetchNext( ) call will return the error GX_DA_FETCHNEXT_RESULTS.GX_DA_BUFFER_EXCEEDED.

RS_MAX_ROWS specifies the maximum number of rows for the buffer. If the result set size exceeds this setting, a fetchNext( ) call will return the error GX_DA_FETCHNEXT_RESULTS.GX_DA_BUFFER_EXCEEDED.

RS_MAX_SIZE specifies the maximum number of bytes for the buffer.

If RS_BUFFERING is enabled and if the optional parameters are not specified, the global values in the registry are used instead..

Usage
After constructing a hierarchical query using addQuery( ), the AppLogic uses execute( ) to execute the query on the database server. Results are returned in a hierarchical result set.

Rule
AppLogic must first construct the hierarchical query using addQuery( ).

Return Value
IHierResultSet object that contains the result set of the hierarchical query, or null for failure (such as invalid parameters).

Example

// Create the flat query

IQuery qry = createQuery();

qry.setTables("CTLusers");

qry.setFields("loginName, Password, AccessLevel")

query.setWhere("UserId"+"="+wantedUser.hashCode());



// Create the hierarchical query

IHierQuery hqry = createHierQuery();

hqry.addQuery(qry, conn, "USERS", "", "");



// Execute the hierarchical query

IHierResultSet hrs = hqry.execute(0, 0, null);



// Process rows in result set

if(hrs.getRowNumber("USERS")>0)

. . .

loadHierQuery( ) in the AppLogic class (deprecated)

IHierResultSet interface (deprecated)

IValList interface