IResultSet interface (deprecated)
IResultSet is deprecated and is provided for backward compatibility only. New applications should use the ResultSet interface from the JDBC Core API.
The IResultSet interface represents the results of a flat query. IResultSet provides methods to iterate through rows in the result set and retrieve data from each row. To retrieve data from the result set, the AppLogic uses methods tailored for specific column types. For example, if retrieving data from a string column, use getValueString( ). If retrieving binary data, use getValueBinary( ).
To process hierarchical result sets, use methods in the IHierResultSet interface (deprecated) or evalTemplate( ) in the AppLogic class (deprecated) instead.
IResultSet is part of the Data Access Engine (DAE) service.
To create an instance of the IResultSet interface, use executeQuery( ) in the IDataConn interface (deprecated) or execute( ) in the IPreparedQuery interface (deprecated), as shown in the following example:
IResultSet rs;
rs = conn.executeQuery(0, qry, null, null);
Package
com.kivasoft
Methods
Example
The following code copies the data from all the rows in a result set into a log file:
do {
int invID
double invTotal;
String invCustomer;
Date invDate
invID = rs.getValueInt(1);
invDate = rs.getValueDate(2);
invTotal = rs.getValueDouble(3);
invCustomer = rs.getValueString(4);
Log("Invoice : " + String.valueOf(invID));
Log(" Date : " + String.valueOf(invDate));
Log(" Total : " + String.valueOf(invTotal));
Log(" Customer : " + invCustomer);
} while (rs.fetchNext() == 0);
Related Topics
executeQuery( ) in the IDataConn interface (deprecated)
execute( ) in the IPreparedQuery interface (deprecated)
close( )
Releases the connection used by the result set.
Syntax
public int close(
int dwFlags)
dwFlags.
Specify 0 (zero). Internal use only.
Usage
Call close( ) to release a connection used by a result set object when the connection is no longer required. An AppLogic should release unused connections to prevent bottlenecks, especially for applications that support many concurrent users, or that access heavily-used databases.
Tip
After calling close( ), release the result set object by calling the GX.Release( ) method.
Return Value
GXE.SUCCESS if the method succeeds.
enumColumnReset( )
Resets the column enumeration to the first column in the result set.
Syntax
public int enumColumnReset()
Usage
Use enumColumnReset( ) before iterating through and retrieving columns in a result set. The enumColumnReset( ) method ensures that column retrieval starts from the first column.
Thereafter, use enumColumns( ) to retrieve each column sequentially. Each enumColumns( ) call returns an IColumn object for the next column.
Return Value
GXE.SUCCESS if the method succeeds.
Example
The following code enumerates columns in a result set and creates an HTML page that displays the name and type of the columns:
String htmlString;
IColumn col;
IResultSet rs = conn.executeQuery(0, query, null, null);
htmlString += "<h2>Products Table</h2>";
rs.enumColumnReset();
while ((col = rs.enumColumns()) != null) {
htmlString += "Column Name = ";
htmlString += col.getName();
htmlString += ", Column Type = ";
htmlString += col.getType();
htmlString += "<br>";
};
return result(htmlString)
Related Topics
enumColumns( )
Returns the definition of the next column in the result set.
Syntax
public IColumn enumColumns()
Usage
Use enumColumns( ) when the column definition is unknown and required for subsequent operations. The AppLogic can use the returned IColumn object to determine characteristics of the column, such as its name, data type, size, whether nulls are allowed, and so on.
Before iterating through columns, the AppLogic should call enumColumnReset( ) to ensure that enumColumns( ) starts with the first column in the table. Each subsequent enumColumns( ) call moves to the next sequential column in the result set and retrieves its column definition in an IColumn object.
Tips
Return Value
IColumn object containing the next column of data, or null for failure (such as no more columns in the table).
Example
The following code enumerates columns in a result set and creates an HTML page that displays the name and type of the columns:
String htmlString;
IColumn col;
IResultSet rs = conn.executeQuery(0, query, null, null);
htmlString += "<h2>Products Table</h2>";
rs.enumColumnReset();
while ((col = rs.enumColumns()) != null) {
htmlString += "Column Name = ";
htmlString += col.getName();
htmlString += ", Column Type = ";
htmlString += col.getType();
htmlString += "<br>";
};
return result(htmlString)
Related Topics
IColumn interface (deprecated)
fetchNext( )
Retrieves the next row in the result set.
Syntax
public int fetchNext()
Usage
Use fetchNext( ) when iterating through rows in the result set to retrieve the contents of the next sequential row and put them in the row buffer for subsequent processing (if RS_BUFFERING has been turned ON).
If result set buffering was activated, fetchNext( ) checks the buffer first before fetching the result set from the actual data source. For more information about result set buffering, see the description of the props parameter of executeQuery( ) in the IDataConn interface (deprecated).
Tips
Return Value
GXE.SUCCESS if the method succeeds. The AppLogic can test for the following return values:
Example
The following code copies the data from all the rows in a result set into a log file:
do {
int invID
double invTotal;
String invCustomer;
Date invDate
invID = rs.getValueInt(1);
invDate = rs.getValueDate(2);
invTotal = rs.getValueDouble(3);
invCustomer = rs.getValueString(4);
Log("Invoice : " + String.valueOf(invID));
Log(" Date : " + String.valueOf(invDate));
Log(" Total : " + String.valueOf(invTotal));
Log(" Customer : " + invCustomer);
} while (rs.fetchNext() == 0);
Related Topics
executeQuery( ) in the IDataConn interface (deprecated)
execute( ) in the IPreparedQuery interface (deprecated)
getColumn( )
Returns the column definition of the column with the specified name.
Syntax
public IColumn getColumn(
String colName)
colName.
Name of a column or column alias (such as computed columns) in the result set, or an empty string if no alias is specified for the computed column.
Usage
Use getColumn( ) when the data definition of the column is unknown and is required for subsequent operations. The AppLogic can then use methods in the IColumn interface (deprecated) to obtain descriptive information about a table column from the database catalog, such as the column name, precision, scale, size, table, and data type.
Tips
Return Value
IColumn object, or null for failure (such as an invalid column name).
Example
// Determine whether the column name is valid
IColumn col;
if((col=rs.getColumn("CustID"))==null)
return null;
// otherwise, process column using IColumn methods ...
Related Topics
IColumn interface (deprecated)
executeQuery( ) in the IDataConn interface (deprecated)
execute( ) in the IPreparedQuery interface (deprecated)
getColumnByOrd( )
Returns the column definition for the column in the specified ordinal position.
Syntax
public IColumn getColumnByOrd(
int colIndex)
colIndex.
Ordinal position of a column in the result set. The ordinal position of the first column in the result set is 1, the second column is 2, and so on. The ODBC maximum is 255 columns.
Usage
Use getColumnByOrd( ) when the name of the column is unknown and is required for subsequent operations. The AppLogic can then use methods in the IColumn interface (deprecated) to obtain descriptive information about a table column from the database catalog, such as the column name, precision, scale, size, table, and data type.
Tip
Use getColumn( ) instead when the column name is known but its ordinal position is unknown.
Return Value
IColumn object, or null for failure (such as an invalid column position).
Example
// Determine whether the column position is valid
IColumn col;
if((col=rs.getColumnByOrd(colOrd))==null)
return null;
// otherwise, process column using IColumn methods . . .
Related Topics
IColumn interface (deprecated)
executeQuery( ) in the IDataConn interface (deprecated)
execute( ) in the IPreparedQuery interface (deprecated)
getColumnOrdinal( )
Returns the ordinal position of the column with the specified name.
Syntax
public int getColumnOrdinal(
String szColumn)
szColumn.
Name of a column in the result set.
Usage
Use getColumnOrdinal( ) when the ordinal position of the column is unknown but is required for subsequent operations. For example, the ordinal position of a column is a required parameter value for the getValue**( ) methods, such as getValueString( ) and getValueInt( ).
Return Value
An int value representing the ordinal position of the specified column, or zero for failure (such as an invalid column name). The ordinal position of the first column in the result set is 1, the second column is 2, and so on.
Example
// Execute the query
IResultSet rs=conn.executeQuery(0, query, null, null);
// Check for a non empty result
if((rs!=null)&&(rs.getRowNumber()>0))
return result("Sorry, this user already exists");
// Get the ordinal positions of named columns
int cCustId = rs.getColumnOrdinal("CustomerId");
int cFirst = rs.getColumnOrdinal("FirstName");
int cLast = rs.getColumnOrdinal("LastName");
int cPassword = rs.getColumnOrdinal("Password");
int cAddr1 = rs.getColumnOrdinal("BillAddr1");
int cAddr2 = rs.getColumnOrdinal("BillAddr2");
int cCity = rs.getColumnOrdinal("BillCity");
int cState = rs.getColumnOrdinal("BillState");
int cZip = rs.getColumnOrdinal("BillZip");
int cEmail = rs.getColumnOrdinal("Email");
int cPhone = rs.getColumnOrdinal("Phone");
if((cCustId*cFirst*cLast*cPassword*cAddr1*cAddr2*cCity*cState*cZip*cEma
il*cPhone)==0)
return result("Can't map columns");
Related Topics
executeQuery( ) in the IDataConn interface (deprecated)
execute( ) in the IPreparedQuery interface (deprecated)
getNumColumns( )
Returns the number of columns in the result set.
Syntax
public int getNumColumns()
Usage
Use getNumColumns( ) if the number of columns in the result set is unknown and required for subsequent operations. For example, when iterating through columns in the result set, the AppLogic can use this information to specify the maximum number of iterations.
Return Value
An int value representing the number of columns, or zero for failure.
Related Topics
executeQuery( ) in the IDataConn interface (deprecated)
getOrder( )
For asynchronous queries, returns an IOrder object used for obtaining the current status and return value of the query.
Syntax
public IOrder getOrder()
Usage
Use getOrder( ) to create an IOrder object that the AppLogic can use to return status information about an asynchronous query.
Rule
The query must be run asynchronously. To run an asynchronous query, the AppLogic must specify GX_DA_EXECUTEQUERY_FLAGS.GX_DA_EXEC_ASYNC as the dwFlags parameter in executeQuery( ) in the IDataConn interface (deprecated).
Tips
Return Value
IOrder object representing the status and return value of the asynchronous query, or null for failure (such as when the query is synchronous).
Related Topics
IOrder interface (deprecated)
executeQuery( ) in the IDataConn interface (deprecated)
getRowNumber( )
Returns the number of the current row in the result set.
Syntax
public int getRowNumber()
Usage
When iterating through rows in the result set, use getRowNumber( ) to keep track of the number of rows processed.
Return Value
An int value representing the number of the current row, or zero for an empty result set or failure (such as an invalid row). The number of the first row in the result set is 1, the second row is 2, and so on. If zero is returned the first time the AppLogic calls getRowNumber( ), that means the result set is empty.
Example
// Execute the query
IResultSet rs = conn.executeQuery(0, qry, null, null);
// Test for an empty result set
if((rs==null)||(rs.getRowNumber()==0))
return result("Customer does not exist");
Related Topics
executeQuery( ) in the IDataConn interface (deprecated)
execute( ) in the IPreparedQuery interface (deprecated)
getStatus( )
Returns the processing status of the asynchronous database operation on the database server.
Syntax
public int getStatus()
Usage
Use getStatus( ) to return status information to use in error-handling code.
Return Value
One of the following:
getValueBinary( )
Returns the value of a BINARY column in the current row of the result set.
Syntax
public byte[] getValueBinary(
int Ordinal)
Ordinal.
Ordinal number (position) of the column in the table definition. The first column is 1, the second column is 2, and so on.
Usage
Use getValueBinary( ) to retrieve binary data of which the total size is equal to or smaller than 64Kb. If the value of the data is larger than 64Kb, use getValueBinaryPiece( ).
Rule
The data type of the column must be BINARY, VARBINARY, or equivalent database type.
Tip
If the value of the data is of type LONGBINARY, use getValueBinaryPiece( ).
Return Value
A byte array for success, or null for failure (such as an invalid column number or data type mismatch).
getValueBinaryPiece( )
Returns the value of a LONGBINARY column in the current row from the result set.
Syntax
public byte[] getValueBinaryPiece(
int Ordinal,
int nLength)
Ordinal.
Ordinal number (position) of the column in the table definition. The first column is 1, the second column is 2, and so on.
nLength.
The requested length of the data, in bytes. Up to 64Kb.
Usage
Use getValueBinaryPiece( ) to retrieve binary data of which the total size is larger than 64K. Such binary data must be retrieved in 64K increments. Therefore, you might use getValueBinaryPiece( ) several times to retrieve large amounts of data.
Rules
Tips
Return Value
A byte array for success, or null for failure (such as an invalid column number or data type mismatch).
Example
The following example shows how to retrieve BLOBs from a database:
IQuery query = null;
IResultSet rs = null;
query = createQuery();
query.setTables("blobtable");
query.setFields("blobcol");
rs = conn.executeQuery(0, query, null, null);
if (rs != null && rs.getRowNumber() > 0)
{
byte BlobChunk[];
int expectSize, gotSize;
expectSize = 65535;
BlobChunk = rs.getValueBinaryPiece(1, expectSize);
gotSize = rs.getValueSize(1);
if (gotSize == expectSize)
System.out.println("got a full chunk," +
"size = "+gotSize);
else
System.out.println("got a partial chunk," +
"size = "+gotSize);
rs.close(0);
}
getValueDateString( )
Returns the value of a Date type column, as a string, from the current row in the result set.
Syntax
public String getValueDateString(
int colIndex)
colIndex.
Ordinal position of a column in the result set. The ordinal position of the first column in the result set is 1, the second column is 2, and so on.
Usage
Use getValueDateString( ) to retrieve date values from the result set for subsequent processing. The following is an example of the format in which getValueDateString( ) returns a date:
Jan 26 1998 12:35:00
Rule
The specified column must be a Date, Date Time, or Time data type.
Return Value
The date value as a string, or null for failure (such as an invalid column number or data type mismatch).
Example
IResultSet rs=conn.executeQuery(0, qry, null, null);
// Check input parameters
if((rs==null)||(rs.getRowNumber()==0)||(colName==null))
return null;
int colOrd=rs.getColumnOrdinal(colName);
IColumn col;
if((col=rs.getColumnByOrd(colOrd))==null)
return null;
String valStr=null;
// Switch type
switch(col.getType()) {
case GX_DA_DATA_TYPES.GX_DA_TYPE_STRING:
valStr = rs.getValueString(colOrd);
break;
case GX_DA_DATA_TYPES.GX_DA_TYPE_LONG:
valStr=String.valueOf(rs.getValueInt(colOrd));
break;
case IGX_DA_DATA_TYPES.GX_DA_TYPE_DATE:
valStr=rs.getValueDateString(colOrd);
break;
case GX_DA_DATA_TYPES.GX_DA_TYPE_DOUBLE:
valStr=String.valueOf(rs.getValueDouble(colOrd));
break;
default:
};
return valStr;
getValueDouble( )
Returns the value of a double type column from the current row in the result set.
Syntax
public double getValueDouble(
int colIndex)
colIndex.
Ordinal position of a column in the result set. The ordinal position of the first column in the result set is 1, the second column is 2, and so on.
Usage
Use getValueDouble( ) to retrieve decimal, floats, real, numeric, and double values from the result set for subsequent processing.
Rule
The specified column must be a double data type.
Return Value
A double value, or zero for failure (such as an invalid column number or data type mismatch).
Example 1
The following code retrieves data from a result set:
// Execute the query
rs = conn.executeQuery(0, query, null, null);
if((rs==null)||(rs.getRowNumber()==0))
{
// It does not exist, so remove it from the basket
session.removeProduct(product, this);
continue;
}
// Retrieve values from the result set
String prodName=
rs.getValueString(rs.getColumnOrdinal("ProdName"));
double price;
price = rs.getValueDouble(rs.getColumnOrdinal("Price"));
Example 2
The following code copies the data from all the rows in a result set into a log file:
do {
int invID
double invTotal;
String invCustomer;
Date invDate
invID = rs.getValueInt(1);
invDate = rs.getValueDate(2);
invTotal = rs.getValueDouble(3);
invCustomer = rs.getValueString(4);
Log("Invoice : " + String.valueOf(invID));
Log(" Date : " + String.valueOf(invDate));
Log(" Total : " + String.valueOf(invTotal));
Log(" Customer : " + invCustomer);
} while (rs.fetchNext() == 0);
getValueInt( )
Returns the value of an int type column from the current row in the result set.
Syntax
public int getValueInt(
int colIndex)
colIndex.
Ordinal position of a column. The ordinal position of the first column in the result set is 1, the second column is 2, and so on.
Usage
Use getValueInt( ) to retrieve int or long values from the result set for subsequent processing.
Rule
The specified column must be an int or long data type.
Return Value
An int value, or zero for failure (such as an invalid column number or data type mismatch).
Example 1
The following code retrieves data from a result set:
// Execute the query
IResultSet rs=conn.executeQuery(0, query, null, null);
// Check the results
if((rs==null)||(rs.getRowNumber()>0))
{
// Pull the current inventory and name for the product
int prodInv=
rs.getValueInt(rs.getColumnOrdinal("COL_INVENTORY"));
String prodName=
rs.getValueString(rs.getColumnOrdinal("COL_PRODNAME"));
Example 2
The following code copies the data from all the rows in a result set into a log file:
do {
int invID
double invTotal;
String invCustomer;
Date invDate
invID = rs.getValueInt(1);
invDate = rs.getValueDate(2);
invTotal = rs.getValueDouble(3);
invCustomer = rs.getValueString(4);
Log("Invoice : " + String.valueOf(invID));
Log(" Date : " + String.valueOf(invDate));
Log(" Total : " + String.valueOf(invTotal));
Log(" Customer : " + invCustomer);
} while (rs.fetchNext() == 0);
getValueSize( )
Returns the cumulutive number of bytes that have been fetched from a column in the current row of the result set.
Syntax
public int getValueSize(
int colIndex);
colIndex.
Ordinal number (position) of the column in the table definition. The first column is 1, the second column is 2, and so on.
Usage
Use getValueSize( ) during data retrieval to check the size of the BLOB column that has been retrieved. When the AppLogic first calls getValueSize( ) before calling getValueBinaryPiece( ) to retrieve the value of a LONGBINARY column, getValueSize( ) returns 0.
Each subsequent getValueSize( ) call during data retrieval returns the cumulative size of the data that has been retrieved.
Return Value
An integer value representing the number of bytes retrieved from a column, or a negative number for failure.
Related Topics
getValueBinaryPiece( )
getValueString( )
Returns the value of a String type column from the current row in the result set.
Syntax
public String getValueString(
int colIndex)
colIndex.
Ordinal position of a column in the result set. The ordinal position of the first column in the result set is 1, the second column is 2, and so on.
Usage
Use getValueString( ) to retrieve String values from the result set for subsequent processing.
Rule
The specified column must be a String data type.
Return Value
A String value, or null for failure (such as an invalid column number or data type mismatch).
Example 1
The following code retrieves data from a result set:
// Execute the query
rs = conn.executeQuery(0, query, null, null);
if((rs==null)||(rs.getRowNumber()==0))
{
// It does not exist, so remove it from the basket
session.removeProduct(product, this);
continue;
}
// Retrieve values from the result set
String prodName=
rs.getValueString(rs.getColumnOrdinal("ProdName"));
double price=
rs.getValueDouble(rs.getColumnOrdinal("Price"));
Example 2
The following code copies the data from all the rows in a result set into a log file:
do {
int invID
double invTotal;
String invCustomer;
Date invDate
invID = rs.getValueInt(1);
invDate = rs.getValueDate(2);
invTotal = rs.getValueDouble(3);
invCustomer = rs.getValueString(4);
Log("Invoice : " + String.valueOf(invID));
Log(" Date : " + String.valueOf(invDate));
Log(" Total : " + String.valueOf(invTotal));
Log(" Customer : " + invCustomer);
} while (rs.fetchNext() == 0);
getValueText( )
Returns the value of a TEXT column in the current row from the result set.
Syntax
public String getValueText(
int Ordinal)
Ordinal.
Ordinal number (position) of the column in the table definition. The first column is 1, the second column is 2, and so on.
Usage
Use getValueText( ) to retrieve TEXT data of which the total size is equal to or smaller than 64K.
Rule
The data type of the column must be TEXT or database equivalent.
Tips
Return Value
A String object, or null for failure (such as an invalid column number or data type mismatch).
getValueTextPiece( )
Returns the value of a LONGTEXT column in the current row from the result set.
Syntax
public String getValueTextPiece(
int Ordinal,
int nLength)
Ordinal.
Ordinal number (position) of the column in the table definition. The first column is 1, the second column is 2, and so on.
nLength.
The requested length of the data, in bytes. Up to 64Kb.
Usage
Use getValueTextPiece( ) to retrieve LONGTEXT data. LONGTEXT values must be retrieved in 64K increments, therefore, you must use getValueTextPiece( ) repeatedly to retrieve the data.
Rules
Tips
Return Value
A String object, or null for failure (such as an invalid column number or data type mismatch).
moveTo( )
Moves to the specified row in the result set.
Syntax
public int moveTo(
int nRow)
nRow.
Number of the row in the result set to move to. The number of the first row in the result set is 1, the second row is 2, and so on.
Usage
Use moveTo( ) to move the internal cursor to a specific row in the result set, skipping over rows to be excluded from processing. In addition, if RS_BUFFERING is ON, after iterating through all rows in a result set, the AppLogic can return to the first row in the result set in preparation for the next iteration.
Rules
Tip
Use rowCount( ), if the database driver supports it, to obtain the maximum number of rows in the result set.
Return Value
GXE.SUCCESS if the method succeeds.
Related Topics
executeQuery( ) in the IDataConn interface (deprecated)
execute( ) in the IPreparedQuery interface (deprecated)
rowCount( )
Returns the total number of rows retrieved thus far from the data source.
Syntax
public int rowCount()
Usage
Use rowCount( ) to return the current number of rows processed so far in the result set. This method is useful for checking that data exists in the result set before processing the result set.
If iterating through rows in a result set that has been completely returned, use rowCount( ) to determine the current maximum number of rows to process.
Tip
If result set buffering is enabled, the AppLogic can use rowCount( ) to find the current number of rows in the buffer.
Return Value
An int value representing the total number of rows in the result set, or zero for failure (such as an empty result set or unable to retrieve any rows).
Example
do {
htmlString += rs.getValueString(DESCRIPTION_COL);
// Truncate the report after 10 rows.
if (rs.rowCount() > 10)
break;
} while (rs.fetchNext() == GXE_SUCCESS);
Related Topics
executeQuery( ) in the IDataConn interface (deprecated)
execute( ) in the IPreparedQuery interface (deprecated)
wasNull( )
Checks if the value of a column is null or not.
Syntax
public boolean wasNull(
int Ordinal)
Ordinal.
Ordinal number (position) of the column in the table definition. The first column is 1, the second column is 2, and so on.
Usage
Use wasNull( ) to check if a column value is null or not. This method is useful for determining if a null return value is an error condition or if the column contained no value.
Return Value
True if the column value is null, false if the value is not.
|
Previous
